feat(mode_switch): one-call ModeSwitch::step() for every platform; document the 2D/3D transition contract

[dfattal]

Why

David: "ease 2D<->3D transitions (mode switching) the same way we do on Windows; that's valid for all apps and should be clear in displayxr-common."

What Windows does today is entirely app-side: the runtime switches a rendering mode in one frame (atlas recipe, DP weave-vs-flat, lens all follow the mode the moment it lands, ADR-028) and never ramps the stereo disparity. The only runtime aid is the one-frame #615 eye-set guard. The Leia plug-in has no fade on any platform either. The smooth transition the Windows cube apps show is dxr::ModeSwitch (this repo), driven by XrSessionUpdateModeSwitch().

That glue takes the Windows-only XrSessionManager, so the non-Windows legs could not call it: the runtime's macOS cube_handle_* apps and the modelviewer demo hand-copied ~40 lines each, and several apps on every platform (all the zones apps, cube_handle_vk_linux) never wired it. The contract was also written nowhere in this repo.

What

• mode_switch.h is header-only and gains ModeSwitch::step(dt, requestedMode, modeCount, modeViewCounts, currentMode, steadyIpd) -> {ipd, fire, mode} plus ModeSwitch::cycleTarget(). step() is the glue every platform now shares. It applies the "ramp from the on-screen ipd" rule that fixed the first-press snap (4307382) and drops a fire for the mode the runtime is already in, so a caller cannot re-introduce either bug. kModeSwitchDefaultDurationS (0.18 s) names the shared ramp. mode_switch.cpp is gone.
• Because it is header-only it is reachable through displayxr::rules, so Android legs and engine ports can include it without linking displayxr_common_lib.
• XrSessionUpdateModeSwitch is now a thin Windows wrapper over step() with the same behaviour.
• README, "Smooth 2D<->3D transitions (mode_switch.h), every app, every platform" covers: what the runtime does and does not do, the ramp/request ordering table, wiring for Windows and for every other leg, the inputs (where currentMode / modeViewCounts / steadyIpd come from), and the mode changes an app cannot ease (runtime-owned V in hosted/legacy apps, the shell's Ctrl+V, agent requests).
• Tests (tests/common_smoke.cpp): step() routing, idle steady value, cycle and absolute requests, out-of-range and same-mode requests, a null view-count table, and a fresh sequencer's first 3D->2D. I mutation-checked the last one: reverting step() to the pre-4307382 rule fails it.

Consumers

• feat(test_apps): macOS cube apps ease 2D/3D through dxr::ModeSwitch::step(); linter INV-2.9 displayxr-runtime#1904: the macOS cube_handle_{metal,vk,gl} apps switch from their inline copies to step(), and the macOS zones apps adopt it. A new advisory linter rule, INV-2.9, flags apps that request modes without the sequencer. That PR pins this branch's commit and must be re-pinned to the release tag before it merges, so this PR merges and tags first.
• The modelviewer demo's macOS/Linux inline copies keep working unchanged. Moving them to step() is an optional follow-up.

Doc companion: DisplayXR/displayxr-leia-plugin#331 (no arm of the plug-in fades; the transition is app-side).

Testing

• ctest on macOS: 5/5 pass, including the new step() cases.
• Runtime macOS apps built against this branch on sim-display (anaglyph, built-in display), with scripted toggles (DXR_TEST_MODE_TOGGLE_S). 3D->2D ramps the disparity from 1 to 0 over about 0.18 s and requests 2D on the landing frame. 2D->3D requests on the first frame (ipd about 0.01) and ramps back to 1. Both checked for Metal, Vulkan (vk_native), GL and the four zones apps.
• Not run: Windows (no Windows box in this session; the wrapper's behaviour is unchanged by construction), Linux, Android.

🤖 Generated with Claude Code