iPhone First: an open iPhone sets the shared terminal size by default

CLI/CMUXCLI+SurfaceSizing.swift

@@ -30,10 +30,16 @@ extension CMUXCLI {
             let (rows, afterRows) = parseOption(afterCols, name: "--rows")
             remaining = afterRows
             guard let mode = remaining.first else {
-                throw CLIError(message: "surface size-policy requires a mode: latest, smallest, largest, priority or fixed")
+                throw CLIError(message: "surface size-policy requires a mode: iphone-first, latest, smallest, largest, priority or fixed")
             }
             remaining.removeFirst()
-            params["mode"] = mode.lowercased()
+            if mode.lowercased() == "iphone-first" {
+                // iPhone First fits everyone while no phone is attached.
+                params["mode"] = "smallest"
+                params["handheld_first"] = true
+            } else {
+                params["mode"] = mode.lowercased()
+            }
             if let cols, let rows {
                 guard let colsValue = Int(cols), let rowsValue = Int(rows) else {
                     throw CLIError(message: "surface size-policy: --cols and --rows must be integers")
@@ -86,7 +92,9 @@ extension CMUXCLI {
         }
         let selfID = payload["self_participant_id"] as? String
         let owners = Set(state["owners"] as? [String] ?? [])
-        let mode = (state["policy"] as? [String: Any])?["mode"] as? String ?? "smallest"
+        let policy = state["policy"] as? [String: Any]
+        let mode = policy?["handheld_first"] as? Bool == true
+            ? "iphone-first" : policy?["mode"] as? String ?? "smallest"
         var lines = ["\(cols)x\(rows)  mode=\(mode)  reason=\(state["reason"] as? String ?? "")"]
         if let detachment = payload["detachment"] as? [String: Any] {
             // The grid above is the last state seen before this view was detached.

CLI/CMUXCLI+VMTui.swift

@@ -836,7 +836,7 @@ extension CMUXCLI {
                \(String(localized: "cli.surface.newDisplay.usage", defaultValue: "cmux surface new-display --machine <cloud-id> [--workspace <id|ref|index>] [--no-open] [--focus|--no-focus] [--json]", bundle: CLIExecutableLocator.enclosingAppBundle() ?? .main))
                cmux surface resume …   (restart metadata; see `cmux surface resume --help`)
                cmux surface size [--surface <id|ref>] [--json]
-               cmux surface size-policy <latest|smallest|largest|priority|fixed> [--cols N --rows N] [--surface <id|ref>]
+               cmux surface size-policy <iphone-first|latest|smallest|largest|priority|fixed> [--cols N --rows N] [--surface <id|ref>]
                cmux surface size-to-me [--surface <id|ref>]
                cmux surface size-counts <true|false|auto> [--participant <id>] [--surface <id|ref>]
                cmux surface participants [--surface <id|ref>] [--json]

CLI/Commands/SurfaceCommands.swift

@@ -296,7 +296,7 @@ struct SurfaceSizePolicyCommand: SharedLegacyFacadeCommand {
     // Strings, not Int: the legacy runner owns the integer check.
     @Option(name: .customLong("cols")) var cols: String?
     @Option(name: .customLong("rows")) var rows: String?
-    @Argument(completion: .list(["latest", "smallest", "largest", "priority", "fixed"])) var mode: String?
+    @Argument(completion: .list(["iphone-first", "latest", "smallest", "largest", "priority", "fixed"])) var mode: String?
     @Argument(parsing: .allUnrecognized) var arguments: [String] = []
     static let configuration = CommandConfiguration(commandName: "size-policy", helpNames: [])
 }

CLI/cmux.swift

@@ -22707,7 +22707,7 @@ struct CMUXCLI {
                    cmux surface resume get [--json] [flags]
                    cmux surface resume clear [flags]
                    cmux surface size|participants [--surface <id|ref|index>] [--json]
-                   cmux surface size-policy <latest|smallest|largest|priority|fixed> [--cols <n> --rows <n>] [--surface <id|ref|index>]
+                   cmux surface size-policy <iphone-first|latest|smallest|largest|priority|fixed> [--cols <n> --rows <n>] [--surface <id|ref|index>]
                    cmux surface size-to-me|disconnect-others [--surface <id|ref|index>]
                    cmux surface size-counts <true|false|auto> [--participant <id>] [--surface <id|ref|index>]
                    cmux surface disconnect-participant <participant-id> [--surface <id|ref|index>]

Packages/Shared/CmuxTerminalSizing/Sources/CmuxTerminalSizing/TerminalSizingEngine.swift

@@ -19,7 +19,7 @@ public struct TerminalSizingEngine: Sendable {
     /// - Parameters:
     ///   - initialSize: the grid before anyone reports, usually the PTY's current size.
     ///   - policy: the effective policy (workspace default or terminal override).
-    public init(initialSize: TerminalGridSize, policy: TerminalSizingPolicy = .fitEveryone) {
+    public init(initialSize: TerminalGridSize, policy: TerminalSizingPolicy = .standard) {
         self.policy = policy
         self.held = initialSize.clamped
         self.state = TerminalSizingState(
@@ -100,6 +100,8 @@ public struct TerminalSizingEngine: Sendable {
         let p = entry.participant
         guard p.viewport != nil else { return false }
         if let explicit = p.countsOverride { return explicit }
+        // iPhone First: an open phone always counts, so it can own the grid.
+        if policy.handheldFirst && p.deviceKind.isHandheld { return true }
         // Fit-everyone modes promise to count every attached view; the handheld
         // deferral only stops a phone from taking the grid by activity.
         if policy.mode == .smallest || policy.mode == .largest { return true }
@@ -121,6 +123,13 @@ public struct TerminalSizingEngine: Sendable {
         func newest(_ list: [Entry]) -> Entry {
             list.max { $0.activity < $1.activity }!
         }
+        if policy.handheldFirst {
+            let handhelds = counting.filter { $0.participant.deviceKind.isHandheld }
+            if !handhelds.isEmpty {
+                let owner = newest(handhelds)
+                return (owner.participant.viewport!, [owner.participant.id], .latest)
+            }
+        }
         switch policy.mode {
         case .latest, .fixed:
             let owner = newest(counting)

Packages/Shared/CmuxTerminalSizing/Sources/CmuxTerminalSizing/TerminalSizingTypes.swift

@@ -126,14 +126,30 @@ public struct TerminalSizingPolicy: Codable, Hashable, Sendable {
     public var priority: [String]
     /// Grid used by `.fixed`.
     public var fixed: TerminalGridSize?
+    /// Whether an attached phone or tablet sets the grid ("iPhone First").
+    /// While one counts, the newest active handheld owns the whole grid and
+    /// `mode` waits; when none is attached, `mode` decides. `fixed` with a
+    /// grid still wins. A policy decoded without this key is an explicit
+    /// choice and has it off.
+    public var handheldFirst: Bool
 
-    public init(mode: TerminalSizingMode = .smallest, priority: [String] = [], fixed: TerminalGridSize? = nil) {
+    public init(
+        mode: TerminalSizingMode = .smallest,
+        priority: [String] = [],
+        fixed: TerminalGridSize? = nil,
+        handheldFirst: Bool = false
+    ) {
         self.mode = mode
         self.priority = priority
         self.fixed = fixed?.clamped
+        self.handheldFirst = handheldFirst
     }
 
-    /// The default: fit everyone, so every attached device sees the whole grid.
+    /// The default: an attached phone sets the grid while it views the
+    /// terminal, and the grid fits everyone else when no phone is attached.
+    public static let standard = TerminalSizingPolicy(mode: .smallest, handheldFirst: true)
+
+    /// Fit everyone, so every attached device sees the whole grid.
     public static let fitEveryone = TerminalSizingPolicy(mode: .smallest)
 
     public static let latest = TerminalSizingPolicy(mode: .latest)
@@ -154,7 +170,8 @@ public struct TerminalSizingPolicy: Codable, Hashable, Sendable {
         self.init(
             mode: try c.decodeIfPresent(TerminalSizingMode.self, forKey: .mode) ?? .smallest,
             priority: try c.decodeIfPresent([String].self, forKey: .priority) ?? [],
-            fixed: try c.decodeIfPresent(TerminalGridSize.self, forKey: .fixed)
+            fixed: try c.decodeIfPresent(TerminalGridSize.self, forKey: .fixed),
+            handheldFirst: try c.decodeIfPresent(Bool.self, forKey: .handheldFirst) ?? false
         )
     }
 
@@ -163,9 +180,51 @@ public struct TerminalSizingPolicy: Codable, Hashable, Sendable {
         try c.encode(mode, forKey: .mode)
         try c.encode(priority, forKey: .priority)
         try c.encode(fixed, forKey: .fixed)
+        try c.encode(handheldFirst, forKey: .handheldFirst)
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case mode, priority, fixed
+        case handheldFirst = "handheld_first"
+    }
+}
+
+/// One entry of a size picker: "iPhone First" or one plain mode.
+public enum TerminalSizingChoice: Hashable, Sendable {
+    case handheldFirst
+    case mode(TerminalSizingMode)
+
+    /// Every picker entry, "iPhone First" first.
+    public static let allCases: [TerminalSizingChoice] =
+        [.handheldFirst] + TerminalSizingMode.allCases.map(TerminalSizingChoice.mode)
+}
+
+extension TerminalSizingPolicy {
+    /// The picker entry this policy shows as.
+    public var choice: TerminalSizingChoice {
+        handheldFirst ? .handheldFirst : .mode(mode)
     }
 
-    enum CodingKeys: String, CodingKey { case mode, priority, fixed }
+    /// The same policy with another picker entry chosen, keeping the
+    /// priority list and fixed grid. A plain mode turns "iPhone First" off;
+    /// "iPhone First" fits everyone while no phone is attached.
+    ///
+    /// - Parameters:
+    ///   - choice: the picked entry.
+    ///   - fallbackFixed: the grid `fixed` uses when no fixed grid is set yet.
+    /// - Returns: the adjusted policy.
+    public func withChoice(_ choice: TerminalSizingChoice, fallbackFixed: TerminalGridSize) -> TerminalSizingPolicy {
+        switch choice {
+        case .handheldFirst:
+            return TerminalSizingPolicy(mode: .smallest, priority: priority, fixed: fixed, handheldFirst: true)
+        case let .mode(mode):
+            return TerminalSizingPolicy(
+                mode: mode,
+                priority: priority,
+                fixed: mode == .fixed ? (fixed ?? fallbackFixed) : fixed
+            )
+        }
+    }
 }
 
 /// Why the grid has its current size.
@@ -320,6 +379,6 @@ extension TerminalSizingPolicy {
                 keys.append(next)
             }
         }
-        return TerminalSizingPolicy(mode: mode, priority: keys, fixed: fixed)
+        return TerminalSizingPolicy(mode: mode, priority: keys, fixed: fixed, handheldFirst: handheldFirst)
     }
 }

Packages/Shared/CmuxTerminalSizing/Tests/CmuxTerminalSizingTests/TerminalSizingHandheldFirstTests.swift

@@ -0,0 +1,51 @@
+import CmuxTerminalSizing
+import Foundation
+import Testing
+
+/// "iPhone First" is the default policy. A policy stored or sent before the
+/// key existed is an explicit choice and keeps its old behavior.
+struct TerminalSizingHandheldFirstTests {
+    @Test func defaultPolicyIsHandheldFirstOverFitEveryone() {
+        #expect(TerminalSizingPolicy.standard.handheldFirst)
+        #expect(TerminalSizingPolicy.standard.mode == .smallest)
+        #expect(TerminalSizingEngine(initialSize: TerminalGridSize(cols: 80, rows: 24)).state.policy == .standard)
+    }
+
+    @Test func policyWithoutTheKeyDecodesWithHandheldFirstOff() throws {
+        let data = Data(#"{"mode":"latest","priority":[],"fixed":null}"#.utf8)
+        let policy = try JSONDecoder().decode(TerminalSizingPolicy.self, from: data)
+        #expect(policy == .latest)
+        #expect(!policy.handheldFirst)
+    }
+
+    @Test func policyRoundTripsHandheldFirst() throws {
+        let data = try JSONEncoder().encode(TerminalSizingPolicy.standard)
+        let object = try #require(JSONSerialization.jsonObject(with: data) as? [String: Any])
+        #expect(object["handheld_first"] as? Bool == true)
+        #expect(try JSONDecoder().decode(TerminalSizingPolicy.self, from: data) == .standard)
+    }
+
+    @Test func pickingAModeTurnsHandheldFirstOffAndPickingItBackFitsEveryone() {
+        let grid = TerminalGridSize(cols: 90, rows: 30)
+        let latest = TerminalSizingPolicy.standard.withChoice(.mode(.latest), fallbackFixed: grid)
+        #expect(latest == .latest)
+        #expect(latest.choice == .mode(.latest))
+        let fixed = TerminalSizingPolicy.standard.withChoice(.mode(.fixed), fallbackFixed: grid)
+        #expect(fixed.fixed == grid)
+        #expect(!fixed.handheldFirst)
+        let back = TerminalSizingPolicy(mode: .priority, priority: ["k"]).withChoice(.handheldFirst, fallbackFixed: grid)
+        #expect(back == TerminalSizingPolicy(mode: .smallest, priority: ["k"], handheldFirst: true))
+        #expect(back.choice == .handheldFirst)
+    }
+
+    @Test func pickerListsHandheldFirstThenEveryMode() {
+        #expect(TerminalSizingChoice.allCases.first == .handheldFirst)
+        #expect(TerminalSizingChoice.allCases.count == TerminalSizingMode.allCases.count + 1)
+    }
+
+    @Test func legacyKeyMigrationKeepsHandheldFirst() {
+        let policy = TerminalSizingPolicy(mode: .priority, priority: ["u1/mac"], handheldFirst: true)
+        let mac = TerminalSizingParticipant(id: "m", userID: "u1", deviceKind: .mac, deviceID: "d")
+        #expect(policy.migratingLegacyPriorityKeys([mac]).handheldFirst)
+    }
+}

Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/MobileDisplaySettings.swift

@@ -117,8 +117,10 @@ public final class MobileDisplaySettings {
     }
 
     /// Whether an inactive iPhone releases its terminal viewport so a Mac can
-    /// take the grid. Defaults to `false`, preserving the host policy and the
-    /// last confirmed grid across a background/foreground transition.
+    /// take the grid. Defaults to `true`: under the default "iPhone First"
+    /// size policy the phone owns the whole grid while it views a terminal,
+    /// and the Mac gets it back once the app goes to the background. A stored
+    /// choice (either value) is kept.
     public var handoffTerminalSizingWhenInactive: Bool {
         didSet {
             defaults.set(
@@ -253,7 +255,7 @@ public final class MobileDisplaySettings {
         self.useLegacyTerminalSizing = defaults.object(forKey: Self.useLegacyTerminalSizingKey) as? Bool ?? false
         self.handoffTerminalSizingWhenInactive = defaults.object(
             forKey: Self.handoffTerminalSizingWhenInactiveKey
-        ) as? Bool ?? false
+        ) as? Bool ?? true
         self.hapticFeedbackEnabled = haptics.isEnabled
         self.terminalScrollbackRows = MobileTerminalScrollbackPreference.resolve(from: defaults)
         let storedPreviewLines = defaults.object(forKey: Self.workspacePreviewLineCountKey) as? Int

Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/TerminalSizeSheet.swift

@@ -71,11 +71,12 @@ struct TerminalSizeSheet: View {
     private func list(_ presentation: MobileTerminalSizingPresentation) -> some View {
         List {
             Section {
-                Picker(TerminalSizingText.sizePicker(), selection: modeBinding(presentation)) {
-                    ForEach(TerminalSizingMode.allCases, id: \.self) { mode in
-                        Text(TerminalSizingText.modeName(mode)).tag(mode)
+                Picker(TerminalSizingText.sizePicker(), selection: choiceBinding(presentation)) {
+                    ForEach(TerminalSizingChoice.allCases, id: \.self) { choice in
+                        Text(TerminalSizingText.choiceName(choice)).tag(choice)
                     }
                 }
+                .accessibilityIdentifier("MobileTerminalSizingModePicker")
                 .pickerStyle(.menu)
                 if presentation.policy.mode == .fixed {
                     fixedSizeRow(presentation)
@@ -263,18 +264,16 @@ struct TerminalSizeSheet: View {
 
     // MARK: Actions
 
-    private func modeBinding(_ presentation: MobileTerminalSizingPresentation) -> Binding<TerminalSizingMode> {
+    private func choiceBinding(_ presentation: MobileTerminalSizingPresentation) -> Binding<TerminalSizingChoice> {
         Binding(
-            get: { presentation.policy.mode },
-            set: { mode in
-                var policy = presentation.policy
-                policy.mode = mode
-                if mode == .fixed, policy.fixed == nil {
-                    policy.fixed = presentation.grid
+            get: { presentation.policy.choice },
+            set: { choice in
+                var policy = presentation.policy.withChoice(choice, fallbackFixed: presentation.grid)
+                if policy.mode == .fixed, presentation.policy.fixed == nil {
                     fixedColumns = presentation.grid.cols
                     fixedRows = presentation.grid.rows
                 }
-                if mode == .priority, policy.priority.isEmpty {
+                if policy.mode == .priority, policy.priority.isEmpty {
                     policy.priority = allRows(presentation).map(\.priorityKey)
                 }
                 run { await store.setTerminalSizePolicy(policy, surfaceID: surfaceID) }

Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/TerminalSizingText.swift

@@ -112,6 +112,13 @@ struct TerminalSizingText {
         L10n.string("mobile.terminal.sizing.chip.accessibilityHint", defaultValue: "Opens terminal size settings")
     }
 
+    static func choiceName(_ choice: TerminalSizingChoice) -> String {
+        switch choice {
+        case .handheldFirst: L10n.string("mobile.terminal.sizing.mode.handheldFirst", defaultValue: "iPhone first")
+        case let .mode(mode): modeName(mode)
+        }
+    }
+
     static func modeName(_ mode: TerminalSizingMode) -> String {
         switch mode {
         case .latest: L10n.string("mobile.terminal.sizing.mode.latest", defaultValue: "Follow latest")

Packages/iOS/CmuxMobileShellUI/Tests/CmuxMobileShellUITests/MobileDisplaySettingsTests.swift

@@ -115,10 +115,10 @@ import Testing
         #expect(!MobileDisplaySettings(defaults: defaults).useLegacyTerminalSizing)
     }
 
-    @Test func handoffTerminalSizingDefaultsToOffWithoutAWrite() throws {
+    @Test func handoffTerminalSizingDefaultsToOnWithoutAWrite() throws {
         let defaults = try makeDefaults("handoffTerminalSizingDefaults")
         let settings = MobileDisplaySettings(defaults: defaults)
-        #expect(!settings.handoffTerminalSizingWhenInactive)
+        #expect(settings.handoffTerminalSizingWhenInactive)
         #expect(defaults.object(forKey: "cmux.mobile.handoffTerminalSizingWhenInactive") == nil)
     }
 

Packages/macOS/CmuxTerminalSharing/Sources/CmuxTerminalSharing/LocalTerminalSizingHost.swift

@@ -39,7 +39,7 @@ public struct LocalTerminalSizingHost: Sendable {
     public init(
         macParticipant: TerminalSizingParticipant,
         initialSize: TerminalGridSize,
-        policy: TerminalSizingPolicy = .fitEveryone
+        policy: TerminalSizingPolicy = .standard
     ) {
         macParticipantID = macParticipant.id
         self.macParticipant = macParticipant

Packages/macOS/CmuxTerminalSharing/Sources/CmuxTerminalSharing/TerminalSharingStore.swift

@@ -73,8 +73,15 @@ public final class TerminalSharingStore {
     /// `fixed` without a fixed grid fixes the current grid.
     @discardableResult
     public func setMode(_ mode: TerminalSizingMode, surfaceID: UUID) -> Bool {
+        setChoice(.mode(mode), surfaceID: surfaceID)
+    }
+
+    /// Picks a size picker entry ("iPhone First" or a mode), keeping the
+    /// priority list and fixed grid.
+    @discardableResult
+    public func setChoice(_ choice: TerminalSizingChoice, surfaceID: UUID) -> Bool {
         guard let snapshot = snapshots[surfaceID] else { return false }
-        let policy = snapshot.state.policy.withMode(mode, fallbackFixed: snapshot.state.size)
+        let policy = snapshot.state.policy.withChoice(choice, fallbackFixed: snapshot.state.size)
         guard policy != snapshot.state.policy else { return true }
         return setPolicy(policy, surfaceID: surfaceID)
     }
@@ -92,7 +99,10 @@ public final class TerminalSharingStore {
     public func setPriority(_ keys: [String], surfaceID: UUID) -> Bool {
         guard let snapshot = snapshots[surfaceID] else { return false }
         let current = snapshot.state.policy
-        return setPolicy(TerminalSizingPolicy(mode: current.mode, priority: keys, fixed: current.fixed), surfaceID: surfaceID)
+        return setPolicy(
+            TerminalSizingPolicy(mode: current.mode, priority: keys, fixed: current.fixed, handheldFirst: current.handheldFirst),
+            surfaceID: surfaceID
+        )
     }
 
     /// Sets or clears one participant's counts override.