Decouple iOS primary terminal scroll

Packages/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift

@@ -29,7 +29,11 @@ extension MobileShellComposite {
         terminalOutputQueuesBySurfaceID[surfaceID] = queue
         if let immediate {
             continuation.yield(
-                MobileTerminalOutputChunk(data: immediate.bytes, streamToken: streamToken)
+                MobileTerminalOutputChunk(
+                    data: immediate.bytes,
+                    streamToken: streamToken,
+                    activeScreen: immediate.activeScreen
+                )
             )
         }
     }
@@ -45,6 +49,10 @@ extension MobileShellComposite {
               terminalOutputStreamTokensBySurfaceID[surfaceID] == streamToken else {
             return
         }
-        continuation.yield(MobileTerminalOutputChunk(data: next.bytes, streamToken: streamToken))
+        continuation.yield(MobileTerminalOutputChunk(
+            data: next.bytes,
+            streamToken: streamToken,
+            activeScreen: next.activeScreen
+        ))
     }
 }

Packages/CmuxMobileShell/Sources/CmuxMobileShell/TerminalOutputDelivery.swift

@@ -29,6 +29,15 @@ struct TerminalOutputDelivery: Equatable, Sendable {
             frame.vtPatchBytes()
         }
     }
+
+    var activeScreen: MobileTerminalRenderGridFrame.Screen? {
+        switch payload {
+        case .bytes:
+            nil
+        case .renderGrid(let frame):
+            frame.activeScreen
+        }
+    }
 }
 
 /// Backpressure queue for one mounted mobile terminal output stream.

Packages/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalOutputDeliveryQueueTests.swift

@@ -90,6 +90,22 @@ import Testing
     #expect(!vt.contains("old"))
 }
 
