Clarify Cloud Ports and use the established VPN onboarding page

Sources/Cloud/CloudMachineSurfacePresentation.swift

@@ -42,29 +42,43 @@ struct CloudMachineSurfacePresentation {
     }
 
     static func emptyPorts(info: SurfaceMachineInfo) -> CloudTreeNode {
-        let text: String
-        let style: CloudTreePlaceholder.Style
-        switch info.linkState {
-        case .connecting:
-            text = String(localized: "cloudTree.ports.loading", defaultValue: "Discovering ports…")
-            style = .connecting
-        case .error:
-            text = info.linkError ?? String(localized: "cloudTree.ports.failed", defaultValue: "Couldn’t discover ports. Refresh to retry.")
-            style = .error
-        case .asleep:
-            text = String(localized: "cloudTree.ports.asleep", defaultValue: "Open the machine to discover ports")
-            style = .dimmed
-        case .unavailable:
-            text = String(localized: "cloudTree.ports.unavailable", defaultValue: "Port discovery unavailable. Refresh to retry.")
-            style = .dimmed
-        case .connected, .notApplicable:
-            text = String(localized: "cloudTree.ports.empty", defaultValue: "No reachable ports")
-            style = .dimmed
-        }
+        let presentation = CloudPortsStatusPresentation.make(info: info)
+        let style: CloudTreePlaceholder.Style = {
+            switch info.portDiscoveryState {
+            case .loading:
+                return .connecting
+            case .notRequested:
+                switch info.linkState {
+                case .connecting: return .connecting
+                case .error: return .error
+                default: return .dimmed
+                }
+            case .unavailable, .stale:
+                return .error
+            case .empty, .unsupported, .available:
+                return .dimmed
+            }
+        }()
+        return CloudTreeNode(
+            id: "machine:\(info.id.rawValue)/ports/status",
+            kind: .placeholder(machine: info.id, CloudTreePlaceholder(
+                text: presentation.title,
+                style: style,
+                opensMachine: info.linkState == .asleep || presentation.action == .openMachine,
+                portStatus: presentation
+            ))
+        )
+    }
+
+    static func portStatus(info: SurfaceMachineInfo) -> CloudTreeNode? {
+        guard info.portDiscoveryState.keepsStatusAlongsideRows else { return nil }
+        let presentation = CloudPortsStatusPresentation.make(info: info)
         return CloudTreeNode(
             id: "machine:\(info.id.rawValue)/ports/status",
             kind: .placeholder(machine: info.id, CloudTreePlaceholder(
-                text: text, style: style, opensMachine: info.linkState == .asleep
+                text: presentation.title,
+                style: .error,
+                portStatus: presentation
             ))
         )
     }

Sources/Cloud/CloudPortsStatusAction.swift

@@ -0,0 +1,9 @@
+import Foundation
+
+/// The action exposed by an actionable Ports status callout.
+enum CloudPortsStatusAction: Equatable {
+    case none
+    case refresh
+    case openMachine
+    case openShell
+}

Sources/Cloud/CloudPortsStatusContent.swift

