From 325c15151b2cbc2f5b24b87fcef8d5f9e8d2bd18 Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Sat, 20 Jun 2026 20:57:16 -0700
Subject: [PATCH 1/7] Add iOS scroll-to-bottom toolbar coverage

---
 .../TerminalAccessoryConfigurationTests.swift | 75 ++++++++++++++++++-
 1 file changed, 73 insertions(+), 2 deletions(-)

diff --git a/ios/cmuxPackage/Tests/cmuxFeatureTests/TerminalAccessoryConfigurationTests.swift b/ios/cmuxPackage/Tests/cmuxFeatureTests/TerminalAccessoryConfigurationTests.swift
index cb04c8a51745..8ead02d70584 100644
--- a/ios/cmuxPackage/Tests/cmuxFeatureTests/TerminalAccessoryConfigurationTests.swift
+++ b/ios/cmuxPackage/Tests/cmuxFeatureTests/TerminalAccessoryConfigurationTests.swift
@@ -42,6 +42,8 @@ struct TerminalAccessoryConfigurationTests {
         let tabIndex = try #require(order.firstIndex(of: id(.tab)))
         #expect(order[tabIndex + 1] == id(.escape))
         #expect(order[tabIndex + 2] == id(.returnKey))
+        let pageDownIndex = try #require(order.firstIndex(of: id(.pageDown)))
+        #expect(order[pageDownIndex + 1] == id(.scrollToBottom))
         // Everything is shown on a fresh install, including the now-configurable
         // modifiers (⇧ among them)/zoom/paste.
         for action in TerminalInputAccessoryAction.configurableActions {
@@ -78,9 +80,31 @@ struct TerminalAccessoryConfigurationTests {
         #expect(stored == "builtin.\(TerminalInputAccessoryAction.returnKey.rawValue)")
         let parsed = ToolbarItemID(storageKey: stored)
         #expect(parsed == id(.returnKey))
-        // Appended last: its raw value is the max across all cases.
+        #expect(TerminalInputAccessoryAction.scrollToBottom.rawValue > TerminalInputAccessoryAction.returnKey.rawValue)
+    }
+
+    // MARK: - Scroll to Bottom key
+
+    @Test("Scroll to Bottom is shown by default next to navigation keys and has no byte output")
+    func scrollToBottomDefaultsAndOutput() throws {
+        let config = TerminalAccessoryConfiguration(defaults: freshDefaults())
+        let order = config.displayOrder
+
+        let pageDownIndex = try #require(order.firstIndex(of: id(.pageDown)))
+        #expect(order[pageDownIndex + 1] == id(.scrollToBottom))
+        #expect(config.isEnabled(id(.scrollToBottom)))
+        #expect(TerminalInputAccessoryAction.scrollToBottom.output == nil)
+        #expect(TerminalInputAccessoryAction.scrollToBottom.isUserConfigurable)
+    }
+
+    @Test("Scroll to Bottom's persisted identifier is stable")
+    func scrollToBottomStableIdentifier() {
+        let stored = TerminalInputAccessoryAction.scrollToBottom.itemID.storageKey
+        #expect(stored == "builtin.\(TerminalInputAccessoryAction.scrollToBottom.rawValue)")
+        let parsed = ToolbarItemID(storageKey: stored)
+        #expect(parsed == id(.scrollToBottom))
         let maxRaw = TerminalInputAccessoryAction.allCases.map(\.rawValue).max()
-        #expect(TerminalInputAccessoryAction.returnKey.rawValue == maxRaw)
+        #expect(TerminalInputAccessoryAction.scrollToBottom.rawValue == maxRaw)
     }
 
     // MARK: - Reorder + hide/show round-trips
@@ -417,4 +441,51 @@ struct TerminalAccessoryConfigurationTests {
         let escIndex = try #require(config.displayOrder.firstIndex(of: id(.escape)))
         #expect(config.displayOrder[escIndex + 1] == id(.returnKey))
     }
+
+    // MARK: - Gating test #5: existing v3 layout gains Scroll to Bottom
+
+    @Test("an existing v3 layout without Scroll to Bottom gains it force-enabled after Page Down")
+    func migratesExistingV3LayoutForceEnablingScrollToBottom() throws {
+        let defaults = freshDefaults()
+        // A v3 layout persisted before Scroll to Bottom became configurable.
+        let preScroll: [TerminalInputAccessoryAction] = [
+            .control, .alternate, .command, .shift, .paste,
+            .tab, .escape, .returnKey,
+            .home, .end, .pageUp, .pageDown,
+            .zoomOut, .zoomIn,
+        ]
+        defaults.set(preScroll.map { id($0).storageKey }, forKey: "cmux.terminal.toolbar.order.v3")
+        defaults.set(preScroll.map { id($0).storageKey }, forKey: "cmux.terminal.toolbar.enabled.v3")
+
+        let config = TerminalAccessoryConfiguration(defaults: defaults)
+
+        #expect(config.displayOrder.contains(id(.scrollToBottom)))
+        #expect(config.isEnabled(id(.scrollToBottom)))
+        let pageDownIndex = try #require(config.displayOrder.firstIndex(of: id(.pageDown)))
+        #expect(config.displayOrder[pageDownIndex + 1] == id(.scrollToBottom))
+        for action in preScroll {
+            #expect(config.displayOrder.contains(id(action)))
+            #expect(config.isEnabled(id(action)))
+        }
+    }
+
+    @Test("Scroll to Bottom folded into a v3 layout stays hidden once the user hides it")
+    func foldedScrollToBottomHonorsLaterHide() {
+        let defaults = freshDefaults()
+        let preScroll: [TerminalInputAccessoryAction] = [
+            .control, .alternate, .command, .shift, .paste,
+            .tab, .escape, .returnKey,
+            .home, .end, .pageUp, .pageDown,
+        ]
+        defaults.set(preScroll.map { id($0).storageKey }, forKey: "cmux.terminal.toolbar.order.v3")
+        defaults.set(preScroll.map { id($0).storageKey }, forKey: "cmux.terminal.toolbar.enabled.v3")
+
+        let config = TerminalAccessoryConfiguration(defaults: defaults)
+        #expect(config.isEnabled(id(.scrollToBottom)))
+
+        config.setEnabled(id(.scrollToBottom), false)
+        let reloaded = TerminalAccessoryConfiguration(defaults: defaults)
+        #expect(!reloaded.isEnabled(id(.scrollToBottom)))
+        #expect(reloaded.displayOrder.contains(id(.scrollToBottom)))
+    }
 }

From 32b7d70623e9fb48a6b8e4ecacfcd657a9b52f09 Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Sat, 20 Jun 2026 20:57:21 -0700
Subject: [PATCH 2/7] Restore iOS scroll-to-bottom toolbar button

---
 .../GhosttySurfaceView.swift                  | 27 ++++++++++++++-
 .../TerminalAccessoryConfiguration.swift      | 14 ++++++--
 .../TerminalInputTextView.swift               | 10 ++++++
 ios/cmux/Resources/Localizable.xcstrings      | 34 +++++++++++++++++++
 4 files changed, 81 insertions(+), 4 deletions(-)

diff --git a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
index 2ee6c4f08855..fba4c8ee02f4 100644
--- a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
+++ b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
@@ -215,6 +215,10 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
     /// stable; its default on-bar position is curated separately in
     /// ``defaultConfigurableOrder``.
     case returnKey
+    /// Scroll the terminal viewport to the newest output. Appended at the end so
+    /// existing persisted raw values stay stable; its default on-bar position is
+    /// curated separately in ``defaultConfigurableOrder``.
+    case scrollToBottom
     var title: String {
         title(isMacRemote: false)
     }
@@ -235,6 +239,8 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
             return ""
         case .composer:
             return ""
+        case .scrollToBottom:
+            return ""
         case .escape:
             return String(localized: "terminal.input_accessory.title.escape", defaultValue: "Esc")
         case .tab:
@@ -293,6 +299,7 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
         case .zoomOut: return "terminal.inputAccessory.zoomOut"
         case .zoomIn: return "terminal.inputAccessory.zoomIn"
         case .composer: return "terminal.inputAccessory.composer"
+        case .scrollToBottom: return "terminal.inputAccessory.scrollToBottom"
         case .escape: return "terminal.inputAccessory.escape"
         case .tab: return "terminal.inputAccessory.tab"
         case .returnKey: return "terminal.inputAccessory.return"
@@ -329,6 +336,8 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
             return String(localized: "terminal.input_accessory.paste", defaultValue: "Paste")
         case .composer:
             return String(localized: "terminal.input_accessory.composer", defaultValue: "Composer")
+        case .scrollToBottom:
+            return String(localized: "terminal.input_accessory.scroll_to_bottom", defaultValue: "Scroll to Bottom")
         default:
             return nil
         }
