feat(apple): PyroWave Phase 5 — native Metal decode on Mac / Apple TV / iPad (§4.7)

The Apple client now decodes PyroWave natively on the presenter's own MTLDevice —
no MoltenVK, no upstream C++ in the app. Completes and wires up the decoder whose
early working-tree snapshot rode along in 9127c346:

- MetalWaveletShaders.swift: wavelet_dequant + idwt hand-ported from the vendored
  GLSL (STORAGE_MODE 0 only; subgroup scans → 32-wide simdgroups; DCShift spec
  constant → function constant; precision-1 split: fp16 levels 0-1 / fp32 2-4).
- MetalWaveletDecoder.swift: Swift reimplementation of push_packet/decode_packet
  incl. the Phase-4 chunk-aligned window walk (FRAG chains, zeroed missing shards,
  the >half-blocks partial rule), init_block_meta's block-index space, and the
  42-dequant + 13-idwt dispatch structure with encoder-boundary barriers. SOF-dims
  changes rebuild the size-dependent resources, which is also the mid-stream
  resize path. Ring of 4 output plane sets on the presenter's queue.
- Presenter: pf_frag_planar (3xR8, the planar_csc.frag twin) + renderPlanar with
  a shared present tail; ReadyFrame carries an image enum (.video | .planar).
- Stage2Pipeline: a dedicated PyroWave pump — no VideoToolbox machinery, no
  keyframe/re-anchor recovery (all-intra; partials render as localized blur by
  design), newest-frame-index staleness guard for late partials.
- Opt-in: "PyroWave (wired LAN)" codec entry (probe-gated, ≈A13 floor via a real
  kernel-compile probe), selecting it advertises + prefers the codec and forces
  the session SDR (HDR/10-bit/4:4:4 caps dropped, plan contract).
- Core ABI: punktfunk_connection_shard_payload() — the Welcome's negotiated shard
  payload, needed by native decoders to walk chunk-aligned AUs.
- Validation: golden fixtures generated by the host encoder + upstream's own
  decoder (pyrowave_dump_golden, RTX 5070 Ti); the Metal decode PSNR-matches at
  77-88 dB across all planes for dense AND chunk-aligned AUs, and a hole-punched
  partial still decodes. Parser unit tests cover the window walk, FRAG chains,
  broken chains, the half-blocks gate, and the block-index layout.

Tests: apple 134 green (mac; iOS/tvOS build), host 312 w/ pyrowave on .21,
core 148 w/ quic; clippy/fmt clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

clients/apple/Package.swift

@@ -42,6 +42,13 @@ let package = Package(
         .executableTarget(name: "PunktfunkClient", dependencies: ["PunktfunkKit"]),
         // PunktfunkCore is a direct dep too so the wire tests can name the C ABI's
         // `PunktfunkInputEvent` / `PUNKTFUNK_INPUT_KIND_*` when asserting the gamepad byte layout.
-        .testTarget(name: "PunktfunkKitTests", dependencies: ["PunktfunkKit", "PunktfunkCore"]),
+        .testTarget(
+            name: "PunktfunkKitTests", dependencies: ["PunktfunkKit", "PunktfunkCore"],
+            resources: [
+                // PyroWave golden fixtures: host-encoded AUs + upstream-decoded reference
+                // planes (regenerate with punktfunk-host's `pyrowave_dump_golden` on a
+                // Vulkan box — see PyroWaveDecoderTests.swift).
+                .copy("PyroWaveFixtures")
+            ]),
     ]
 )

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -46,6 +46,7 @@ struct ContentView: View {
         case "h264": return PunktfunkConnection.codecH264
         case "hevc": return PunktfunkConnection.codecHEVC
         case "av1": return PunktfunkConnection.codecAV1
+        case "pyrowave": return PunktfunkConnection.codecPyroWave
         default: return 0
         }
     }

clients/apple/Sources/PunktfunkClient/Session/SessionModel.swift

