feat(apple/M0): App Group + PunktfunkShared + punktfunk:// deep links
Foundation milestone for Live Activities & Widgets (design/apple-live- activities-and-widgets.md). No user-visible change beyond the URL scheme. - New dependency-free PunktfunkShared SwiftPM target (+ library product) so a future widget extension can link it WITHOUT PunktfunkKit (Rust staticlib + presentation layer). Moves StoredHost (model + JSON codec), DefaultsKeys, and punktfunkDefaultMgmtPort there; adds AppGroup.suiteName and the punktfunk:// DeepLink builder/parser. PunktfunkKit @_exported-imports it (no call-site churn for consumers; intra-Kit files import it explicitly since imports are file-scoped). - HostStore reads/writes the shared App-Group suite (group.io.unom.punktfunk) with a one-time migration from UserDefaults.standard (old value left in place for staged rollout); reloads the "PunktfunkHosts" widget timeline on change. - App Group entitlement on iOS/tvOS + macOS. - CFBundleURLTypes scheme `punktfunk`; ContentView.onOpenURL routes connect/<uuid>[?launch=<GameEntry.id>] into the existing connect() path (unknown host / already-streaming guards; never tears down a live session). - Round-trip tests: StoredHost JSON codec (+ legacy missing-optional decode), DeepLink grammar. `swift build` + `swift test` green (142 tests, 0 failures). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,23 @@
|
||||
// The App-Group foundation shared by the app and its extensions (Widgets / Live Activity).
|
||||
//
|
||||
// PunktfunkShared is deliberately dependency-free: it links NEITHER PunktfunkKit (which drags in
|
||||
// the Rust staticlib + presentation layer) NOR any Apple UI framework. A widget process gets ~30 MB,
|
||||
// so everything an extension needs — the stored-host model + its JSON codec, the settings-key names,
|
||||
// the deep-link grammar, and (later) the Live Activity attributes — lives here and here only.
|
||||
|
||||
import Foundation
|
||||
|
||||
/// The one App-Group identifier, matched by `Config/*.entitlements`
|
||||
/// (`com.apple.security.application-groups`). Registered on the developer portal for both the app
|
||||
/// id (`io.unom.punktfunk`) and the widget extension id (`io.unom.punktfunk.widgets`).
|
||||
public enum AppGroup {
|
||||
public static let suiteName = "group.io.unom.punktfunk"
|
||||
|
||||
/// The shared defaults suite. Non-nil in a correctly-entitled process; falls back to
|
||||
/// `.standard` if the group is somehow unavailable (unsigned `swift run`, a misprovisioned
|
||||
/// build) so the app still functions single-process rather than crashing — the widget just
|
||||
/// won't see the same store there.
|
||||
public static var defaults: UserDefaults {
|
||||
UserDefaults(suiteName: suiteName) ?? .standard
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
// The `punktfunk://` deep-link grammar — the single builder/parser shared by the widget (which
|
||||
// emits links via `widgetURL`/`Link`) and the app (`ContentView.onOpenURL`, which routes them into
|
||||
// the existing connect path). Keeping both sides on one type means the wire format can't drift.
|
||||
//
|
||||
// Grammar (v1):
|
||||
// punktfunk://connect/<host-uuid> — connect to a stored host
|
||||
// punktfunk://connect/<host-uuid>?launch=<GameEntry.id> — connect and ask the host to launch it
|
||||
//
|
||||
// `launch` carries a `GameEntry.id` (e.g. "steam:570"); it is percent-encoded on build and decoded
|
||||
// on parse, so ids with reserved characters survive the round trip.
|
||||
|
||||
import Foundation
|
||||
|
||||
public enum DeepLink: Equatable {
|
||||
/// Connect to a saved host; `launchID` is a `GameEntry.id` to launch on arrival, if any.
|
||||
case connect(host: UUID, launchID: String?)
|
||||
|
||||
public static let scheme = "punktfunk"
|
||||
|
||||
/// Build the canonical URL for a route. Non-optional: every route is representable.
|
||||
public var url: URL {
|
||||
switch self {
|
||||
case let .connect(host, launchID):
|
||||
var comps = URLComponents()
|
||||
comps.scheme = Self.scheme
|
||||
comps.host = "connect"
|
||||
comps.path = "/\(host.uuidString)"
|
||||
if let launchID, !launchID.isEmpty {
|
||||
comps.queryItems = [URLQueryItem(name: "launch", value: launchID)]
|
||||
}
|
||||
// URLComponents percent-encodes the query value; force-unwrap is safe for a URL we
|
||||
// fully control (scheme/host/path are all valid).
|
||||
return comps.url!
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse an incoming URL, or nil if it isn't a recognized `punktfunk://` route. Tolerant of
|
||||
/// case in the scheme and of a trailing slash on the path.
|
||||
public init?(_ url: URL) {
|
||||
guard url.scheme?.lowercased() == Self.scheme else { return nil }
|
||||
guard let comps = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return nil }
|
||||
|
||||
switch comps.host?.lowercased() {
|
||||
case "connect":
|
||||
// Path is "/<uuid>"; strip the leading slash and any trailing one.
|
||||
let raw = comps.path
|
||||
.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
|
||||
guard let host = UUID(uuidString: raw) else { return nil }
|
||||
let launch = comps.queryItems?
|
||||
.first(where: { $0.name == "launch" })?.value
|
||||
.flatMap { $0.isEmpty ? nil : $0 }
|
||||
self = .connect(host: host, launchID: launch)
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,124 @@
|
||||
// One source of truth for the client's UserDefaults / @AppStorage keys. A magic-string key
|
||||
// duplicated across a setting's writer (a Settings @AppStorage) and reader (e.g. a stream view
|
||||
// reading UserDefaults) splits silently on a typo — the setting just stops taking effect. These
|
||||
// live in the dependency-free PunktfunkShared module (re-exported by PunktfunkKit) because the app,
|
||||
// the kit's views, AND the widget extension all read them — the widget needs `DefaultsKey.hosts`.
|
||||
|
||||
import Foundation
|
||||
|
||||
/// Persisted-setting keys. The string VALUES are stable on disk — rename the symbol freely, but
|
||||
/// never the string (it would orphan everyone's saved value).
|
||||
public enum DefaultsKey {
|
||||
public static let streamWidth = "punktfunk.width"
|
||||
public static let streamHeight = "punktfunk.height"
|
||||
public static let streamHz = "punktfunk.hz"
|
||||
/// Match-window resolution policy (design/midstream-resolution-resize.md D1/D2): when on, the
|
||||
/// stream mode FOLLOWS the session view — the connect asks for the view's pixel size and a
|
||||
/// mid-session resize (a windowed macOS window, an iPad Stage Manager / Split View scene)
|
||||
/// renegotiates the host's virtual display + encoder (`PunktfunkConnection.requestMode`), so a
|
||||
/// windowed session streams native-resolution pixels instead of scaling. Off (default): the
|
||||
/// explicit `streamWidth`/`streamHeight` are used and never auto-resized (a fullscreen session
|
||||
/// is native either way, so this degenerates to Auto-native there). Read per session by the
|
||||
/// stream views' `MatchWindowFollower`.
|
||||
public static let matchWindow = "punktfunk.matchWindow"
|
||||
public static let compositor = "punktfunk.compositor"
|
||||
public static let gamepadType = "punktfunk.gamepadType"
|
||||
public static let gamepadID = "punktfunk.gamepadID"
|
||||
public static let bitrateKbps = "punktfunk.bitrateKbps"
|
||||
/// 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"`, `"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"
|
||||
public static let micUID = "punktfunk.micUID"
|
||||
/// macOS: which input channel of the chosen mic device feeds the host. 0 = "Auto" (sum every
|
||||
/// channel to mono — a mic on a single input of a multi-channel interface passes at full
|
||||
/// level); n≥1 pins 1-based input channel n. Multi-channel interfaces expose the mic on ONE
|
||||
/// discrete channel, and the default N→stereo downmix grabs channels 0/1 (silence when the mic
|
||||
/// is higher up), so we fold to mono ourselves. Only meaningful for multi-channel devices.
|
||||
public static let micChannel = "punktfunk.micChannel"
|
||||
/// Which presenter runs a session: "stage2" (default — explicit decode + Metal present on
|
||||
/// frame arrival), "stage3" (same pipeline, glass-gated present pacing — the experimental
|
||||
/// low-display-latency A/B; see Stage2Pipeline's PresentPacing), or "stage1" (DEBUG-only
|
||||
/// system-layer fallback). Resolved once per session by SessionPresenter;
|
||||
/// PUNKTFUNK_PRESENTER=stage1|stage2|stage3 overrides it for A/B.
|
||||
public static let presenter = "punktfunk.presenter"
|
||||
/// macOS: V-Sync the stream's presents — each decoded frame flips on the next display vsync
|
||||
/// (evenly paced, no tearing under direct scanout) instead of as soon as the GPU finishes
|
||||
/// (lowest latency — the default, OFF). Resolved once per session;
|
||||
/// PUNKTFUNK_PRESENT_MODE=immediate|vsync overrides it for A/B. See Stage2Pipeline's header.
|
||||
public static let vsync = "punktfunk.vsync"
|
||||
/// Allow variable refresh rate: hand the display link a wide frame-rate RANGE (low floor,
|
||||
/// preferred = stream rate) so a ProMotion / adaptive-sync display can vary its physical
|
||||
/// refresh to match the stream. On by default; a no-op on fixed-refresh displays. When off,
|
||||
/// macOS lets the link free-run at the display's native rate and iOS keeps its proven 30 Hz
|
||||
/// floor. Read per session/reconfigure by `SessionPresenter.syncFrameRate`.
|
||||
public static let allowVRR = "punktfunk.allowVRR"
|
||||
/// Request a 10-bit BT.2020 PQ (HDR10) stream. On by default; only takes effect when the host
|
||||
/// has HDR content AND this display supports HDR — otherwise the stream stays 8-bit SDR.
|
||||
public static let hdrEnabled = "punktfunk.hdrEnabled"
|
||||
/// Request a full-chroma 4:4:4 stream when this device can HARDWARE-decode it (`Stage444Probe`).
|
||||
/// On by default; only takes effect when the host also opted in to 4:4:4 (otherwise the stream
|
||||
/// stays 4:2:0). Sharper text/UI at the cost of more bandwidth.
|
||||
public static let enable444 = "punktfunk.enable444"
|
||||
public static let hosts = "punktfunk.hosts"
|
||||
/// Client-side cursor mode: "auto" (shown only in gamescope sessions), "always", "never".
|
||||
public static let cursorMode = "punktfunk.cursorMode"
|
||||
/// iPad: capture the mouse/trackpad pointer (pointer lock → relative movement) for games,
|
||||
/// rather than forwarding an absolute cursor position. On by default. Only meaningful on iPad
|
||||
/// with a hardware mouse/trackpad; the system grants the lock only to a full-screen, frontmost
|
||||
/// scene and silently falls back to the absolute pointer when it can't (Stage Manager / Slide
|
||||
/// Over). Read by `StreamViewController.prefersPointerLocked`.
|
||||
public static let pointerCapture = "punktfunk.pointerCapture"
|
||||
/// iPhone/iPad: how touchscreen fingers drive the host — a `TouchInputMode` raw value:
|
||||
/// "trackpad" (default: relative cursor with tap-click / two-finger-scroll gestures),
|
||||
/// "pointer" (the cursor jumps to the finger), or "touch" (real multi-touch passthrough).
|
||||
/// Read live per gesture by `StreamLayerUIView`.
|
||||
public static let touchMode = "punktfunk.touchMode"
|
||||
/// Experimental: show the host's game library (browsed over the management API). Off by default.
|
||||
public static let libraryEnabled = "punktfunk.libraryEnabled"
|
||||
/// macOS: take the window fullscreen while streaming and restore it on the host list. On by default.
|
||||
public static let fullscreenWhileStreaming = "punktfunk.fullscreenWhileStreaming"
|
||||
/// LEGACY (pre-tiered overlay): the old boolean stats-overlay toggle. Kept ONLY as the
|
||||
/// migration fallback `StatsVerbosity.current` reads when `statsVerbosity` was never
|
||||
/// written (absent-or-true → .normal, explicit false → .off). Never written anymore.
|
||||
public static let hudEnabled = "punktfunk.hudEnabled"
|
||||
/// The statistics overlay tier — a `StatsVerbosity` raw value ("off"/"compact"/"normal"/
|
||||
/// "detailed"). Absent → migrated from the legacy `hudEnabled` bool (see above). Cycle it
|
||||
/// while streaming with ⌃⌥⇧S (the cross-client Ctrl+Alt+Shift+S; macOS / hardware
|
||||
/// keyboard) or a three-finger tap (touch), matching the Android client.
|
||||
public static let statsVerbosity = "punktfunk.statsVerbosity"
|
||||
/// Which corner the statistics overlay sits in — a `HUDPlacement` raw value
|
||||
/// ("topLeading"/"topTrailing"/"bottomLeading"/"bottomTrailing"). Default top-trailing.
|
||||
public static let hudPlacement = "punktfunk.hudPlacement"
|
||||
/// iOS/iPadOS/macOS: switch the host list, settings and game library to a controller-friendly
|
||||
/// layout (the console launcher, gamepad-navigable settings, a coverflow-style library)
|
||||
/// whenever a gamepad is connected. On by default; see `GamepadUIEnvironment.isActive`.
|
||||
public static let gamepadUIEnabled = "punktfunk.gamepadUIEnabled"
|
||||
/// iPhone: ALSO play the rumble the host addresses to controller 1 (wire pad 0) on this
|
||||
/// device's own Taptic Engine — for phone-clip pads that ship without rumble motors, where
|
||||
/// the phone body is the only actuator in the player's hands. Off by default (opt-in); read
|
||||
/// once per session by `GamepadFeedback`. The toggle is shown only where the device actually
|
||||
/// has a haptic actuator (no iPad/Mac/TV).
|
||||
public static let rumbleOnDevice = "punktfunk.rumbleOnDevice"
|
||||
/// Auto-wake on connect: when connecting to a saved host that isn't advertising on mDNS, fire
|
||||
/// Wake-on-LAN and, if the dial fails, wait for it to come back before retrying (the "Waking…"
|
||||
/// overlay). On by default. Turn off if a host that's already on just isn't seen on mDNS (a
|
||||
/// routed/VPN host), so connects go straight through instead of waiting out the wake timeout.
|
||||
/// The explicit "Wake Host" action stays available regardless. Read by ContentView.startSession.
|
||||
public static let autoWake = "punktfunk.autoWake"
|
||||
}
|
||||
|
||||
extension Notification.Name {
|
||||
/// Posted by the app's Stream menu ("Release Mouse", ⌃⌥⇧Q): the key window's stream view
|
||||
/// releases input capture if it holds it. Only reachable while NOT captured (a captured
|
||||
/// session swallows the combo in InputCapture's monitor and the frozen cursor can't click
|
||||
/// menus) — it exists so the menu item is honest whenever it CAN fire, and as the shortcut's
|
||||
/// discoverable menu-bar surface.
|
||||
public static let punktfunkReleaseCapture = Notification.Name("io.unom.punktfunk.release-capture")
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
// The saved-host model + its on-disk JSON wire format — the widget/extension depends on BOTH, so
|
||||
// they live in the dependency-free shared module. The `ObservableObject` store that wraps them
|
||||
// (`HostStore`, with add/remove/pin/reachability) stays in the app target; discovery-join helpers
|
||||
// (`matches`, `advertises`) stay there too because they reference PunktfunkKit's `DiscoveredHost`.
|
||||
//
|
||||
// Wire-format stability: the JSON encoding of `StoredHost` is now a shared contract between the app
|
||||
// (writer) and the widget (reader). The `PunktfunkSharedTests` codec round-trip pins it — do not
|
||||
// rename the coding keys or make a stored `Optional` non-optional (older saved JSON must still
|
||||
// decode; synthesized Decodable treats a missing Optional as nil).
|
||||
|
||||
import Foundation
|
||||
|
||||
/// The management-API port default (distinct from the data-plane `port`). Lives here (not in
|
||||
/// PunktfunkKit's LibraryClient, which re-exports it) so `StoredHost.effectiveMgmtPort` can resolve
|
||||
/// it without the shared module taking a dependency on the kit.
|
||||
public let punktfunkDefaultMgmtPort: UInt16 = 47990
|
||||
|
||||
public struct StoredHost: Identifiable, Codable, Hashable {
|
||||
public var id = UUID()
|
||||
public var name: String
|
||||
public var address: String
|
||||
public var port: UInt16 = 9777
|
||||
/// SHA-256 of the host's certificate, set after the user explicitly trusted it.
|
||||
public var pinnedSHA256: Data?
|
||||
/// Last time a streaming session actually started (nil until the first one).
|
||||
public var lastConnected: Date?
|
||||
/// Management-API port for the library browser (distinct from the data-plane `port`). Optional
|
||||
/// (NOT a defaulted non-optional) so older saved hosts — whose JSON lacks this key — still
|
||||
/// decode: synthesized Decodable ignores property defaults but treats a missing Optional as
|
||||
/// nil. Resolve via `effectiveMgmtPort`. (Auth is mTLS by the pinned identity — no token.)
|
||||
public var mgmtPort: UInt16?
|
||||
/// Wake-on-LAN MAC address(es) of the host's wake-capable NIC(s), each `aa:bb:cc:dd:ee:ff`.
|
||||
/// Learned from the host's mDNS `mac` TXT record while it's awake and persisted here, so the
|
||||
/// client can send a magic packet to wake the host later (when it's asleep and no longer
|
||||
/// advertising). Optional (same forward-compat reason as `mgmtPort`); nil until first learned.
|
||||
public var macAddresses: [String]?
|
||||
|
||||
public init(
|
||||
id: UUID = UUID(), name: String, address: String, port: UInt16 = 9777,
|
||||
pinnedSHA256: Data? = nil, lastConnected: Date? = nil, mgmtPort: UInt16? = nil,
|
||||
macAddresses: [String]? = nil
|
||||
) {
|
||||
self.id = id
|
||||
self.name = name
|
||||
self.address = address
|
||||
self.port = port
|
||||
self.pinnedSHA256 = pinnedSHA256
|
||||
self.lastConnected = lastConnected
|
||||
self.mgmtPort = mgmtPort
|
||||
self.macAddresses = macAddresses
|
||||
}
|
||||
|
||||
public var displayName: String { name.isEmpty ? address : name }
|
||||
public var effectiveMgmtPort: UInt16 { mgmtPort ?? punktfunkDefaultMgmtPort }
|
||||
/// Wake-capable, in a form the wake helper accepts (empty when none learned yet).
|
||||
public var wakeMacs: [String] { macAddresses ?? [] }
|
||||
}
|
||||
Reference in New Issue
Block a user