feat(apple): App Store screenshot harness + CI zip artifact

A DEBUG-only "shot mode" renders one mock-populated screen full-bleed
(PUNKTFUNK_SHOT_SCENE=<name> -> ScreenshotHostView instead of ContentView),
so the OS can screenshot the REAL, fully-rendered UI. tools/screenshots.sh
drives it: screencapture for the mac window, `simctl io booted screenshot`
for the iOS/iPad/tvOS Simulators, at exactly the App Store Connect sizes.

ImageRenderer was tried first and rejected: it can't rasterize this app's
chrome (NavigationStack, Form/TabView, Liquid-Glass/NSVisualEffect all render
black or the "can't render" placeholder). Capturing the live window/Simulator
avoids that. Only the stream hero is synthetic (StreamView needs a live
connection) - a synthwave frame + the real glass HUD, overridable via
PUNKTFUNK_SHOT_HERO.

CI: a new `screenshots` job in apple.yml builds the iOS (+ tvOS best-effort)
xcframework slices, runs the harness per platform best-effort, and attaches
the result as a single zip artifact (punktfunk-appstore-screenshots). It is
isolated from the build/test job and skipped on PRs, so a capture gap (missing
Simulator runtime, or no Screen Recording grant for the mac window capture)
never reds the core signal.

Generated PNGs (clients/apple/screenshots/) are gitignored.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

clients/apple/Sources/PunktfunkClient/Screenshots/ScreenshotDevice.swift

@@ -0,0 +1,57 @@
+// App Store screenshot harness — device catalog.
+//
+// The harness captures the REAL running UI (not an offscreen ImageRenderer snapshot, which can't
+// rasterize NavigationStack / Form / Liquid-Glass — they come out black). The app is launched in
+// "shot mode" (PUNKTFUNK_SHOT_SCENE=<name>, see ScreenshotHost) showing one mock-populated scene
+// full-bleed, and the OS screenshots it: `xcrun simctl io booted screenshot` on the iOS/tvOS
+// simulators (native pixels = the exact App Store size), `screencapture` for the mac window.
+// tools/screenshots.sh drives it. DEBUG-only — none of this ships in Release.
+//
+// This catalog records the target App Store sizes; on Apple platforms only the mac size is read
+// at runtime (to size the capture window) — the simulator IS the device, so iOS/tvOS pixels are
+// whatever the booted device is.
+
+#if DEBUG
+import CoreGraphics
+
+enum ShotOrientation { case natural, portrait, landscape }
+
+/// A target App Store canvas: a natural-orientation pixel size + backing scale.
+struct ShotDevice {
+    let id: String
+    let naturalWidth: Int
+    let naturalHeight: Int
+    let scale: CGFloat
+
+    func pixels(_ o: ShotOrientation) -> (w: Int, h: Int) {
+        let long = max(naturalWidth, naturalHeight)
+        let short = min(naturalWidth, naturalHeight)
+        switch o {
+        case .natural: return (naturalWidth, naturalHeight)
+        case .portrait: return (short, long)
+        case .landscape: return (long, short)
+        }
+    }
+
+    /// Logical point size (pixels / scale) — used to size the mac capture window so that a
+    /// `screencapture` on a 2× display yields exactly `pixels(_:)`.
+    func points(_ o: ShotOrientation) -> CGSize {
+        let (w, h) = pixels(o)
+        return CGSize(width: CGFloat(w) / scale, height: CGFloat(h) / scale)
+    }
+
+    /// Mac: 2880×1800 (16:10 Retina) — an accepted size; on a 1× display the window capture is
+    /// 1440×900, also accepted.
+    static let mac = ShotDevice(id: "mac", naturalWidth: 2880, naturalHeight: 1800, scale: 2)
+
+    /// iPhone 6.9" (required) — for reference / the driver script's simulator choice.
+    static let iphone69 = ShotDevice(id: "iphone-6.9", naturalWidth: 1320, naturalHeight: 2868,
+                                     scale: 3)
+    /// iPad 13" (required).
+    static let ipad13 = ShotDevice(id: "ipad-13", naturalWidth: 2064, naturalHeight: 2752,
+                                   scale: 2)
+    /// Apple TV (always landscape).
+    static let appleTV = ShotDevice(id: "appletv", naturalWidth: 1920, naturalHeight: 1080,
+                                    scale: 1)
+}
+#endif

clients/apple/Sources/PunktfunkClient/Screenshots/ScreenshotHost.swift