+@Test func terminalOutputDeliveryCarriesRenderGridActiveScreen() throws {
+    let frame = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal",
+        stateSeq: 1,
+        columns: 12,
+        rows: 2,
+        rowSpans: [],
+        activeScreen: .alternate
+    )
+    let delivery = TerminalOutputDelivery(renderGrid: frame, replaceable: false)
+    let rawDelivery = TerminalOutputDelivery(bytes: Data("raw".utf8), replaceable: false)
+
+    #expect(delivery.activeScreen == .alternate)
+    #expect(rawDelivery.activeScreen == nil)
+}
+
 @Test func terminalOutputQueuePreservesNonreplaceableBarriers() {
     var queue = TerminalOutputDeliveryQueue()
     let inFlight = TerminalOutputDelivery(bytes: Data("in-flight".utf8), replaceable: false)

Packages/CmuxMobileShellModel/Sources/CmuxMobileShellModel/MobileTerminalOutputSinking.swift

@@ -1,3 +1,4 @@
+public import CMUXMobileCore
 public import Foundation
 
 /// A seam exposing per-surface terminal output as an `AsyncStream`.
@@ -14,10 +15,18 @@ public import Foundation
 /// propagation is a structured, cancellable `AsyncSequence` instead of a stored
 /// callback.
 public struct MobileTerminalOutputChunk: Sendable {
+    /// The active terminal screen captured by the render-grid frame that
+    /// produced ``data``. Raw byte fallback chunks carry `nil`.
+    public let activeScreen: MobileTerminalRenderGridFrame.Screen?
     public let data: Data
     public let streamToken: UUID
 
-    public init(data: Data, streamToken: UUID) {
+    public init(
+        data: Data,
+        streamToken: UUID,
+        activeScreen: MobileTerminalRenderGridFrame.Screen? = nil
+    ) {
+        self.activeScreen = activeScreen
         self.data = data
         self.streamToken = streamToken
     }

Packages/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift

@@ -137,6 +137,7 @@ struct GhosttySurfaceRepresentable: UIViewRepresentable {
                 for await chunk in store.terminalOutputStream(surfaceID: surfaceID) {
                     guard !Task.isCancelled else { return }
                     guard let surfaceView else { return }
+                    surfaceView.applyTerminalOutputMetadata(activeScreen: chunk.activeScreen)
                     await surfaceView.processOutputAndWait(chunk.data)
                     store.terminalOutputDidProcess(
                         surfaceID: surfaceID,

Packages/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift

@@ -622,6 +622,8 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
     private var lastAppliedContentScale: CGFloat = 0
     private var surfaceHasReceivedOutput: Bool = false
     private var shouldScrollInitialOutputToBottom = true
+    private var activeScreen: MobileTerminalRenderGridFrame.Screen = .primary
+    private let scrollForwardingPolicy = MobileTerminalScrollForwardingPolicy()
     /// Serial background queue for `ghostty_surface_process_output`, which
     /// blocks on libghostty's internal renderer/IO futex. Running it on the
     /// main thread hangs the app until the scene-update watchdog kills it.
@@ -1811,6 +1813,9 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         let cell = pendingScrollCell
         pendingScrollLines = 0
         applyLocalScrollbackScroll(lines: lines, col: cell.col, row: cell.row)
+        guard scrollForwardingPolicy.shouldForwardToHost(activeScreen: activeScreen) else {
+            return
+        }
         delegate?.ghosttySurfaceView(self, didScrollLines: lines, atCol: cell.col, row: cell.row)
     }
 
@@ -2109,6 +2114,20 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         processOutput(data, completion: nil)
     }
 
+    /// Applies metadata attached to the next terminal output chunk.
+    ///
+    /// Render-grid output carries the authoritative active screen, which lets
+    /// local scrollback stay phone-local on the primary screen while alternate
+    /// screen TUIs still receive host mouse-wheel events.
+    /// - Parameter activeScreen: The active screen from the render-grid frame,
+    ///   or `nil` for raw byte fallback chunks.
+    public func applyTerminalOutputMetadata(
+        activeScreen: MobileTerminalRenderGridFrame.Screen?
+    ) {
+        guard let activeScreen else { return }
+        self.activeScreen = activeScreen
+    }
+
     /// Process terminal output and return after the output has been applied.
     ///
     /// The call still performs libghostty output processing on the serial

Packages/CmuxMobileTerminalKit/Sources/CmuxMobileTerminalKit/MobileTerminalScrollForwardingPolicy.swift

@@ -0,0 +1,22 @@
+public import CMUXMobileCore
+
+/// Decides whether a mobile terminal scroll gesture must be sent to the Mac.
+public struct MobileTerminalScrollForwardingPolicy: Sendable {
+    /// Creates the forwarding policy.
+    public init() {}
+
+    /// Returns whether a scroll should be forwarded to the host surface.
+    ///
+    /// Primary-screen scrollback is already mirrored into the phone's local
+    /// Ghostty surface, so forwarding would make scroll feel network-bound.
+    /// Alternate-screen scroll must still reach the host so TUIs with mouse
+    /// reporting receive wheel events.
+    /// - Parameter activeScreen: The screen currently rendered by the mobile
+    ///   Ghostty mirror.
+    /// - Returns: `true` when the scroll should be sent to the Mac.
+    public func shouldForwardToHost(
+        activeScreen: MobileTerminalRenderGridFrame.Screen
+    ) -> Bool {
+        activeScreen == .alternate
+    }
+}

Packages/CmuxMobileTerminalKit/Tests/CmuxMobileTerminalKitTests/MobileTerminalScrollForwardingPolicyTests.swift

@@ -0,0 +1,17 @@
+import CMUXMobileCore
+import CmuxMobileTerminalKit
+import Testing
+
+@Suite struct MobileTerminalScrollForwardingPolicyTests {
+    @Test func primaryScreenScrollStaysLocal() {
+        let policy = MobileTerminalScrollForwardingPolicy()
+
+        #expect(policy.shouldForwardToHost(activeScreen: .primary) == false)
+    }
+
+    @Test func alternateScreenScrollForwardsToHost() {
+        let policy = MobileTerminalScrollForwardingPolicy()
+
+        #expect(policy.shouldForwardToHost(activeScreen: .alternate))
+    }
+}