[raiseCatError]

Summary

A virtual display rebuilt right after the Mac wakes no longer loses its saved position. Before this change, a stalled first check could save macOS's default spot as if the user had dragged the display there. Every later session then placed the display in that wrong spot.

This ports upstream OpenDisplay's fix onto MeowDisplay's VirtualDisplay. It is a manual adaptation, not a cherry-pick.

Upstream source

Issue	peetzweg/opendisplay#390: "Display arrangement lost when a post-sleep rebuild stalls the restore window"
Pull request	peetzweg/opendisplay#392: "fix(mac): start the arrangement restore window on the first tick"
Source commit	1522cd22699b21932d69c718b4afc18bee45d546, by peetzweg, GPL-3.0 (the same licence as this repository)

The upstream references are in code spans on purpose, so this PR adds no cross-reference events to the upstream tracker.

The bug (present here at cbbad7f)

• Mac/VirtualDisplay.swift started the 6 s arrangement restore window in init.
• The display's tick task runs ensureNotMirrored(), then selectHiDPIMode(), then manageOrigin().
• After sleep, a mode change can block the main actor for about 10 s. Upstream's field log shows exactly this.
• In that case the first manageOrigin() runs after the window has already closed. It sees macOS's default origin and reports it through onOriginChange.
• DisplayArrangement.save then overwrites the device's saved placement.
• resize(…, movingTo:) started its new window from the wall clock in the same way.

What changes (4 files, +244 / −47)

• Mac/OriginRestore.swift (new): upstream's pure restore/observe policy. The window now starts on the first tick, not when it is armed. A window that closes before any check succeeds starts observing instead of saving wherever macOS left the display. On first contact (no saved placement), the initial spot is still recorded.
• Mac/VirtualDisplay.swift: three restore fields become one originRestore.
  • init arms the restore.
  • resize calls rearm(at:).
  • manageOrigin switches on tick(origin:).
• MacTests/OriginRestoreTests.swift (new): upstream's 9 tests, unchanged, plus 2 tests for this fork.
• project.yml: adds Mac/OriginRestore.swift to the hostless OpenSidecarMacTests sources. The app picks it up through - Mac.

Why not a cherry-pick

A dry-run cherry-pick of 1522cd2 conflicts in Mac/VirtualDisplay.swift and project.yml. Upstream's VirtualDisplay has diverged from this fork's: this fork has its own HiDPI enforcement and a headless-main path that upstream doesn't have.

Fork-specific handling: headless main display

This fork's repositionForHeadlessMain(to:) moves the virtual display to (0,0) when no usable physical display exists. This gives macOS's login and lock UI a main display to render on. It used to re-arm the same restore window.

• It now calls a new OriginRestore.retarget(to:). This restarts the window on the next tick without marking (0,0) as observed.
• Result: if every attempt to apply the move fails, nothing is reported and the saved placement stays untouched.
• Using upstream's rearm(at: .zero) instead would have saved a spurious drag when the window closed. A dedicated test covers this case.
• The method's doc comment had absorbed manageOrigin's; it is split back into two.

Not touched: sender session management, transport, pairing/TLS, DisplayArrangement storage, the wire protocol, and the existing sleep/lock capture recovery. OriginRestore is a value type mutated only inside VirtualDisplay, through the same main-thread call sites as the fields it replaces, so there is no new concurrency surface.

Verification

• Mac unit tests on this branch: xcodebuild test -scheme OpenSidecarMac -destination platform=macOS, unsigned. Result: TEST SUCCEEDED, 1856 tests, 0 failures (1845 before + 11 OriginRestoreTests). The touched files compile in OpenSidecarMac and OpenSidecarMacTests with no warnings; the 7 warnings in the log are pre-existing.
• Preview merge with the Mac draft stack: a throwaway merge of feat(mac): one MeowDisplay app that can also be a display #26 (879da2c, which contains feat(mac): independent Mirror/Extend per connected device #24 and feat(mac-receiver): keyboard and trackpad control of the sending Mac #25) with this commit. Result: TEST SUCCEEDED, 2013 tests, 0 failures.
• Merge compatibility: git merge-tree dry runs are clean into feat(mac): independent Mirror/Extend per connected device #24 66de410, feat(mac-receiver): keyboard and trackpad control of the sending Mac #25 ffd2b6b, feat(mac): one MeowDisplay app that can also be a display #26 879da2c, fix(ios): touch-control UX fixes, a Return key and 8× local zoom #27 2ea0025 and release/app-store-rc.
• Reproduction: a standalone Swift 6 harness models the old logic. Delaying the first tick 10 s returns report(1512,0) (the bug). OriginRestore returns apply(saved) and reports nothing afterwards.
• iOS: not built. No file compiled by the iOS app, its UI tests or the Mac Receiver target changes.
• GitHub CI (Tests / mac, Xcode 26.6 on macos-26-arm64): the Mac test step passed: 1856 tests, 0 failures, ** TEST SUCCEEDED **, with all 11 OriginRestoreTests green. The job then fails in its later iOS build step: iOS/ReceiverControls.swift:1426: the compiler is unable to type-check this expression in reasonable time.
  • That file is unchanged from the base cbbad7f.
  • The same error has failed every Tests run since 2026-10-25 11:26, including feat(mac): independent Mirror/Extend per connected device #24–fix(ios): touch-control UX fixes, a Return key and 8× local zoom #27 (fix(ios): touch-control UX fixes, a Return key and 8× local zoom #27 reports line 1488).
  • It is a pre-existing CI blocker on Xcode 26.6, to be fixed separately, not a regression from this PR.

Not verified

• No physical sleep/wake validation. The field failure needs a sender whose WindowServer stalls a mode change for more than 6 s after wake. Only the policy is unit-tested here, not CoreGraphics behaviour.
• Suggested hardware check:
  1. Extend to a device and drag its display to a non-default spot. Disconnect and reconnect, and confirm it comes back there.
  2. Let the Mac sleep for several minutes while the session is up, then wake it.
  3. Confirm the display returns to the saved spot. The log should show origin … → restored, followed by no arrangement save of macOS's default.
  4. Repeat with no usable physical display (headless).

Attribution

The original change is by peetzweg in upstream OpenDisplay. The commit message credits peetzweg and records (adapted from commit 1522cd22699b21932d69c718b4afc18bee45d546). The commit is authored with this repository's maintainer identity because it contains fork-specific code beyond the upstream change.

Draft. Not for merge until the hardware check above is done.