@@ -0,0 +1,106 @@
+import AppKit
+
+/// Native, wrapping Ports guidance hosted above the outline's passthrough SwiftUI row.
+@MainActor
+final class CloudPortsStatusContent: NSView {
+    private let titleLabel = NSTextField(wrappingLabelWithString: "")
+    private let messageLabel = NSTextField(wrappingLabelWithString: "")
+    private let actionButton = NSButton(title: "", target: nil, action: nil)
+    private var presentation: CloudPortsStatusPresentation?
+    private var style = CloudTreeStyle.defaultStyle
+    private var actionHandler: (() -> Void)?
+
+    override var isFlipped: Bool { true }
+
+    override func hitTest(_ point: NSPoint) -> NSView? {
+        guard !actionButton.isHidden, actionButton.frame.contains(point) else { return nil }
+        return actionButton.hitTest(convert(point, to: actionButton))
+    }
+
+    override init(frame frameRect: NSRect) {
+        super.init(frame: frameRect)
+        titleLabel.font = .systemFont(ofSize: 11, weight: .semibold)
+        titleLabel.maximumNumberOfLines = 0
+        titleLabel.lineBreakMode = .byWordWrapping
+        messageLabel.maximumNumberOfLines = 0
+        messageLabel.lineBreakMode = .byWordWrapping
+        messageLabel.textColor = .secondaryLabelColor
+        actionButton.bezelStyle = .inline
+        actionButton.target = self
+        actionButton.action = #selector(performAction)
+        actionButton.setAccessibilityRole(.button)
+        addSubview(titleLabel)
+        addSubview(messageLabel)
+        addSubview(actionButton)
+        setAccessibilityRole(.group)
+        setAccessibilityIdentifier("CloudPortsStatus")
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    func configure(
+        presentation: CloudPortsStatusPresentation,
+        style: CloudTreeStyle,
+        action: @escaping () -> Void
+    ) {
+        self.presentation = presentation
+        self.style = style
+        actionHandler = action
+        titleLabel.stringValue = presentation.title
+        messageLabel.stringValue = presentation.message
+        actionButton.title = presentation.actionTitle ?? ""
+        actionButton.isHidden = presentation.action == .none || presentation.actionTitle == nil
+        actionButton.setAccessibilityLabel(presentation.actionTitle ?? presentation.title)
+        let fontSize = GlobalFontMagnification.scaledSize(max(10, style.detailSize))
+        titleLabel.font = .systemFont(ofSize: fontSize, weight: .semibold)
+        messageLabel.font = style.monospacedText
+            ? .monospacedSystemFont(ofSize: fontSize, weight: .regular)
+            : .systemFont(ofSize: fontSize)
+        setAccessibilityLabel("\(presentation.title), \(presentation.message)")
+        needsLayout = true
+    }
+
+    override func layout() {
+        super.layout()
+        let width = max(1, bounds.width)
+        let inset: CGFloat = 2
+        let titleHeight = Self.textHeight(titleLabel.stringValue, font: titleLabel.font ?? .systemFont(ofSize: 11), width: width - inset * 2)
+        titleLabel.frame = NSRect(x: inset, y: 2, width: width - inset * 2, height: titleHeight)
+        let messageY = titleLabel.frame.maxY + 2
+        let messageHeight = Self.textHeight(messageLabel.stringValue, font: messageLabel.font ?? .systemFont(ofSize: 11), width: width - inset * 2)
+        messageLabel.frame = NSRect(x: inset, y: messageY, width: width - inset * 2, height: messageHeight)
+        if actionButton.isHidden {
+            actionButton.frame = .zero
+        } else {
+            actionButton.frame = NSRect(x: inset, y: messageLabel.frame.maxY + 4, width: actionButton.fittingSize.width, height: 22)
+        }
+    }
+
+    override var intrinsicContentSize: NSSize {
+        guard let presentation else { return NSSize(width: NSView.noIntrinsicMetric, height: 0) }
+        return NSSize(width: NSView.noIntrinsicMetric, height: Self.height(width: max(180, bounds.width), presentation: presentation, style: style))
+    }
+
+    static func height(width: CGFloat, presentation: CloudPortsStatusPresentation, style: CloudTreeStyle) -> CGFloat {
+        let fontSize = GlobalFontMagnification.scaledSize(max(10, style.detailSize))
+        let titleFont = NSFont.systemFont(ofSize: fontSize, weight: .semibold)
+        let messageFont = style.monospacedText
+            ? NSFont.monospacedSystemFont(ofSize: fontSize, weight: .regular)
+            : NSFont.systemFont(ofSize: fontSize)
+        let contentWidth = max(1, width - 4)
+        let title = textHeight(presentation.title, font: titleFont, width: contentWidth)
+        let message = textHeight(presentation.message, font: messageFont, width: contentWidth)
+        let button = presentation.action == .none ? 0 : 26
+        return ceil(title + message + button + 10)
+    }
+
+    private static func textHeight(_ text: String, font: NSFont, width: CGFloat) -> CGFloat {
+        ceil(NSAttributedString(string: text, attributes: [.font: font]).boundingRect(
+            with: NSSize(width: max(1, width), height: .greatestFiniteMagnitude),
+            options: [.usesLineFragmentOrigin, .usesFontLeading]
+        ).height)
+    }
+
+    @objc private func performAction() { actionHandler?() }
+}

Sources/Cloud/CloudPortsStatusPresentation.swift

@@ -0,0 +1,159 @@
+import Foundation
+
+/// Localized, actionable copy for a Ports group that cannot show a trustworthy
+/// list or route. The model is independent of AppKit so the state matrix stays
+/// testable without constructing an outline view.
+struct CloudPortsStatusPresentation: Equatable {
+    let title: String
+    let message: String
+    let action: CloudPortsStatusAction
+    let actionTitle: String?
+
+    static func make(info: SurfaceMachineInfo) -> Self {
+        if case .notRequested = info.portDiscoveryState {
+            switch info.linkState {
+            case .connecting:
+                return Self(
+                    title: String(localized: "cloudTree.ports.loading", defaultValue: "Discovering ports…"),
+                    message: String(localized: "cloudTree.ports.loading.detail", defaultValue: "cmux is reading the machine’s listening services."),
+                    action: .none,
+                    actionTitle: nil
+                )
+            case .error:
+                return Self(
+                    title: String(localized: "cloudTree.ports.failed", defaultValue: "Cloud link unavailable"),
+                    message: info.linkError ?? String(localized: "cloudTree.ports.failed", defaultValue: "Reconnect the machine or refresh to discover ports again."),
+                    action: .refresh,
+                    actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+                )
+            case .asleep:
+                return Self(
+                    title: String(localized: "cloudTree.ports.asleep", defaultValue: "Machine is asleep"),
+                    message: String(localized: "cloudTree.ports.asleep.detail", defaultValue: "Wake the machine to discover its listening services."),
+                    action: .openMachine,
+                    actionTitle: String(localized: "cloudTree.ports.action.wake", defaultValue: "Wake Machine")
+                )
+            case .unavailable:
+                return Self(
+                    title: String(localized: "cloudTree.ports.unavailable", defaultValue: "Port discovery unavailable"),
+                    message: String(localized: "cloudTree.ports.unavailable.detail", defaultValue: "Refresh to retry port discovery."),
+                    action: .refresh,
+                    actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+                )
+            case .connected, .notApplicable:
+                break
+            }
+        }
+        let routeNote = String(
+            localized: "cloudTree.ports.routeNote",
+            defaultValue: "cmux’s authenticated in-app forwarding works without the system-wide Cloud VPN. Safari, Chrome, and other Mac apps using the machine’s private address do require Cloud VPN."
+        )
+        switch info.portDiscoveryState {
+        case .notRequested:
+                return Self(
+                    title: String(localized: "cloudTree.ports.empty", defaultValue: "No reachable ports"),
+                    message: String(localized: "cloudTree.ports.notRequested", defaultValue: "Expand this group to scan the machine for reachable services."),
+                action: .none,
+                actionTitle: nil
+            )
+        case .loading:
+            return Self(
+                title: String(localized: "cloudTree.ports.loading", defaultValue: "Discovering ports…"),
+                message: String(localized: "cloudTree.ports.loading.detail", defaultValue: "cmux is reading the machine’s listening services."),
+                action: .none,
+                actionTitle: nil
+            )
+        case .available:
+            return Self(
+                title: String(localized: "cloudTree.ports.empty", defaultValue: "No reachable ports"),
+                message: routeNote,
+                action: .none,
+                actionTitle: nil
+            )
+        case .empty(let reason):
+            switch reason {
+            case .noListeningService:
+                return Self(
+                    title: String(localized: "cloudTree.ports.empty", defaultValue: "No reachable ports"),
+                    message: String(
+                        format: String(localized: "cloudTree.ports.empty.noService", defaultValue: "No service is listening on a reachable port. Start an HTTP service on the machine, then refresh. %@"),
+                        routeNote
+                    ),
+                    action: .refresh,
+                    actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+                )
+            case .loopbackOnly:
+                return Self(
+                    title: String(localized: "cloudTree.ports.empty", defaultValue: "No reachable ports"),
+                    message: String(
+                        format: String(localized: "cloudTree.ports.empty.loopback", defaultValue: "A service is listening only on loopback. Bind it to the machine network, then refresh. %@"),
+                        routeNote
+                    ),
+                    action: .refresh,
+                    actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+                )
+            }
+        case .unavailable(let reason):
+            switch reason {
+            case .privateAddress:
+                let privateAddressMessage = String(
+                    format: String(localized: "cloudTree.port.noPrivateAddress", defaultValue: "%@ has no private network address yet; refresh the machine list and retry."),
+                    info.id.rawValue
+                )
+                return Self(
+                    title: String(localized: "cloudTree.ports.privateAddress", defaultValue: "Private address unavailable"),
+                    message: "\(privateAddressMessage) \(routeNote)",
+                    action: .refresh,
+                    actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+                )
+            case .machineAsleep:
+                return Self(
+                    title: String(localized: "cloudTree.ports.asleep", defaultValue: "Open the machine to discover ports"),
+                    message: String(localized: "cloudTree.ports.asleep.detail", defaultValue: "Wake the machine to discover its listening services."),
+                    action: .openMachine,
+                    actionTitle: String(localized: "cloudTree.ports.action.wake", defaultValue: "Wake Machine")
+                )
+            case .link:
+                let linkMessage = String(localized: "cloudTree.ports.failed", defaultValue: "Couldn’t discover ports. Refresh to retry.")
+                return Self(
+                    title: String(localized: "cloudTree.ports.failed", defaultValue: "Couldn’t discover ports. Refresh to retry."),
+                    message: "\(linkMessage) \(routeNote)",
+                    action: .refresh,
+                    actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+                )
+            case .transport:
+                let transportMessage = String(localized: "cloudTree.ports.unavailable", defaultValue: "Port discovery unavailable. Refresh to retry.")
+                return Self(
+                    title: String(localized: "cloudTree.ports.unavailable", defaultValue: "Port discovery unavailable. Refresh to retry."),
+                    message: "\(transportMessage) \(routeNote)",
+                    action: .refresh,
+                    actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh Ports")
+                )
+            case .hub:
+                return Self(
+                    title: String(localized: "cloudTree.ports.unavailable", defaultValue: "Port discovery unavailable. Refresh to retry."),
+                    message: String(localized: "cloudTree.ports.hub.detail", defaultValue: "This build cannot start cmux’s authenticated Cloud forward. Update cmux, then retry."),
+                    action: .refresh,
+                    actionTitle: String(localized: "common.retry", defaultValue: "Retry")
+                )
+            }
+        case .stale:
+            return Self(
+                title: String(localized: "cloudTree.ports.stale", defaultValue: "Port list may be out of date"),
+                message: String(
+                    format: String(localized: "cloudTree.ports.stale.detail", defaultValue: "Reconnect or refresh before relying on this list. %@"),
+                    routeNote
+                ),
+                action: .refresh,
+                actionTitle: String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+            )
+        case .unsupported:
+            return Self(
+                title: String(localized: "cloudTree.ports.unsupported", defaultValue: "Ports are not supported by this provider."),
+                message: String(format: String(localized: "cloudTree.port.unsupported", defaultValue: "%@’s provider cannot open machine ports as previews; reach the service from inside the machine with `cmux vm exec %@ -- …`."), info.id.rawValue, info.id.rawValue),
+                action: .openShell,
+                actionTitle: String(localized: "machines.menu.openShell", defaultValue: "Open Shell")
+            )
+        }
+    }
+}