cmux-next agent pane: apply a render-rate change to the live page

[teamleaderleo]

Summary

Follows #16487. The agent pane's render rate can now change on a live page. Before this, changing it with the adaptive governor or the full_rate debug action did nothing (measured). WebKit reads PreferPageRenderingUpdatesNear60FPSEnabled only when the page's visibility changes, so a pane kept the rate it was created with.

Change. When rendersAtFullRate changes, the pane briefly hides its web view and shows it again, which makes WebKit re-read the rate:

1. It takes a snapshot of the page and lays it over the web view.
2. It hides the web view for 33 ms, then shows it.
3. It removes the snapshot 50 ms later.

If there's no snapshot, it skips this rather than blink.

The adaptive governor only changes the rate once a scroll has settled (250 ms after the last scroll), so the switch happens on an idle page and the snapshot matches what's on screen.

Testing

Unit test. AgentPaneRenderingTests.aLiveRateChangeReShowsThePageUnderASnapshot checks the sequence and that setting the current rate does nothing.

• Red at ddbcef0fe88 (stubs only): no hide happens.
• Green: see the next commit.

Live, on cmux-mac-mini (M4) with a 120 Hz virtual display (fleet vdisplay, cmuxterm-hq#1121), using an experiment build of the same mechanism. The pane launched capped, then each variant toggled the rate on and off with a fling after each toggle.

re-apply	after toggling on	after toggling off
none (main today)	181 frames, p50 17 ms	181, 17 ms
hide, 0 ms	181, 17 ms	181, 17 ms
remove from and re-add to the window	181, 17 ms	181, 17 ms
hide 50 ms	360, 8 ms	182, 17 ms
snapshot cover, hide 16 / 33 / 50 ms	361 / 362 / 360, 8 ms	182 / 181 / 181, 17 ms

Flicker. I recorded the virtual display during the toggles and checked the brightness of the pane's header in each frame.

• The plain 50 ms hide shows a blank pane (header gone) for a frame.
• None of the six snapshot-cover toggles shows one.
• The recorder captures at most 60 fps and only when pixels change, so a single 8 ms glitch at 120 Hz could in principle slip through.

Not built locally (no local app builds on this Mac). The Swift test runs in CI.

Changelog

none

Red and green

• aLiveRateChangeReShowsThePageUnderASnapshot:
  • Red at 2894973: (steps.first?.hidden → nil) == true. The first red commit, ddbcef0, didn't compile.
  • Green at 2221e87.
• aLiveRateChangeKeepsKeyboardFocusOnThePage covers a review finding: hiding the web view moved keyboard focus to the window.
  • Red at e1ed3e1: (window.firstResponder → <NSWindow>) === (pane.webView → <WKWebView>).
  • Green at 9a9dc96, where all 38 checks passed, including cmux-next swift test.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RYQHfug1ZVQDp4eWgwVUtD

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Fixes the agent pane's render rate so changing it via the adaptive governor or full_rate takes effect on a live page. WebKit only reads PreferPageRenderingUpdatesNear60FPSEnabled on a page visibility change, so a pane kept the rate it was created with; the pane now briefly hides and re-shows its web view under a snapshot of the page, so nothing visibly blinks.

• On a rate change, the pane snapshots the page, hides the web view for 33 ms, shows it again, and removes the snapshot 50 ms later; without a snapshot it skips the blink, and a WebKit without the feature skips it too.
• Hiding the web view hands keyboard focus to the next key view; the re-apply returns it to the page when the page had it and the user hasn't moved it.
• Adds a snapshot and pause hook, plus tests verifying the re-show sequence, focus retention, and that setting the current rate changes nothing.

^{Written for commit 9a9dc96. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 3d20e668-e5bf-4a78-8b9f-b8e96720a87b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[teamleaderleo]

Subagent review at 9a9dc96: APPROVE.

The two findings from the review at 2221e87 are fixed:

• High: hiding the web view moved keyboard focus to the window. Focus now goes back to the page when it held focus and the user hasn't moved it. aLiveRateChangeKeepsKeyboardFocusOnThePage pins this; it was red at e1ed3e1 with firstResponder being the NSWindow.
• Low: a WebKit without the feature re-showed the page for nothing. The re-apply is now skipped when setWebKitFeature returns false. No test covers it, because a missing feature can't be simulated.

Gap, not blocking: no test covers the case where the user moves focus during the 33 ms hide.