feat(client): opt-in "Rumble on this phone" mirrors pad-0 rumble onto the device

iOS + Android: a new opt-in setting mirrors controller 1's rumble onto the
device's own actuator (Apple RumbleRenderer Actuator.device / CoreHaptics,
Android deviceBodyVibrator), so a motor-less clip-on pad still gives haptic
feedback through the phone/tablet it's clamped to. Default off; wired through
the gamepad settings on both platforms.

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

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

@@ -15,6 +15,9 @@ import PunktfunkKit
 import SwiftUI
 #if os(iOS) || os(macOS) || os(tvOS)
 import GameController
+#if os(iOS)
+import CoreHaptics
+#endif
 
 struct GamepadSettingsView: View {
     @Environment(\.dismiss) private var dismiss
@@ -38,6 +41,9 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
     @AppStorage(DefaultsKey.autoWake) private var autoWakeEnabled = true
     @AppStorage(DefaultsKey.presenter) private var presenter = SettingsOptions.presenterDefault
+    #if os(iOS)
+    @AppStorage(DefaultsKey.rumbleOnDevice) private var rumbleOnDevice = false
+    #endif
     @ObservedObject private var gamepads = GamepadManager.shared
 
     #if os(iOS)
@@ -230,7 +236,7 @@ struct GamepadSettingsView: View {
             .map { (label: "\($0) Hz", tag: $0) }
         let bitrate = SettingsOptions.bitrateOptions(current: bitrateKbps)
         let controllers = SettingsOptions.controllerOptions(gamepads)
-        return [
+        var list: [Row] = [
             choiceRow(
                 id: "resolution", header: "Stream", icon: "aspectratio",
                 label: "Resolution",
@@ -329,6 +335,23 @@ struct GamepadSettingsView: View {
                 detail: "Turn off to use the touch interface even with a controller connected.",
                 value: $gamepadUIEnabled),
         ]
+        #if os(iOS)
+        // The device-rumble mirror slots in after "Controller type" (staying inside the
+        // Controller group — the next row carries the "Interface" header). iPhone only in
+        // practice: hidden where the device itself can't play haptics (iPad).
+        if CHHapticEngine.capabilitiesForHardware().supportsHaptics,
+            let at = list.firstIndex(where: { $0.id == "padType" }) {
+            list.insert(
+                toggleRow(
+                    id: "deviceRumble", icon: "iphone.radiowaves.left.and.right",
+                    label: "Rumble on this iPhone",
+                    detail: "Also play player 1's rumble on the phone's own Taptic Engine — "
+                        + "for clip-on pads without rumble motors.",
+                    value: $rumbleOnDevice),
+                at: at + 1)
+        }
+        #endif
+        return list
     }
 
     /// Resolution choices as "WxH" tags — the current size is inserted when it's a custom mode

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Sections.swift

@@ -1,6 +1,9 @@
 // SettingsView's shared sections — each setting's Section is defined exactly once here and
 // composed by the per-platform bodies in SettingsView.swift.
 
+#if os(iOS)
+import CoreHaptics
+#endif
 import PunktfunkKit
 import SwiftUI
 
@@ -471,6 +474,12 @@ extension SettingsView {
                     Text(option.label).tag(option.tag)
                 }
             }
+            #if os(iOS)
+            // iPhone only in practice: hidden where the device itself can't play haptics (iPad).
+            if CHHapticEngine.capabilitiesForHardware().supportsHaptics {
+                Toggle("Rumble on this iPhone", isOn: $rumbleOnDevice)
+            }
+            #endif
             #if !os(tvOS)
             Toggle("Gamepad-optimized browsing", isOn: $gamepadUIEnabled)
             #endif
@@ -487,6 +496,11 @@ extension SettingsView {
             // for its own footer and has no such toggle to describe.
             VStack(alignment: .leading, spacing: 6) {
                 Text(Self.controllersFooter)
+                #if os(iOS)
+                if CHHapticEngine.capabilitiesForHardware().supportsHaptics {
+                    Text(Self.deviceRumbleFooter)
+                }
+                #endif
                 #if !os(tvOS)
                 Text(Self.gamepadUIFooter)
                 #endif

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Support.swift

@@ -88,6 +88,13 @@ extension SettingsView {
         + "controller (a DualSense keeps adaptive triggers, lightbar, touchpad and motion). "
         + "Applies from the next session."
 
+    #if os(iOS)
+    static let deviceRumbleFooter =
+        "Rumble on this iPhone plays player 1's rumble on the phone's own Taptic Engine as "
+        + "well — for clip-on controllers that have no rumble motors of their own. Applies "
+        + "from the next session."
+    #endif
+
     #if !os(tvOS)
     static let gamepadUIFooter =
         "When a controller connects, the host list and library switch to a controller-"

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

@@ -55,6 +55,7 @@ struct SettingsView: View {
     #if os(iOS)
     @AppStorage(DefaultsKey.pointerCapture) var pointerCapture = true
     @AppStorage(DefaultsKey.touchMode) var touchMode = TouchInputMode.trackpad.rawValue
+    @AppStorage(DefaultsKey.rumbleOnDevice) var rumbleOnDevice = false
     // The sidebar selection drives the detail pane on iPad and the pushed sub-page on iPhone.
     // Width class decides the initial value: nil on iPhone (show the category list first),
     // General on iPad (a two-column layout should never open with an empty detail).

clients/apple/Sources/PunktfunkKit/Gamepad/GamepadFeedback.swift

@@ -20,6 +20,7 @@
 // (triggers off, player index unset) and its renderer silenced.
 
 import Combine
+import CoreHaptics
 import Foundation
 import GameController
 
@@ -50,9 +51,26 @@ public final class GamepadFeedback {
     private let routingLock = NSLock()
     private var rumbleByPad: [UInt8: RumbleRenderer] = [:]
 
+    /// Opt-in device mirror (`DefaultsKey.rumbleOnDevice`, iPhone only): rumble the host
+    /// addresses to controller 1 (wire pad 0) is ALSO rendered 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. Session-scoped (the setting is read once here); nil
+    /// when off or where the device has no haptic actuator.
+    private let deviceRumble: RumbleRenderer?
+
     public init(connection: PunktfunkConnection, manager: GamepadManager) {
         self.connection = connection
         self.manager = manager
+        #if os(iOS)
+        if UserDefaults.standard.bool(forKey: DefaultsKey.rumbleOnDevice),
+            CHHapticEngine.capabilitiesForHardware().supportsHaptics {
+            deviceRumble = RumbleRenderer(policy: .session, actuator: .device)
+        } else {
+            deviceRumble = nil
+        }
+        #else
+        deviceRumble = nil
+        #endif
         // Capture self weakly in the hop too, so the inner sink's weak capture isn't shadowing
         // an implicit strong one — and the subscription (stored on self) never retain-cycles.
         Task { @MainActor [weak self] in
@@ -189,6 +207,7 @@ public final class GamepadFeedback {
             return r
         }
         for r in renderers { r.stop() }
+        deviceRumble?.stop()
         // Drop the subscription and every dead pad's cached feedback — a controller change after
         // teardown must not replay this session's triggers/LEDs.
         Task { @MainActor in
@@ -203,6 +222,10 @@ public final class GamepadFeedback {
     private func routeRumble(pad: UInt8, low: UInt16, high: UInt16, ttlMs: UInt32) {
         let renderer = withRouting { rumbleByPad[pad] }
         renderer?.apply(low: low, high: high, ttlMs: ttlMs)
+        // The opt-in device mirror follows controller 1 unconditionally — the pads it exists for
+        // have no motors (their renderer above no-ops), and mirroring deliberately isn't gated on
+        // that: capability probing can't see a motor-less MFi pad, and the user opted in.
+        if pad == 0 { deviceRumble?.apply(low: low, high: high, ttlMs: ttlMs) }
     }
 
     private func withRouting<R>(_ body: () -> R) -> R {

clients/apple/Sources/PunktfunkKit/Gamepad/RumbleRenderer.swift

@@ -119,8 +119,19 @@ final class RumbleRenderer: @unchecked Sendable {
         static let manual = Policy(staleAfter: nil)
     }
 
+    /// Which physical actuator this renderer drives: the forwarded controller's haptics engine
+    /// (the default), or THIS device's own Taptic Engine (`CHHapticEngine()`) — the opt-in
+    /// "rumble on this device" mirror for phone-clip pads that ship without rumble motors.
+    /// Device mode ignores `retarget`'s controller and always renders one combined motor
+    /// (a phone body has a single actuator).
+    enum Actuator {
+        case controller
+        case device
+    }
+
     private let queue = DispatchQueue(label: "io.unom.punktfunk.haptics", qos: .userInteractive)
     private let policy: Policy
+    private let actuator: Actuator
 
     /// One finite haptic play on a motor: the player plus when (engine timeline) it expires.
     /// A PLAIN pattern player on purpose: the controller haptics server (gamecontrollerd)
@@ -198,8 +209,9 @@ final class RumbleRenderer: @unchecked Sendable {
         ((0, 0), DispatchTime(uptimeNanoseconds: 0))
     #endif
 
-    init(policy: Policy = .session) {
+    init(policy: Policy = .session, actuator: Actuator = .controller) {
         self.policy = policy
+        self.actuator = actuator
     }
 
     /// `onBackend`, if given, is invoked (on the internal queue) with a human-readable name of the
@@ -468,6 +480,10 @@ final class RumbleRenderer: @unchecked Sendable {
     /// high = right/light — the Xbox/XInput convention the wire carries); one combined
     /// engine otherwise, driven by whichever amplitude is stronger.
     private func setup() {
+        if actuator == .device {
+            setupDevice()
+            return
+        }
         guard let haptics = controller?.haptics else {
             // No haptics engine at all — an Xbox controller on an OS/firmware that doesn't expose
             // rumble through GameController (works on Android via the standard Vibrator path, but
@@ -517,10 +533,41 @@ final class RumbleRenderer: @unchecked Sendable {
         }
     }
 
+    /// Device-actuator mode: one combined motor on this device's own Taptic Engine. Only an
+    /// iPhone has one — everything else (iPad, Mac, TV) reports no haptic hardware and latches
+    /// off (nothing to retry; the settings toggle is hidden there anyway, this is the backstop).
+    private func setupDevice() {
+        #if os(iOS)
+        guard CHHapticEngine.capabilitiesForHardware().supportsHaptics else {
+            log.info("rumble: this device has no haptic actuator — device rumble unavailable")
+            broken = true
+            reportHealth("This device has no haptic actuator.")
+            return
+        }
+        do {
+            low = startMotor(try CHHapticEngine(), sharpness: RumbleTuning.sharpnessCombined)
+        } catch {
+            log.warning("rumble: device haptic engine creation failed: \(error, privacy: .public)")
+        }
+        if low == nil {
+            // Same shape as the controller path: haptics exist but the engine couldn't be built
+            // right now — back off and retry, don't latch off.
+            scheduleRetryBackoff()
+        }
+        #else
+        broken = true
+        #endif
+    }
+
     private func makeMotor(
         _ haptics: GCDeviceHaptics, _ locality: GCHapticsLocality, sharpness: Float
     ) -> Motor? {
         guard let engine = haptics.createEngine(withLocality: locality) else { return nil }
+        return startMotor(engine, sharpness: sharpness)
+    }
+
+    /// Configure + start an engine (controller-locality or the device's own) into a [`Motor`].
+    private func startMotor(_ engine: CHHapticEngine, sharpness: Float) -> Motor? {
         // A controller's motors carry no audio, so keep this engine OUT of the app's audio session
         // (the default is to join it). Streaming keeps an AVAudioSession active the whole time;
         // letting a haptics-only engine join it is a needless coupling that can get its
@@ -546,7 +593,7 @@ final class RumbleRenderer: @unchecked Sendable {
             try engine.start()
             return Motor(engine: engine, sharpness: sharpness)
         } catch {
-            log.warning("haptic engine setup failed (\(locality.rawValue, privacy: .public)): \(error, privacy: .public)")
+            log.warning("haptic engine setup failed: \(error, privacy: .public)")
             return nil
         }
     }

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

@@ -97,6 +97,12 @@ public enum DefaultsKey {
     /// 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