Keep browser page state when Memory Saver frees a hidden pane

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/MediaPlayback/BrowserMediaPlaybackFrames.swift

@@ -0,0 +1,29 @@
+/// Media playback across a page's frames, folded from the per-frame reports
+/// of the injected media-playback hook.
+public struct BrowserMediaPlaybackFrames: Equatable, Sendable {
+    private var playingFrameIDs: Set<String> = []
+    private var audibleFrameIDs: Set<String> = []
+    private var pictureInPictureFrameIDs: Set<String> = []
+
+    public init() {}
+
+    /// Whether any frame has actively playing media.
+    public var isPlaying: Bool { !playingFrameIDs.isEmpty }
+    /// Whether any frame is playing media that is audible.
+    public var isAudible: Bool { !audibleFrameIDs.isEmpty }
+    /// Whether any frame has a video in Picture in Picture, playing or paused.
+    public var isPictureInPictureActive: Bool { !pictureInPictureFrameIDs.isEmpty }
+
+    /// Replaces the reporting frame's state with the report.
+    public mutating func apply(_ report: BrowserMediaPlaybackReport) {
+        playingFrameIDs.update(report.frameID, isMember: report.isPlaying)
+        audibleFrameIDs.update(report.frameID, isMember: report.isPlaying && report.isAudible)
+        pictureInPictureFrameIDs.update(report.frameID, isMember: report.isPictureInPicture)
+    }
+}
+
+private extension Set<String> {
+    mutating func update(_ frameID: String, isMember: Bool) {
+        if isMember { insert(frameID) } else { remove(frameID) }
+    }
+}

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/MediaPlayback/BrowserMediaPlaybackMessageHandler.swift

@@ -1,35 +1,47 @@
 public import Foundation
 public import WebKit
 
-/// Receives `{ frameID, playing, audible }` from the injected media-playback hook and
+/// Receives `{ frameID, playing, audible, pip }` from the injected media-playback hook and
 /// forwards it to the owning ``BrowserPanel`` on the main actor.
 ///
 /// Mirrors ``ReactGrabMessageHandler``: a thin `NSObject` adapter so the panel
-/// itself never has to conform to `WKScriptMessageHandler`.
+/// itself never has to conform to `WKScriptMessageHandler`. It is bound to one
+/// web view: a popup the page opens is built from the opener's configuration
+/// and shares its content controller, so the popup's reports reach this handler
+/// too and are dropped.
+@MainActor
 public final class BrowserMediaPlaybackMessageHandler: NSObject, WKScriptMessageHandler {
+    private weak var webView: WKWebView?
     private let onReport: @MainActor (BrowserMediaPlaybackReport) -> Void
 
-    public init(onReport: @escaping @MainActor (BrowserMediaPlaybackReport) -> Void) {
+    public init(
+        webView: WKWebView,
+        onReport: @escaping @MainActor (BrowserMediaPlaybackReport) -> Void
+    ) {
+        self.webView = webView
         self.onReport = onReport
     }
 
     public func userContentController(
         _ userContentController: WKUserContentController,
         didReceive message: WKScriptMessage
     ) {
-        guard let body = message.body as? [String: Any],
+        guard message.webView === webView,
+              let body = message.body as? [String: Any],
               let frameID = body["frameID"] as? String,
               let playing = body["playing"] as? Bool else { return }
-        let audible = body["audible"] as? Bool ?? false
-        let report = BrowserMediaPlaybackReport(frameID: frameID, isPlaying: playing, isAudible: audible)
+        let report = BrowserMediaPlaybackReport(
+            frameID: frameID,
+            isPlaying: playing,
+            isAudible: body["audible"] as? Bool ?? false,
+            isPictureInPicture: body["pip"] as? Bool ?? false
+        )
         // WebKit delivers script messages on the main thread. Apply the report
         // synchronously instead of hopping through a `Task` so it lands in
         // WebKit's delivery order relative to navigation callbacks: a report
         // emitted by a document before it navigates away is applied before the
         // matching `didCommit` reset, so a stale `playing: true` cannot re-add a
         // dead frame id after the reset and pin the pane against discard.
-        MainActor.assumeIsolated {
-            onReport(report)
-        }
+        onReport(report)
     }
 }

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/MediaPlayback/BrowserMediaPlaybackReport.swift

@@ -9,14 +9,18 @@ public struct BrowserMediaPlaybackReport: Sendable {
     public let isPlaying: Bool
     /// Whether that frame currently has an unmuted, non-zero-volume audio source.
     public let isAudible: Bool
+    /// Whether that frame has a video in Picture in Picture, playing or paused.
+    public let isPictureInPicture: Bool
 
     public init(
         frameID: String,
         isPlaying: Bool,
-        isAudible: Bool
+        isAudible: Bool,
+        isPictureInPicture: Bool = false
     ) {
         self.frameID = frameID
         self.isPlaying = isPlaying
         self.isAudible = isAudible
+        self.isPictureInPicture = isPictureInPicture
     }
 }

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/PageRestoration/BrowserDiscardRestoreStrategy.swift

@@ -0,0 +1,89 @@
+public import Foundation
+
+/// How a pane that was discarded for memory brings its page back when it is
+/// shown again.
+///
+/// WebKit's `interactionState` carries the native back/forward list together
+/// with each entry's scroll and view state, so assigning it to the replacement
+/// web view returns the page the user left, like a Chrome tab discard. Loading
+/// the URL from scratch is the fallback for panes whose captured state cannot
+/// be replayed safely.
+public enum BrowserDiscardRestoreStrategy: Equatable, Sendable {
+    /// Assign the captured WebKit session state to the replacement web view.
+    case restoreInteractionState(Data)
+    /// Load the restore URL from scratch.
+    case replayURL(URL)
+
+    /// Pane conditions that force the URL fallback.
+    public struct Conditions: Equatable, Sendable {
+        /// The user asked for a reload, which must fetch a fresh document.
+        public var isExplicitReload: Bool
+        /// A remote workspace pane. Its pages load through a loopback proxy
+        /// whose endpoint can change across reconnects, so session state would
+        /// replay stale proxy URLs. The URL path also queues until the
+        /// endpoint is up.
+        public var usesRemoteWorkspaceProxy: Bool
+        /// Cloud browser routing owns its own connection flow.
+        public var usesCloudAccessRouting: Bool
+        /// The web content process died and recovery replaces the web view.
+        public var hasRecoverableWebContentTermination: Bool
+        /// An http page the insecure-HTTP gate would stop. Session state
+        /// replays as a back/forward load, which asks again; the URL path
+        /// reopens a page the user already chose to open without asking.
+        public var requiresInsecureHTTPConsent: Bool
+
+        public init(
+            isExplicitReload: Bool = false,
+            usesRemoteWorkspaceProxy: Bool = false,
+            usesCloudAccessRouting: Bool = false,
+            hasRecoverableWebContentTermination: Bool = false,
+            requiresInsecureHTTPConsent: Bool = false
+        ) {
+            self.isExplicitReload = isExplicitReload
+            self.usesRemoteWorkspaceProxy = usesRemoteWorkspaceProxy
+            self.usesCloudAccessRouting = usesCloudAccessRouting
+            self.hasRecoverableWebContentTermination = hasRecoverableWebContentTermination
+            self.requiresInsecureHTTPConsent = requiresInsecureHTTPConsent
+        }
+
+        var forcesURLReplay: Bool {
+            isExplicitReload
+                || usesRemoteWorkspaceProxy
+                || usesCloudAccessRouting
+                || hasRecoverableWebContentTermination
+                || requiresInsecureHTTPConsent
+        }
+    }
+
+    /// Whether session state may be captured, persisted or restored for a
+    /// document at `url`. Web and local file documents qualify; the caller
+    /// re-grants a local file's trust before assigning the state. App-internal
+    /// documents such as the diff viewer resolve through their own handlers,
+    /// which a back/forward replay would bypass.
+    public static func canRestoreSessionState(for url: URL?) -> Bool {
+        guard let scheme = url?.scheme?.lowercased() else { return false }
+        return scheme == "http" || scheme == "https" || scheme == "file"
+    }
+
+    /// Picks the restore path for `restoreURL`. Captured state is used only
+    /// when it was taken for the same page the pane is about to restore, so a
+    /// navigation issued while the pane was discarded always wins. A page
+    /// shown as a form submission result loads by URL, because assigning its
+    /// state would send the form again.
+    public static func resolve(
+        restoreURL: URL,
+        capture: BrowserPageStateCapture?,
+        conditions: Conditions = Conditions()
+    ) -> BrowserDiscardRestoreStrategy {
+        guard !conditions.forcesURLReplay,
+              canRestoreSessionState(for: restoreURL),
+              let capture,
+              capture.anchorURL == restoreURL,
+              !capture.documentHasFormSubmission,
+              let interactionState = capture.interactionState,
+              !interactionState.isEmpty else {
+            return .replayURL(restoreURL)
+        }
+        return .restoreInteractionState(interactionState)
+    }
+}

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/PageRestoration/BrowserFormStateMessageHandler.swift

@@ -0,0 +1,37 @@
+public import Foundation
+public import WebKit
+
+/// Receives unsaved form input from the injected
+/// ``WKUserScript/browserFormStateObserver()`` and forwards it to the
+/// owning panel on the main actor.
+///
+/// A thin `NSObject` adapter so the panel never conforms to
+/// `WKScriptMessageHandler` itself. It is bound to one web view: a popup the
+/// page opens is built from the opener's configuration and shares its content
+/// controller, so the popup's reports reach this handler too and are dropped.
+@MainActor
+public final class BrowserFormStateMessageHandler: NSObject, WKScriptMessageHandler {
+    private weak var webView: WKWebView?
+    private let onReport: @MainActor (BrowserFormStateSnapshot) -> Void
+
+    public init(
+        webView: WKWebView,
+        onReport: @escaping @MainActor (BrowserFormStateSnapshot) -> Void
+    ) {
+        self.webView = webView
+        self.onReport = onReport
+    }
+
+    public func userContentController(
+        _ userContentController: WKUserContentController,
+        didReceive message: WKScriptMessage
+    ) {
+        guard message.frameInfo.isMainFrame,
+              message.webView === webView,
+              let snapshot = BrowserFormStateSnapshot(messageBody: message.body) else { return }
+        // WebKit delivers script messages on the main thread, in order with
+        // navigation callbacks, so a report sent by a document before it
+        // navigates away lands before the next document's commit resets it.
+        onReport(snapshot)
+    }
+}

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/PageRestoration/BrowserFormStateSnapshot.swift

@@ -0,0 +1,147 @@
+public import Foundation
+
+/// Unsaved input in the main frame's form controls, reported by the injected
+/// form-state observer.
+///
+/// WebKit's `interactionState` only carries form values for history entries
+/// the user navigated away from, so the current page's typed input would be
+/// lost when a discarded pane restores. This snapshot fills that gap. It is
+/// kept in memory only and never written to the session file. Password,
+/// payment, one-time-code and `autocomplete="off"` fields are never reported;
+/// a change to one only sets ``hasUnrestorableInput``.
+public struct BrowserFormStateSnapshot: Equatable, Sendable {
+    /// Largest number of fields kept per document.
+    public static let maxFieldCount = 200
+    /// Largest value, in UTF-16 code units, kept per field.
+    public static let maxValueLength = 64 * 1024
+
+    public struct Field: Equatable, Sendable {
+        /// Stable locator for the control: `id:`, `name:` or `path:` prefixed.
+        public var key: String
+        /// Text value for text-like inputs and text areas.
+        public var value: String?
+        /// Checked state for checkboxes and radio buttons.
+        public var isChecked: Bool?
+        /// Selected option indexes for select elements.
+        public var selectedOptionIndexes: [Int]?
+
+        public init(key: String, value: String? = nil, isChecked: Bool? = nil, selectedOptionIndexes: [Int]? = nil) {
+            self.key = key
+            self.value = value
+            self.isChecked = isChecked
+            self.selectedOptionIndexes = selectedOptionIndexes
+        }
+    }
+
+    /// URL of the document the fields belong to.
+    public var documentURL: URL
+    public var fields: [Field]
+    /// Whether the document also holds typed input a restore cannot replay,
+    /// such as a password, a file selection or a rich-text edit.
+    public var hasUnrestorableInput: Bool
+
+    public init(documentURL: URL, fields: [Field], hasUnrestorableInput: Bool = false) {
+        self.documentURL = documentURL
+        self.fields = fields
+        self.hasUnrestorableInput = hasUnrestorableInput
+    }
+
+    /// Parses `{ url, fields: [{ k, v?, c?, s? }], unrestorable? }` from the
+    /// observer. Returns nil for a malformed body. Oversized values and fields
+    /// past ``maxFieldCount`` are dropped and count as unrestorable input.
+    public init?(messageBody: Any) {
+        guard let body = messageBody as? [String: Any],
+              let urlString = body["url"] as? String,
+              let documentURL = URL(string: urlString),
+              let rawFields = body["fields"] as? [Any] else {
+            return nil
+        }
+        var fields: [Field] = []
+        var hasUnrestorableInput = body["unrestorable"] as? Bool ?? false
+        for rawField in rawFields {
+            guard fields.count < Self.maxFieldCount else {
+                hasUnrestorableInput = true
+                break
+            }
+            guard let entry = rawField as? [String: Any],
+                  let key = entry["k"] as? String,
+                  !key.isEmpty else { continue }
+            let field: Field
+            if let value = entry["v"] as? String {
+                guard value.utf16.count <= Self.maxValueLength else {
+                    hasUnrestorableInput = true
+                    continue
+                }
+                field = Field(key: key, value: value)
+            } else if let checked = entry["c"] as? Bool {
+                field = Field(key: key, isChecked: checked)
+            } else if let selected = entry["s"] as? [Any] {
+                let indexes = selected.compactMap { ($0 as? NSNumber)?.intValue }
+                guard indexes.count == selected.count else {
+                    hasUnrestorableInput = true
+                    continue
+                }
+                field = Field(key: key, selectedOptionIndexes: indexes)
+            } else {
+                continue
+            }
+            fields.append(field)
+        }
+        self.init(documentURL: documentURL, fields: fields, hasUnrestorableInput: hasUnrestorableInput)
+    }
+
+    /// Whether there are no fields to restore.
+    public var isEmpty: Bool { fields.isEmpty }
+
+    /// Whether the fields were typed on the same origin as `url`. Values are
+    /// never carried to another site. The report URL can trail the document
+    /// URL after a same-document route change, so paths are not compared,
+    /// except for file URLs, whose origin is the file itself.
+    public func sharesOrigin(with url: URL?) -> Bool {
+        guard let url else { return false }
+        if documentURL.isFileURL || url.isFileURL {
+            return documentURL.isFileURL && url.isFileURL && Self.isSameDocument(documentURL, url)
+        }
+        guard let scheme = documentURL.scheme?.lowercased(), let host = documentURL.host?.lowercased() else {
+            return false
+        }
+        guard scheme == url.scheme?.lowercased(), host == url.host?.lowercased() else { return false }
+        let defaultPort = scheme == "https" ? 443 : scheme == "http" ? 80 : nil
+        return (documentURL.port ?? defaultPort) == (url.port ?? defaultPort)
+    }
+
+    /// Whether two URLs load the same document. Fragment changes keep the
+    /// same document, so they are ignored.
+    public static func isSameDocument(_ lhs: URL, _ rhs: URL) -> Bool {
+        documentIdentity(lhs) == documentIdentity(rhs)
+    }
+
+    /// Fields in the shape the restore script expects as its `fields` argument.
+    public var restorePayload: [[String: Any]] {
+        fields.map { field in
+            var entry: [String: Any] = ["k": field.key]
+            if let value = field.value {
+                entry["v"] = value
+            } else if let isChecked = field.isChecked {
+                entry["c"] = isChecked
+            } else if let selectedOptionIndexes = field.selectedOptionIndexes {
+                entry["s"] = selectedOptionIndexes
+            }
+            return entry
+        }
+    }
+
+    static func documentIdentity(_ url: URL) -> String {
+        if url.isFileURL {
+            let standardized = url.standardizedFileURL
+            let host = url.host?.lowercased() ?? ""
+            let port = url.port.map(String.init) ?? ""
+            return "\(host):\(port):\(standardized.path)"
+        }
+        guard var components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
+            return url.absoluteString
+        }
+        components.fragment = nil
+        return components.string ?? url.absoluteString
+    }
+}