embedded: add ghostty_surface_is_alternate_screen

[teamleaderleo]

Adds a cheap C API query for whether a surface's terminal is on the alternate screen:

GHOSTTY_API bool ghostty_surface_is_alternate_screen(ghostty_surface_t);

Implementation: Surface.isAlternateScreen() takes renderer_state.mutex (lockUncancelable), reads io.terminal.screens.active_key == .alternate, and unlocks. This is the same locking as ghostty_surface_mouse_captured / Surface.mouseCaptured(), and the export sits next to it in embedded.zig and ghostty.h.

Why: cmux#14863 (manaflow-ai/cmux#14863) gates text-editing gestures and the terminalAlternateScreen shortcut when-key on whether the terminal is in the alternate screen. It currently detects that through a costlier probe (viewport serialization with a cached result). This export lets cmux replace that with a direct query.

cmux will adopt this in a follow-up after it lands. #14863 does not bump the submodule.

Not compiled locally; the fork's Test workflow skips build jobs, so this is unbuilt until a GhosttyKit build picks it up.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Adds a cheap C API query to check whether a surface's terminal is in the alternate screen.

• Exposes ghostty_surface_is_alternate_screen alongside ghostty_surface_mouse_captured, using the same renderer state mutex locking.
• Lets cmux replace its costlier viewport-serialization probe when gating text-editing gestures and the terminalAlternateScreen shortcut.

^{Written for commit 1021743. Summary will update on new commits.}

Summary by CodeRabbit

• New Features
  • Added an API to check whether a terminal surface is currently displaying the alternate screen.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 4bed309c-027b-4743-b8ec-e4340411a035

📥 Commits

Reviewing files that changed from the base of the PR and between b84832a and 1021743.

📒 Files selected for processing (3)

• include/ghostty.h
• src/Surface.zig
• src/apprt/embedded.zig

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds a public API to query whether a terminal surface’s active screen is the alternate screen. The implementation checks the active screen while holding the renderer-state mutex.

Changes

Alternate-screen query

Layer / File(s)	Summary
Expose alternate-screen state include/ghostty.h, src/apprt/embedded.zig, src/Surface.zig	The header declares ghostty_surface_is_alternate_screen. The embedded implementation forwards the query to the surface method, which checks whether the active screen is .alternate under the renderer-state mutex.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Feature

Suggested reviewers: mitchellh

Merge Risk: ⚪ Minimal · up to 10217

The new query exposes the active-screen state through the public C API. No concrete behavior or integration failure is evident; normal build checks remain appropriate.

Architecture Summary

Architecture risk: 🔵 Low · up to 10217

The change affects 2 systems.

Changed systems: src, include

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — src (service) was modified; 2 changed files map to changed impact.
• observed — include (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in include/ghostty.h: Added the ghostty_surface_is_alternate_screen declaration and comments describing its alternate-screen query and renderer-state mutex use.
• observed — Modified behavior in src/Surface.zig: Added the public isAlternateScreen query; it reads the active screen key under the renderer-state mutex and returns whether it is .alternate.
• observed — Modified behavior in src/apprt/embedded.zig: Added the exported ghostty_surface_is_alternate_screen function, which returns the core surface’s alternate-screen state.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the embedded ghostty_surface_is_alternate_screen API.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[teamleaderleo]

Compile check: rebased onto current main (clean cherry-pick) and built the embedded C API library on Linux with zig build -Dapp-runtime=none -Di18n=false. libghostty-internal.so exports ghostty_surface_is_alternate_screen next to ghostty_surface_mouse_captured. Linux needed a local-only stub for two pre-existing CoreText-only lines in embedded.zig (face.font.copyPostScriptName / copyAttribute(.url), not touched by this PR); nothing else errored. Self-review found no issues; CodeRabbit had no actionable comments.