@@ -344,6 +353,8 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
             return "doc.on.clipboard"
         case .composer:
             return "square.and.pencil"
+        case .scrollToBottom:
+            return "arrow.down.to.line"
         default:
             return nil
         }
@@ -370,7 +381,7 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
 
     public var output: Data? {
         switch self {
-        case .control, .alternate, .command, .shift, .zoomOut, .zoomIn, .paste, .composer:
+        case .control, .alternate, .command, .shift, .zoomOut, .zoomIn, .paste, .composer, .scrollToBottom:
             return nil
         case .escape:
             return Data([0x1B])
@@ -482,6 +493,7 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
             .tilde, .dollar, .slash, .atSign, .pipe,
             .ctrlZ,
             .home, .end, .pageUp, .pageDown,
+            .scrollToBottom,
         ] + defaultTrailingActions
     }
 
@@ -511,6 +523,7 @@ public enum TerminalInputAccessoryAction: Int, CaseIterable, Sendable {
         case .end: return String(localized: "terminal.shortcut.name.end", defaultValue: "End")
         case .pageUp: return String(localized: "terminal.shortcut.name.pageUp", defaultValue: "Page Up")
         case .pageDown: return String(localized: "terminal.shortcut.name.pageDown", defaultValue: "Page Down")
+        case .scrollToBottom: return String(localized: "terminal.shortcut.name.scrollToBottom", defaultValue: "Scroll to Bottom")
         case .paste: return String(localized: "terminal.input_accessory.paste", defaultValue: "Paste")
         case .control: return String(localized: "terminal.shortcut.name.control", defaultValue: "Control")
         case .alternate: return String(localized: "terminal.shortcut.name.alternate", defaultValue: "Option")
@@ -919,6 +932,9 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
             guard let self else { return }
             self.handleComposerButtonTap()
         }
