Move active surfaces between panes with automatic directional splits

Merged
AU
4mo ago
+1418-177

Summary

  • add six configurable actions to move the active surface to the previous/next pane in wrapping spatial order or left/right/above/below
  • move through one shared same-workspace transfer path so terminal, browser, and WebView instances retain their live identity and state
  • create an automatic 50/50 split in the requested direction when no adjacent destination exists, while preserving the parent divider extent
  • bound held directional shortcut repeats so they can enter existing panes but never recursively create edge splits
  • expose every action in Keyboard Shortcuts settings, the Command Palette, the View menu, and cmux.json
  • localize labels and shortcut documentation in English and Japanese

Behavior

SurfacePaneMovement is the shared six-action model. Workspace resolves spatial wrapping or Bonsplit directional adjacency, computes the insertion point, and delegates to the existing same-workspace surface transfer machinery used by drag-and-drop. Keyboard routing, Command Palette handlers, View-menu items, and tab context actions converge on the same movement path.

When a directional destination is missing, cmux creates an equal split in that direction and moves the existing surface instance into it. Keyboard auto-repeat can still move into an existing adjacent pane, but cannot create another split while the key is held at an edge. Successful moves insert after the destination pane's selected surface, focus the moved surface, and allow Bonsplit to collapse an emptied source pane. Failed moves restore the previous layout and split-zoom state.

Canvas and remote-tmux mirror layouts reject the action without mutation. Previous/next is a no-op with one pane, and Dock keyboard focus cannot mutate a background workspace.

The existing within-pane actions are labeled “Reorder Surface Left/Right” so they remain distinct from cross-pane movement.

Default shortcuts

  • Previous pane: Control+Command+Shift+[
  • Next pane: Control+Command+Shift+]
  • Left/right/above/below: Option+Command+Shift+Arrow

The directional family adds Shift to the existing Option+Command+Arrow pane-focus bindings. Previous/next adds Control to the existing Command+Shift+[/] surface-navigation family. The defaults are collision-free across current cmux and Ghostty bindings, include Command so they do not steal PTY control sequences, and remain rebindable or unbindable.

Coverage

Behavior-level tests cover:

  • previous/next spatial wrapping
  • all four directional moves, including automatic equal-split creation
  • preservation of parent split extent
  • insertion after destination selection and moved-surface focus
  • source-pane collapse and failure rollback
  • terminal, browser, and WebView identity preservation
  • single-pane no-ops and Canvas/remote-tmux rejection
  • Dock-focus background-workspace protection
  • runtime/Settings default alignment, collision freedom, and Command Palette mapping
  • shared tab-context-action routing

Validation on the merged branch head:

  • 30 focused tests passed across WorkspaceAdjacentPaneMoveTests, DockShortcutRoutingTests, and ReorderShortcutActionTests
  • tagged Debug build passed with ./scripts/reload.sh --tag issue-8752-split
  • PBX normalization and test wiring, workspace package grouping, Package.resolved policy, localization/JSON parsing, locale completeness, and git diff --check passed

At validation time, origin/main had a test-target compile regression. The branch includes the exact reviewed head of upstream repair PR #8857 and a minimal fixture update adding the newly required nil transfer field.

Closes #8752