Android predictive-back gesture with a live screen peek

[ScottMorris]

Closes #12

Summary

Ports the Android predictive-back "peek" gesture from PR #13 (open since January, built on 563-commits-old code before the app rename and the event-driven Rust rewrite -- a literal rebase wasn't viable) as a fresh implementation against current main, fixing several real bugs found in that original attempt (wrong API-level gate, a Rust command macro that doesn't compile in tauri v2, a manifest flag that was never set, an unverified event-name guess, and a param-guessing underlay renderer its own comments admitted was broken).

• plugins/predictive-back (new): registers OnBackAnimationCallback (API 33+) via a Channel to Rust, re-emitted as a predictive-back:event Tauri event. onResume() forces a clean re-registration, since the system's dispatcher registration doesn't reliably survive a pause/resume cycle (e.g. screen off then back on) even though the Kotlin callback object reference does.
• RouteStage.tsx (new) replaces the plain <Outlet/> wrapper, layering the current route over a cached previous screen (ScreenStack -- the actual previously-rendered component with its real params, not a placeholder) and transforming both by live gesture progress.
• plugins/os-prefs (renamed from time-prefs): it was about to gain a second, unrelated reading (Developer Options' animator duration scale) alongside its existing time-format read, so it's renamed to match -- the custom counterpart to the official @tauri-apps/plugin-os (static device info), but for OS preferences instead.
• The settle animation (snap back on cancel, finish the slide on commit -- matching how native Android's own predictive-back completes the motion regardless of exact release point) is scaled by that OS animator duration scale.
• android:enableOnBackInvokedCallback="true" is required on <application> for any of this to activate. update_android_manifest() only inserts child elements before a closing tag, with no path to an attribute on the tag itself, so instead plugins/predictive-back/android/src/main/AndroidManifest.xml declares its own <application> with that attribute, and Android's standard Gradle library-manifest merge folds it into the consuming app's final manifest automatically -- the same mechanism alarm-manager and wear-sync already rely on for their own receivers and services. No app-shell-level wiring needed.

Two device-only bugs found and fixed

Both were only reproducible on a real device (Pixel 8 Pro) -- neither showed up in review or in the emulator-free CI checks:

• Committing a gesture calls router.history.back(), which is asynchronous -- popstate fires on a later tick (confirmed ~17ms later via direct device logging). Resetting the underlay/transform in the same tick visibly animated the outgoing screen snapping back into view, and the incoming screen then inherited that same still-running animation once the route swap landed mid-animation -- looking exactly like the incoming screen was "sliding in". Fixed by deferring the reset to a location.pathname effect that only fires once the navigation has actually landed.
• @tanstack/router-core's defaultViewTransition option (configured as a function, per its own documented pattern) is only ever checked for truthiness by the installed version -- never actually invoked -- so the discrete View Transition system can't be suppressed the documented way for a raw history.back() call. Confirmed via direct source inspection and a temporary document.startViewTransition monkey-patch that logged every real call. Worked around by setting the same internal flag commitLocation() would have set. This also means ordinary (non-gesture) navigation's directional slide CSS types likely never actually apply anywhere in the app currently -- a genuine pre-existing issue, out of scope to fix broadly here.

Review fixes

A few issues surfaced in review, all fixed:

• ScreenStack only collapsed back to the entry directly below the top, so a couple of existing navigation flows that reach a second leaf without passing back through Home first (e.g. Settings' test-ringing button, whose dismissal navigates forward with replace: true rather than history.back()) grew the stack by a few entries on every repeat, unboundedly over a long-running session. Fixed by collapsing to any earlier matching entry, bounding growth by the number of distinct paths actually visited.
• RouteStage's gesture-lifecycle effect cleanup cancelled its settle timers but not the commit's 1-second finalize-fallback timer, so a brand-new gesture starting while a previous commit's navigation was still stalled could later have that orphaned timer fire mid-gesture, forcibly hiding the underlay. Fixed by also clearing it (and resetting the pending-commit flag) in the cleanup.
• The os-prefs rename left its frontend time-format wrapper (utils/timePrefs.ts, export TimePrefs) still named after the retired time-prefs plugin. Renamed to utils/timeFormatPrefs.ts / TimeFormatPrefs, matching AnimationScale.ts's feature-scoped naming for the plugin's other reading.

Test plan

• cargo test --workspace, pnpm -r run typecheck, pnpm --filter threshold test all clean
• Real-device-verified on a Pixel 8 Pro via scripts/build-android-dev.sh: swipe-back on Edit Alarm/Settings shows the real previous screen peeking through; partial swipe + release snaps back smoothly; full commit finishes the slide (with a fade) and navigates once, cleanly, with no ghosting or double-animation; gesture survives a screen-off/on cycle; Home/Ringing correctly disable the gesture; desktop is unaffected

🤖 Generated with Claude Code

https://claude.ai/code/session_01MM1S4DNyxhwcbkMcx3hDp2

[ScottMorris]

IN the spirit of the Tauri plugins managing themselves this looks like it should be managed by the predictive-back plugin itself. If others were to use it they'd want this done as well.

[ScottMorris]

This file is written with forced line wraps

[ScottMorris]

This file is written with forced line wraps!