루트 계약

/// An engine: the thing that turns an identity into pages.
@MainActor
public protocol BrowserEngine: AnyObject {
    /// A short stable name; it tags the page states this engine writes.
    var name: String { get }
    /// For diagnostics. The engine belongs to the operating system; Voyager
    /// reports its version and never pins it.
    var version: String { get }

    var downloadDelegate: (any EngineDownloadDelegate)? { get set }

    /// A new page for `identity`, at the place `state` describes when it is
    /// this engine's own.
    func makePage(identity: IdentityID, restoring state: PageState?) -> any EnginePage

    /// A page for an extension's own address, loaded with the extension
    /// context's own web view configuration — the only one WebKit serves
    /// those pages to. Nil when the engine hosts no such extension.
    /// 1Password's Add browser opens its extension's app page by a
    /// `chrome-extension://` address, routed here.
    func makePage(forExtensionPageAt url: URL, identity: IdentityID) -> (any EnginePage)?
    func extensionPageURL(for url: URL) -> URL?
    func canonicalExtensionPageURL(for url: URL) -> URL?

    /// A panel that may load `origin` and nothing else. Its page may use the
    /// microphone without a prompt: it is Pippa's own voice surface, on the
    /// origin Dad configured for her.
    func makePanel(origin: PageOrigin) -> any PanelSurface

    /// Removes one site's cookies and storage from one identity's store.
    func removeData(of identity: IdentityID, host: String) async

    /// Removes an identity's whole store: every cookie and sign-in. No page
    /// of that identity may still be open.
    func removeData(of identity: IdentityID) async throws

    /// The last private window closed. Drop only the ephemeral session's
    /// store synchronously, before another private window can open.
    func endPrivateSession()

/// The closed list of things a page may be granted (invariant 6). A new kind
/// is added here by name, with its reason, and nowhere else.
public enum PermissionKind: String, Sendable, Codable, CaseIterable {
    case microphone
    case camera
    case cameraAndMicrophone
}

public struct PermissionRequest: Sendable, Equatable {
    /// The frame that asks.
    public var origin: PageOrigin
    /// The page Dad sees in the tab. A frame inside another site's page is
    /// judged with that page: content never raises its own zone by being
    /// embedded, or by embedding.
    public var topOrigin: PageOrigin
    public var kind: PermissionKind

    public init(origin: PageOrigin, topOrigin: PageOrigin? = nil, kind: PermissionKind) {
        self.origin = origin
        self.topOrigin = topOrigin ?? origin
        self.kind = kind
    }
}

public enum PermissionDecision: Sendable, Equatable {
    case grant
    case deny
    /// The engine asks Dad itself, as Safari would.
    case ask
}