Fix terminal first render for Cmd+N workspaces
Summary
- add a regression test for the real
Cmd+Nworkspace-creation path that requires the newly selected workspace to present a terminal frame without any follow-up tab switch - add a regression test for switching back to an already-existing workspace, requiring the first return to present a frame without a second switch
- refresh a visible terminal again when its runtime Ghostty surface reports ready, reusing the same redraw nudge that already exists for
visible=false -> trueportal visibility restores - start the workspace-level portal/layout follow-up loop when a workspace is reselected so remounted terminal and browser portals get a first-return reconciliation pass immediately
References:
Root cause
There are two closely related first-visible-frame gaps here.
-
Brand-new visible terminal path
GhosttySurfaceScrollView.setVisibleInUI(_:)already callsrefreshSurfaceNow(...)when a terminal becomes visible again after being hidden, which is why switching away and back immediately recovers the blank view. But a brand-new selected workspace starts out visible on its first SwiftUI render, so it never passes through thatfalse -> truevisibility transition.On that path, the runtime Ghostty surface becomes ready,
terminalSurfaceDidBecomeReadyfires, and the code only re-ran first-responder focus handling. There was no equivalent visible redraw nudge at surface-ready time, so the first Metal frame could remain blank until a later tab/workspace switch toggled visibility and finally hit the existing refresh path. -
Existing workspace remount / first-return path
Several user reports are broader than brand-new workspaces: an already-existing workspace comes back blank on the first switch and only recovers after another switch. The shared workspace-level follow-up loop is the path that reconciles terminal and browser portal visibility after attach/remount, but workspace selection did not start that loop at all.That meant a reselected workspace could remount portal-hosted views and restore focus without ever running the shared post-attach reconciliation pass until some later interaction caused a second visibility/layout churn.
Reproduction
- Cold-launch cmux.
- Open multiple workspaces with
Cmd+Nin the main window. - Observe that one of the newly selected workspaces can stay blank even though the workspace is selected and the terminal runtime is alive.
- Wait for time-to-first-render: affected workspaces can stay blank indefinitely, or in the 3068 report roughly a minute, until another selection change happens.
- Click or switch to another workspace/tab and then switch back.
- The terminal content immediately appears, showing that the runtime surface existed and only the visible first-frame refresh / remount reconciliation was missing.
The same family also explains broader reports where returning to an existing workspace blanks on the first switch but recovers on a second switch, and why browser panes have shown a similar “white until another selection/layout churn” symptom.
Regression tests
tests_v2/test_workspace_shortcut_initial_render.pytests_v2/test_workspace_switch_initial_render.py
The first test drives the real Cmd+N shortcut path instead of socket background workspace.create, creates a burst of workspaces to amplify the attach timing churn, and asserts that the final selected workspace presents at least one terminal frame without any manual tab switch, typing, or refresh-surfaces workaround.
The second test warms two existing workspaces, switches between them repeatedly, and requires each first return to present a new frame without a second switch. That locks the broader remount/reattach path covered by user reports outside the brand-new-workspace case.
The commits keep the repository’s failure-before-fix structure:
8f030400test only for new visible workspaces3eb2c00ffix for runtime-surface-ready visible redrawa8d3b6b5test only for existing-workspace first return5737b45bfix for workspace-selection follow-up reconciliation
Issue relationship
- This PR should close https://github.com/manaflow-ai/cmux/issues/3068.
- I still do not think it should automatically close https://github.com/manaflow-ai/cmux/issues/2555 yet. This PR now covers more of the workspace-selection/remount family, but
2555also includes longer-running-session and browser-specific reports that may still have additional causes.
Nightly status
At the time of this update, current origin/main / nightly does not contain this fix stack. The branch includes commits not present on origin/main, so reproducing on current nightly is expected unless another unrelated fix lands separately.
Testing
- Not run locally per repository policy.
- Verified
git diff --check. - Verified Python syntax with
python3 -m py_compile tests_v2/test_workspace_shortcut_initial_render.py tests_v2/test_workspace_switch_initial_render.py.
[!NOTE]
Medium Risk
Touches workspace selection and portal/layout follow-up scheduling, which can affect focus/visibility timing across terminals and browser panels, but is limited to UI rendering behavior with added regression coverage.
Overview
Fixes a blank-first-frame regression where newly created or reselected workspaces could show mounted terminal/browser portals without presenting an initial frame until a second workspace/tab switch.
When a terminalSurfaceDidBecomeReady notification arrives for a visible terminal, GhosttyTerminalView now triggers an immediate refreshSurfaceNow to nudge the first Metal frame. Workspace selection also now starts a dedicated selection render follow-up (scheduleSelectionRenderFollowUp) so remounted portal-hosted views get an immediate post-attach reconciliation pass.
Adds two tests_v2 regressions that drive the real Cmd+N creation path and repeated workspace switching, asserting presentCount advances without any extra user interaction.
Reviewed by Cursor Bugbot for commit 51ab42993a70e75968b5ea2e83a388d26aca73d9. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by CodeRabbit
-
Bug Fixes
- Improved rendering performance when switching between workspaces and creating new workspaces
- Terminal content now displays more promptly during initial workspace selection
-
Tests
- Added regression tests for workspace creation and switching rendering behavior
Closes #3068