BrowserEngineKit Patterns

import BrowserEngineKit

/// Proxy for sending messages from the host app to a web content extension.
final class WebContentProxy: Sendable {
    let connection: xpc_connection_t

    init(connection: xpc_connection_t) {
        self.connection = connection
        xpc_connection_set_event_handler(connection) { event in
            // Handle connection errors
        }
        xpc_connection_resume(connection)
    }

    func loadURL(_ url: URL) async throws -> Data {
        // Encode request as XPC dictionary, send, await reply
        let message = xpc_dictionary_create(nil, nil, 0)
        xpc_dictionary_set_string(message, "action", "load")
        xpc_dictionary_set_string(message, "url", url.absoluteString)

        return try await withCheckedThrowingContinuation { continuation in
            xpc_connection_send_message_with_reply(
                connection, message, .main
            ) { reply in
                // Decode reply
            }
        }
    }
}

// Host app side
func bootstrapContentExtension() async throws {
    // 1. Get endpoints from networking and rendering extensions
    let networkConn = try networkProcess.makeLibXPCConnection()
    let networkProxy = NetworkingProxy(connection: networkConn)
    let networkEndpoint = try await networkProxy.getEndpoint()

    let renderConn = try renderingProcess.makeLibXPCConnection()
    let renderProxy = RenderingProxy(connection: renderConn)
    let renderEndpoint = try await renderProxy.getEndpoint()

    // 2. Send both endpoints to the content extension
    let contentConn = try contentProcess.makeLibXPCConnection()
    let contentProxy = WebContentProxy(connection: contentConn)
    try await contentProxy.bootstrap(
        networkEndpoint: networkEndpoint,
        renderEndpoint: renderEndpoint
    )
}

// Inside the web content extension
func handleBootstrap(
    networkEndpoint: xpc_endpoint_t,
    renderEndpoint: xpc_endpoint_t
) async throws {
    let networkConn = xpc_connection_create_from_endpoint(networkEndpoint)
    let renderConn = xpc_connection_create_from_endpoint(renderEndpoint)

    // Verify connections are alive
    try await networkConn.ping()
    try await renderConn.ping()

    self.networkProxy = NetworkingProxy(connection: networkConn)
    self.renderProxy = RenderingProxy(connection: renderConn)
}

final class MyWebContentExtension: WebContentExtension {
    private var hostConnection: xpc_connection_t?

    override func handle(xpcConnection: xpc_connection_t) {
        hostConnection = xpcConnection
        xpc_connection_set_event_handler(xpcConnection) { [weak self] event in
            guard let self else { return }
            if xpc_get_type(event) == XPC_TYPE_DICTIONARY {
                self.handleMessage(event)
            }
        }
        xpc_connection_resume(xpcConnection)
    }

    private func handleMessage(_ message: xpc_object_t) {
        guard let action = xpc_dictionary_get_string(message, "action") else {
            return
        }
        switch String(cString: action) {
        case "load":
            // Handle page load request
            break
        case "bootstrap":
            // Handle bootstrap with extension endpoints
            break
        default:
            break
        }
    }
}

import BrowserEngineKit
import UIKit

final class BrowserTextView: UIView, BETextInput {
    var asyncInputDelegate: (any BETextInputDelegate)?
    var isEditable: Bool = true

    func handleKeyEntry(
        _ entry: BEKeyEntry,
        completionHandler: (BEKeyEntry, Bool) -> Void
    ) {
        let handled = entry.state == .down
            ? processKeyDown(entry.key)
            : processKeyUp(entry.key)
        completionHandler(entry, handled)
    }

    func shiftKeyStateChanged(
        fromState: BEKeyModifierFlags,
        toState: BEKeyModifierFlags
    ) {
        if toState == .shift { beginExtendingSelection() }
    }

    var selectedText: String?
    var selectedTextRange: UITextRange?
    var isSelectionAtDocumentStart: Bool = false

    func updateCurrentSelection(
        to point: CGPoint,
        from gesture: BEGestureType,
        in state: UIGestureRecognizer.State
    ) {
        switch gesture {
        case .oneFingerTap: moveCaret(to: point)
        case .oneFingerDoubleTap: selectWord(at: point)
        case .oneFingerTripleTap: selectParagraph(at: point)
        default: break
        }
    }

    var markedText: String?
    var attributedMarkedText: NSAttributedString?
    var markedTextRange: UITextRange?
    var hasMarkedText: Bool { markedText != nil }

    func setMarkedText(_ text: String?, selectedRange: NSRange) {
        markedText = text
    }

    func unmarkText() {
        markedText = nil
    }

    // Additional BETextInput requirements omitted for brevity.
    // See Apple docs for the full protocol surface.
}

let textInteraction = BETextInteraction()
textInteraction.delegate = self
browserTextView.addInteraction(textInteraction)

// Rendering extension: create layer hierarchy
import BrowserEngineKit
import QuartzCore

func createPageLayer() throws -> LayerHierarchyHandle {
    let hierarchy = try LayerHierarchy()

    let pageLayer = CALayer()
    pageLayer.bounds = CGRect(x: 0, y: 0, width: 390, height: 844)
    // ... populate layer with rendered content ...

    hierarchy.layer = pageLayer
    return hierarchy.handle
}

// Host app: display remote layer
func displayPage(handle: LayerHierarchyHandle) {
    let hostingView = LayerHierarchyHostingView()
    hostingView.handle = handle
    hostingView.frame = containerView.bounds
    containerView.addSubview(hostingView)
}

// Sender
let xpcRep = handle.createXPCRepresentation()
xpc_dictionary_set_value(message, "layerHandle", xpcRep)

// Receiver
let xpcRep = xpc_dictionary_get_value(message, "layerHandle")
let handle = try LayerHierarchyHandle(xpcRepresentation: xpcRep)

// Both processes create coordinators from the same XPC representation
let coordinator = try LayerHierarchyHostingTransactionCoordinator()

// Host app adds its hosting view
coordinator.add(hostingView)

// Rendering extension adds its hierarchy
coordinator.add(hierarchy)

// Either side commits when ready
coordinator.commit()

import BrowserEngineKit

final class BrowserScrollView: BEScrollView {
    override init(frame: CGRect) {
        super.init(frame: frame)
        delegate = self
    }

    required init?(coder: NSCoder) {
        super.init(coder: coder)
        delegate = self
    }
}

extension BrowserScrollView: BEScrollViewDelegate {
    func scrollView(
        _ scrollView: BEScrollView,
        handle update: BEScrollViewScrollUpdate,
        completion: (Bool) -> Void
    ) {
        let translation = update.translation(in: self)

        switch update.phase {
        case .began:
            beginCustomScroll(at: update.location(in: self))
        case .changed:
            updateCustomScroll(by: translation)
        case .ended:
            endCustomScroll(velocity: translation)
        case .cancelled:
            cancelCustomScroll()
        @unknown default:
            break
        }

        // Return true if the browser handled the scroll
        completion(true)
    }

    func parentScrollView(for scrollView: BEScrollView) -> BEScrollView? {
        // Return parent scroll view for nested scrolling coordination
        superview?.firstScrollViewAncestor()
    }
}

import BrowserEngineKit

final class BrowserDragHandler: NSObject, BEDragInteractionDelegate {
    func dragInteraction(
        _ interaction: BEDragInteraction,
        prepare session: any UIDragSession,
        completion: () -> Bool
    ) {
        // Asynchronously determine what content to drag
        // (e.g., hit-test the DOM at the drag point)
        let dragItems = prepareDragItems(for: session)
        session.items.append(contentsOf: dragItems)
        completion()  // Return true if drag should proceed
    }

    func dragInteraction(
        _ interaction: BEDragInteraction,
        itemsForAddingTo session: any UIDragSession,
        forTouchAt point: CGPoint,
        completion: ([UIDragItem]) -> Bool
    ) {
        // Add more items to an existing drag session
        completion([])
    }
}

// Attach to a browser view
let dragInteraction = BEDragInteraction(delegate: dragHandler)
browserView.addInteraction(dragInteraction)

import BrowserEngineKit

func handleContextMenu(at point: CGPoint) {
    let config = BEContextMenuConfiguration()

    // Asynchronously determine context menu content from DOM
    determineContextContent(at: point) { uiConfig in
        // Fulfill with UIKit configuration when ready
        config.fulfill(using: uiConfig)
    }
}

import BrowserEngineKit

func shouldLoadURL(_ url: URL, completion: @escaping (Bool) -> Void) {
    guard BEWebContentFilter.shouldEvaluateURLs else {
        completion(true)
        return
    }

    let filter = BEWebContentFilter()
    filter.evaluateURL(url) { isRestricted, filterData in
        if isRestricted {
            // URL is blocked by content filter
            completion(false)
        } else {
            completion(true)
        }
    }
}

func requestFilterBypass(for url: URL) {
    let filter = BEWebContentFilter()
    filter.allow(url) { allowed, error in
        if allowed {
            // User/parent approved access
        }
    }
}

import BrowserEngineKit

// In the rendering extension
let remoteElement = BEAccessibilityRemoteElement(
    identifier: "page-content-\(pageID)",
    hostPid: hostProcessID
)

// In the host app
let hostElement = BEAccessibilityRemoteHostElement(
    identifier: "page-content-\(pageID)",
    remotePid: renderingProcessID
)
hostElement.accessibilityContainer = browserContainerView

import BrowserEngineKit
import UniformTypeIdentifiers

func startDownload(from url: URL, to destination: URL) async throws {
    let progress = Progress(totalUnitCount: 100)

    guard let token = BEDownloadMonitor.createAccessToken() else {
        // Handle token creation failure
        return
    }

    let monitor = BEDownloadMonitor(
        sourceURL: url,
        destinationURL: destination,
        observedProgress: progress,
        liveActivityAccessToken: token
    )

    // Request a placeholder in the Downloads folder
    monitor.useDownloadsFolder(
        placeholderType: UTType.data
    ) { location in
        if let location {
            // System created a placeholder file
            // Move final file to location.url when complete
        }
    }

    // Begin monitoring - shows system download UI
    let location = try await monitor.beginMonitoring()

    // Update progress as download proceeds
    // progress.completedUnitCount = bytesReceived
}

func resumeDownload(monitor: BEDownloadMonitor, placeholder: URL) async throws {
    try await monitor.resumeMonitoring(placeholderURL: placeholder)
    // Continue updating progress
}

import BrowserEngineKit

actor BrowserProcessManager {
    private var contentProcesses: [String: WebContentProcess] = [:]
    private var networkProcess: NetworkingProcess?
    private var renderingProcess: RenderingProcess?

    func getOrLaunchNetworkProcess() async throws -> NetworkingProcess {
        if let existing = networkProcess { return existing }
        let process = try await NetworkingProcess(
            bundleIdentifier: nil
        ) { [weak self] in
            Task { await self?.handleNetworkInterruption() }
        }
        networkProcess = process
        return process
    }

    func getOrLaunchRenderingProcess() async throws -> RenderingProcess {
        if let existing = renderingProcess { return existing }
        let process = try await RenderingProcess(
            bundleIdentifier: nil
        ) { [weak self] in
            Task { await self?.handleRenderingInterruption() }
        }
        renderingProcess = process
        return process
    }

    func launchContentProcess(tabID: String) async throws -> WebContentProcess {
        let process = try await WebContentProcess(
            bundleIdentifier: nil
        ) { [weak self] in
            Task { await self?.handleContentInterruption(tabID: tabID) }
        }
        contentProcesses[tabID] = process
        return process
    }

    func closeTab(_ tabID: String) {
        contentProcesses[tabID]?.invalidate()
        contentProcesses.removeValue(forKey: tabID)
    }

    func bootstrapContentProcess(tabID: String) async throws {
        guard let content = contentProcesses[tabID] else { return }
        let network = try await getOrLaunchNetworkProcess()
        let rendering = try await getOrLaunchRenderingProcess()

        let networkProxy = NetworkingProxy(
            connection: try network.makeLibXPCConnection()
        )
        let renderProxy = RenderingProxy(
            connection: try rendering.makeLibXPCConnection()
        )

        let contentProxy = WebContentProxy(
            connection: try content.makeLibXPCConnection()
        )
        try await contentProxy.bootstrap(
            networkEndpoint: try await networkProxy.getEndpoint(),
            renderEndpoint: try await renderProxy.getEndpoint()
        )
    }

    private func handleNetworkInterruption() { networkProcess = nil }
    private func handleRenderingInterruption() { renderingProcess = nil }
    private func handleContentInterruption(tabID: String) {
        contentProcesses.removeValue(forKey: tabID)
    }

    func shutdownAll() {
        contentProcesses.values.forEach { $0.invalidate() }
        contentProcesses.removeAll()
        networkProcess?.invalidate()
        networkProcess = nil
        renderingProcess?.invalidate()
        renderingProcess = nil
    }
}

// Host app: create bookmark for a file URL
func sendFileToExtension(
    url: URL,
    via proxy: WebContentProxy
) async throws {
    let bookmarkData = try url.bookmarkData(
        options: .withSecurityScope,
        includingResourceValuesForKeys: nil,
        relativeTo: nil
    )
    try await proxy.sendBookmark(bookmarkData)
}

// Web content extension: resolve and access the file
func handleBookmark(_ data: Data) throws {
    var isStale = false
    let url = try URL(
        resolvingBookmarkData: data,
        options: .withSecurityScope,
        bookmarkDataIsStale: &isStale
    )
    guard url.startAccessingSecurityScopedResource() else {
        throw BrowserError.fileAccessDenied
    }
    defer { url.stopAccessingSecurityScopedResource() }

    let fileData = try Data(contentsOf: url)
    // Process the file content
}

// Requires entitlements:
// - com.apple.developer.memory.transfer_send on rendering extension
// - com.apple.developer.memory.transfer_accept on web content extension
//   (both with the host app's bundle identifier as value)

// The actual memory transfer is performed via Mach VM operations
// coordinated over the XPC connection between the extensions.
// See Apple's sample project for the full implementation.