Decouple iOS primary terminal scroll

Packages/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Debug/ControlCommandCoordinator+Debug.swift

@@ -74,6 +74,8 @@ extension ControlCommandCoordinator {
             return debugSimulateTerminalFileDrop(request.params)
         case "debug.terminal.read_text":
             return debugReadTerminalText(request.params)
+        case "debug.terminal.scroll_to_row_offset":
+            return debugTerminalScrollToRowOffset(request.params)
         case "debug.terminal.render_stats":
             return debugRenderStats(request.params)
         case "debug.layout":

Packages/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Debug/ControlCommandCoordinator+Debug2.swift

@@ -232,6 +232,28 @@ extension ControlCommandCoordinator {
         return .ok(.object(["base64": .string(b64)]))
     }
 
+    /// `debug.terminal.scroll_to_row_offset` — drive Ghostty's fractional
+    /// row-offset scroll API for renderer verification.
+    func debugTerminalScrollToRowOffset(_ params: [String: JSONValue]) -> ControlCallResult {
+        let surfaceArg = string(params, "surface_id") ?? ""
+        guard let rowOffset = double(params, "row_offset"), rowOffset.isFinite else {
+            return .err(code: "invalid_params", message: "Missing or invalid row_offset", data: nil)
+        }
+        let didScroll = debugContext?.controlDebugTerminalScrollToRowOffset(
+            surfaceArgument: surfaceArg,
+            rowOffset: rowOffset
+        ) ?? false
+        guard didScroll else {
+            return .err(code: "not_found", message: "Terminal surface not found", data: .object([
+                "surface_id": .string(surfaceArg)
+            ]))
+        }
+        return .ok(.object([
+            "surface_id": .string(surfaceArg),
+            "row_offset": .double(rowOffset)
+        ]))
+    }
+
     /// `debug.terminal.render_stats` — renderer stats (shared v1 body's JSON,
     /// decoded exactly as the legacy wrapper did).
     func debugRenderStats(_ params: [String: JSONValue]) -> ControlCallResult {

Packages/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Debug/ControlDebugContext.swift

@@ -71,6 +71,16 @@ public protocol ControlDebugContext: AnyObject {
     /// - Returns: The raw v1 response (`"OK <base64>"` or an `ERROR:` line).
     func controlDebugReadTerminalText(surfaceArgument: String) -> String
 
+    /// Drives a terminal's Ghostty scrollback to a fractional row offset for
+    /// renderer verification.
+    ///
+    /// - Parameters:
+    ///   - surfaceArgument: The surface id/index argument (may be empty for the
+    ///     focused surface).
+    ///   - rowOffset: Fractional row offset from the top of primary scrollback.
+    /// - Returns: `true` when the target terminal exists and has a live surface.
+    func controlDebugTerminalScrollToRowOffset(surfaceArgument: String, rowOffset: Double) -> Bool
+
     /// Runs the shared v1 `render_stats` body for `debug.terminal.render_stats`.
     ///
     /// - Parameter surfaceArgument: The surface id/index argument.

Packages/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandContextTestStubs+Debug.swift

@@ -16,6 +16,7 @@ extension ControlDebugContext {
     func controlDebugActivateApp() -> String { "ERROR: not implemented" }
     func controlDebugIsTerminalFocused(surfaceArgument: String) -> String { "ERROR: not implemented" }
     func controlDebugReadTerminalText(surfaceArgument: String) -> String { "ERROR: not implemented" }
+    func controlDebugTerminalScrollToRowOffset(surfaceArgument: String, rowOffset: Double) -> Bool { false }
     func controlDebugRenderStats(surfaceArgument: String) -> String { "ERROR: not implemented" }
     func controlDebugLayout() -> String { "ERROR: not implemented" }
     func controlDebugBonsplitUnderflowCount() -> String { "ERROR: not implemented" }

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+LocalScrollbackScroll.swift

@@ -9,8 +9,8 @@ extension GhosttySurfaceView {
     /// screens libghostty turns this into mouse-wheel bytes; the mirror is
     /// display-only and drops those bytes, so the authoritative Mac response
     /// remains the visible update for TUIs.
-    func applyLocalScrollbackScroll(lines: Double, col: Int, row: Int) {
-        guard lines != 0, let surface else { return }
+    func applyLocalScrollbackScroll(pixelDeltaY: Double, col: Int, row: Int) {
+        guard pixelDeltaY != 0, let surface else { return }
         let displayScale = window?.windowScene?.screen.scale ?? traitCollection.displayScale
         let scale = max(Double(displayScale), 1)
         let size = ghostty_surface_size(surface)
@@ -19,7 +19,8 @@ extension GhosttySurfaceView {
         let posX = (Double(max(0, col)) + 0.5) * cellWidthPt
         let posY = (Double(max(0, row)) + 0.5) * cellHeightPt
         ghostty_surface_mouse_pos(surface, posX, posY, GHOSTTY_MODS_NONE)
-        ghostty_surface_mouse_scroll(surface, 0, lines, 0)
+        let precisionScrollMods: Int32 = 0b0000_0001
+        ghostty_surface_mouse_scroll(surface, 0, pixelDeltaY, precisionScrollMods)
         drawForWakeup()
     }
 }

Packages/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift

@@ -8,37 +8,6 @@ import UIKit
 
 private let log = Logger(subsystem: "ai.manaflow.cmux.ios", category: "ghostty.surface")
 
-// lint:allow namespace-enum — file-local DEBUG input-trace logger on the off-limits typing-latency render path; type reshape deferred to the GhosttySurfaceView UI-god-object split wave.
-enum TerminalInputDebugLog {
-    private static let isEnabled = ProcessInfo.processInfo.environment["CMUX_INPUT_DEBUG"] == "1"
-    private static let logger = Logger(subsystem: "ai.manaflow.cmux.ios", category: "ghostty.input")
-
-    static func log(_ message: String) {
-        #if DEBUG
-        if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil {
-            return
-        }
-        #endif
-        guard isEnabled else { return }
-        logger.debug("input: \(message, privacy: .public)")
-    }
-
-    static func textSummary(_ text: String) -> String {
-        let summary = String(reflecting: text)
-        guard summary.count > 96 else { return summary }
-        return "\(summary.prefix(96))..."
-    }
-
-    static func dataSummary(_ data: Data) -> String {
-        let prefix = data.prefix(32)
-        let prefixData = Data(prefix)
-        let hex = prefix.map { String(format: "%02X", $0) }.joined(separator: " ")
-        let utf8 = String(data: prefixData, encoding: .utf8) ?? "<non-utf8>"
-        let suffix = data.count > prefix.count ? " ..." : ""
-        return "len=\(data.count) hex=\(hex)\(suffix) utf8=\(textSummary(utf8))"
-    }
-}
-
 @MainActor
 public protocol GhosttySurfaceViewDelegate: AnyObject {
     func ghosttySurfaceView(_ surfaceView: GhosttySurfaceView, didProduceInput data: Data)
@@ -622,6 +591,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.
@@ -1784,14 +1755,17 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
         // deceleration, and momentum. The Mac still owns terminal semantics:
         // normal-screen scrollback and alt-screen mouse-wheel delivery.
         guard deltaY != 0 else { return }
+        let scale = max(preferredScreenScale, 1)
         let cellHeightPt = cellPixelSize.height / max(preferredScreenScale, 1)
         let divisor = cellHeightPt > 1 ? Double(cellHeightPt) * 3 : 42
         pendingScrollLines += -Double(deltaY) / divisor
+        pendingLocalScrollPixels += -Double(deltaY) * Double(scale)
         pendingScrollCell = scrollCell(at: touchPoint)
     }
 
     /// Coalesced native scroll forwarded to the Mac once per display-link frame.
     private var pendingScrollLines: Double = 0
+    private var pendingLocalScrollPixels: Double = 0
     private var pendingScrollCell: (col: Int, row: Int) = (0, 0)
 
     /// Map a touch point to a grid cell (shared effective grid with the Mac), so
@@ -1806,11 +1780,17 @@ public final class GhosttySurfaceView: UIView, TerminalSurfaceHosting {
     }
 
     private func flushPendingScrollIfNeeded() {
-        guard pendingScrollLines != 0 else { return }
+        guard pendingScrollLines != 0 || pendingLocalScrollPixels != 0 else { return }
         let lines = pendingScrollLines
+        let pixelDeltaY = pendingLocalScrollPixels
         let cell = pendingScrollCell
         pendingScrollLines = 0
-        applyLocalScrollbackScroll(lines: lines, col: cell.col, row: cell.row)
+        pendingLocalScrollPixels = 0
+        applyLocalScrollbackScroll(pixelDeltaY: pixelDeltaY, col: cell.col, row: cell.row)
+        guard scrollForwardingPolicy.shouldForwardToHost(activeScreen: activeScreen) else {
+            return
+        }
+        guard lines != 0 else { return }
         delegate?.ghosttySurfaceView(self, didScrollLines: lines, atCol: cell.col, row: cell.row)
     }
 
@@ -2109,6 +2089,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/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalInputDebugLog.swift

@@ -0,0 +1,35 @@
+#if canImport(UIKit)
+import Foundation
+import OSLog
+
+// lint:allow namespace-enum — DEBUG input-trace logger on the off-limits typing-latency render path; type reshape deferred to the GhosttySurfaceView UI-god-object split wave.
+enum TerminalInputDebugLog {
+    private static let isEnabled = ProcessInfo.processInfo.environment["CMUX_INPUT_DEBUG"] == "1"
+    private static let logger = Logger(subsystem: "ai.manaflow.cmux.ios", category: "ghostty.input")
+
+    static func log(_ message: String) {
+        #if DEBUG
+        if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil {
+            return
+        }
+        #endif
+        guard isEnabled else { return }
+        logger.debug("input: \(message, privacy: .public)")
+    }
+
+    static func textSummary(_ text: String) -> String {
+        let summary = String(reflecting: text)
+        guard summary.count > 96 else { return summary }
+        return "\(summary.prefix(96))..."
+    }
+
+    static func dataSummary(_ data: Data) -> String {
+        let prefix = data.prefix(32)
+        let prefixData = Data(prefix)
+        let hex = prefix.map { String(format: "%02X", $0) }.joined(separator: " ")
+        let utf8 = String(data: prefixData, encoding: .utf8) ?? "<non-utf8>"
+        let suffix = data.count > prefix.count ? " ..." : ""
+        return "len=\(data.count) hex=\(hex)\(suffix) utf8=\(textSummary(utf8))"
+    }
+}
+#endif

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))
+    }
+}

Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Debug.swift

@@ -69,6 +69,15 @@ extension TerminalSurface {
         additionalEnvironment
     }
 
+    /// Test-only helper to drive Ghostty scrollback by fractional row offset.
+    @MainActor
+    public func debugScrollToRowOffsetForTesting(_ rowOffset: Double) -> Bool {
+        guard let surface else { return false }
+        ghostty_surface_scroll_to_offset(surface, rowOffset)
+        forceRefresh(reason: "debugScrollToRowOffsetForTesting")
+        return true
+    }
+
     /// How many force refreshes ran since the last reset.
     public func debugForceRefreshCount() -> Int {
         debugForceRefreshCountLock.lock()

Sources/TerminalController+ControlDebugContext.swift

@@ -68,6 +68,19 @@ extension TerminalController: ControlDebugContext {
         readTerminalText(surfaceArgument)
     }
 
+    func controlDebugTerminalScrollToRowOffset(surfaceArgument: String, rowOffset: Double) -> Bool {
+        guard let tabManager else { return false }
+        let trimmed = surfaceArgument.trimmingCharacters(in: .whitespacesAndNewlines)
+        let panel: TerminalPanel?
+        if trimmed.isEmpty {
+            panel = tabManager.selectedTerminalPanel
+        } else {
+            panel = resolveTerminalPanel(from: trimmed, tabManager: tabManager)
+        }
+        guard let panel else { return false }
+        return panel.surface.debugScrollToRowOffsetForTesting(rowOffset)
+    }
+
     func controlDebugRenderStats(surfaceArgument: String) -> String {
         renderStats(surfaceArgument)
     }