cmux/docs/ghostty-fork.md

Ghostty Fork Changes (manaflow-ai/ghostty)

This repo uses a fork of Ghostty for local patches that aren't upstream yet. When we change the fork, update this document and the parent submodule SHA.

Fork update checklist

1. Make changes in ghostty/.
2. Commit and push to manaflow-ai/ghostty.
3. Update this file with the new change summary + conflict notes.
4. In the parent repo: git add ghostty and commit the submodule SHA.

Current fork changes

Fork rebased onto upstream v1.3.0 plus newer main commits as of March 12, 2026.

1) OSC 99 (kitty) notification parser

• Commit: a2252e7a9 (Add OSC 99 notification parser)
• Files:
  • src/terminal/osc.zig
  • src/terminal/osc/parsers.zig
  • src/terminal/osc/parsers/kitty_notification.zig
• Summary:
  • Adds a parser for kitty OSC 99 notifications and wires it into the OSC dispatcher.

2) macOS display link restart on display changes

• Commit: c07e6c5a5 (macos: restart display link after display ID change)
• Files:
  • src/renderer/generic.zig
• Summary:
  • Restarts the CVDisplayLink when setMacOSDisplayID updates the current CGDisplay.
  • Prevents a rare state where vsync is "running" but no callbacks arrive, which can look like a frozen surface until focus/occlusion changes.

3) Keyboard copy mode selection C API

• Commit: a50579bd5 (Add C API for keyboard copy mode selection)
• Files:
  • src/Surface.zig
  • src/apprt/embedded.zig
• Summary:
  • Restores ghostty_surface_select_cursor_cell and ghostty_surface_clear_selection.
  • Keeps cmux keyboard copy mode working against the refreshed Ghostty base.

4) macOS resize stale-frame mitigation

Sections 3 and 4 are grouped by feature, not by commit order. The section 4 resize commits were applied earlier than the section 3 copy-mode commit, but they are kept together here because they touch the same stale-frame mitigation path and tend to conflict in the same files during rebases.

• Commits:
  • 769bbf7a9 (macos: reduce transient blank/scaled frames during resize)
  • 9efcdfdf8 (macos: keep top-left gravity for stale-frame replay)
• Files:
  • pkg/macos/animation.zig
  • src/Surface.zig
  • src/apprt/embedded.zig
  • src/renderer/Metal.zig
  • src/renderer/generic.zig
  • src/renderer/metal/IOSurfaceLayer.zig
• Summary:
  • Replays the last rendered frame during resize and keeps its geometry anchored correctly.
  • Reduces transient blank or scaled frames while a macOS window is being resized.

5) zsh prompt redraw markers use OSC 133 P

• Commit: 8ade43ce5 (zsh: use OSC 133 P for prompt redraws)
• Files:
  • src/shell-integration/zsh/ghostty-integration
• Summary:
  • Emits one OSC 133;A fresh-prompt mark for real prompt transitions.
  • Uses OSC 133;P markers for prompt redraws so async zsh themes do not look like extra prompt lines.

6) zsh Pure-style multiline prompt redraws

• Commits:
  • 0cf559581 (zsh: fix Pure-style multiline prompt redraws)
  • 312c7b23a (zsh: avoid extra Pure continuation markers)
• Files:
  • src/shell-integration/zsh/ghostty-integration
• Summary:
  • Handles multiline prompts that use \n%{\r%} to return to column 0 before the visible prompt line.
  • Keeps redraw-safe prompt-start markers for async themes.
  • Avoids inserting an explicit continuation marker after Pure's hidden carriage return, because Ghostty already tracks the newline as prompt continuation and the extra marker duplicates the preprompt row.

The fork branch HEAD is now the section 6 zsh redraw commit.

Upstreamed fork changes

cursor-click-to-move respects OSC 133 click-to-move

• Was local in the fork as 10a585754.
• Landed upstream as bb646926f, so it is no longer carried as a fork-only patch.

Merge conflict notes

These files change frequently upstream; be careful when rebasing the fork:

• src/terminal/osc/parsers.zig

  • Upstream uses std.testing.refAllDecls(@This()) in test {}.
  • Ensure iterm2 import stays, and keep kitty_notification import added by us.

• src/terminal/osc.zig

  • OSC dispatch logic moves often. Re-check the integration points for the OSC 99 parser.

• src/shell-integration/zsh/ghostty-integration

  • Prompt marker handling is easy to regress when upstream adjusts zsh redraw behavior. Keep the OSC 133;A vs OSC 133;P split intact for redraw-heavy themes. Pure-style \n%{\r%} prompt newlines should not get an extra explicit continuation marker after the hidden CR.

If you resolve a conflict, update this doc with what changed.