Skip to content

chore(desktop): upgrade Tauri to 2.11.x to fix blank window after sleep on macOS#600

Merged
tlongwell-block merged 1 commit into
mainfrom
chore/upgrade-tauri-2.11
May 15, 2026
Merged

chore(desktop): upgrade Tauri to 2.11.x to fix blank window after sleep on macOS#600
tlongwell-block merged 1 commit into
mainfrom
chore/upgrade-tauri-2.11

Conversation

@tlongwell-block

Copy link
Copy Markdown
Collaborator

What

Bumps the desktop Tauri runtime to 2.11.x.

Crate From To
tauri 2.10.3 2.11.1
tauri-runtime 2.10.1 2.11.1
tauri-runtime-wry 2.10.1 2.11.1
wry 0.54.4 0.55.1
tao 0.34.8 0.35.2
tauri-build 2.5.6 2.6.1
@tauri-apps/api ~2.10 ~2.11
@tauri-apps/cli ~2.10 ~2.11

Why

After leaving the laptop locked/asleep for a long while, the Sprout window comes back blank and only a full app restart recovers it.

Root cause is a known WKWebView behavior on macOS: the OS aggressively suspends/terminates a backgrounded WebContent process to reclaim memory. When the user returns, the Tauri NSWindow is still alive but its webview is empty, with no JS context to recover from.

Until tauri-runtime-wry 2.11.0, wry had no plumbing for the underlying webViewWebContentProcessDidTerminate delegate, so apps had no chance to react. 2.11.x ships a default macOS/iOS handler that calls webview.reload() on web content process termination, so the window self-heals after a wake — exactly the recovery this bug needs. Sprout requires no app-side changes to opt in; the fix is inherited by bumping the runtime.

Confirmed by reading the released crate source (tauri-runtime-wry-2.11.1/src/lib.rs registers a default with_on_web_content_process_terminate_handler that logs and reloads; that code is absent in 2.10.1).

Related upstream:

How

cd desktop/src-tauri && cargo update -p tauri --precise 2.11.1
# bump @tauri-apps/api and @tauri-apps/cli to ~2.11 in desktop/package.json
cd desktop && pnpm install

desktop/src-tauri/Cargo.toml already specifies caret-2 for all tauri-* crates, so no manifest edits were needed — only the lockfile moved.

Verified locally

  • cargo check on desktop/src-tauri: clean
  • cargo clippy --no-deps: clean (33 pre-existing warnings, none new)
  • cargo fmt --check: clean
  • pnpm typecheck: clean
  • pnpm lint (biome): clean
  • pnpm build (vite): clean
  • Pre-commit + pre-push hooks (desktop-check, desktop-tauri-check, desktop-build, rust-clippy, rust-tests, mobile-check, mobile-test, web-build): all green

Smoke test plan for the bug itself

  1. Run the new build, leave it open with a relay connection.
  2. Lock the laptop and leave it overnight (or several hours with significant memory pressure).
  3. Unlock — the window should auto-reload instead of staying blank. Console.app filtered to the Sprout process should show web content process terminated from Tauri's default handler at the moment it triggers.

Risk

Low. Caret-2 already allowed 2.11 on the next cargo update; this PR just makes it deliberate. Plugin crates and Tauri's own API surface are additive between 2.10→2.11. Two areas worth a manual eyeball before merge:

  • Updater plugin — version-coupled to Tauri internals. Verify update checks still work in a release build.
  • Deep-link plugin + single-instance — likewise. Verify a sprout:// deep link from another app still focuses the running instance.

Out of scope (worth doing separately)

  • No top-level React ErrorBoundary in desktop/src. If anything throws on wake-time re-render the tree unmounts → same blank-screen symptom from a different cause. Worth adding regardless of this bump.
  • prevent_sleep.rs uses PreventUserIdleSystemSleep which keeps the system awake while agents are active but does not prevent the WebContent process from being jetsam'd on lid-close/lock. The Tauri upgrade is the right place to fix that; nothing to change in prevent_sleep.

@tlongwell-block tlongwell-block force-pushed the chore/upgrade-tauri-2.11 branch 2 times, most recently from 6927615 to 4163217 Compare May 15, 2026 21:51
…ep on macOS

macOS aggressively suspends/terminates WKWebView's WebContent process during
long screen-lock/sleep. Until tauri-runtime-wry 2.11.0, there was no default
handler for this, so on resume the Tauri window remained alive but the webview
rendered blank with no JS context — only an app restart recovered it.

tauri-runtime-wry 2.11.x ships a default macOS/iOS handler that calls
webview.reload() on web content process termination (via the new wry
webViewWebContentProcessDidTerminate hook). We inherit this automatically by
bumping the runtime.

Bumps (via cargo update -p tauri --precise 2.11.1 in desktop/src-tauri):
- tauri              2.10.3 -> 2.11.1
- tauri-runtime      2.10.1 -> 2.11.1
- tauri-runtime-wry  2.10.1 -> 2.11.1
- wry                0.54.4 -> 0.55.1
- tao                0.34.8 -> 0.35.2
- tauri-build        2.5.6  -> 2.6.1
- tauri-utils        2.8.3  -> 2.9.1
- @tauri-apps/api    ~2.10  -> ~2.11
- @tauri-apps/cli    ~2.10  -> ~2.11

Verified:
- cargo check / clippy --no-deps / fmt --check on desktop/src-tauri: clean
- pnpm typecheck / lint / build on desktop/: clean

Refs: tauri-apps/tauri#10662, tauri-apps/tauri#14523, tauri-apps/wry#1619
Signed-off-by: Tyler Longwell <109685178+tlongwell-block@users.noreply.github.com>
@tlongwell-block tlongwell-block force-pushed the chore/upgrade-tauri-2.11 branch from 4163217 to 605469c Compare May 15, 2026 22:03
@tlongwell-block tlongwell-block merged commit d1097aa into main May 15, 2026
15 checks passed
@tlongwell-block tlongwell-block deleted the chore/upgrade-tauri-2.11 branch May 15, 2026 22:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant