Fix terminal first render for Cmd+N workspaces

Closed
AU
2mo ago
+365-5

Summary

  • add a regression test for the real Cmd+N workspace-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 -> true portal 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.

  1. Brand-new visible terminal path
    GhosttySurfaceScrollView.setVisibleInUI(_:) already calls refreshSurfaceNow(...) 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 that false -> true visibility transition.

    On that path, the runtime Ghostty surface becomes ready, terminalSurfaceDidBecomeReady fires, 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.

  2. 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

  1. Cold-launch cmux.
  2. Open multiple workspaces with Cmd+N in the main window.
  3. Observe that one of the newly selected workspaces can stay blank even though the workspace is selected and the terminal runtime is alive.
  4. 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.
  5. Click or switch to another workspace/tab and then switch back.
  6. 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.py
  • tests_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:

  • 8f030400 test only for new visible workspaces
  • 3eb2c00f fix for runtime-surface-ready visible redraw
  • a8d3b6b5 test only for existing-workspace first return
  • 5737b45b fix for workspace-selection follow-up reconciliation

Issue relationship

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