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>

docs-site/content/docs/pyrowave.md

@@ -47,9 +47,14 @@ setting.
 1. **Host** (Linux): build/install a host with the `pyrowave` feature. On an NVIDIA host the
    capture path additionally needs `PUNKTFUNK_ENCODER=pyrowave` in `host.env` for the codec to
    be advertised; AMD/Intel hosts advertise it automatically when the feature is present.
-2. **Client** (Linux session client with the `pyrowave` feature): set **Settings → Video
-   codec → PyroWave (wired LAN)** in the gamepad console, or launch with
-   `PUNKTFUNK_PREFER_PYROWAVE=1`.
+2. **Client**:
+   - Linux session client (with the `pyrowave` feature): set **Settings → Video codec →
+     PyroWave (wired LAN)** in the gamepad console, or launch with
+     `PUNKTFUNK_PREFER_PYROWAVE=1`.
+   - Apple (Mac, Apple TV 4K, iPad — wired networking strongly recommended): set
+     **Settings → Codec → PyroWave (wired LAN)**. The option appears only on devices whose
+     GPU passes the decode probe (Apple Silicon and A13-class or newer); picking it forces
+     the session SDR.
 3. Leave the bitrate on Automatic: a PyroWave session pins itself to the ~1.6 bpp rate for
    your mode (≈200 Mbps at 1080p60). An explicit bitrate is honored if you set one, but the
    adaptive-bitrate controller stays off either way — this codec has no useful low-rate
@@ -61,6 +66,7 @@ The stats overlay shows `pyrowave` as the decode path when the mode is active.
 
 ## Current limits
 
-- Linux host + Linux client (including docked Deck) today; the Windows host and the Apple
-  native port are tracked on the [roadmap](/docs/roadmap).
+- Linux host + Linux client (including docked Deck) and Apple clients (native Metal decode
+  on Mac / Apple TV 4K / iPad) today; the Windows host is tracked on the
+  [roadmap](/docs/roadmap).
 - 8-bit SDR, 4:2:0 only.