tmux: display-popup support

[daiimus]

Summary

Support tmux's `display-popup` command, which creates an overlay popup pane.

What's needed

Zig side (Ghostty fork)

1. Send `display-popup` command with appropriate arguments
2. Handle the popup pane lifecycle — popup panes appear as regular panes with output, but are temporary

Swift side (Geistty)

3. Render the popup as an overlay view on top of the current terminal
4. Handle popup dismissal

Why this matters

`display-popup` is increasingly used by tmux users and plugins (e.g., tmux-fzf, lazygit popup). Without support, popup content may appear as garbled output or be lost.

Considerations

• Popup behavior in control mode may differ from regular mode
• Need to verify how tmux surfaces popup pane creation/destruction in control mode notifications
• May require `%layout-change` or a new notification type

Priority

Low — niche feature used by power users and specific plugins.

Upstream potential

Fully upstreamable.

[daiimus]

Current Implementation

Swift side (Geistty)

• docs/archive/TMUX_INTEGRATION.md:238-239 — Future work: "tmux 3.2+ popup windows" / "Could map to iOS sheets/popovers"
• NOT FOUND — No display-popup implementation exists

Zig fork side (ios-external-backend)

• NOT FOUND — No popup support in the fork

What upstream needs

• display-popup command support in the viewer
• Popup output rendering — tmux popups create a floating pane with its own content
• %popup-close or equivalent notification handling (if tmux sends one in control mode)
• For iOS (Geistty), this could map to UIKit sheets/popovers as the archived doc suggests
• For upstream desktop Ghostty, this could be a floating window or overlay
• Requires tmux 3.2+ — version gating (tmux: version-gated behavior for tmux 3.4+ features #97) would be relevant here

[daiimus]

Plain SSH vs tmux mode

tmux-only. Popup windows are a tmux feature (tmux 3.2+). Plain SSH sessions have no equivalent floating pane concept. The rendering challenge (floating overlay on a Ghostty surface) is tmux-specific.

[daiimus]

Upstream Ghostty impact

Hard for both desktop and iOS. Tmux popups are floating panes rendered as overlays. Neither desktop apprt (GTK or macOS) has floating overlay rendering for terminal surfaces today. This would be a significant new capability requiring:

• A new surface type or rendering mode for floating/popup terminals
• Z-ordering and positioning relative to the parent pane
• Input routing to the popup while it's active

On desktop, this could potentially map to a floating window or a compositor overlay. On iOS (Geistty), it could map to a UIKit sheet or popover. Both are substantial features.

[daiimus]

Analysis: display-popup is blocked by the tmux protocol

After thorough investigation of tmux's control mode protocol and the Ghostty fork's architecture:

Finding: No control mode support for popups

tmux does not support display-popup in control mode. There are no %popup-* notifications in the tmux control mode protocol (verified against tmux man page through v3.6a).

The complete set of tmux control mode notifications was enumerated. None relate to popups:

%client-detached, %client-session-changed, %config-error, %continue, %exit, %extended-output, %layout-change, %message, %output, %pane-mode-changed, %paste-buffer-changed, %paste-buffer-deleted, %pause, %session-changed, %session-renamed, %session-window-changed, %sessions-changed, %subscription-changed, %unlinked-window-add, %unlinked-window-close, %unlinked-window-renamed, %window-add, %window-close, %window-pane-changed, %window-renamed

How popups work in normal (non-control) mode

In a normal terminal, display-popup works because tmux itself renders the popup using terminal escape sequences — it draws a box, runs a command inside it, and handles input routing. The terminal emulator doesn't know it's a "popup" — it just sees escape sequences.

In control mode, the client owns all rendering. tmux would need to tell the client:

1. "A popup opened at position X,Y with size WxH"
2. Stream the popup's terminal output separately from pane output
3. "The popup closed"

None of this protocol exists.

iOS architectural advantage

Ironically, iOS is architecturally better positioned for popup support than desktop Ghostty:

• UIKit natively supports view layering/z-ordering
• SwiftUI has .overlay() modifiers
• Creating a floating interactive terminal overlay is trivial with UIKit
• The ghostty_surface_tmux_attach_to_pane C API could theoretically bind a popup surface to a popup terminal

The problem isn't rendering capability — it's that tmux gives us nothing to render.

Possible approaches

Approach	Description	Feasibility
Wait for tmux upstream	tmux could add %popup-* notifications in a future version	Unknown timeline; no open PRs or issues in tmux
Client-side popup emulation	Intercept display-popup intent, create a local terminal overlay running the popup's command directly	Most feasible; doesn't depend on tmux changes; but breaks tmux session semantics (popup runs locally, not on the remote server)
Hook-based detection	Use tmux hooks to detect popup open/close	Can detect lifecycle but cannot get popup content stream
Defer	Acknowledge the protocol limitation and move on	Honest

Recommendation

Re-scope this issue to either:

1. Client-side popup emulation (significant effort, questionable value)
2. Deferred until tmux adds control mode popup support

This is a tmux protocol limitation, not a Ghostty implementation gap.

[daiimus]

Status: Blocked

Formally marking this as blocked. The dilemma:

tmux's control mode protocol has no popup support. There are no %popup-* notifications — display-popup works in normal mode because tmux itself draws the popup using escape sequences. In control mode, the client owns rendering, but tmux provides no lifecycle events or content stream for popups. We can't render what we're never told about.

The options are all bad:

• Wait for tmux upstream — no indication this is coming; no open PRs or issues in the tmux project
• Client-side emulation — we could intercept the intent and spawn a local overlay, but the popup's command would run locally instead of on the remote server, breaking tmux session semantics entirely
• Hook-based detection — set-hook could tell us a popup opened/closed, but still can't give us the popup's output stream

Until tmux adds control mode notification support for popups, this issue is architecturally impossible to implement correctly. Leaving it open as a tracking issue but removing it from active work.