+        inputProxy.onScrollToBottom = { [weak self] in
+            self?.scrollToBottom()
+        }
         inputProxy.onHideKeyboard = { [weak self] in
             guard let self else { return }
             #if DEBUG
@@ -2272,6 +2288,15 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
     private func scrollInitialOutputToBottomIfNeeded() {
         guard shouldScrollInitialOutputToBottom, let surface else { return }
         shouldScrollInitialOutputToBottom = false
+        scrollToBottom(surface: surface)
+    }
+
+    private func scrollToBottom() {
+        guard let surface else { return }
+        scrollToBottom(surface: surface)
+    }
+
+    private func scrollToBottom(surface: ghostty_surface_t) {
         // `ghostty_surface_binding_action` takes the same internal surface lock
         // as `process_output`/`render_now`. This runs on the MAIN thread (inside
         // the `processOutput` completion hop), so calling it inline would contend
diff --git a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalAccessoryConfiguration.swift b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalAccessoryConfiguration.swift
index 45e59d45e361..a28c3341f67d 100644
--- a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalAccessoryConfiguration.swift
+++ b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalAccessoryConfiguration.swift
@@ -92,7 +92,7 @@ public final class TerminalAccessoryConfiguration {
             let order = v3Order.compactMap(ToolbarItemID.init(storageKey:))
             let enabled = (defaults.array(forKey: Self.enabledDefaultsKey) as? [String])?
                 .compactMap(ToolbarItemID.init(storageKey:))
-            // ⇧ and Return each became user-configurable after the v3 schema
+            // ⇧, Return, and Scroll to Bottom each became user-configurable after the v3 schema
             // shipped, so a layout persisted under the v3 keys has no record of
             // them and a naive load would leave them hidden. Fold each in next to
             // its neighbours and show it — once per id, keyed off that id's
@@ -144,7 +144,7 @@ public final class TerminalAccessoryConfiguration {
     }
 
     /// Folds the built-ins that became user-configurable *after* the v3 schema
-    /// shipped (⇧, then Return) into a persisted v3 layout, each adjacent to its
+    /// shipped (⇧, Return, then Scroll to Bottom) into a persisted v3 layout, each adjacent to its
     /// canonical neighbours and force-shown, exactly once per id. Returns the
     /// possibly-folded order and enabled set; `enabled` is passed through
     /// unchanged (including `nil`) when no fold applies, so a config already
@@ -159,7 +159,8 @@ public final class TerminalAccessoryConfiguration {
         // Each entry is the newly-configurable id plus the predecessors to insert
         // it after (first present wins; front if none present), mirroring
         // `defaultConfigurableOrder`: ⇧ trails the other modifiers, Return trails
-        // Esc (then Tab, then the modifiers).
+        // Esc (then Tab, then the modifiers), and Scroll to Bottom trails the
+        // navigation controls.
         let folds: [(id: ToolbarItemID, anchors: [ToolbarItemID])] = [
             (TerminalInputAccessoryAction.shift.itemID, [
                 TerminalInputAccessoryAction.command.itemID,
@@ -173,6 +174,13 @@ public final class TerminalAccessoryConfiguration {
                 TerminalInputAccessoryAction.alternate.itemID,
                 TerminalInputAccessoryAction.control.itemID,
             ]),
+            (TerminalInputAccessoryAction.scrollToBottom.itemID, [
+                TerminalInputAccessoryAction.pageDown.itemID,
+                TerminalInputAccessoryAction.end.itemID,
+                TerminalInputAccessoryAction.home.itemID,
+                TerminalInputAccessoryAction.returnKey.itemID,
+                TerminalInputAccessoryAction.escape.itemID,
+            ]),
         ]
         for fold in folds {
             if let widened = migration.foldingNewlyConfigurable(
diff --git a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputTextView.swift b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputTextView.swift
index c5cf0d55db2f..ff92f9919d49 100644
--- a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputTextView.swift
+++ b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputTextView.swift
@@ -51,6 +51,9 @@ final class TerminalInputTextView: UIView, UIKeyInput, UITextInput {
     /// Invoked when the composer accessory button is tapped. The host toggles
     /// the iMessage-style composer above the terminal.
     var onToggleComposer: (() -> Void)?
+    /// Invoked when the scroll-to-bottom accessory button is tapped. The host
+    /// owns the surface binding because this responder has no Ghostty surface.
+    var onScrollToBottom: (() -> Void)?
     /// Fired by the pinned HIDE button: temporarily hides the toolbar + composer
     /// until the next terminal tap.
     var onHideChrome: (() -> Void)?
@@ -1065,6 +1068,13 @@ final class TerminalInputTextView: UIView, UIKeyInput, UITextInput {
             return
         }
 
+        if action == .scrollToBottom {
+            disarmAllModifiers()
+            refreshAccessoryButtonStyles()
+            onScrollToBottom?()
+            return
+        }
+
         if controlAccessoryArmed,
            !action.isModifier {
             if !controlAccessorySticky {
diff --git a/ios/cmux/Resources/Localizable.xcstrings b/ios/cmux/Resources/Localizable.xcstrings
index a7fb7961b298..aee36b92a843 100644
--- a/ios/cmux/Resources/Localizable.xcstrings
+++ b/ios/cmux/Resources/Localizable.xcstrings
@@ -4506,6 +4506,23 @@
         }
       }
     },
+    "terminal.input_accessory.scroll_to_bottom": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Scroll to Bottom"
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "一番下までスクロール"
+          }
+        }
+      }
+    },
     "mobile.pairing.accountMismatch": {
       "extractionState": "manual",
       "localizations": {
@@ -6155,6 +6172,23 @@
         }
       }
     },
+    "terminal.shortcut.name.scrollToBottom": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Scroll to Bottom"
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "一番下までスクロール"
+          }
+        }
+      }
+    },
     "mobile.deviceTree.online": {
       "extractionState": "manual",
       "localizations": {

From 712136b86ee6a46aa0605b87f8eebd67f50c71d2 Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Sat, 20 Jun 2026 21:52:26 -0700
Subject: [PATCH 3/7] Add iOS scroll-to-bottom RPC coverage

---
 .../ComposerSubmitRoutingTestSupport.swift     | 18 ++++++++++++++++++
 .../TerminalScrollDeliveryQueueTests.swift     | 15 +++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/ComposerSubmitRoutingTestSupport.swift b/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/ComposerSubmitRoutingTestSupport.swift
index c3645f4c3513..39688c855da5 100644
--- a/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/ComposerSubmitRoutingTestSupport.swift
+++ b/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/ComposerSubmitRoutingTestSupport.swift
@@ -40,9 +40,15 @@ actor RoutingHostRouter {
         var surfaceID: String
         var text: String
     }
+    struct ScrollToBottomRecord: Sendable {
+        var workspaceID: String
+        var surfaceID: String
+        var clientID: String
+    }
 
     private(set) var pasteImages: [PasteImageRecord] = []
     private(set) var pastes: [PasteRecord] = []
+    private(set) var scrollToBottomRequests: [ScrollToBottomRecord] = []
     /// Reject the Nth (0-based) and later paste_image requests; `nil` accepts all.
     private var rejectPasteImageFromIndex: Int?
     private var holdFirstPasteImage = false
@@ -89,13 +95,16 @@ actor RoutingHostRouter {
 
     func recordedPasteImages() -> [PasteImageRecord] { pasteImages }
     func recordedPastes() -> [PasteRecord] { pastes }
+    func recordedScrollToBottomRequests() -> [ScrollToBottomRecord] { scrollToBottomRequests }
 
     /// Sendable extract of the request fields the router needs, pulled off the
     /// non-Sendable params dictionary before crossing the Task boundary.
     struct RequestInfo: Sendable {
         var method: String?
         var id: String?
+        var workspaceID: String?
         var surfaceID: String?
+        var clientID: String?
         var imageFormat: String?
         var text: String?
     }
@@ -163,6 +172,13 @@ actor RoutingHostRouter {
             let text = info.text ?? ""
             pastes.append(PasteRecord(surfaceID: surfaceID, text: text))
             return try? Self.resultFrame(id: id, result: [:])
+        case "mobile.terminal.scroll_to_bottom":
+            scrollToBottomRequests.append(ScrollToBottomRecord(
+                workspaceID: info.workspaceID ?? "",
+                surfaceID: info.surfaceID ?? "",
+                clientID: info.clientID ?? ""
+            ))
+            return try? Self.resultFrame(id: id, result: [:])
         case "mobile.events.unsubscribe", "mobile.terminal.replay", "mobile.terminal.viewport":
             return try? Self.resultFrame(id: id, result: [:])
         default:
@@ -232,7 +248,9 @@ private actor RoutingTransport: CmxByteTransport {
             let info = RoutingHostRouter.RequestInfo(
                 method: parsed?["method"] as? String,
                 id: parsed?["id"] as? String,
+                workspaceID: params?["workspace_id"] as? String,
                 surfaceID: params?["surface_id"] as? String,
+                clientID: params?["client_id"] as? String,
                 imageFormat: params?["image_format"] as? String,
                 text: params?["text"] as? String
             )
diff --git a/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalScrollDeliveryQueueTests.swift b/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalScrollDeliveryQueueTests.swift
index 1a7eecf24c73..6ee54423eff3 100644
--- a/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalScrollDeliveryQueueTests.swift
+++ b/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalScrollDeliveryQueueTests.swift
@@ -110,3 +110,18 @@ import Testing
     var queueAfterStaleCompletion = try #require(store.terminalScrollQueuesBySurfaceID[surfaceID])
     #expect(queueAfterStaleCompletion.completeInFlight() == pending)
 }
+
+@MainActor
+@Test func scrollToBottomSendsAbsoluteMobileRPC() async throws {
+    let router = RoutingHostRouter()
+    let store = try await makeRoutingConnectedStore(router: router)
+
+    await store.scrollTerminalToBottom(surfaceID: RoutingHostRouter.terminalA)
+
+    let requests = await router.recordedScrollToBottomRequests()
+    let request = try #require(requests.first)
+    #expect(requests.count == 1)
+    #expect(request.workspaceID == RoutingHostRouter.workspaceID)
+    #expect(request.surfaceID == RoutingHostRouter.terminalA)
+    #expect(!request.clientID.isEmpty)
+}

From b2526fb0fcf4321b8ed140ef8fa23d26ce6a82e2 Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Sat, 20 Jun 2026 21:52:31 -0700
Subject: [PATCH 4/7] Route iOS scroll-to-bottom through Mac surface

---
 ...hellComposite+TerminalScrollDelivery.swift | 20 +++++++++++++++
 .../GhosttySurfaceRepresentable.swift         |  9 +++++++
 .../GhosttySurfaceView.swift                  | 10 +++++++-
 .../Surface/TerminalSurface+Mobile.swift      | 12 +++++++++
 Sources/Mobile/MobileHostService.swift        |  3 ++-
 Sources/TerminalController.swift              | 25 +++++++++++++++++++
 6 files changed, 77 insertions(+), 2 deletions(-)

diff --git a/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalScrollDelivery.swift b/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalScrollDelivery.swift
index 251f1a7c68c2..cd7f90703941 100644
--- a/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalScrollDelivery.swift
+++ b/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalScrollDelivery.swift
@@ -32,6 +32,26 @@ extension MobileShellComposite {
         ))
     }
 
+    public func scrollTerminalToBottom(surfaceID: String) async {
+        guard let client = remoteClient,
+              let workspaceID = workspaceID(forTerminalID: surfaceID) else {
+            return
+        }
+        do {
+            let request = try MobileCoreRPCClient.requestData(
+                method: "mobile.terminal.scroll_to_bottom",
+                params: [
+                    "workspace_id": workspaceID.rawValue,
+                    "surface_id": surfaceID,
+                    "client_id": clientID,
+                ]
+            )
+            _ = try await client.sendRequest(request)
+        } catch {
+            terminalScrollDeliveryLog.error("scroll-to-bottom failed surface=\(surfaceID, privacy: .public) error=\(String(describing: error), privacy: .public)")
+        }
+    }
+
     private func enqueueTerminalScroll(_ delivery: TerminalScrollDelivery) {
         guard delivery.lines != 0 else { return }
         let queueToken = terminalScrollQueueTokensBySurfaceID[delivery.surfaceID] ?? UUID()
diff --git a/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift b/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift
index 41525293e8af..ec31be55af0f 100644
--- a/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift
+++ b/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift
@@ -311,6 +311,15 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
             }
         }
 
+        func ghosttySurfaceViewDidRequestScrollToBottom(_ surfaceView: GhosttySurfaceView) {
+            // Forward to the Mac's real surface so the phone's mirror and the
+            // authoritative Mac viewport agree after the local preview jumps.
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                await self.store?.scrollTerminalToBottom(surfaceID: self.surfaceID)
+            }
+        }
+
         func ghosttySurfaceViewDidRequestToolbarSettings(_ surfaceView: GhosttySurfaceView) {
             // The "customize" button on the keyboard toolbar. The editor view
             // lives in this UI package, so present it here (the terminal package
diff --git a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
index fba4c8ee02f4..06d21acd6b3e 100644
--- a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
+++ b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
@@ -52,6 +52,9 @@ public protocol GhosttySurfaceViewDelegate: AnyObject {
     /// The Mac's libghostty self-gates: a normal screen treats it as a harmless
     /// empty selection. Optional.
     func ghosttySurfaceView(_ surfaceView: GhosttySurfaceView, didTapAtCol col: Int, row: Int)
+    /// Request the Mac's real surface to jump its viewport to newest output.
+    /// Optional.
+    func ghosttySurfaceViewDidRequestScrollToBottom(_ surfaceView: GhosttySurfaceView)
     /// The user tapped the "customize" button at the end of the input-accessory
     /// bar; the host should present the toolbar shortcuts editor. Optional.
     func ghosttySurfaceViewDidRequestToolbarSettings(_ surfaceView: GhosttySurfaceView)
@@ -79,6 +82,7 @@ public protocol GhosttySurfaceViewDelegate: AnyObject {
 public extension GhosttySurfaceViewDelegate {
     func ghosttySurfaceView(_ surfaceView: GhosttySurfaceView, didScrollLines lines: Double, atCol col: Int, row: Int) {}
     func ghosttySurfaceView(_ surfaceView: GhosttySurfaceView, didTapAtCol col: Int, row: Int) {}
+    func ghosttySurfaceViewDidRequestScrollToBottom(_ surfaceView: GhosttySurfaceView) {}
     func ghosttySurfaceViewDidRequestToolbarSettings(_ surfaceView: GhosttySurfaceView) {}
     func ghosttySurfaceView(_ surfaceView: GhosttySurfaceView, didPasteImage data: Data, format: String) {}
     /// Default no-op so hosts without a composer can ignore the toggle request.
@@ -2294,6 +2298,7 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
     private func scrollToBottom() {
         guard let surface else { return }
         scrollToBottom(surface: surface)
+        delegate?.ghosttySurfaceViewDidRequestScrollToBottom(self)
     }
 
     private func scrollToBottom(surface: ghostty_surface_t) {
@@ -2307,10 +2312,13 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         // `process_output` also preserves ordering. The return was already
         // discarded.
         let action = "scroll_to_bottom"
-        Self.outputQueue.async {
+        Self.outputQueue.async { [weak self] in
             action.withCString { pointer in
                 _ = ghostty_surface_binding_action(surface, pointer, UInt(action.utf8.count))
             }
+            DispatchQueue.main.async {
+                self?.drawForWakeup()
+            }
         }
     }
 
diff --git a/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift b/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift
index 772b2c9a6d3e..a726c74c652e 100644
--- a/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift
+++ b/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift
@@ -27,6 +27,18 @@ extension TerminalSurface {
         ghostty_surface_mouse_scroll(surface, 0, deltaLines, 0)
     }
 
+    /// Jump the authoritative Mac surface to newest output for a paired phone.
+    /// This uses the same Ghostty binding as the desktop scroll-to-bottom action,
+    /// so normal-screen scrollback semantics stay owned by the real surface.
+    @MainActor
+    public func mobileScrollToBottom() {
+        guard let surface = liveSurfaceForGhosttyAccess(reason: "mobileScrollToBottom") else { return }
+        let action = "scroll_to_bottom"
+        action.withCString { pointer in
+            _ = ghostty_surface_binding_action(surface, pointer, UInt(action.utf8.count))
+        }
+    }
+
     /// Forward a mobile tap to this real surface as a left mouse click at the
     /// given grid cell. libghostty does the mode-correct thing: a program with
     /// mouse reporting (alt-screen TUIs like lazygit/htop/fzf) gets an encoded
diff --git a/Sources/Mobile/MobileHostService.swift b/Sources/Mobile/MobileHostService.swift
index 9b40e93fa8be..6e20f5b43366 100644
--- a/Sources/Mobile/MobileHostService.swift
+++ b/Sources/Mobile/MobileHostService.swift
@@ -1394,7 +1394,8 @@ final class MobileHostService {
              "mobile.terminal.paste_image", "terminal.paste_image",
              "mobile.terminal.replay", "terminal.replay",
              "mobile.terminal.viewport", "terminal.viewport",
-             "mobile.terminal.scroll", "terminal.scroll":
+             "mobile.terminal.scroll", "terminal.scroll",
+             "mobile.terminal.scroll_to_bottom", "terminal.scroll_to_bottom":
             return ticketTerminalAuthorizationError(
                 authorization: authorization,
                 workspaceSelection: workspaceSelection.value,
diff --git a/Sources/TerminalController.swift b/Sources/TerminalController.swift
index 94aef45928c7..eabe0638175b 100644
--- a/Sources/TerminalController.swift
+++ b/Sources/TerminalController.swift
@@ -12897,6 +12897,8 @@ class TerminalController {
             result = v2MobileTerminalViewport(params: request.params)
         case "mobile.terminal.scroll", "terminal.scroll":
             result = v2MobileTerminalScroll(params: request.params)
+        case "mobile.terminal.scroll_to_bottom", "terminal.scroll_to_bottom":
+            result = v2MobileTerminalScrollToBottom(params: request.params)
         case "mobile.terminal.mouse", "terminal.mouse":
             result = v2MobileTerminalMouse(params: request.params)
         case "workspace.action":
@@ -13534,6 +13536,29 @@ class TerminalController {
         ))
     }
 
+    /// Jump the Mac-owned terminal viewport to newest output for a paired phone.
+    /// This is separate from relative scroll because the button needs an
+    /// absolute action, not a guessed large delta.
+    func v2MobileTerminalScrollToBottom(params: [String: Any]) -> V2CallResult {
+        if let error = mobileWorkspaceIDValidationError(params: params) {
+            return error
+        }
+        if let error = mobileTerminalAliasValidationError(params: params) {
+            return error
+        }
+        guard let resolved = mobileResolveWorkspaceAndSurface(params: params, requireTerminal: true),
+              let surfaceId = resolved.surfaceId,
+              let terminalPanel = resolved.workspace.terminalPanel(for: surfaceId) else {
+            return .err(code: "not_found", message: "Terminal surface not found", data: nil)
+        }
+        terminalPanel.surface.mobileScrollToBottom()
+        MobileTerminalRenderObserver.shared.noteTerminalBytes(surfaceID: terminalPanel.id)
+        return .ok([
+            "workspace_id": resolved.workspace.id.uuidString,
+            "surface_id": surfaceId.uuidString,
+        ])
+    }
+
     func v2MobileTerminalMouse(params: [String: Any]) -> V2CallResult {
         if let error = mobileWorkspaceIDValidationError(params: params) {
             return error

From f4efc111deadf5f9e7f02d4b40e1a73ca625086c Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Sat, 20 Jun 2026 22:00:54 -0700
Subject: [PATCH 5/7] Refresh Swift file length budget for scroll button

---
 .github/swift-file-length-budget.tsv | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/swift-file-length-budget.tsv b/.github/swift-file-length-budget.tsv
index 700c1661f861..e7b0bc5ed247 100644
--- a/.github/swift-file-length-budget.tsv
+++ b/.github/swift-file-length-budget.tsv
@@ -4,7 +4,7 @@
 34334	CLI/cmux.swift
 17706	Sources/AppDelegate.swift
 16052	Sources/ContentView.swift
-13992	Sources/TerminalController.swift
+14017	Sources/TerminalController.swift
 12695	Sources/Workspace.swift
 12144	cmuxTests/AppDelegateShortcutRoutingTests.swift
 11841	Sources/GhosttyTerminalView.swift
@@ -28,7 +28,7 @@
 3937	Sources/Feed/FeedPanelView.swift
 3926	cmuxTests/TabManagerUnitTests.swift
 3896	cmuxTests/WindowAndDragTests.swift
-3734	Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
+3767	Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
 3699	cmuxTests/CLIGenericHookPersistenceTests.swift
 3397	Sources/CmuxConfig.swift
 3364	cmuxTests/TabManagerSessionSnapshotTests.swift
@@ -39,7 +39,7 @@
 2565	Sources/Panels/CmuxWebView.swift
 2546	cmuxTests/WorkspaceManualUnreadTests.swift
 2524	cmuxTests/CommandPaletteSearchEngineTests.swift
-2395	Sources/Mobile/MobileHostService.swift
+2396	Sources/Mobile/MobileHostService.swift
 2355	Sources/FileExplorerView.swift
 2328	cmuxTests/CJKIMEInputTests.swift
 2257	Sources/TerminalNotificationStore.swift
@@ -57,7 +57,7 @@
 1687	cmuxTests/MarkdownPanelTests.swift
 1680	cmuxUITests/BrowserPaneNavigationKeybindUITests.swift
 1652	cmuxTests/CMUXCLIErrorOutputRegressionTests.swift
-1581	Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputTextView.swift
+1591	Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputTextView.swift
 1560	cmuxTests/TextBoxMentionCompletionTests.swift
 1547	cmuxTests/TerminalControllerSocketSecurityTests.swift
 1500	cmuxUITests/MultiWindowNotificationsUITests.swift

From 9b84342b6b4c90c3fbbb7960c89d5992a5145c49 Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Tue, 23 Jun 2026 03:11:03 -0700
Subject: [PATCH 6/7] Restore iOS terminal jump-to-bottom button

---
 .../MobileTerminalRenderGrid.swift            | 27 ++++--
 .../MobileTerminalRenderGridTests.swift       | 78 +++++++++++++++++
 ...hellComposite+TerminalOutputDelivery.swift |  4 +
 .../MobileShellComposite.swift                | 15 ++++
 .../TerminalOutputDeliveryQueueTests.swift    | 52 ++++++++++++
 .../GhosttySurfaceRepresentable.swift         |  5 ++
 .../WorkspaceDetailView.swift                 |  3 +-
 .../GhosttySurfaceView.swift                  | 83 +++++++++++++++++++
 .../ScrollToBottomButton.swift                | 61 ++++++++++++++
 .../TerminalSurfaceNativeViewing.swift        | 10 +++
 .../Surface/TerminalSurface+Mobile.swift      |  3 +-
 Sources/GhosttyTerminalView.swift             |  6 ++
 .../Mobile/MobileTerminalRenderObserver.swift | 16 +++-
 cmuxTests/MobileHostAuthorizationTests.swift  | 15 ++++
 14 files changed, 368 insertions(+), 10 deletions(-)
 create mode 100644 Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/ScrollToBottomButton.swift

diff --git a/Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGrid.swift b/Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGrid.swift
index 5c135cb4978d..114bfcae0e1a 100644
--- a/Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGrid.swift
+++ b/Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGrid.swift
@@ -43,6 +43,15 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
     /// Styled spans for the scrollback lines, row index `0..<scrollbackRows`
     /// (oldest first). Reuses ``styles`` by `styleID`.
     public var scrollbackSpans: [RowSpan]
+    /// Whether the producing Mac surface is pinned to the live bottom. `nil`
+    /// means an older producer did not report the position, so clients should
+    /// keep jump-to-bottom UI hidden rather than guessing.
+    public var atBottom: Bool?
+
+    /// Whether a client can scroll toward newer terminal output.
+    public var hasRoomToScrollToBottom: Bool {
+        atBottom == false
+    }
 
     public init(
         format: String = Self.currentFormat,
@@ -61,7 +70,8 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
         terminalBackground: String? = nil,
         terminalCursorColor: String? = nil,
         scrollbackRows: Int = 0,
-        scrollbackSpans: [RowSpan] = []
+        scrollbackSpans: [RowSpan] = [],
+        atBottom: Bool? = nil
     ) throws {
         guard format == Self.currentFormat else {
             throw MobileTerminalRenderGridError.invalidFormat(format)
@@ -138,6 +148,7 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
         self.terminalCursorColor = terminalCursorColor
         self.scrollbackRows = full ? resolvedScrollbackRows : 0
         self.scrollbackSpans = full ? scrollbackSpans : []
+        self.atBottom = atBottom
     }
 
     public init(from decoder: Decoder) throws {
@@ -159,6 +170,7 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
         let terminalCursorColor = try container.decodeIfPresent(String.self, forKey: .terminalCursorColor)
         let scrollbackRows = try container.decodeIfPresent(Int.self, forKey: .scrollbackRows) ?? 0
         let scrollbackSpans = try container.decodeIfPresent([RowSpan].self, forKey: .scrollbackSpans) ?? []
+        let atBottom = try container.decodeIfPresent(Bool.self, forKey: .atBottom)
         try self.init(
             format: format,
             surfaceID: surfaceID,
@@ -176,7 +188,8 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
             terminalBackground: terminalBackground,
             terminalCursorColor: terminalCursorColor,
             scrollbackRows: scrollbackRows,
-            scrollbackSpans: scrollbackSpans
+            scrollbackSpans: scrollbackSpans,
+            atBottom: atBottom
         )
     }
 
@@ -188,7 +201,8 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
         text: String,
         cursor: Cursor? = nil,
         full: Bool = true,
-        changedRows: Set<Int>? = nil
+        changedRows: Set<Int>? = nil,
+        atBottom: Bool? = nil
     ) throws -> MobileTerminalRenderGridFrame {
         let lines = normalizedRows(from: text, maxRows: rows)
         let includedRows = changedRows ?? Set(0..<rows)
@@ -211,7 +225,8 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
             cursor: cursor,
             full: full,
             clearedRows: full ? [] : Array(includedRows.sorted()),
-            rowSpans: spans
+            rowSpans: spans,
+            atBottom: atBottom
         )
     }
 
@@ -294,7 +309,8 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
             terminalBackground: full ? terminalBackground : nil,
             terminalCursorColor: full ? terminalCursorColor : nil,
             scrollbackRows: full ? scrollbackRows : 0,
-            scrollbackSpans: full ? scrollbackSpans : []
+            scrollbackSpans: full ? scrollbackSpans : [],
+            atBottom: atBottom
         )
     }
 
@@ -405,6 +421,7 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
         case terminalCursorColor = "terminal_cursor_color"
         case scrollbackRows = "scrollback_rows"
         case scrollbackSpans = "scrollback_spans"
+        case atBottom = "at_bottom"
     }
 
     /// Which terminal screen a full snapshot represents.
diff --git a/Packages/Shared/CMUXMobileCore/Tests/CMUXMobileCoreTests/MobileTerminalRenderGridTests.swift b/Packages/Shared/CMUXMobileCore/Tests/CMUXMobileCoreTests/MobileTerminalRenderGridTests.swift
index 5a561be482b3..23f353b18b35 100644
--- a/Packages/Shared/CMUXMobileCore/Tests/CMUXMobileCoreTests/MobileTerminalRenderGridTests.swift
+++ b/Packages/Shared/CMUXMobileCore/Tests/CMUXMobileCoreTests/MobileTerminalRenderGridTests.swift
@@ -354,6 +354,84 @@ import Testing
     #expect(decoded.terminalForeground == "#010203")
 }
 
+@Test func renderGridHasRoomToScrollOnlyWhenProducerReportsScrolledUp() throws {
+    let atBottom = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal-a",
+        stateSeq: 1,
+        columns: 8,
+        rows: 1,
+        rowSpans: [],
+        atBottom: true
+    )
+    let scrolledUp = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal-a",
+        stateSeq: 2,
+        columns: 8,
+        rows: 1,
+        rowSpans: [],
+        atBottom: false
+    )
+    let unknown = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal-a",
+        stateSeq: 3,
+        columns: 8,
+        rows: 1,
+        rowSpans: []
+    )
+
+    #expect(!atBottom.hasRoomToScrollToBottom)
+    #expect(scrolledUp.hasRoomToScrollToBottom)
+    #expect(!unknown.hasRoomToScrollToBottom)
+}
+
+@Test func renderGridAtBottomSurvivesJSONRoundTrip() throws {
+    let frame = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal-a",
+        stateSeq: 1,
+        columns: 8,
+        rows: 1,
+        rowSpans: [],
+        atBottom: false
+    )
+
+    let decoded = try MobileTerminalRenderGridFrame.decodeJSONObject(frame.jsonObject())
+
+    #expect(decoded.atBottom == false)
+    #expect(decoded.hasRoomToScrollToBottom)
+}
+
+@Test func renderGridDecodesMissingAtBottomAsUnknown() throws {
+    let object: [String: Any] = [
+        "format": MobileTerminalRenderGridFrame.currentFormat,
+        "surface_id": "terminal-a",
+        "state_seq": NSNumber(value: 44),
+        "columns": 8,
+        "rows": 4,
+        "row_spans": [],
+    ]
+
+    let frame = try MobileTerminalRenderGridFrame.decodeJSONObject(object)
+
+    #expect(frame.atBottom == nil)
+    #expect(!frame.hasRoomToScrollToBottom)
+}
+
+@Test func renderGridDeltaFrameCarriesAtBottom() throws {
+    let frame = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal-a",
+        stateSeq: 1,
+        columns: 8,
+        rows: 2,
+        rowSpans: [.init(row: 1, column: 0, text: "hi")],
+        atBottom: false
+    )
+
+    let delta = try frame.filteredRows([1], full: false)
+
+    #expect(delta.atBottom == false)
+    #expect(delta.hasRoomToScrollToBottom)
+}
+
 @Test func renderGridDeltaDropsFullStateFields() throws {
     let frame = try MobileTerminalRenderGridFrame(
         surfaceID: "terminal-a",
diff --git a/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift b/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift
index 2abb1c60a5db..2246b2eed57e 100644
--- a/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift
+++ b/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift
@@ -12,6 +12,10 @@ extension MobileShellComposite {
     }
 
     func deliverTerminalRenderGrid(_ frame: MobileTerminalRenderGridFrame, surfaceID: String) {
+        updateTerminalScrolledUp(
+            surfaceID: surfaceID,
+            scrolledUp: frame.hasRoomToScrollToBottom
+        )
         deliverTerminalOutput(
             TerminalOutputDelivery(
                 renderGrid: frame,
diff --git a/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift b/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift
index d36532176b2f..5bc7d1fe1379 100644
--- a/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift
+++ b/Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift
@@ -598,6 +598,8 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
     var terminalScrollQueueTokensBySurfaceID: [String: UUID]
     var terminalScrollQueuesBySurfaceID: [String: TerminalScrollDeliveryQueue]
     var terminalScrollbackPrefetchStatesBySurfaceID: [String: TerminalScrollbackPrefetchState]
+    /// Latest server-reported scroll position by terminal surface.
+    public private(set) var terminalScrolledUpBySurfaceID: [String: Bool]
     private var rawTerminalInputBuffer: MobileTerminalInputSendBuffer
     private var pairingAttemptID: UUID
 
@@ -727,6 +729,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         self.terminalScrollQueueTokensBySurfaceID = [:]
         self.terminalScrollQueuesBySurfaceID = [:]
         self.terminalScrollbackPrefetchStatesBySurfaceID = [:]
+        self.terminalScrolledUpBySurfaceID = [:]
         self.rawTerminalInputBuffer = MobileTerminalInputSendBuffer()
         self.pairingAttemptID = UUID()
     }
@@ -3567,6 +3570,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         terminalScrollQueueTokensBySurfaceID = [:]
         terminalScrollQueuesBySurfaceID = [:]
         terminalScrollbackPrefetchStatesBySurfaceID = [:]
+        terminalScrolledUpBySurfaceID = [:]
         terminalOutputTransport = .rawBytes
         supportedHostCapabilities = []
         terminalSubscriptionRefreshTask?.cancel()
@@ -4922,6 +4926,16 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         deliverTerminalRenderGrid(renderGrid, surfaceID: renderGrid.surfaceID)
     }
 
+    /// Returns whether the terminal surface is currently scrolled away from the bottom.
+    public func terminalScrolledUp(surfaceID: String) -> Bool {
+        terminalScrolledUpBySurfaceID[surfaceID] ?? false
+    }
+
+    func updateTerminalScrolledUp(surfaceID: String, scrolledUp: Bool) {
+        guard terminalScrolledUpBySurfaceID[surfaceID] != scrolledUp else { return }
+        terminalScrolledUpBySurfaceID[surfaceID] = scrolledUp
+    }
+
     private static func terminalSnapshotReplacementBytes(_ snapshotBytes: Data) -> Data {
         var bytes = Data("\u{1B}c\u{1B}[H\u{1B}[2J\u{1B}[3J".utf8)
         bytes.append(snapshotBytes)
@@ -4955,6 +4969,7 @@ public final class MobileShellComposite: MobileTerminalOutputSinking {
         terminalScrollQueueTokensBySurfaceID.removeValue(forKey: surfaceID)
         terminalScrollQueuesBySurfaceID.removeValue(forKey: surfaceID)
         terminalScrollbackPrefetchStatesBySurfaceID.removeValue(forKey: surfaceID)
+        terminalScrolledUpBySurfaceID.removeValue(forKey: surfaceID)
         deliveredTerminalByteEndSeqBySurfaceID.removeValue(forKey: surfaceID)
         pendingTerminalByteEndSeqBySurfaceID.removeValue(forKey: surfaceID)
         // Tell the Mac this device is no longer viewing the surface so it stops
diff --git a/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalOutputDeliveryQueueTests.swift b/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalOutputDeliveryQueueTests.swift
index b11327969a3c..fe9361900928 100644
--- a/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalOutputDeliveryQueueTests.swift
+++ b/Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalOutputDeliveryQueueTests.swift
@@ -41,6 +41,58 @@ import Testing
     #expect(String(decoding: secondChunk.data, as: UTF8.self) == "new-second")
 }
 
+@MainActor
+@Test func renderGridDeliveryTracksScrolledUpState() async throws {
+    let store = MobileShellComposite.preview()
+    let surfaceID = "terminal"
+    var iterator = store.terminalOutputStream(surfaceID: surfaceID).makeAsyncIterator()
+
+    let scrolledUpFrame = try MobileTerminalRenderGridFrame.fromPlainRows(
+        surfaceID: surfaceID,
+        stateSeq: 1,
+        columns: 12,
+        rows: 2,
+        text: "scrolled",
+        atBottom: false
+    )
+    store.deliverAuthoritativeTerminalRenderGrid(scrolledUpFrame, source: "test")
+    _ = try #require(await iterator.next())
+
+    #expect(store.terminalScrolledUp(surfaceID: surfaceID))
+
+    let atBottomFrame = try MobileTerminalRenderGridFrame.fromPlainRows(
+        surfaceID: surfaceID,
+        stateSeq: 2,
+        columns: 12,
+        rows: 2,
+        text: "bottom",
+        atBottom: true
+    )
+    store.deliverAuthoritativeTerminalRenderGrid(atBottomFrame, source: "test")
+
+    #expect(!store.terminalScrolledUp(surfaceID: surfaceID))
+}
+
+@MainActor
+@Test func replayRenderGridDeliveryTracksScrolledUpState() async throws {
+    let store = MobileShellComposite.preview()
+    let surfaceID = "terminal"
+    var iterator = store.terminalOutputStream(surfaceID: surfaceID).makeAsyncIterator()
+
+    let replayFrame = try MobileTerminalRenderGridFrame.fromPlainRows(
+        surfaceID: surfaceID,
+        stateSeq: 1,
+        columns: 12,
+        rows: 2,
+        text: "replay",
+        atBottom: false
+    )
+    store.deliverTerminalRenderGrid(replayFrame, surfaceID: surfaceID)
+    _ = try #require(await iterator.next())
+
+    #expect(store.terminalScrolledUp(surfaceID: surfaceID))
+}
+
 @Test func terminalOutputQueueCoalescesReplaceableViewportFramesBehindBackpressure() {
     var queue = TerminalOutputDeliveryQueue()
     let inFlight = TerminalOutputDelivery(bytes: Data("in-flight".utf8), replaceable: false)
diff --git a/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift b/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift
index ec31be55af0f..f021d8c6c7fc 100644
--- a/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift
+++ b/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift
@@ -36,6 +36,9 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
     /// band and pins first responder so the keyboard hands over in place; when it
     /// flips off, the field is unmounted and the band collapses to zero height.
     var isComposerActive: Bool = false
+    /// Whether the Mac reports this surface is scrolled up into scrollback.
+    /// Drives the floating jump-to-bottom affordance inside the terminal view.
+    var scrolledUp: Bool = false
 
     func makeCoordinator() -> Coordinator {
         Coordinator(surfaceID: surfaceID, store: store)
@@ -74,6 +77,7 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
         // seed the surface's composerActive flag to match. SwiftUI does call
         // `updateUIView` right after `makeUIView`, but the compose button's intent
         // math reads this flag, so it must never depend on that ordering contract.
+        view.setScrolledUp(scrolledUp)
         view.setComposerActive(isComposerActive)
         context.coordinator.setComposerMounted(isComposerActive)
         return view
@@ -88,6 +92,7 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
         // state write, so it is safe in `updateUIView`.
         guard let surfaceView = uiView as? GhosttySurfaceView else { return }
         surfaceView.autoFocusOnWindowAttach = autoFocusOnWindowAttach
+        surfaceView.setScrolledUp(scrolledUp)
         surfaceView.setComposerActive(isComposerActive)
         context.coordinator.setComposerMounted(isComposerActive)
         // A width change (rotation) is not a text change, so the field-content trigger
diff --git a/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/WorkspaceDetailView.swift b/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/WorkspaceDetailView.swift
index 31312dff52fe..7cb2fdf4731d 100644
--- a/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/WorkspaceDetailView.swift
+++ b/Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/WorkspaceDetailView.swift
@@ -319,7 +319,8 @@ struct WorkspaceDetailView: View {
                     // field).
                     autoFocusOnWindowAttach: store.shouldAutoFocusTerminalSurface(terminalID)
                         && !store.isComposerPresented,
-                    isComposerActive: store.isComposerPresented
+                    isComposerActive: store.isComposerPresented,
+                    scrolledUp: store.terminalScrolledUp(surfaceID: terminalID)
                 )
                 // Identity must track the selected terminal. The representable's
                 // coordinator binds its byte sink to the surfaceID at make time and
diff --git a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
index 06d21acd6b3e..49598e2b6a00 100644
--- a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
+++ b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
@@ -1153,6 +1153,10 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
     /// flush with the grid bottom (no gap) and its bottom rests on the keyboard
     /// edge (up) or above the home indicator (down).
     private weak var dockedToolbar: UIView?
+    /// Floating jump-to-bottom button shown when the Mac reports this viewport is
+    /// scrolled up into scrollback.
+    private weak var scrollToBottomButton: ScrollToBottomButton?
+    private var scrolledUp = false
     /// Whether the iMessage-style composer is currently open. The surface owns the
     /// whole bottom dock (terminal grid / toolbar / composer band / keyboard) in ONE
     /// coordinate system, so `composerActive` only drives the first-responder
@@ -1329,10 +1333,24 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         // is visible above the strip.
         toolbar.layer.zPosition = Self.bottomChromeZPosition
         toolbar.clipsToBounds = false
+        installScrollToBottomButton()
         updateDockedToolbarVisibility()
         layoutBottomDock()
     }
 
+    private func installScrollToBottomButton() {
+        guard scrollToBottomButton == nil else { return }
+        let button = ScrollToBottomButton()
+        button.layer.zPosition = Self.bottomChromeZPosition
+        button.alpha = 0
+        button.isHidden = true
+        button.onTap = { [weak self] in
+            self?.scrollToBottom()
+        }
+        addSubview(button)
+        scrollToBottomButton = button
+    }
+
     /// Layer `zPosition` for the bottom chrome (toolbar + composer band), placing it
     /// above the Ghostty renderer's sublayer so a lifted Liquid-Glass button is not
     /// clipped by the terminal render bounds (item 6). Below the zoom HUD (1100).
@@ -1401,6 +1419,7 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         // ``bottomDockFrames()``); toggling `isHidden` also stops it intercepting taps.
         composerContainer.isHidden = !shouldShow || composerContainer.subviews.isEmpty
         reservedToolbarHeight = reserved
+        updateScrollToBottomButtonVisibility(animated: true)
         setNeedsGeometrySync()
         setNeedsLayout()
     }
@@ -1444,6 +1463,7 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
             // double-animate against the keyboard rise.
             layoutBottomDock()
         }
+        updateScrollToBottomButtonVisibility(animated: true)
         setNeedsGeometrySync()
     }
 
@@ -1789,6 +1809,64 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         let frames = bottomDockFrames()
         composerContainer.frame = frames.composer
         dockedToolbar?.frame = frames.toolbar
+        layoutScrollToBottomButton(aboveDockTop: frames.toolbar.minY)
+    }
+
+    /// Updates whether the remote terminal viewport is away from the bottom.
+    public func setScrolledUp(_ value: Bool) {
+        guard scrolledUp != value else { return }
+        scrolledUp = value
+        layoutBottomDock()
+        updateScrollToBottomButtonVisibility(animated: true)
+    }
+
+    private var scrollToBottomButtonShouldBeVisible: Bool {
+        scrolledUp && !chromeHidden
+    }
+
+    private func updateScrollToBottomButtonVisibility(animated: Bool) {
+        guard let button = scrollToBottomButton else { return }
+        let shouldShow = scrollToBottomButtonShouldBeVisible
+        let targetAlpha: CGFloat = shouldShow ? 1 : 0
+        guard button.alpha != targetAlpha || button.isHidden == shouldShow else { return }
+
+        if shouldShow {
+            button.isHidden = false
+        }
+
+        let apply = {
+            button.alpha = targetAlpha
+        }
+        let completion: (Bool) -> Void = { _ in
+            if !shouldShow {
+                button.isHidden = true
+            }
+        }
+
+        if animated {
+            UIView.animate(
+                withDuration: 0.18,
+                delay: 0,
+                options: [.beginFromCurrentState, .curveEaseInOut],
+                animations: apply,
+                completion: completion
+            )
+        } else {
+            apply()
+            completion(true)
+        }
+    }
+
+    private static let scrollToBottomButtonMargin: CGFloat = 12
+
+    private func layoutScrollToBottomButton(aboveDockTop dockTop: CGFloat) {
+        guard let button = scrollToBottomButton else { return }
+        let size = ScrollToBottomButton.diameter
+        let margin = Self.scrollToBottomButtonMargin
+        let referenceTop = chromeHidden ? bounds.height - safeAreaInsetsBottom : dockTop
+        let x = max(0, bounds.width - size - margin)
+        let y = referenceTop - size - margin
+        button.frame = CGRect(x: x, y: max(0, y), width: size, height: size)
     }
 
     /// Animate the whole bottom dock (composer band + toolbar) in lockstep with a
@@ -1820,6 +1898,7 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         ) { [weak self] in
             self?.composerContainer.frame = frames.composer
             self?.dockedToolbar?.frame = frames.toolbar
+            self?.layoutScrollToBottomButton(aboveDockTop: frames.toolbar.minY)
         }
     }
 