@@ -239,6 +239,18 @@ final class SessionModel: ObservableObject {
             // from these + the soft `preferredCodec`; `resolvedCodec` reflects what it chose.
             var videoCodecs = PunktfunkConnection.codecH264 | PunktfunkConnection.codecHEVC
             if AV1.hardwareDecodeSupported { videoCodecs |= PunktfunkConnection.codecAV1 }
+            // PyroWave (wired LAN) is a pure opt-in: picking it in the codec setting both
+            // advertises the bit and prefers it — the host never auto-selects it, and the
+            // picker only offers it when the Metal decode probe passed (simdgroup floor ≈ A13;
+            // every M-series Mac and the ATV 4K gen 3 pass). The codec is 8-bit 4:2:0 SDR
+            // BT.709 by contract, so the opt-in also drops the HDR/10-bit/4:4:4 caps for this
+            // session — HDR sessions stay HEVC/AV1 (plan §4.7).
+            if preferredCodec == PunktfunkConnection.codecPyroWave, MetalWaveletDecoder.supported {
+                videoCodecs |= PunktfunkConnection.codecPyroWave
+                videoCaps &= ~(PunktfunkConnection.videoCap10Bit
+                    | PunktfunkConnection.videoCapHDR
+                    | PunktfunkConnection.videoCap444)
+            }
             let result = Result { try PunktfunkConnection(
                 host: host.address, port: host.port,
                 width: width, height: height, refreshHz: hz,

clients/apple/Sources/PunktfunkClient/Settings/SettingsOptions.swift

@@ -79,6 +79,13 @@ enum SettingsOptions {
         if AV1.hardwareDecodeSupported {
             options.insert(("AV1", "av1"), at: 2)
         }
+        // PyroWave is the opt-in wired-LAN low-latency codec (100–400 Mbps all-intra wavelet,
+        // 8-bit SDR): selecting it advertises + prefers it for the session. Offered only when
+        // the Metal decode probe passes (same gate SessionModel advertises by) — elsewhere the
+        // host could never emit it.
+        if MetalWaveletDecoder.supported {
+            options.append(("PyroWave (wired LAN)", "pyrowave"))
+        }
         return options
     }()
 

clients/apple/Sources/PunktfunkKit/Connection/PunktfunkConnection.swift

@@ -337,9 +337,15 @@ public final class PunktfunkConnection {
     public private(set) var resolvedAudioChannels: UInt8 = 2
 
     /// The video codec the host resolved for this session (`Welcome.codec`, `PUNKTFUNK_CODEC_*`):
-    /// `2` = HEVC (default / older host), `1` = H.264, `4` = AV1. Build the decoder from THIS. The
-    /// resolved value honors the client's `preferredCodec` when the host could emit it.
+    /// `2` = HEVC (default / older host), `1` = H.264, `4` = AV1, `8` = PyroWave (only when this
+    /// client opted in). Build the decoder from THIS. The resolved value honors the client's
+    /// `preferredCodec` when the host could emit it.
     public private(set) var resolvedCodec: UInt8 = 2 // PUNKTFUNK_CODEC_HEVC
+
+    /// The session's negotiated wire shard payload (`Welcome.shard_payload`, bytes) — the
+    /// parse-window size for `USER_FLAG_CHUNK_ALIGNED` PyroWave AUs (plan §4.4). Other codecs
+    /// never need it.
+    public private(set) var shardPayload: UInt32 = 1408
     /// The resolved codec as a `VideoCodec` (H.264 / HEVC / AV1) — drives the bitstream framing
     /// (Annex-B NAL parsing vs the AV1 OBU repack).
     public var videoCodec: VideoCodec { VideoCodec(wire: resolvedCodec) }
@@ -452,6 +458,9 @@ public final class PunktfunkConnection {
         var codec: UInt8 = 2 // PUNKTFUNK_CODEC_HEVC
         _ = punktfunk_connection_codec(handle, &codec)
         resolvedCodec = codec
+        var shard: UInt32 = 1408
+        _ = punktfunk_connection_shard_payload(handle, &shard)
+        shardPayload = shard
     }
 
     /// A bandwidth speed-test measurement (see `startSpeedTest`). Partial until `done`.
@@ -790,6 +799,15 @@ public final class PunktfunkConnection {
     public static let codecH264: UInt8 = UInt8(PUNKTFUNK_CODEC_H264)
     public static let codecHEVC: UInt8 = UInt8(PUNKTFUNK_CODEC_HEVC)
     public static let codecAV1: UInt8 = UInt8(PUNKTFUNK_CODEC_AV1)
+    /// PyroWave (opt-in wired-LAN wavelet codec, 8-bit SDR): the host only ever resolves it
+    /// when the client both advertises the bit AND names it `preferredCodec` — never
+    /// auto-selected. Decoded by the Metal wavelet decoder, not VideoToolbox.
+    public static let codecPyroWave: UInt8 = UInt8(PUNKTFUNK_CODEC_PYROWAVE)
+
+    /// `AccessUnit.flags` bit: the AU is shard-aligned self-delimiting chunks (the wire's
+    /// `USER_FLAG_CHUNK_ALIGNED`, PyroWave datagram-aligned mode §4.4) — walk it
+    /// window-by-window at `shardPayload`. (The C `#define` doesn't import into Swift.)
+    public static let userFlagChunkAligned: UInt32 = 64
 
     /// 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,

clients/apple/Sources/PunktfunkKit/Support/DefaultsKeys.swift

@@ -27,8 +27,10 @@ public enum DefaultsKey {
     /// Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
     /// can capture; the resolved count drives the in-core decode + AVAudioEngine layout.
     public static let audioChannels = "punktfunk.audioChannels"
-    /// Preferred video codec: `"auto"` (host decides), `"hevc"`, or `"h264"`. A soft preference —
-    /// the host emits it when it can, else falls back. Drives the decoder via `Welcome.codec`.
+    /// Preferred video codec: `"auto"` (host decides), `"hevc"`, `"h264"`, `"av1"`, or
+    /// `"pyrowave"` (the opt-in wired-LAN wavelet codec — picking it advertises AND prefers it,
+    /// and forces the session SDR). A soft preference — the host emits it when it can, else
+    /// falls back. Drives the decoder via `Welcome.codec`.
     public static let codec = "punktfunk.codec"
     public static let micEnabled = "punktfunk.micEnabled"
     public static let speakerUID = "punktfunk.speakerUID"

clients/apple/Sources/PunktfunkKit/Video/AV1.swift

@@ -543,19 +543,24 @@ public enum AV1 {
 
 extension VideoCodec {
     /// Codec-dispatching format-description refresh: the AV1 path keys on an in-band sequence
-    /// header, the NAL codecs on in-band parameter sets — one call site in each pump.
+    /// header, the NAL codecs on in-band parameter sets — one call site in each pump. PyroWave
+    /// has no CoreMedia representation at all (its pump feeds the Metal wavelet decoder raw).
     public func formatDescription(fromKeyframe au: Data) -> CMVideoFormatDescription? {
-        self == .av1
-            ? AV1.formatDescription(fromKeyframe: au)
-            : AnnexB.formatDescription(fromIDR: au, codec: self)
+        switch self {
+        case .av1: return AV1.formatDescription(fromKeyframe: au)
+        case .pyrowave: return nil
+        default: return AnnexB.formatDescription(fromIDR: au, codec: self)
+        }
     }
 
     /// Codec-dispatching sample wrap (see `formatDescription(fromKeyframe:)`).
     public func sampleBuffer(
         au: AccessUnit, format: CMVideoFormatDescription
     ) -> CMSampleBuffer? {
-        self == .av1
-            ? AV1.sampleBuffer(au: au, format: format)
-            : AnnexB.sampleBuffer(au: au, format: format, codec: self)
+        switch self {
+        case .av1: return AV1.sampleBuffer(au: au, format: format)
+        case .pyrowave: return nil
+        default: return AnnexB.sampleBuffer(au: au, format: format, codec: self)
+        }
     }
 }

clients/apple/Sources/PunktfunkKit/Video/AnnexB.swift

@@ -26,12 +26,18 @@ public enum VideoCodec: Equatable {
     case h264
     case hevc
     case av1
+    /// PyroWave wavelet (opt-in wired-LAN low-latency codec): not a NAL/OBU codec and not
+    /// VideoToolbox-decoded at all — the Metal wavelet decoder consumes the raw AUs
+    /// (Stage2Pipeline's PyroWave pump). Only ever resolved when this client both advertised
+    /// and preferred it.
+    case pyrowave
 
     /// Resolve from the wire `Welcome.codec` byte (`PUNKTFUNK_CODEC_*`; unknown → HEVC).
     public init(wire: UInt8) {
         switch wire {
         case 0x01: self = .h264 // PUNKTFUNK_CODEC_H264
         case 0x04: self = .av1 // PUNKTFUNK_CODEC_AV1
+        case 0x08: self = .pyrowave // PUNKTFUNK_CODEC_PYROWAVE
         default: self = .hevc // PUNKTFUNK_CODEC_HEVC — the default / older-host codec
         }
     }
@@ -147,8 +153,8 @@ public enum AnnexB {
             sets = [vps, sps, pps]
         case .h264:
             sets = [sps, pps]
-        case .av1:
-            return nil // OBU stream, no parameter-set NALs — handled in AV1.swift, never here
+        case .av1, .pyrowave:
+            return nil // no parameter-set NALs — dispatched in AV1.swift, never reaches here
         }
 
         var format: CMVideoFormatDescription?
@@ -184,8 +190,8 @@ public enum AnnexB {
                     parameterSetSizes: sizes,
                     nalUnitHeaderLength: 4,
                     formatDescriptionOut: &format)
-            case .av1:
-                break // unreachable — the .av1 arm above already returned
+            case .av1, .pyrowave:
+                break // unreachable — the arm above already returned
             }
         }
         return status == noErr ? format : nil

clients/apple/Sources/PunktfunkKit/Video/MetalVideoPresenter.swift

@@ -149,6 +149,28 @@ fragment float4 pf_frag(VOut in [[stage_in]],
     return float4(sampleRgb(lumaTex, chromaTex, in.uv, csc), 1.0);
 }
 
+// PyroWave planar SDR: three separate R8 planes (Y full-res, Cb/Cr half-res 4:2:0) from the
+// Metal wavelet decoder — the Metal twin of pf-presenter's planar_csc.frag. Same bicubic luma
+// and left-cosited chroma correction as the biplanar path (chromaUV self-disables at 4:4:4).
+fragment float4 pf_frag_planar(VOut in [[stage_in]],
+                               texture2d<float> lumaTex [[texture(0)]],
+                               texture2d<float> cbTex [[texture(1)]],
+                               texture2d<float> crTex [[texture(2)]],
+                               constant CscUniform& csc [[buffer(0)]]) {
+    constexpr sampler s(filter::linear, address::clamp_to_edge);
+#ifdef PF_BILINEAR_LUMA
+    float lumaY = lumaTex.sample(s, in.uv).r;
+#else
+    float lumaY = catmullRomLuma(lumaTex, s, in.uv);
+#endif
+    float2 cuv = chromaUV(lumaTex, cbTex, in.uv);
+    float3 yuv = float3(lumaY, cbTex.sample(s, cuv).r, crTex.sample(s, cuv).r);
+    float3 rgb = saturate(float3(dot(csc.r0.xyz, yuv) + csc.r0.w,
+                                 dot(csc.r1.xyz, yuv) + csc.r1.w,
+                                 dot(csc.r2.xyz, yuv) + csc.r2.w));
+    return float4(rgb, 1.0);
+}
+
 // HDR: 10-bit P010 / 4:4:4 (BT.2020, PQ-encoded Y′CbCr) → full-range PQ R′G′B′, output as-is —
 // the CAMetalLayer's itur_2100_PQ colour space + edrMetadata tell the compositor the samples are
 // PQ, so it does the PQ→display tone-map. No EOTF here. The rows fold in the exact 10-bit
@@ -215,8 +237,16 @@ public final class MetalVideoPresenter {
     /// tvOS only: the in-shader PQ→SDR tone-map fallback (pf_frag_hdr_tv → bgra8), used whenever
     /// the display is composited without HDR headroom — see `setDisplayHeadroom`. nil elsewhere.
     private let pipelineHDRToneMap: MTLRenderPipelineState?
+    /// PyroWave's 3-plane SDR path (pf_frag_planar → bgra8) — see `renderPlanar`.
+    private let pipelinePlanar: MTLRenderPipelineState
     private var textureCache: CVMetalTextureCache?
 
+    /// The PyroWave Metal decoder records on the presenter's device + queue: one device means
+    /// decode, CSC and present share textures with zero interop, and one queue means Metal's
+    /// hazard tracking orders a ring-slot rewrite after the render still sampling it.
+    var metalDevice: MTLDevice { device }
+    var metalQueue: MTLCommandQueue { queue }
+
     /// Current layer configuration — switched in `configure(hdr:)` when a frame's HDR-ness differs.
     /// Render-thread confined once the pipeline runs (Stage2Pipeline.start's one pre-thread
     /// `configure` call is ordered before the thread starts, so it doesn't race).
@@ -258,6 +288,7 @@ public final class MetalVideoPresenter {
         let pipelineSDR: MTLRenderPipelineState
         let pipelineHDR: MTLRenderPipelineState
         let pipelineHDRToneMap: MTLRenderPipelineState?
+        let pipelinePlanar: MTLRenderPipelineState
         do {
             // DEBUG A/B lever: PUNKTFUNK_BILINEAR_LUMA=1 compiles the shader with Catmull-Rom OFF
             // (plain bilinear luma) by prepending a #define ahead of the source. Default (unset) is
@@ -292,6 +323,11 @@ public final class MetalVideoPresenter {
             #else
             pipelineHDRToneMap = nil
             #endif
+            let planar = MTLRenderPipelineDescriptor()
+            planar.vertexFunction = vtx
+            planar.fragmentFunction = library.makeFunction(name: "pf_frag_planar")
+            planar.colorAttachments[0].pixelFormat = .bgra8Unorm // PyroWave is 8-bit SDR
+            pipelinePlanar = try device.makeRenderPipelineState(descriptor: planar)
         } catch {
             return nil
         }
@@ -331,12 +367,14 @@ public final class MetalVideoPresenter {
 
         return MetalVideoPresenter(
             device: device, queue: queue, pipelineSDR: pipelineSDR, pipelineHDR: pipelineHDR,
-            pipelineHDRToneMap: pipelineHDRToneMap, textureCache: textureCache, layer: layer)
+            pipelineHDRToneMap: pipelineHDRToneMap, pipelinePlanar: pipelinePlanar,
+            textureCache: textureCache, layer: layer)
     }
 
     private init(
         device: MTLDevice, queue: MTLCommandQueue, pipelineSDR: MTLRenderPipelineState,
         pipelineHDR: MTLRenderPipelineState, pipelineHDRToneMap: MTLRenderPipelineState?,
+        pipelinePlanar: MTLRenderPipelineState,
         textureCache: CVMetalTextureCache, layer: CAMetalLayer
     ) {
         self.device = device
@@ -344,6 +382,7 @@ public final class MetalVideoPresenter {
         self.pipelineSDR = pipelineSDR
         self.pipelineHDR = pipelineHDR
         self.pipelineHDRToneMap = pipelineHDRToneMap
+        self.pipelinePlanar = pipelinePlanar
         self.textureCache = textureCache
         self.layer = layer
     }
@@ -514,6 +553,67 @@ public final class MetalVideoPresenter {
                 pixelBuffer, plane: 1, format: tenBit ? .rg16Unorm : .rg8Unorm, cache: textureCache)
         else { return false }
 
+        #if os(tvOS)
+        // HDR splits by the display's headroom (kept in step with the layer by `configure` above):
+        // PQ passthrough into an HDR-composited display, the tone-map shader otherwise.
+        let hdrPipeline = hdrPassthroughActive ? pipelineHDR : (pipelineHDRToneMap ?? pipelineHDR)
+        let pipeline = hdrActive ? hdrPipeline : pipelineSDR
+        #else
+        let pipeline = hdrActive ? pipelineHDR : pipelineSDR
+        #endif
+        let decodedSize = CGSize(
+            width: CVPixelBufferGetWidth(pixelBuffer), height: CVPixelBufferGetHeight(pixelBuffer))
+        return encodePresent(
+            decodedSize: decodedSize, targetFromLayout: targetFromLayout, pipeline: pipeline,
+            presentAtMediaTime: presentAtMediaTime, onPresented: onPresented,
+            // Hold the CVMetalTextures + source pixel buffer (its IOSurface) alive until the GPU
+            // finishes sampling — releasing them at scope exit could free the backing mid-read.
+            keepAlive: [luma, chroma, pixelBuffer]
+        ) { encoder in
+            encoder.setFragmentTexture(CVMetalTextureGetTexture(luma), index: 0)
+            encoder.setFragmentTexture(CVMetalTextureGetTexture(chroma), index: 1)
+            encoder.setFragmentBytes(&csc, length: MemoryLayout<CscUniform>.stride, index: 0)
+        }
+    }
+
+    /// Draw one PyroWave planar frame (three R8 planes off the Metal wavelet decoder) and
+    /// present it. RENDER THREAD, same contract as `render` — PyroWave is 8-bit SDR, so the
+    /// layer always takes the plain SDR config, and the CSC rows arrive precomputed from the
+    /// stream's own sequence-header signaling (no CVPixelBuffer to inspect).
+    @discardableResult
+    func renderPlanar(
+        _ planes: WaveletPlanes,
+        presentAtMediaTime: CFTimeInterval? = nil,
+        onPresented: ((Int64?) -> Void)? = nil
+    ) -> Bool {
+        stagingLock.lock()
+        let targetFromLayout = drawableTarget
+        stagingLock.unlock()
+        configure(hdr: false)
+        var csc = planes.csc
+        return encodePresent(
+            decodedSize: CGSize(width: planes.width, height: planes.height),
+            targetFromLayout: targetFromLayout, pipeline: pipelinePlanar,
+            presentAtMediaTime: presentAtMediaTime, onPresented: onPresented,
+            // The ring textures stay valid by ring depth; retaining them here also pins the
+            // slot's set until the sample completes (mirrors the biplanar keep-alive).
+            keepAlive: [planes.y, planes.cb, planes.cr]
+        ) { encoder in
+            encoder.setFragmentTexture(planes.y, index: 0)
+            encoder.setFragmentTexture(planes.cb, index: 1)
+            encoder.setFragmentTexture(planes.cr, index: 2)
+            encoder.setFragmentBytes(&csc, length: MemoryLayout<CscUniform>.stride, index: 0)
+        }
+    }
+
+    /// The shared present tail of `render`/`renderPlanar`: size the drawable, encode one
+    /// fullscreen triangle with `pipeline` (`bind` supplies the fragment resources), schedule
+    /// the present and the on-glass callback.
+    private func encodePresent(
+        decodedSize: CGSize, targetFromLayout: CGSize, pipeline: MTLRenderPipelineState,
+        presentAtMediaTime: CFTimeInterval?, onPresented: ((Int64?) -> Void)?,
+        keepAlive: [Any], bind: (MTLRenderCommandEncoder) -> Void
+    ) -> Bool {
         // Size the drawable to the LAYER's pixels (its laid-out frame × contentsScale, pushed here by
         // SessionPresenter.layout via `setDrawableTarget` — not read off the layer, whose geometry the
         // main thread owns) so the Catmull-Rom shader performs the decoded→on-screen scale in one pass:
@@ -522,8 +622,6 @@ public final class MetalVideoPresenter {
         // Before the first layout (zero target) fall back to the decoded size. drawableSize does NOT
         // track bounds (defaults to 0), so set it BEFORE nextDrawable; re-set only on a change
         // (layout / Reconfigure / HDR flip — and every frame of a live resize, which is fine).
-        let decodedSize = CGSize(
-            width: CVPixelBufferGetWidth(pixelBuffer), height: CVPixelBufferGetHeight(pixelBuffer))
         let targetSize = (targetFromLayout.width > 0 && targetFromLayout.height > 0)
             ? targetFromLayout : decodedSize
         if layer.drawableSize != targetSize { layer.drawableSize = targetSize }
@@ -542,17 +640,8 @@ public final class MetalVideoPresenter {
         guard let encoder = commandBuffer.makeRenderCommandEncoder(descriptor: pass) else {
             return false
         }
-        #if os(tvOS)
-        // HDR splits by the display's headroom (kept in step with the layer by `configure` above):
-        // PQ passthrough into an HDR-composited display, the tone-map shader otherwise.
-        let hdrPipeline = hdrPassthroughActive ? pipelineHDR : (pipelineHDRToneMap ?? pipelineHDR)
-        encoder.setRenderPipelineState(hdrActive ? hdrPipeline : pipelineSDR)
-        #else
-        encoder.setRenderPipelineState(hdrActive ? pipelineHDR : pipelineSDR)
-        #endif
-        encoder.setFragmentTexture(CVMetalTextureGetTexture(luma), index: 0)
-        encoder.setFragmentTexture(CVMetalTextureGetTexture(chroma), index: 1)
-        encoder.setFragmentBytes(&csc, length: MemoryLayout<CscUniform>.stride, index: 0)
+        encoder.setRenderPipelineState(pipeline)
+        bind(encoder)
         encoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
         encoder.endEncoding()
         if let onPresented {
@@ -580,9 +669,8 @@ public final class MetalVideoPresenter {
         } else {
             commandBuffer.present(drawable)
         }
-        // Hold the CVMetalTextures + source pixel buffer (its IOSurface) alive until the GPU finishes
-        // sampling — releasing them at scope exit could free the backing mid-read.
-        commandBuffer.addCompletedHandler { _ in _ = (luma, chroma, pixelBuffer) }
+        // Keep the bound sources alive until the GPU finishes sampling (see the callers).
+        commandBuffer.addCompletedHandler { _ in _ = keepAlive }
         commandBuffer.commit()
         return true
     }

clients/apple/Sources/PunktfunkKit/Video/MetalWaveletDecoder.swift

@@ -183,18 +183,12 @@ enum WaveletBitstream {
             }
             return state.pushPackets(UnsafeBufferPointer(start: base, count: count))
         }
-        guard ok, var frame = state.finish() else { return nil }
+        guard ok, let frame = state.finish() else { return nil }
         // Upstream decode_is_ready(allow_partial=true): with no SOF the frame is undecodable;
         // at half the blocks or fewer it is presumed garbage.
         guard frame.totalBlocks > 0, frame.decodedBlocks > frame.totalBlocks / 2 else {
             return nil
         }
-        // The dequant kernel indexes the offset table by the LAYOUT's block space; the wire's
-        // total_blocks only counts blocks the encoder emitted. They agree for a full-coverage
-        // frame, but size the table by the layout.
-        if frame.offsets.count != frame.layout.blockCount32 {
-            frame.offsets = Array(frame.offsets.prefix(frame.layout.blockCount32))
-        }
         return frame
     }
 
@@ -293,17 +287,17 @@ enum WaveletBitstream {
 
 /// One decoded frame's output planes, handed to the presenter's planar render path. The
 /// textures belong to the decoder's ring — ring depth (4) plus same-queue hazard tracking keep
-/// them valid while referenced.
-struct WaveletPlanes {
-    let y: MTLTexture
-    let cb: MTLTexture
-    let cr: MTLTexture
-    let csc: CscUniform
-    var width: Int { y.width }
-    var height: Int { y.height }
+/// them valid while referenced. Public because it rides inside `ReadyImage`.
+public struct WaveletPlanes: @unchecked Sendable {
+    public let y: MTLTexture
+    public let cb: MTLTexture
+    public let cr: MTLTexture
+    public let csc: CscUniform
+    public var width: Int { y.width }
+    public var height: Int { y.height }
 }
 
-final class MetalWaveletDecoder {
+public final class MetalWaveletDecoder {
     /// Matches the Vulkan client's ring: deep enough that a slot is never rewritten while the
     /// presenter still samples it in practice; same-queue hazard tracking is the hard backstop.
     private static let ringDepth = 4
@@ -312,7 +306,7 @@ final class MetalWaveletDecoder {
     /// dequant kernel needs simdgroup prefix sums with its 16 header lanes inside one
     /// simdgroup, so compile the real kernels once and check the pipeline facts. Apple6 (A13)
     /// and every Mac2 device pass the family check; the compile probe is authoritative.
-    static let supported: Bool = {
+    public static let supported: Bool = {
         guard let device = MTLCreateSystemDefaultDevice() else { return false }
         guard device.supportsFamily(.apple6) || device.supportsFamily(.mac2) else { return false }
         do {
@@ -358,6 +352,12 @@ final class MetalWaveletDecoder {
     private var slots: [Slot] = []
     private var nextSlot = 0
 
+    /// The current geometry (from the last SOF that built the resources) — the pump reports
+    /// decoded-size changes to the resize overlay from this. PUMP THREAD.
+    var decodedSize: (width: Int, height: Int)? {
+        layout.map { ($0.width, $0.height) }
+    }
+
     /// The pump thread owns `decode`; everything mutable is confined to it.
     init?(device: MTLDevice, queue: MTLCommandQueue) {
         self.device = device

clients/apple/Sources/PunktfunkKit/Video/Stage2Pipeline.swift

@@ -37,6 +37,7 @@
 #if canImport(Metal) && canImport(QuartzCore)
 import AVFoundation
 import Foundation
+import Metal
 import QuartzCore
 
 /// PUNKTFUNK_PRESENT_DEBUG=1: the render thread prints a once-per-second line with the decode
@@ -257,6 +258,7 @@ public final class Stage2Pipeline {
     /// the pipeline's lifetime; SessionPresenter resolves it per session (see PresentPacing).
     private let pacing: PresentPacing
     private let endToEndMeter: LatencyMeter?
+    private let decodeMeter: LatencyMeter?
     private let displayMeter: LatencyMeter?
     private let recovery = KeyframeRecovery()
     /// Post-loss freeze-until-reanchor gate (shared core policy via the C ABI). Created here seeded 0;
@@ -306,6 +308,7 @@ public final class Stage2Pipeline {
         self.presenter = presenter
         self.pacing = pacing
         self.endToEndMeter = endToEndMeter
+        self.decodeMeter = decodeMeter
         self.displayMeter = displayMeter
         let ring = ring
         let recovery = recovery
@@ -362,7 +365,21 @@ public final class Stage2Pipeline {
         let presenter = presenter
         let pumpStopped = pumpStopped
         let reanchorGate = gate
-        let thread = Thread {
+        // PyroWave rides a different decode half: no CMFormatDescription/VideoToolbox machinery
+        // (a wavelet AU has no parameter sets), no keyframe recovery or re-anchor freeze (the
+        // stream is all-intra and Phase 4's partial delivery WANTS lossy frames on glass as
+        // localized blur, not a freeze). The ready ring, render thread, pacing and meters are
+        // shared unchanged.
+        let thread: Thread
+        if connection.videoCodec == .pyrowave {
+            thread = Self.makePyroWavePump(
+                connection: connection, token: token, pumpStopped: pumpStopped,
+                ring: ring, renderSignal: renderSignal,
+                device: presenter.metalDevice, queue: presenter.metalQueue,
+                decodeMeter: decodeMeter,
+                onFrame: onFrame, onSessionEnd: onSessionEnd, onDecodedSize: onDecodedSize)
+        } else {
+            thread = Thread {
             defer { pumpStopped.signal() } // let stop() join the pump (bounded) before decoder.reset()
             var format: CMVideoFormatDescription?
             // Report coded dims to the resize overlay only on a CHANGE (new-mode IDR), not per
@@ -445,6 +462,7 @@ public final class Stage2Pipeline {
                 }
                 }
             }
+            }
         }
         thread.name = "punktfunk-stage2-pump"
         thread.qualityOfService = .userInteractive
@@ -504,9 +522,7 @@ public final class Stage2Pipeline {
                 let presentAt = vsyncEnabled
                     ? vsyncClock.nextVsync(after: CACurrentMediaTime()) : nil
                 let renderStarted = CACurrentMediaTime()
-                let rendered = presenter.render(
-                    frame.pixelBuffer, isHDR: frame.isHDR, presentAtMediaTime: presentAt
-                ) { presentedNs in
+                let onGlass: (Int64?) -> Void = { presentedNs in
                     // Stage-3: the flip reached glass (or was dropped) — free the present slot,
                     // then re-signal so the freshest waiting ring frame goes out immediately.
                     if let gate {
@@ -525,6 +541,18 @@ public final class Stage2Pipeline {
                     displayMeter?.record(ptsNs: UInt64(frame.decodedNs), atNs: atNs, offsetNs: 0)
                     debugStats?.presented(atNs: presentedNs)
                 }
+                // One present tail, two decode sources: the VideoToolbox biplanar buffer or the
+                // PyroWave Metal planes — the ring, pacing and meters are agnostic to which.
+                let rendered: Bool
+                switch frame.image {
+                case .video(let pixelBuffer, let isHDR):
+                    rendered = presenter.render(
+                        pixelBuffer, isHDR: isHDR, presentAtMediaTime: presentAt,
+                        onPresented: onGlass)
+                case .planar(let planes):
+                    rendered = presenter.renderPlanar(
+                        planes, presentAtMediaTime: presentAt, onPresented: onGlass)
+                }
                 debugStats?.renderReturned(
                     ok: rendered, tookMs: (CACurrentMediaTime() - renderStarted) * 1000)
                 if !rendered {
@@ -592,6 +620,93 @@ public final class Stage2Pipeline {
         renderSignal.signal() // wake the render thread so it can observe the stop and exit
     }
 
+    /// The PyroWave pump: AUs go straight into the Metal wavelet decoder (no VideoToolbox, no
+    /// format descriptions), decoded planes ride the same ready ring / render thread. All-intra
+    /// stream, so none of the VT pump's recovery machinery applies: keyframe/RFI requests are
+    /// silenced host-side for this codec, and a lossy (partial-delivery) frame is MEANT to
+    /// present as localized blur — never a freeze. Static + capture-by-parameter for the same
+    /// reason the VT pump avoids capturing `self` (a missed stop must not leak a live pipeline).
+    private static func makePyroWavePump(
+        connection: PunktfunkConnection, token: StopFlag, pumpStopped: DispatchSemaphore,
+        ring: ReadyRing, renderSignal: DispatchSemaphore,
+        device: MTLDevice, queue: MTLCommandQueue,
+        decodeMeter: LatencyMeter?,
+        onFrame: (@Sendable (AccessUnit) -> Void)?,
+        onSessionEnd: (@Sendable () -> Void)?,
+        onDecodedSize: (@Sendable (Int, Int) -> Void)?
+    ) -> Thread {
+        // The chunk-aligned parse window = the session's negotiated shard payload (Welcome);
+        // the 64-byte floor mirrors the Rust client's guard against a nonsense value.
+        let windowSize = max(64, Int(connection.shardPayload))
+        return Thread {
+            defer { pumpStopped.signal() }
+            // Compiles the two compute kernels on the session's first frames' thread — ~tens of
+            // ms, once per session. Failure = this device can't run the negotiated codec (the
+            // advertisement probe should have prevented this); end the session cleanly.
+            guard let decoder = MetalWaveletDecoder(device: device, queue: queue) else {
+                if !token.isStopped { onSessionEnd?() }
+                return
+            }
+            // Newest decoded frame index — a late partial (the reassembler's 30 ms fuse can
+            // deliver one behind a newer complete frame) must not travel back in time.
+            var newestIndex: UInt32?
+            var lastDims: (w: Int, h: Int)?
+            var alive = true
+            while alive, !token.isStopped {
+                alive = autoreleasepool { () -> Bool in
+                    do {
+                        guard let au = try connection.nextAU(timeoutMs: 100) else { return true }
+                        onFrame?(au)
+                        if let newest = newestIndex,
+                           Int32(bitPattern: au.frameIndex &- newest) <= 0 {
+                            return true // stale (or duplicate) frame — skip
+                        }
+                        guard !token.isStopped else { return true }
+                        let chunkAligned =
+                            au.flags & PunktfunkConnection.userFlagChunkAligned != 0
+                        let ptsNs = au.ptsNs
+                        let receivedNs = au.receivedNs
+                        let flags = au.flags
+                        let submitted = decoder.decode(
+                            au: au.data, chunkAligned: chunkAligned, windowSize: windowSize
+                        ) { planes in
+                            // Metal completed-handler thread — stamp + enqueue, don't block
+                            // (the exact contract of the VT output callback).
+                            guard let planes else { return }
+                            var ts = timespec()
+                            clock_gettime(CLOCK_REALTIME, &ts)
+                            let decodedNs =
+                                Int64(ts.tv_sec) * 1_000_000_000 + Int64(ts.tv_nsec)
+                            decodeMeter?.record(
+                                ptsNs: UInt64(receivedNs), atNs: decodedNs, offsetNs: 0)
+                            ring.submit(
+                                ReadyFrame(
+                                    ptsNs: ptsNs, receivedNs: receivedNs, decodedNs: decodedNs,
+                                    image: .planar(planes), flags: flags))
+                            renderSignal.signal()
+                        }
+                        if submitted {
+                            newestIndex = au.frameIndex
+                            // Decoded-size changes come from the SOF dims (this is also how a
+                            // mid-stream Reconfigure lands here) — report like the VT pump.
+                            if let size = decoder.decodedSize,
+                               lastDims?.w != size.width || lastDims?.h != size.height {
+                                lastDims = (size.width, size.height)
+                                onDecodedSize?(size.width, size.height)
+                            }
+                        }
+                        // A dropped AU (malformed / SOF lost / too few blocks) is just skipped:
+                        // every PyroWave frame is independently decodable, the next one heals.
+                        return true
+                    } catch {
+                        if !token.isStopped { onSessionEnd?() }
+                        return false // session closed
+                    }
+                }
+            }
+        }
+    }
+
     /// Convert a `CADisplayLink.targetTimestamp` (CACurrentMediaTime basis) to a `CLOCK_REALTIME`
     /// nanosecond instant — the present clock the AU pts + skew offset live in. Projects to the target
     /// present time (when the frame is actually on glass), not the moment we drew.

clients/apple/Sources/PunktfunkKit/Video/VideoDecoder.swift

@@ -12,7 +12,23 @@ import CoreVideo
 import Foundation
 import VideoToolbox
 
-/// One decoded frame waiting to be presented. Owns a retained `CVPixelBuffer` until shown.
+/// A decoded frame's pixels — which present path they take. VideoToolbox codecs deliver a
+/// biplanar `CVPixelBuffer` (NV12/P010/444v/x444); the PyroWave Metal decoder delivers three
+/// separate R8 plane textures straight off its compute pass (there is no CVPixelBuffer — the
+/// planes never leave the GPU).
+public enum ReadyImage: @unchecked Sendable {
+    /// 8-bit NV12 / 4:4:4 biplanar (SDR) or 10-bit P010 / x444 (HDR), Metal-compatible.
+    /// `isHDR` = the stream is BT.2020 PQ and the presenter must configure EDR output.
+    case video(CVPixelBuffer, isHDR: Bool)
+    #if canImport(Metal)
+    /// PyroWave planar output (Y full-res + Cb/Cr half-res, 8-bit SDR) with its precomputed
+    /// CSC rows — presented by `MetalVideoPresenter.renderPlanar`.
+    case planar(WaveletPlanes)
+    #endif
+}
+
+/// One decoded frame waiting to be presented. Owns its image (a retained `CVPixelBuffer`, or
+/// the PyroWave ring textures) until shown.
 public struct ReadyFrame: @unchecked Sendable {
     /// Host capture clock (the AU's pts), in nanoseconds.
     public let ptsNs: UInt64
@@ -22,15 +38,26 @@ public struct ReadyFrame: @unchecked Sendable {
     public let receivedNs: Int64
     /// Client `CLOCK_REALTIME` instant decode completed, in nanoseconds.
     public let decodedNs: Int64
-    /// The decoded image — 8-bit NV12 biplanar (SDR) or 10-bit P010 biplanar (HDR), Metal-compatible.
-    public let pixelBuffer: CVPixelBuffer
-    /// True when the stream is HDR (BT.2020 PQ): the buffer is 10-bit P010 and the presenter must
-    /// configure EDR + BT.2020 PQ output. Derived from the decoded buffer's pixel format.
-    public let isHDR: Bool
+    /// The decoded image and which present path it takes.
+    public let image: ReadyImage
     /// The AU's wire `user_flags` (`AccessUnit.flags`), threaded through the decode via the frame
     /// context so the re-anchor gate can classify this decoded frame (IDR / RFI anchor / recovery
     /// mark) at present time — the async decode callback has no other access to it. 0 when unknown.
     public let flags: UInt32
+
+    /// The VideoToolbox path's buffer; nil for a PyroWave planar frame. (Kept as the accessor
+    /// the decode round-trip tests assert against.)
+    public var pixelBuffer: CVPixelBuffer? {
+        if case .video(let buffer, _) = image { return buffer }
+        return nil
+    }
+
+    /// Whether this frame presents on the HDR path. PyroWave planar frames are 8-bit SDR by
+    /// contract.
+    public var isHDR: Bool {
+        if case .video(_, let hdr) = image { return hdr }
+        return false
+    }
 }
 
 /// Per-frame context threaded through the VideoToolbox frame refcon: the AU's receipt instant (for
@@ -286,6 +313,6 @@ public final class VideoDecoder: @unchecked Sendable {
         onDecoded(
             ReadyFrame(
                 ptsNs: ptsNs, receivedNs: receivedNs, decodedNs: decodedNs,
-                pixelBuffer: imageBuffer, isHDR: isHDR, flags: flags))
+                image: .video(imageBuffer, isHDR: isHDR), flags: flags))
     }
 }

clients/apple/Tests/PunktfunkKitTests/AV1Tests.swift

@@ -237,10 +237,11 @@ final class AV1Tests: XCTestCase {
         let ready = try XCTUnwrap(frame)
         XCTAssertEqual(ready.ptsNs, 42_000_000)
         XCTAssertFalse(ready.isHDR)
-        XCTAssertEqual(CVPixelBufferGetWidth(ready.pixelBuffer), 320)
-        XCTAssertEqual(CVPixelBufferGetHeight(ready.pixelBuffer), 180)
+        let buffer = try XCTUnwrap(ready.pixelBuffer, "a VT decode delivers a .video frame")
+        XCTAssertEqual(CVPixelBufferGetWidth(buffer), 320)
+        XCTAssertEqual(CVPixelBufferGetHeight(buffer), 180)
         XCTAssertEqual(
-            CVPixelBufferGetPixelFormatType(ready.pixelBuffer),
+            CVPixelBufferGetPixelFormatType(buffer),
             kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange, "SDR AV1 must decode to NV12")
         decoder.reset()
     }

clients/apple/Tests/PunktfunkKitTests/PyroWaveDecoderTests.swift

@@ -0,0 +1,292 @@
+// PyroWave Metal decoder tests — two layers:
+//
+// 1. Bitstream/window-walk parser tests (pure CPU): hand-crafted packet streams assert the
+//    exact wire semantics of pyrowave_decoder.cpp's push_packet walk + the Phase-4
+//    chunk-aligned framing (4-byte window prefix, FRAG chains, zeroed missing shards).
+//
+// 2. Golden-frame PSNR tests (Metal GPU): host-encoded fixtures (crates/punktfunk-host
+//    encode/linux/pyrowave.rs `pyrowave_dump_golden`, run on a Vulkan box) decoded by the
+//    Metal port and PSNR-matched against upstream's own decoder output. Float wavelet math is
+//    not bit-exact across implementations (upstream ships precision variants), so the gate is
+//    PSNR, not equality. This is the §4.7 validation oracle for the hand-ported kernels —
+//    the gather/mirror addressing in idwt is the spot most likely to drift.
+
+#if canImport(Metal)
+import Metal
+import XCTest
+
+@testable import PunktfunkKit
+
+final class PyroWaveParserTests: XCTestCase {
+    // 256x144 → aligned 256x160; block space identical to the committed fixtures.
+    private let width = 256
+    private let height = 144
+
+    /// A BitstreamSequenceHeader (START_OF_FRAME) for `width`x`height`, 4:2:0 BT.709 limited.
+    private func sof(totalBlocks: Int, sequence: UInt32 = 1) -> [UInt8] {
+        let word0 =
+            UInt32(width - 1) | (UInt32(height - 1) << 14) | (sequence << 28) | (1 << 31)
+        // code=0 (SOF), chroma=0 (420), primaries/trc/matrix=0 (BT.709), range=1 (LIMITED),
+        // siting=0.
+        let word1 = UInt32(totalBlocks) | (1 << 30)
+        return le32(word0) + le32(word1)
+    }
+
+    /// A minimal coefficient packet: ballot=0 (all 8x8 blocks empty — legal and decodable),
+    /// payload_words=2 (header only).
+    private func packet(blockIndex: Int, sequence: UInt32 = 1) -> [UInt8] {
+        let word0 = UInt32(0) | (2 << 16) | (sequence << 28)
+        let word1 = UInt32(0) | (UInt32(blockIndex) << 8)
+        return le32(word0) + le32(word1)
+    }
+
+    private func le32(_ v: UInt32) -> [UInt8] {
+        [UInt8(v & 0xff), UInt8((v >> 8) & 0xff), UInt8((v >> 16) & 0xff), UInt8(v >> 24)]
+    }
+
+    /// Wrap bodies into `windowSize`-sized windows with the 4-byte used/kind prefix.
+    private func window(_ body: [UInt8], kind: UInt16, size: Int) -> [UInt8] {
+        precondition(body.count + 4 <= size)
+        var out = [UInt8(body.count & 0xff), UInt8(body.count >> 8)]
+        out += [UInt8(kind & 0xff), UInt8(kind >> 8)]
+        out += body
+        out += [UInt8](repeating: 0, count: size - out.count)
+        return out
+    }
+
+    func testLayoutMatchesUpstreamBlockSpace() {
+        // init_block_meta's walk for 256x144 (aligned 256x160): level extents halve from
+        // 128x80; per (comp,level,band) count32 = ceil(ceil(w/8)/4) * ceil(ceil(h/8)/4).
+        let layout = WaveletLayout(width: width, height: height)
+        XCTAssertEqual(layout.alignedWidth, 256)
+        XCTAssertEqual(layout.alignedHeight, 160)
+        XCTAssertEqual(layout.levelWidth(0), 128)
+        XCTAssertEqual(layout.levelHeight(0), 80)
+        XCTAssertEqual(layout.levelWidth(4), 8)
+        XCTAssertEqual(layout.levelHeight(4), 5)
+        // Hand-summed: L4 (8x5 → 1 block) × 3 comps × 4 bands = 12; L3 (16x10 → 1) × 9 = 9;
+        // L2 (32x20 → 1) × 9 = 9; L1 (64x40 → 2x2=4... ) — trust the invariant instead:
+        // every band's count is ceil(w8/4)*ceil(h8/4) and the total is their sum.
+        var expected = 0
+        for level in stride(from: 4, through: 0, by: -1) {
+            let w8 = (layout.levelWidth(level) + 7) / 8
+            let h8 = (layout.levelHeight(level) + 7) / 8
+            let per = ((w8 + 3) / 4) * ((h8 + 3) / 4)
+            for component in 0..<3 {
+                if level == 0 && component != 0 { continue }
+                expected += per * (level == 4 ? 4 : 3)
+            }
+        }
+        XCTAssertEqual(layout.blockCount32, expected)
+        // The finest luma level's stride is its 32-block row width.
+        XCTAssertEqual(layout.blockMeta[0][0][1].stride, (128 + 31) / 32)
+        // Level-0 chroma is not coded in 4:2:0.
+        XCTAssertEqual(layout.blockMeta[1][0][1].offset, -1)
+    }
+
+    func testDenseParseFillsOffsetsAndCountsBlocks() throws {
+        let layout = WaveletLayout(width: width, height: height)
+        var au = sof(totalBlocks: 4)
+        au += packet(blockIndex: 0)
+        au += packet(blockIndex: 3)
+        au += packet(blockIndex: 3) // duplicate — first wins, not double-counted
+        au += packet(blockIndex: layout.blockCount32 - 1)
+        let frame = try XCTUnwrap(
+            WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+        XCTAssertEqual(frame.layout.width, width)
+        XCTAssertEqual(frame.totalBlocks, 4)
+        XCTAssertEqual(frame.decodedBlocks, 3)
+        XCTAssertEqual(frame.offsets[0], 0)
+        XCTAssertEqual(frame.offsets[3], 2) // u32 words: each header-only packet is 2 words
+        XCTAssertEqual(frame.offsets[1], UInt32.max)
+        XCTAssertEqual(frame.payload.count, 6)
+        XCTAssertFalse(frame.bt2020)
+        XCTAssertFalse(frame.fullRange) // range bit 1 = LIMITED
+    }
+
+    func testHalfOrFewerBlocksIsDropped() {
+        var au = sof(totalBlocks: 4)
+        au += packet(blockIndex: 0)
+        au += packet(blockIndex: 1)
+        // 2 of 4 decoded = exactly half — upstream requires MORE than half.
+        XCTAssertNil(WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+    }
+
+    func testMissingSOFIsDropped() {
+        let au = packet(blockIndex: 0) + packet(blockIndex: 1)
+        XCTAssertNil(WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+    }
+
+    func testTruncatedPacketIsRejected() {
+        var au = sof(totalBlocks: 1)
+        // Claims 4 payload words but only the 8-byte header follows.
+        let word0 = UInt32(0) | (4 << 16) | (1 << 28)
+        au += le32(word0) + le32(0)
+        XCTAssertNil(WaveletBitstream.parse(au: Data(au), chunkAligned: false, windowSize: 0))
+    }
+
+    func testWindowWalkPackedFragAndMissingShard() throws {
+        let size = 64
+        // Window 1: SOF + one packet, PACKED. Window 2: a FRAG chain carrying one packet split
+        // across two windows. Window 3: all zeros (a lost shard of a partial frame). Window 4:
+        // a PACKED packet — the chain break must not eat it.
+        let fragPacket = packet(blockIndex: 2)
+        var au = window(sof(totalBlocks: 3) + packet(blockIndex: 0), kind: 0, size: size)
+        au += window(Array(fragPacket[0..<5]), kind: 1, size: size)
+        au += window(Array(fragPacket[5...]), kind: 3, size: size)
+        au += [UInt8](repeating: 0, count: size) // missing shard
+        au += window(packet(blockIndex: 1), kind: 0, size: size)
+        let frame = try XCTUnwrap(
+            WaveletBitstream.parse(au: Data(au), chunkAligned: true, windowSize: size))
+        XCTAssertEqual(frame.decodedBlocks, 3)
+        XCTAssertEqual(frame.offsets[0], 0)
+        XCTAssertEqual(frame.offsets[2], 2)
+        XCTAssertEqual(frame.offsets[1], 4)
+    }
+
+    func testBrokenFragChainIsDiscarded() throws {
+        let size = 64
+        let fragPacket = packet(blockIndex: 2)
+        var au = window(sof(totalBlocks: 1) + packet(blockIndex: 0), kind: 0, size: size)
+        au += window(Array(fragPacket[0..<5]), kind: 1, size: size)
+        au += [UInt8](repeating: 0, count: size) // the chain's middle shard was lost
+        au += window(Array(fragPacket[5...]), kind: 3, size: size) // dangling LAST — dropped
+        let frame = try XCTUnwrap(
+            WaveletBitstream.parse(au: Data(au), chunkAligned: true, windowSize: size))
+        XCTAssertEqual(frame.decodedBlocks, 1)
+        XCTAssertEqual(frame.offsets[2], UInt32.max)
+    }
+}
+
+/// Golden-frame decode against the committed host-encoder fixtures. Skipped when the machine
+/// has no Metal device (headless CI) — everywhere else this is the hand-ported kernels' guard.
+final class PyroWaveGoldenTests: XCTestCase {
+    private static let fixtureDir = "PyroWaveFixtures"
+
+    private func fixture(_ name: String) throws -> Data {
+        let url = try XCTUnwrap(
+            Bundle.module.url(
+                forResource: name, withExtension: "bin", subdirectory: Self.fixtureDir),
+            "missing fixture \(name).bin — regenerate with pyrowave_dump_golden")
+        return try Data(contentsOf: url)
+    }
+
+    /// Completion box — the decode callback lands on a Metal thread.
+    private final class ResultBox: @unchecked Sendable {
+        let lock = NSLock()
+        var planes: WaveletPlanes?
+    }
+
+    /// Decode `au` synchronously and read all three planes back to CPU bytes.
+    private func decode(
+        au: Data, chunkAligned: Bool, windowSize: Int
+    ) throws -> (y: [UInt8], cb: [UInt8], cr: [UInt8]) {
+        let device = try XCTUnwrap(MTLCreateSystemDefaultDevice())
+        let queue = try XCTUnwrap(device.makeCommandQueue())
+        let decoder = try XCTUnwrap(MetalWaveletDecoder(device: device, queue: queue))
+        let done = expectation(description: "decode completes")
+        let box = ResultBox()
+        let submitted = decoder.decode(
+            au: au, chunkAligned: chunkAligned, windowSize: windowSize
+        ) { planes in
+            box.lock.lock()
+            box.planes = planes
+            box.lock.unlock()
+            done.fulfill()
+        }
+        XCTAssertTrue(submitted, "the fixture AU must parse")
+        wait(for: [done], timeout: 10)
+        box.lock.lock()
+        let result = box.planes
+        box.lock.unlock()
+        let planes = try XCTUnwrap(result, "the GPU pass must complete without error")
+        return (
+            try readback(planes.y, device: device, queue: queue),
+            try readback(planes.cb, device: device, queue: queue),
+            try readback(planes.cr, device: device, queue: queue)
+        )
+    }
+
+    private func readback(
+        _ texture: MTLTexture, device: MTLDevice, queue: MTLCommandQueue
+    ) throws -> [UInt8] {
+        let bytesPerRow = texture.width
+        let length = bytesPerRow * texture.height
+        let buffer = try XCTUnwrap(device.makeBuffer(length: length, options: .storageModeShared))
+        let cmd = try XCTUnwrap(queue.makeCommandBuffer())
+        let blit = try XCTUnwrap(cmd.makeBlitCommandEncoder())
+        blit.copy(
+            from: texture, sourceSlice: 0, sourceLevel: 0,
+            sourceOrigin: MTLOrigin(x: 0, y: 0, z: 0),
+            sourceSize: MTLSize(width: texture.width, height: texture.height, depth: 1),
+            to: buffer, destinationOffset: 0, destinationBytesPerRow: bytesPerRow,
+            destinationBytesPerImage: length)
+        blit.endEncoding()
+        cmd.commit()
+        cmd.waitUntilCompleted()
+        return [UInt8](UnsafeRawBufferPointer(start: buffer.contents(), count: length))
+    }
+
+    private func psnr(_ a: [UInt8], _ b: [UInt8]) -> Double {
+        precondition(a.count == b.count)
+        var sse = 0.0
+        for i in 0..<a.count {
+            let d = Double(a[i]) - Double(b[i])
+            sse += d * d
+        }
+        if sse == 0 { return .infinity }
+        let mse = sse / Double(a.count)
+        return 10 * log10(255.0 * 255.0 / mse)
+    }
+
+    private func assertMatchesReference(
+        _ decoded: (y: [UInt8], cb: [UInt8], cr: [UInt8]), prefix: String,
+        file: StaticString = #filePath, line: UInt = #line
+    ) throws {
+        for (name, plane, ref) in [
+            ("y", decoded.y, try fixture("\(prefix)-y")),
+            ("cb", decoded.cb, try fixture("\(prefix)-cb")),
+            ("cr", decoded.cr, try fixture("\(prefix)-cr")),
+        ] {
+            XCTAssertEqual(plane.count, ref.count, file: file, line: line)
+            let db = psnr(plane, [UInt8](ref))
+            print("pyrowave golden \(prefix) \(name): \(db) dB")
+            // The Metal port and upstream's decoder run the same math at the same precision
+            // tier; residual differences are float rounding + the gather/mirror edge handling.
+            // Well-matched ports measure ≫50 dB; 45 catches a real divergence long before it
+            // is visible.
+            XCTAssertGreaterThan(db, 45.0, "plane PSNR \(db) dB", file: file, line: line)
+        }
+    }
+
+    func testDenseGoldenFrame() throws {
+        try XCTSkipIf(!MetalWaveletDecoder.supported, "no capable Metal device")
+        let au = try fixture("au-dense")
+        let decoded = try decode(au: au, chunkAligned: false, windowSize: 0)
+        try assertMatchesReference(decoded, prefix: "ref-dense")
+    }
+
+    func testChunkAlignedGoldenFrame() throws {
+        try XCTSkipIf(!MetalWaveletDecoder.supported, "no capable Metal device")
+        let au = try fixture("au-chunked")
+        let decoded = try decode(au: au, chunkAligned: true, windowSize: 1408)
+        try assertMatchesReference(decoded, prefix: "ref-chunked")
+    }
+
+    /// Phase-4 partial delivery: zero a mid-AU window (a lost shard) — the frame must still
+    /// decode (blocks > half) and stay recognizably the same picture (holes reconstruct as
+    /// localized blur, not garbage).
+    func testPartialFrameStillDecodes() throws {
+        try XCTSkipIf(!MetalWaveletDecoder.supported, "no capable Metal device")
+        var au = try fixture("au-chunked")
+        let windows = au.count / 1408
+        try XCTSkipIf(windows < 3, "fixture too small to punch a hole in")
+        let hole = (windows / 2) * 1408
+        au.replaceSubrange(hole..<(hole + 1408), with: [UInt8](repeating: 0, count: 1408))
+        let decoded = try decode(au: au, chunkAligned: true, windowSize: 1408)
+        let ref = try fixture("ref-chunked-y")
+        let db = psnr(decoded.y, [UInt8](ref))
+        XCTAssertGreaterThan(db, 25.0, "lossy frame should still resemble the source (\(db) dB)")
+    }
+}
+#endif

clients/apple/Tests/PunktfunkKitTests/Stage444Tests.swift

@@ -47,18 +47,21 @@ final class Stage444Tests: XCTestCase {
         box.lock.lock(); let frame = box.frame; let error = box.error; box.lock.unlock()
         XCTAssertNil(error.map { "decode error \($0)" })
         let ready = try XCTUnwrap(frame, "a 4:4:4 ReadyFrame must be delivered")
-        XCTAssertEqual(CVPixelBufferGetWidth(ready.pixelBuffer), 256)
-        XCTAssertEqual(CVPixelBufferGetHeight(ready.pixelBuffer), 256)
-        let pf = CVPixelBufferGetPixelFormatType(ready.pixelBuffer)
+        guard case .video(let buffer, let isHDR) = ready.image else {
+            return XCTFail("a VideoToolbox decode must deliver a .video frame")
+        }
+        XCTAssertEqual(CVPixelBufferGetWidth(buffer), 256)
+        XCTAssertEqual(CVPixelBufferGetHeight(buffer), 256)
+        let pf = CVPixelBufferGetPixelFormatType(buffer)
         XCTAssertTrue(
             pf == kCVPixelFormatType_444YpCbCr8BiPlanarVideoRange
                 || pf == kCVPixelFormatType_444YpCbCr8BiPlanarFullRange,
             "expected a biplanar 4:4:4 8-bit buffer, got \(fourCCString(pf))")
-        XCTAssertFalse(ready.isHDR, "an 8-bit BT.709 4:4:4 stream is SDR")
+        XCTAssertFalse(isHDR, "an 8-bit BT.709 4:4:4 stream is SDR")
         // The chroma plane (plane 1) must be FULL resolution for 4:4:4 (vs half for 4:2:0) — this is
         // what lets the unchanged shader sample chroma at the luma UV.
-        XCTAssertEqual(CVPixelBufferGetWidthOfPlane(ready.pixelBuffer, 1), 256)
-        XCTAssertEqual(CVPixelBufferGetHeightOfPlane(ready.pixelBuffer, 1), 256)
+        XCTAssertEqual(CVPixelBufferGetWidthOfPlane(buffer, 1), 256)
+        XCTAssertEqual(CVPixelBufferGetHeightOfPlane(buffer, 1), 256)
     }
 
     private func fourCCString(_ t: OSType) -> String {

clients/apple/Tests/PunktfunkKitTests/VideoToolboxRoundTripTests.swift

@@ -99,8 +99,9 @@ final class VideoToolboxRoundTripTests: XCTestCase {
         box.lock.unlock()
         XCTAssertNil(error.map { "decode error \($0)" })
         let ready = try XCTUnwrap(frame, "the async output callback must deliver a ReadyFrame")
-        XCTAssertEqual(CVPixelBufferGetWidth(ready.pixelBuffer), width)
-        XCTAssertEqual(CVPixelBufferGetHeight(ready.pixelBuffer), height)
+        let buffer = try XCTUnwrap(ready.pixelBuffer, "a VT decode delivers a .video frame")
+        XCTAssertEqual(CVPixelBufferGetWidth(buffer), width)
+        XCTAssertEqual(CVPixelBufferGetHeight(buffer), height)
         XCTAssertEqual(ready.ptsNs, 42_000_000, "pts round-trips through the decoder")
         XCTAssertEqual(
             ready.receivedNs, 41_000_000, "receivedNs round-trips through the frame refcon")