[raiseCatError]

Refs #12. Stacked on #24: merge #24 first, then retarget this PR. Its diff against feature/per-device-display-mode is only this feature's 3 commits.

What changed

Once the sending Mac grants the session control, the Mac Receiver's own trackpad, mouse and keyboard drive it while the video window is in front, in Mirror and in Extend. It uses the existing pointer, scroll, keyboard and nativeAppGesture messages and the existing per-session request/grant. No new wire message.

Receiver (MacReceiver/ReceiverInputForwarding.swift is pure and tested; ReceiverInputController.swift holds the AppKit glue):

• Pointer: move, left/right click with click counts, drags clamped to the picture and released even outside the window.
• Scroll and gestures: precise and wheel scroll in this Mac's scroll direction, and pinch/rotate.
• Keys: every key of a full keyboard with Shift/Control/Option/Command/Caps Lock, and key repeat.
• Focus: forwarding needs the grant, the window in front, and no local pause. Input is never captured globally: an app-local monitor scoped to the video window means system shortcuts (Command-Tab, Force Quit, Mission Control, Spotlight) stay local. A modifier held from before forwarding (Command-Tab's Command) is never sent.
• Release: everything sent down is released on focus loss, the ⌃⌥⎋ pause, Release, revocation and window close. A disconnect resets locally.
• UI: a titlebar indicator (View Only / Requesting / Controlling / Paused, plus Request Control or Release), a short hint naming the pause shortcut, and the streamed cursor following the local pointer while controlling.

Sender (additive):

• HID usages for grave, F1–F20, Home/End/Page Up/Down, Help/Insert, keypad, ISO and JIS keys.
• keyboard down + repeat: true posts an auto-repeat only for a held key.
• Scroll carries its rounding remainder, so slow trackpad scrolls no longer round away. This also applies to iPhone/iPad.

Docs: RECEIVER_INPUT.md covers behavior, local vs forwarded, guarantees and a 12-step physical checklist. PROTOCOL.md documents the repeat field and the full usage range. README/SETUP/ARCHITECTURE no longer call the Mac Receiver display-only.

Compatibility

• New receiver + 1.20.0 sender: control works; the new keys and key repeat are ignored by that sender (unknown usages and duplicate downs were always ignored).
• iPhone/iPad: unchanged. The sendKeyboardDown(usage:modifiers:) signature is preserved, and messages are byte-identical unless repeat is set.

Verification

• xcodebuild test -scheme OpenSidecarMac (unsigned, Xcode 27.1): 1946 tests, 0 failures (1892 on feat(mac): independent Mirror/Extend per connected device #24's head; 54 new in ReceiverInputForwardingTests).

• OpenSidecarMacReceiver build ✅. OpenSidecariOS generic-device build ✅. The iOS build caught a protocol-conformance break, which is fixed.

• The forwarder's decision cost is measured at about 0.45–0.7 µs per pointer event (10,000 moves in 4.2–6.7 ms after warm-up); no threshold is asserted.

• No test posts events into the live system.

• Not verified on hardware: real trackpad/keyboard feel, latency, and injected events in real apps. See the checklist in RECEIVER_INPUT.md.

• The change is focused, without unrelated refactors

• Relevant behaviour was verified (tests and/or on device): tests only, devices pending

• Documentation updated if needed

• No credentials, secrets or signing material included

• No unrelated generated or build artifacts

[raiseCatError]

Closing as included: this branch's head is an ancestor of dev (merged via #34, merge commit d2e765f), so every commit here is already in the 2.0 development line. The branch itself is left in place.

---

Generated by Claude Code