@@ -3557,6 +3636,10 @@ extension GhosttySurfaceView: UIGestureRecognizerDelegate {
            let touched = touch.view, touched.isDescendant(of: composerContainer) {
             return false
         }
+        if let touched = touch.view,
+           touched is UIControl || touched.superview is UIControl {
+            return false
+        }
         return true
     }
 }
diff --git a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/ScrollToBottomButton.swift b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/ScrollToBottomButton.swift
new file mode 100644
index 000000000000..5ed67be7656a
--- /dev/null
+++ b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/ScrollToBottomButton.swift
@@ -0,0 +1,61 @@
+#if canImport(UIKit)
+  import UIKit
+
+  @MainActor
+  final class ScrollToBottomButton: UIButton {
+    var onTap: (() -> Void)?
+
+    static let diameter: CGFloat = 40
+
+    private let backgroundView = UIVisualEffectView(
+      effect: UIBlurEffect(style: .systemThinMaterial))
+    private let iconView = UIImageView(image: UIImage(systemName: "arrow.down"))
+
+    override init(frame: CGRect) {
+      super.init(frame: frame)
+      isAccessibilityElement = true
+      accessibilityIdentifier = "terminal.scrollToBottom"
+      accessibilityLabel = String(
+        localized: "terminal.input_accessory.scroll_to_bottom",
+        defaultValue: "Scroll to Bottom"
+      )
+
+      backgroundView.isUserInteractionEnabled = false
+      backgroundView.clipsToBounds = true
+      addSubview(backgroundView)
+
+      iconView.isUserInteractionEnabled = false
+      iconView.tintColor = .label
+      iconView.contentMode = .scaleAspectFit
+      addSubview(iconView)
+
+      addTarget(self, action: #selector(handleTap), for: .touchUpInside)
+    }
+
+    @available(*, unavailable, message: "Use init(frame:) instead.")
+    required init?(coder: NSCoder) {
+      return nil
+    }
+
+    override var intrinsicContentSize: CGSize {
+      CGSize(width: Self.diameter, height: Self.diameter)
+    }
+
+    override func layoutSubviews() {
+      super.layoutSubviews()
+      backgroundView.frame = bounds
+      backgroundView.layer.cornerRadius = bounds.height / 2
+      let iconSide: CGFloat = 18
+      iconView.frame = CGRect(
+        x: (bounds.width - iconSide) / 2,
+        y: (bounds.height - iconSide) / 2,
+        width: iconSide,
+        height: iconSide
+      )
+    }
+
+    @objc private func handleTap() {
+      onTap?()
+    }
+  }
+#endif
diff --git a/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Hosting/TerminalSurfaceNativeViewing.swift b/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Hosting/TerminalSurfaceNativeViewing.swift
index 8818f4e49032..9fe483a910c6 100644
--- a/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Hosting/TerminalSurfaceNativeViewing.swift
+++ b/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Hosting/TerminalSurfaceNativeViewing.swift
@@ -20,6 +20,10 @@ public protocol TerminalSurfaceNativeViewing: NSView, TerminalSurfaceHosting {
     /// Whether keyboard copy mode is active on this view.
     var isKeyboardCopyModeActive: Bool { get }
 
+    /// Whether the native viewport is currently pinned to the terminal's live
+    /// bottom. `nil` means the view has not received a scrollbar packet yet.
+    var mobileViewportAtBottom: Bool? { get }
+
     /// Toggles keyboard copy mode.
     ///
     /// - Returns: Whether the view handled the toggle.
@@ -35,3 +39,9 @@ public protocol TerminalSurfaceNativeViewing: NSView, TerminalSurfaceHosting {
     @discardableResult
     func forceRefreshSurface() -> Bool
 }
+
+/// Default mobile viewport metadata for native terminal view adapters.
+public extension TerminalSurfaceNativeViewing {
+    /// Whether the mobile mirror of this terminal is pinned to the live bottom.
+    var mobileViewportAtBottom: Bool? { nil }
+}
diff --git a/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift b/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift
index a726c74c652e..bcfd325953c6 100644
--- a/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift
+++ b/Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift
@@ -86,9 +86,10 @@ extension TerminalSurface {
         guard let ptr = exported.ptr, exported.len > 0 else { return nil }
 
         let data = Data(bytes: ptr, count: Int(exported.len))
-        guard let fullFrame = try? JSONDecoder().decode(MobileTerminalRenderGridFrame.self, from: data) else {
+        guard var fullFrame = try? JSONDecoder().decode(MobileTerminalRenderGridFrame.self, from: data) else {
             return nil
         }
+        fullFrame.atBottom = (attachedView ?? surfaceView).mobileViewportAtBottom
         let frame: MobileTerminalRenderGridFrame
         if full, changedRows == nil {
             frame = fullFrame
diff --git a/Sources/GhosttyTerminalView.swift b/Sources/GhosttyTerminalView.swift
index b358a9991c71..9edd8cca8527 100644
--- a/Sources/GhosttyTerminalView.swift
+++ b/Sources/GhosttyTerminalView.swift
@@ -3537,6 +3537,12 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
     // internal (not fileprivate): witnesses for TerminalSurfaceNativeViewing
     // must match the conforming class's access level.
     var isKeyboardCopyModeActive: Bool { keyboardCopyModeActive }
+    var mobileViewportAtBottom: Bool? {
+        _ = flushPendingScrollbarIfAvailable()
+        guard let scrollbar else { return nil }
+        return scrollbar.offset + scrollbar.len >= scrollbar.total
+    }
+
     var currentKeyStateIndicatorText: String? {
         if let name = keyTables.last {
             return terminalKeyTableIndicatorText(name)
diff --git a/Sources/Mobile/MobileTerminalRenderObserver.swift b/Sources/Mobile/MobileTerminalRenderObserver.swift
index 07debc8ddc10..7d63c3f8bbc9 100644
--- a/Sources/Mobile/MobileTerminalRenderObserver.swift
+++ b/Sources/Mobile/MobileTerminalRenderObserver.swift
@@ -9,14 +9,19 @@ import Foundation
 final class MobileTerminalRenderObserver {
     static let shared = MobileTerminalRenderObserver()
 
-    private struct RenderGridState {
+    struct RenderGridState {
         var columns: Int
         var rows: Int
         var stateSeq: UInt64
+        var atBottom: Bool?
         /// Per-row signatures of text *and* resolved styling, so a style-only
         /// change (e.g. typing over a dimmed shell autosuggestion) still marks
         /// the row dirty. See `MobileTerminalRenderGridFrame.rowSignatures()`.
         var rowSignatures: [String]
+
+        func shouldEmitEmptyDelta(nextStateSeq: UInt64, nextAtBottom: Bool?) -> Bool {
+            stateSeq != nextStateSeq || atBottom != nextAtBottom
+        }
     }
 
     private var releaseFrameDemand: (() -> Void)?
@@ -203,7 +208,10 @@ final class MobileTerminalRenderObserver {
             }
 
             if changedRows.isEmpty {
-                guard previous.stateSeq != snapshot.frame.stateSeq else { return }
+                guard previous.shouldEmitEmptyDelta(
+                    nextStateSeq: snapshot.frame.stateSeq,
+                    nextAtBottom: snapshot.frame.atBottom
+                ) else { return }
                 guard let emptyFrame = try? MobileTerminalRenderGridFrame(
                     surfaceID: snapshot.frame.surfaceID,
                     stateSeq: snapshot.frame.stateSeq,
@@ -212,7 +220,8 @@ final class MobileTerminalRenderObserver {
                     cursor: snapshot.frame.cursor,
                     full: false,
                     styles: snapshot.frame.styles,
-                    rowSpans: []
+                    rowSpans: [],
+                    atBottom: snapshot.frame.atBottom
                 ) else {
                     return
                 }
@@ -231,6 +240,7 @@ final class MobileTerminalRenderObserver {
             columns: frame.columns,
             rows: frame.rows,
             stateSeq: frame.stateSeq,
+            atBottom: frame.atBottom,
             rowSignatures: nextSignatures
         )
         guard let payload = try? frame.jsonObject() else { return }
diff --git a/cmuxTests/MobileHostAuthorizationTests.swift b/cmuxTests/MobileHostAuthorizationTests.swift
index b187e8021817..98a57d446137 100644
--- a/cmuxTests/MobileHostAuthorizationTests.swift
+++ b/cmuxTests/MobileHostAuthorizationTests.swift
@@ -944,6 +944,21 @@ struct MobileHostAuthorizationTests {
         #expect(!MobileHostService.debugHasEventSubscribersForTesting(topic: "terminal.updated"))
         #expect(!observer.debugIsRetainingNotificationDemandForTesting)
     }
+
+    @Test func testTerminalRenderObserverEmitsAtBottomOnlyDelta() {
+        let previous = MobileTerminalRenderObserver.RenderGridState(
+            columns: 80,
+            rows: 24,
+            stateSeq: 10,
+            atBottom: true,
+            rowSignatures: Array(repeating: "same", count: 24)
+        )
+
+        #expect(!previous.shouldEmitEmptyDelta(nextStateSeq: 10, nextAtBottom: true))
+        #expect(previous.shouldEmitEmptyDelta(nextStateSeq: 10, nextAtBottom: false))
+        #expect(previous.shouldEmitEmptyDelta(nextStateSeq: 11, nextAtBottom: true))
+    }
+
     @Test func testMobileWorkspaceListHashIncludesDisplayedDirectories() {
         let workspace = Workspace(
             title: "Mobile",

From d4e6c0de556885e7aa6e56d8b89c71a4190cbb3a Mon Sep 17 00:00:00 2001
From: lawrencecchen <54008264+lawrencecchen@users.noreply.github.com>
Date: Tue, 23 Jun 2026 03:30:33 -0700
Subject: [PATCH 7/7] Show iOS jump-bottom button after local scroll

---
 .../GhosttySurfaceView.swift                  | 53 ++++++++++++++++---
 1 file changed, 46 insertions(+), 7 deletions(-)

diff --git a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
index 49598e2b6a00..26368d9b0e59 100644
--- a/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
+++ b/Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
@@ -1153,10 +1153,12 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
     /// flush with the grid bottom (no gap) and its bottom rests on the keyboard
     /// edge (up) or above the home indicator (down).
     private weak var dockedToolbar: UIView?
-    /// Floating jump-to-bottom button shown when the Mac reports this viewport is
-    /// scrolled up into scrollback.
+    /// Floating jump-to-bottom button shown when either the Mac reports this viewport
+    /// is scrolled up or the local iOS mirror has been scrolled away from newest
+    /// output before the Mac's authoritative state catches up.
     private weak var scrollToBottomButton: ScrollToBottomButton?
-    private var scrolledUp = false
+    private var remoteScrolledUp = false
+    private var localScrollbackLineOffset: Double = 0
     /// Whether the iMessage-style composer is currently open. The surface owns the
     /// whole bottom dock (terminal grid / toolbar / composer band / keyboard) in ONE
     /// coordinate system, so `composerActive` only drives the first-responder
@@ -1348,6 +1350,7 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
             self?.scrollToBottom()
         }
         addSubview(button)
+        bringSubviewToFront(button)
         scrollToBottomButton = button
     }
 
@@ -1814,14 +1817,14 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
 
     /// Updates whether the remote terminal viewport is away from the bottom.
     public func setScrolledUp(_ value: Bool) {
-        guard scrolledUp != value else { return }
-        scrolledUp = value
+        guard remoteScrolledUp != value else { return }
+        remoteScrolledUp = value
         layoutBottomDock()
         updateScrollToBottomButtonVisibility(animated: true)
     }
 
     private var scrollToBottomButtonShouldBeVisible: Bool {
-        scrolledUp && !chromeHidden
+        (remoteScrolledUp || localScrollbackLineOffset > 0.5) && !chromeHidden
     }
 
     private func updateScrollToBottomButtonVisibility(animated: Bool) {
@@ -1863,10 +1866,12 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         guard let button = scrollToBottomButton else { return }
         let size = ScrollToBottomButton.diameter
         let margin = Self.scrollToBottomButtonMargin
-        let referenceTop = chromeHidden ? bounds.height - safeAreaInsetsBottom : dockTop
+        let dockReferenceTop = chromeHidden ? bounds.height - safeAreaInsetsBottom : dockTop
+        let referenceTop = min(dockReferenceTop, bounds.height)
         let x = max(0, bounds.width - size - margin)
         let y = referenceTop - size - margin
         button.frame = CGRect(x: x, y: max(0, y), width: size, height: size)
+        bringSubviewToFront(button)
     }
 
     /// Animate the whole bottom dock (composer band + toolbar) in lockstep with a
@@ -1961,9 +1966,17 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         let cell = pendingScrollCell
         pendingScrollLines = 0
         applyLocalScrollbackScroll(lines: lines, col: cell.col, row: cell.row)
+        updateLocalScrollbackLineOffset(scrolledLines: lines)
         delegate?.ghosttySurfaceView(self, didScrollLines: lines, atCol: cell.col, row: cell.row)
     }
 
+    private func updateLocalScrollbackLineOffset(scrolledLines lines: Double) {
+        let nextOffset = max(0, localScrollbackLineOffset + lines)
+        guard abs(nextOffset - localScrollbackLineOffset) > 0.01 else { return }
+        localScrollbackLineOffset = nextOffset
+        updateScrollToBottomButtonVisibility(animated: true)
+    }
+
     /// A tap both raises the software keyboard (so the user can type) and
     /// forwards a left click at the tapped cell to the Mac. The Mac's libghostty
     /// self-gates: TUIs with mouse reporting get the click; a normal screen
@@ -2219,6 +2232,29 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         syncSurfaceVisibility()
     }
 
+    public override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        if let button = scrollToBottomButton,
+           !button.isHidden,
+           button.alpha > 0.01,
+           button.point(inside: convert(point, to: button), with: event) {
+            return button
+        }
+        return super.hitTest(point, with: event)
+    }
+
+    public override func point(inside point: CGPoint, with event: UIEvent?) -> Bool {
+        if super.point(inside: point, with: event) {
+            return true
+        }
+        if let button = scrollToBottomButton,
+           !button.isHidden,
+           button.alpha > 0.01,
+           button.point(inside: convert(point, to: button), with: event) {
+            return true
+        }
+        return false
+    }
+
     /// Re-seats the bottom dock and grid reservation when the safe-area inset
     /// changes.
     ///
@@ -2376,6 +2412,9 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
 
     private func scrollToBottom() {
         guard let surface else { return }
+        remoteScrolledUp = false
+        localScrollbackLineOffset = 0
+        updateScrollToBottomButtonVisibility(animated: true)
         scrollToBottom(surface: surface)
         delegate?.ghosttySurfaceViewDidRequestScrollToBottom(self)
     }