@@ -0,0 +1,147 @@
+// App Store screenshot harness — the in-app "shot mode" root.
+//
+// Launched with PUNKTFUNK_SHOT_SCENE=<name> (one of ShotScenes.all), the app shows that single
+// mock-populated scene full-bleed instead of ContentView, so the OS can screenshot the REAL,
+// fully-rendered UI (materials, NavigationStack, glass — all the things ImageRenderer can't
+// rasterize offscreen). tools/screenshots.sh drives one launch per scene per device.
+//
+// Capture per platform:
+//   • iOS / tvOS simulator → `xcrun simctl io booted screenshot` (native pixels = exact size).
+//   • macOS → `screencapture -l<windowID>` of the borderless capture window (the configurator
+//     prints `PF_SHOT_WINDOW=<id>`), or the no-permission self-capture fallback
+//     (PUNKTFUNK_SHOT_SELFCAPTURE=<dir> → cacheDisplay; renders the real hierarchy but, like all
+//     non-window-server capture, omits material blur).
+//
+// Every screen prints `PF_SHOT_READY scene=<name>` to stdout once it has settled, so the driver
+// can wait for layout instead of guessing with a fixed sleep.
+
+#if DEBUG
+import SwiftUI
+#if os(macOS)
+import AppKit
+import ImageIO
+#endif
+
+@MainActor
+enum ScreenshotMode {
+    /// The scene requested via PUNKTFUNK_SHOT_SCENE, or nil for a normal launch.
+    static var requestedScene: ShotScene? {
+        let name = ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_SCENE"] ?? ""
+        guard !name.isEmpty else { return nil }
+        return ShotScenes.all.first { $0.name == name }
+    }
+}
+
+/// Full-bleed host for a single scene, with per-platform window sizing / orientation and a
+/// readiness ping for the capture script.
+struct ScreenshotHostView: View {
+    let scene: ShotScene
+
+    var body: some View {
+        scene.make()
+            .environment(\.colorScheme, scene.colorScheme)
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+            .background(Color.black)
+            .ignoresSafeArea()
+            #if os(macOS)
+            .background(MacShotWindowConfigurator(scene: scene))
+            #elseif os(iOS)
+            .background(IOSOrientationConfigurator(orientation: scene.orientation))
+            #endif
+            .task {
+                // Let layout + materials settle, then signal the driver.
+                try? await Task.sleep(nanoseconds: 900_000_000)
+                announceReady()
+            }
+    }
+
+    private func announceReady() {
+        print("PF_SHOT_READY scene=\(scene.name)")
+        fflush(stdout)
+        #if os(macOS)
+        MacSelfCapture.captureIfRequested(scene: scene)
+        #endif
+    }
+}
+
+#if os(macOS)
+/// Sizes the hosting window to the mac canvas, strips the title bar to a clean full-bleed
+/// surface, and prints the CGWindowID for `screencapture -l`.
+private struct MacShotWindowConfigurator: NSViewRepresentable {
+    let scene: ShotScene
+
+    func makeNSView(context: Context) -> NSView { NSView() }
+
+    func updateNSView(_ view: NSView, context: Context) {
+        DispatchQueue.main.async {
+            guard let window = view.window, !context.coordinator.configured else { return }
+            context.coordinator.configured = true
+            // NavigationStack / Form / material chrome follow the WINDOW's appearance, not the
+            // SwiftUI colorScheme — without this the dark scenes render on a light window (white
+            // background, washed-out materials).
+            window.appearance = NSAppearance(named: scene.colorScheme == .dark ? .darkAqua : .aqua)
+            let size = ShotDevice.mac.points(scene.orientation)
+            window.styleMask = [.titled, .fullSizeContentView]
+            window.titlebarAppearsTransparent = true
+            window.titleVisibility = .hidden
+            window.isMovable = false
+            for button in [NSWindow.ButtonType.closeButton, .miniaturizeButton, .zoomButton] {
+                window.standardWindowButton(button)?.isHidden = true
+            }
+            window.setContentSize(size)
+            window.center()
+            window.makeKeyAndOrderFront(nil)
+            NSApp.activate(ignoringOtherApps: true)
+            print("PF_SHOT_WINDOW=\(window.windowNumber) scene=\(scene.name) "
+                + "size=\(Int(size.width))x\(Int(size.height))pt")
+            fflush(stdout)
+        }
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
+    final class Coordinator { var configured = false }
+}
+
+/// No-permission fallback: capture the window's view tree via cacheDisplay. Renders the real
+/// hierarchy (NavigationStack/Form/cards — unlike ImageRenderer) but omits material blur, which
+/// only the window server (screencapture) composites. Used when PUNKTFUNK_SHOT_SELFCAPTURE is set.
+enum MacSelfCapture {
+    static func captureIfRequested(scene: ShotScene) {
+        guard let dir = ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_SELFCAPTURE"],
+              !dir.isEmpty,
+              let window = NSApp.windows.first(where: { $0.isVisible }),
+              let content = window.contentView else { return }
+        let outDir = URL(fileURLWithPath: (dir as NSString).expandingTildeInPath, isDirectory: true)
+        try? FileManager.default.createDirectory(at: outDir, withIntermediateDirectories: true)
+        guard let rep = content.bitmapImageRepForCachingDisplay(in: content.bounds) else { return }
+        content.cacheDisplay(in: content.bounds, to: rep)
+        let url = outDir.appendingPathComponent("\(ShotDevice.mac.id)-\(scene.name).png")
+        if let dest = CGImageDestinationCreateWithURL(
+            url as CFURL, "public.png" as CFString, 1, nil), let cg = rep.cgImage {
+            CGImageDestinationAddImage(dest, cg, nil)
+            CGImageDestinationFinalize(dest)
+            print("PF_SHOT_SAVED \(url.path) \(rep.pixelsWide)x\(rep.pixelsHigh)px")
+        }
+        fflush(stdout)
+        exit(0)
+    }
+}
+#endif
+
+#if os(iOS)
+/// Best-effort orientation lock for the requested scene (landscape for the stream hero, portrait
+/// for chrome). Requires the app to allow those orientations in Info.plist.
+private struct IOSOrientationConfigurator: UIViewControllerRepresentable {
+    let orientation: ShotOrientation
+
+    func makeUIViewController(context: Context) -> UIViewController { UIViewController() }
+
+    func updateUIViewController(_ vc: UIViewController, context: Context) {
+        guard let scene = vc.view.window?.windowScene else { return }
+        let mask: UIInterfaceOrientationMask = orientation == .landscape ? .landscapeRight : .portrait
+        scene.requestGeometryUpdate(.iOS(interfaceOrientations: mask))
+        vc.setNeedsUpdateOfSupportedInterfaceOrientations()
+    }
+}
+#endif
+#endif

clients/apple/Sources/PunktfunkClient/Screenshots/ScreenshotScenes.swift

@@ -0,0 +1,284 @@
+// App Store screenshot scenes — the actual screens we render, each wired with mock data so it
+// looks populated without a live host. Every scene is built from the REAL app views (HomeView,
+// SettingsView, PairSheet, TrustCardView) so the screenshots track the shipping UI; only the
+// live stream is faked (StreamView needs a real punktfunk/1 connection — see ShotStreamHero).
+
+#if DEBUG
+import PunktfunkKit
+import SwiftUI
+
+/// One screen to capture: a name (→ file suffix), the canvas orientation, a color scheme, and a
+/// factory that builds the populated view on the main actor.
+struct ShotScene {
+    let name: String
+    let orientation: ShotOrientation
+    let colorScheme: ColorScheme
+    let make: @MainActor () -> AnyView
+}
+
+@MainActor
+enum ShotScenes {
+    static let all: [ShotScene] = [
+        ShotScene(name: "01-stream", orientation: .landscape, colorScheme: .dark) {
+            AnyView(ShotStreamHero())
+        },
+        ShotScene(name: "02-hosts", orientation: .natural, colorScheme: .dark) {
+            AnyView(ShotHome())
+        },
+        ShotScene(name: "03-pair", orientation: .natural, colorScheme: .dark) {
+            AnyView(ShotPair())
+        },
+        ShotScene(name: "04-trust", orientation: .landscape, colorScheme: .dark) {
+            AnyView(ShotTrust())
+        },
+        ShotScene(name: "05-settings", orientation: .natural, colorScheme: .dark) {
+            AnyView(ShotSettings())
+        },
+    ]
+}
+
+// MARK: - Mock data
+
+@MainActor
+enum ShotMock {
+    /// A populated saved-host grid: a pinned recent host, a couple more, mixed online state.
+    static func hostStore() -> HostStore {
+        let store = HostStore()
+        store.hosts = [
+            StoredHost(name: "Battlestation", address: "192.168.1.20", port: 9777,
+                       pinnedSHA256: fingerprint, lastConnected: Date().addingTimeInterval(-420)),
+            StoredHost(name: "Living Room PC", address: "192.168.1.41", port: 9777,
+                       pinnedSHA256: fingerprint),
+            StoredHost(name: "Workshop", address: "10.0.0.7", port: 9777),
+        ]
+        return store
+    }
+
+    static let host = StoredHost(name: "Battlestation", address: "192.168.1.20", port: 9777,
+                                 pinnedSHA256: fingerprint)
+
+    /// A plausible-looking 32-byte SHA-256 for the trust card / pin lock glyphs.
+    static let fingerprint = Data((0..<32).map { UInt8(($0 &* 37 &+ 0x1d) & 0xff) })
+}
+
+// MARK: - Home
+
+private struct ShotHome: View {
+    @StateObject private var store = ShotMock.hostStore()
+    @StateObject private var model = SessionModel()
+    @StateObject private var discovery = HostDiscovery()
+
+    var body: some View {
+        #if os(macOS)
+        HomeView(
+            store: store, model: model, discovery: discovery,
+            showAddHost: .constant(false), pairingTarget: .constant(nil),
+            speedTestTarget: .constant(nil), libraryTarget: .constant(nil),
+            connect: { _ in }, connectDiscovered: { _ in },
+            onPaired: { _, _ in }, onLaunchTitle: { _, _ in })
+        #else
+        HomeView(
+            store: store, model: model, discovery: discovery,
+            showAddHost: .constant(false), pairingTarget: .constant(nil),
+            speedTestTarget: .constant(nil), libraryTarget: .constant(nil),
+            showSettings: .constant(false),
+            connect: { _ in }, connectDiscovered: { _ in },
+            onPaired: { _, _ in }, onLaunchTitle: { _, _ in })
+        #endif
+    }
+}
+
+// MARK: - Settings
+
+private struct ShotSettings: View {
+    var body: some View {
+        #if os(macOS)
+        // The mac Settings window is a fixed-size tabbed panel — float it over a dimmed host
+        // grid so the shot reads as the preferences window over the running app.
+        ZStack {
+            ShotHome().blur(radius: 24).overlay(Color.black.opacity(0.45))
+            SettingsView()
+                .fixedSize()
+                .clipShape(RoundedRectangle(cornerRadius: 12))
+                .shadow(radius: 40, y: 16)
+        }
+        #elseif os(iOS)
+        NavigationStack {
+            SettingsView()
+                .navigationTitle("Settings")
+                .navigationBarTitleDisplayMode(.inline)
+        }
+        #else
+        NavigationStack { SettingsView() }
+        #endif
+    }
+}
+
+// MARK: - Pair (PIN ceremony)
+
+private struct ShotPair: View {
+    var body: some View {
+        ZStack {
+            ShotHome().blur(radius: 28).overlay(Color.black.opacity(0.5))
+            PairSheet(host: ShotMock.host, onPaired: { _ in })
+                .frame(maxWidth: 460)
+                .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 18))
+                .clipShape(RoundedRectangle(cornerRadius: 18))
+                .shadow(radius: 40, y: 16)
+                .padding(40)
+        }
+    }
+}
+
+// MARK: - Trust (TOFU card over the blurred live stream)
+
+private struct ShotTrust: View {
+    var body: some View {
+        ZStack {
+            ShotDesktopFrame()
+                .blur(radius: 32)
+                .overlay(Color.black.opacity(0.45))
+            TrustCardView(
+                fingerprint: ShotMock.fingerprint, hostName: "Battlestation",
+                onCancel: {}, onTrust: {}, onPairInstead: {})
+        }
+    }
+}
+
+// MARK: - Stream hero
+
+/// The marketing hero: a stand-in streamed frame with the real glass HUD chip on top.
+/// StreamView can't render here (it needs a live punktfunk/1 connection), so the frame is
+/// synthetic — set `PUNKTFUNK_SHOT_HERO=/path/to/frame.png` to drop in a real captured frame.
+private struct ShotStreamHero: View {
+    var body: some View {
+        ZStack(alignment: .topTrailing) {
+            ShotDesktopFrame()
+            ShotHUD()
+        }
+        .background(Color.black)
+    }
+}
+
+/// A faithful copy of StreamHUDView's overlay (which needs a live PunktfunkConnection for the
+/// mode line) with representative numbers, reusing the app's real `.glassBackground`.
+private struct ShotHUD: View {
+    var body: some View {
+        VStack(alignment: .trailing, spacing: 4) {
+            HStack(spacing: 6) {
+                Circle().fill(Color.accentColor).frame(width: 7, height: 7)
+                Text("5120×1440@240  240 fps  812.4 Mb/s")
+                    .font(.system(.caption, design: .monospaced))
+            }
+            Text("capture→client 1.3/2.1 ms p50/p95")
+                .font(.system(.caption2, design: .monospaced))
+                .foregroundStyle(.secondary)
+            #if os(macOS)
+            Text("⌘⎋ releases the mouse")
+                .font(.caption2).foregroundStyle(.secondary)
+            #elseif os(tvOS)
+            Text("Press Menu to disconnect")
+                .font(.caption).foregroundStyle(.secondary)
+            #endif
+        }
+        .padding(10)
+        .glassBackground(RoundedRectangle(cornerRadius: 10))
+        .padding(10)
+    }
+}
+
+/// A synthetic "streamed frame" — a synthwave scene that reads as game content without shipping
+/// any real art. Replaced wholesale when `PUNKTFUNK_SHOT_HERO` points at a real PNG.
+private struct ShotDesktopFrame: View {
+    var body: some View {
+        if let image = Self.overrideImage {
+            image.resizable().scaledToFill()
+        } else {
+            synthetic
+        }
+    }
+
+    private var synthetic: some View {
+        ZStack {
+            LinearGradient(
+                colors: [
+                    Color(red: 0.05, green: 0.02, blue: 0.16),
+                    Color(red: 0.35, green: 0.05, blue: 0.42),
+                    Color(red: 0.95, green: 0.30, blue: 0.35),
+                    Color(red: 0.99, green: 0.62, blue: 0.32),
+                ],
+                startPoint: .top, endPoint: .bottom)
+            Canvas { ctx, size in
+                let horizon = size.height * 0.52
+                // Sun.
+                let sunR = size.height * 0.20
+                let sun = CGRect(x: size.width / 2 - sunR, y: horizon - sunR * 1.6,
+                                 width: sunR * 2, height: sunR * 2)
+                ctx.fill(Path(ellipseIn: sun),
+                         with: .linearGradient(
+                            Gradient(colors: [Color(red: 1, green: 0.95, blue: 0.5),
+                                              Color(red: 1, green: 0.35, blue: 0.45)]),
+                            startPoint: CGPoint(x: sun.midX, y: sun.minY),
+                            endPoint: CGPoint(x: sun.midX, y: sun.maxY)))
+                // Sun scanlines — clip a copy so the base context stays unclipped (GraphicsContext
+                // is a value type; there is no resetClip).
+                var sunCtx = ctx
+                sunCtx.clip(to: Path(ellipseIn: sun))
+                for i in 0..<7 {
+                    let y = sun.minY + sun.height * (0.55 + Double(i) * 0.07)
+                    let bar = CGRect(x: sun.minX, y: y, width: sun.width,
+                                     height: sun.height * (0.012 + Double(i) * 0.006))
+                    sunCtx.fill(Path(bar), with: .color(.black.opacity(0.85)))
+                }
+                // Perspective grid below the horizon.
+                ctx.opacity = 0.55
+                let cx = size.width / 2
+                for col in -10...10 {
+                    var p = Path()
+                    p.move(to: CGPoint(x: cx, y: horizon))
+                    p.addLine(to: CGPoint(x: cx + Double(col) * size.width * 0.11,
+                                          y: size.height))
+                    ctx.stroke(p, with: .color(Color(red: 0.6, green: 0.95, blue: 1)),
+                               lineWidth: 1.5)
+                }
+                var row = horizon
+                var step = size.height * 0.012
+                while row < size.height {
+                    var p = Path()
+                    p.move(to: CGPoint(x: 0, y: row))
+                    p.addLine(to: CGPoint(x: size.width, y: row))
+                    ctx.stroke(p, with: .color(Color(red: 0.6, green: 0.95, blue: 1)),
+                               lineWidth: 1.5)
+                    step *= 1.32
+                    row += step
+                }
+            }
+        }
+        .overlay(alignment: .bottomLeading) {
+            // A small "now playing" chip so the frame reads as live content, not a wallpaper.
+            HStack(spacing: 8) {
+                Image(systemName: "gamecontroller.fill")
+                Text("Streaming from Battlestation")
+                    .font(.system(.callout, weight: .semibold))
+            }
+            .padding(.horizontal, 14).padding(.vertical, 9)
+            .glassBackground(Capsule())
+            .padding(18)
+        }
+        .ignoresSafeArea()
+    }
+
+    /// `PUNKTFUNK_SHOT_HERO=/abs/path.png` → use a real captured frame as the hero background.
+    static var overrideImage: Image? {
+        guard let path = ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_HERO"],
+              !path.isEmpty, FileManager.default.fileExists(atPath: path) else { return nil }
+        #if os(macOS)
+        guard let ns = NSImage(contentsOfFile: path) else { return nil }
+        return Image(nsImage: ns)
+        #else
+        guard let ui = UIImage(contentsOfFile: path) else { return nil }
+        return Image(uiImage: ui)
+        #endif
+    }
+}
+#endif