fix(ios): prevent keyboard transition bounce loop

[azooz2003-bit]

Prevent reentrant keyboard-frame handling while a transition is being applied. This stops the terminal dock from repeatedly starting opposing layout transitions when UIKit emits a nested frame notification.

---

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

---

Summary by cubic

Prevents the terminal dock from bouncing by guarding against reentrant keyboard-frame handling. The new flag stops opposing layout transitions when UIKit emits a nested frame notification.

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

---

Note

Low Risk
Small, localized change to keyboard notification handling on iOS terminal layout; no auth, data, or API surface impact.

Overview
Adds a reentrancy guard on keyboardWillChangeFrame in GhosttySurfaceHostView so nested keyboardWillChangeFrame notifications are ignored while a transition is already being handled.

The host sets isHandlingKeyboardTransition at entry and clears it in defer before calling beginKeyboardLeg. That stops UIKit from starting opposing dock layout legs when a frame notification fires again during the same synchronous handling path (the bounce loop described in the PR).

^{Reviewed by Cursor Bugbot for commit e783402. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes
  • Improved keyboard transition handling to prevent duplicate or overlapping events from being processed.
  • Reduced the risk of unexpected terminal layout behavior during rapid keyboard changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cmux166	Ready	Preview	Sep 8, 2026 9:09pm UTC
cmux41	Ready	Preview	Sep 8, 2026 9:09pm UTC

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 5f33c286-933c-4618-aba6-b68d5f2a0b74

📥 Commits

Reviewing files that changed from the base of the PR and between 742e680 and e783402.

📒 Files selected for processing (1)

• Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceHostView.swift

Included review availability: Your plan provides up to 10 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

The keyboard frame handler now prevents reentrant processing. A private state flag tracks active handling and resets after each notification.

Changes

Keyboard transition handling

Layer / File(s)	Summary
Reentrant keyboard transition guard Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceHostView.swift	The view tracks whether keyboard transition handling is active. Nested notifications return early, and the flag resets with defer after processing.

Priority: ⬇️ Low

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

Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to e7834

Keyboard frame changes now ignore nested transition callbacks, preventing opposing dock-layout transitions while preserving subsequent notification handling. No current merge-readiness risk remains.

🚥 Pre-merge checks | ✅ 23 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains what changed and why, but it omits the required Testing, Demo Video, Review Trigger, and Checklist sections.	Add the required sections from the repository template. Document testing and manual verification, provide a demo video or state the applicable attachment, include the review trigger block, and complete the checklist.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 1 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (23 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: preventing a keyboard transition bounce loop on iOS.
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.
Cmux Swift Actor Isolation	✅ Passed	PASS. The commit changes only GhosttySurfaceHostView.swift and adds a private transition flag plus a defer reset in keyboardWillChangeFrame. GhosttySurfaceHostView is explicitly @MainActor a…
Cmux Swift Blocking Runtime	✅ Passed	PASS. The diff adds only a MainActor-isolated Boolean reentrancy guard and a defer reset in keyboardWillChangeFrame. It adds no semaphore, blocking wait, sleep, delayed dispatch, polling, synchron…
Cmux Browser Automation Off-Main	✅ Passed	PASS: The pull request changes only Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceHostView.swift, adding a reentrancy guard to keyboardWillChangeFrame. The patch adds no…
Cmux Expensive Synchronous Load	✅ Passed	The commit changes only GhosttySurfaceHostView.swift: it adds a Boolean guard and defer cleanup in keyboardWillChangeFrame. The changed lines add no agent-history load, file scan, JSON/JSONL par…
Cmux Cache Substitution Correctness	✅ Passed	PASS: The diff only adds a reentrancy flag and defer cleanup around keyboardWillChangeFrame. It does not replace an authoritative read with a cache or alter any persistence, history, undo, or snap…
Cmux No Hacky Sleeps	✅ Passed	PASS. The commit changes only GhosttySurfaceHostView.swift, which is Swift and outside this check's TypeScript, JavaScript, shell, and non-Swift build/runtime scope. The diff adds a reentrancy guard…
Cmux Algorithmic Complexity	✅ Passed	PASS. The diff adds one Boolean property and constant-time guard/defer logic in GhosttySurfaceHostView.keyboardWillChangeFrame. It does not add collection iteration, filtering, sorting, rescanning, …
Cmux Swift Concurrency	✅ Passed	PASS. The pull request changes only GhosttySurfaceHostView.swift and adds a reentrancy flag with guard, assignment, and defer cleanup around the existing UIKit notification callback. The diff ad…
Cmux Swift @Concurrent	✅ Passed	PASS: The pull request changes only a stored Boolean and the synchronous @objc keyboardWillChangeFrame(_:) method in the @MainActor GhosttySurfaceHostView. The added code contains no async, …
Cmux Swift Package Boundaries	✅ Passed	PASS. The diff adds only a private reentrancy flag and guard to GhosttySurfaceHostView.keyboardWillChangeFrame in Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal. The surrounding code i…
Cmux Swiftpm Lockfiles	✅ Passed	PASS. The pull request changes only Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceHostView.swift. The diff adds a keyboard-transition guard and does not change `Package.sw…
Cmux Swift Logging	✅ Passed	PASS. The diff adds only isHandlingKeyboardTransition state and guard/defer logic in GhosttySurfaceHostView.swift. It adds no print, debugPrint, dump, NSLog, Logger, file logging, or sen…
Cmux User-Facing Error Privacy	✅ Passed	PASS. The commit changes only GhosttySurfaceHostView.swift and adds a private Boolean plus a reentrancy guard in keyboardWillChangeFrame. The added lines contain no user-facing errors, alerts, com…
Cmux Full Internationalization	✅ Passed	PASS. The commit changes only GhosttySurfaceHostView.swift and adds a private Boolean plus guard/defer control flow. It adds no user-facing text, localization key, catalog entry, web message, metada…
Cmux Swiftui State Layout	✅ Passed	PASS. The commit changes only GhosttySurfaceHostView.swift, a UIKit UIView bridge, and adds a private Boolean guard in keyboardWillChangeFrame. The diff introduces no SwiftUI state, `GeometryRea…
Cmux Architecture Rethink	✅ Passed	PASS. The diff adds only a private, @MainActor-local reentrancy guard and a defer reset around the existing keyboardWillChangeFrame callback. It adds no sleep, delayed dispatch, polling, lock, obs…
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PASS. The commit changes only GhosttySurfaceHostView.swift by adding a reentrancy flag to keyboardWillChangeFrame. GhosttySurfaceHostView is a UIView; the diff adds no NSWindow, NSPanel, `…
Cmux Source Artifacts	✅ Passed	The pull request changes one tracked path: Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceHostView.swift. The diff adds a private Swift property and reentrancy guard to an …
Cmux No Test Or Debug Seam In Production Source	✅ Passed	PASS. The PR changes only Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceHostView.swift. It adds the private isHandlingKeyboardTransition state and uses it to guard real …
Cmux No Ambient Global State	✅ Passed	PASS: The commit adds private var isHandlingKeyboardTransition = false at line 57 inside the existing constructable GhosttySurfaceHostView class. The guard and defer at lines 412–414 use per-ins…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ios-keyboard-bounce

---

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