@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/Translation/Translation.swift

@@ -0,0 +1,423 @@
+// Translation (iOS 17.4 / 18): Apple's on-device translation, over the
+// browser's own translator where the page has one. Chrome (138 and later,
+// on desktop) has a built-in `Translator` API that translates on the device
+// with models it downloads per language pair, and a `LanguageDetector`; the
+// page uses them for `translate` host requests (Web/src/translation.ts). A
+// browser without them, and headless runs, answer that no pair is supported,
+// so `LanguageAvailability` reports `.unsupported` and a session's
+// translations fail with `TranslationError.unsupportedLanguagePairing`, as on
+// a device without the pair. Apps that fall back to a server (Ice Cubes
+// translates with the instance or DeepL) then take that path.
+//
+// Exchanges, as host requests of kind `translate`:
+//
+//   { "action": "availability", "source": "en" | null, "target": "fr", "text"?: "…" }
+//     → { "status": "installed" | "supported" | "unsupported" }
+//   { "action": "translate", "source": "en" | null, "target": "fr",
+//     "texts": ["…"], "allowDownload": true }
+//     → { "source": "en", "texts": ["…"] }, or { "status": "unsupported" }
+//
+// Languages travel as BCP 47 language tags ("en", "pt", "zh-Hant").
+
+import Foundation
+import FoundationBridge
+import SwiftUI
+
+// MARK: - Errors
+
+/// Why a translation failed. Compare with `~=` (`catch TranslationError.unsupportedLanguagePairing`).
+public struct TranslationError: Error, LocalizedError, Hashable, Sendable, CustomStringConvertible {
+    enum Code: String, Sendable { case unsupportedSourceLanguage, unsupportedTargetLanguage, unsupportedLanguagePairing,
+                                      unableToIdentifyLanguage, nothingToTranslate, internalError, notInstalled }
+    let code: Code
+
+    /// The source language is one the translator does not have.
+    public static let unsupportedSourceLanguage = TranslationError(code: .unsupportedSourceLanguage)
+    /// The target language is one the translator does not have.
+    public static let unsupportedTargetLanguage = TranslationError(code: .unsupportedTargetLanguage)
+    /// The translator cannot translate between the two languages: always so
+    /// in a browser without a built-in translator.
+    public static let unsupportedLanguagePairing = TranslationError(code: .unsupportedLanguagePairing)
+    /// The source language was not given and could not be detected.
+    public static let unableToIdentifyLanguage = TranslationError(code: .unableToIdentifyLanguage)
+    /// The text was empty.
+    public static let nothingToTranslate = TranslationError(code: .nothingToTranslate)
+    /// The translator failed.
+    public static let internalError = TranslationError(code: .internalError)
+    /// The pair's model is not downloaded and the session may not download it.
+    public static let notInstalled = TranslationError(code: .notInstalled)
+
+    public static func ~= (lhs: TranslationError, rhs: any Error) -> Bool {
+        (rhs as? TranslationError) == lhs
+    }
+
+    public var description: String { "TranslationError.\(code.rawValue)" }
+
+    public var errorDescription: String? {
+        switch code {
+        case .unsupportedSourceLanguage: "The source language is not supported."
+        case .unsupportedTargetLanguage: "The target language is not supported."
+        case .unsupportedLanguagePairing: "Translation between these languages is not supported."
+        case .unableToIdentifyLanguage: "The language of the text could not be identified."
+        case .nothingToTranslate: "There is nothing to translate."
+        case .internalError: "The translation failed."
+        case .notInstalled: "The languages for this translation are not downloaded."
+        }
+    }
+}
+
+// MARK: - The page
+
+/// How the module reaches the page; tests replace `transport`.
+enum _TranslationHost {
+    /// Performs one `translate` request.
+    nonisolated(unsafe) static var transport: @Sendable (_JSON) async throws -> _JSON = { params in
+        try await _Runtime.shared._hostRequest(kind: "translate", params: params,
+                                               headless: .object(["status": .string("unsupported")]))
+    }
+
+    /// A language's BCP 47 tag for the page: its language code, with the
+    /// script for traditional Chinese ("zh-Hant"), which translators treat as a
+    /// language of its own.
+    static func tag(_ language: Locale.Language) -> String {
+        let code = language.languageCode?.identifier ?? language.minimalIdentifier
+        if code == "zh" {
+            let script = language.script?.identifier
+            let region = language.region?.identifier
+            if script == "Hant" || (script == nil && ["TW", "HK", "MO"].contains(region ?? "")) { return "zh-Hant" }
+        }
+        return code
+    }
+
+    /// The language translations go to when a session names none: the viewer's first preferred language.
+    static var defaultTarget: Locale.Language {
+        Locale.Language(identifier: Locale.preferredLanguages.first ?? Locale.current.identifier)
+    }
+
+    static func status(_ value: _JSON) -> LanguageAvailability.Status {
+        guard case .object(let fields) = value, case .string(let status)? = fields["status"] else { return .unsupported }
+        switch status {
+        case "installed": return .installed
+        case "supported": return .supported
+        default: return .unsupported
+        }
+    }
+
+    /// The error a refused request stands for: the page's message starts with a tag.
+    static func error(_ error: any Error) -> TranslationError {
+        if let error = error as? TranslationError { return error }
+        let message = (error as? _HostRequestError)?.message ?? ""
+        if message.hasPrefix("unsupported") { return .unsupportedLanguagePairing }
+        if message.hasPrefix("unidentified") { return .unableToIdentifyLanguage }
+        if message.hasPrefix("download") { return .notInstalled }
+        return .internalError
+    }
+}
+
+// MARK: - Availability
+
+/// Which languages can be translated, as the page's translator reports.
+public final class LanguageAvailability: Sendable {
+    /// Whether a pair can be translated.
+    public enum Status: Sendable, Hashable {
+        /// The pair's model is on the device: translations start at once.
+        case installed
+        /// The pair is supported; its model is downloaded first.
+        case supported
+        /// The pair cannot be translated (always so without a built-in translator).
+        case unsupported
+    }
+
+    public init() {}
+
+    /// The languages Apple's translator offers. In a browser without a
+    /// translator the list is the same: availability is answered per pair.
+    public var supportedLanguages: [Locale.Language] {
+        get async {
+            ["ar", "zh-Hans", "zh-Hant", "nl", "en-US", "en-GB", "fr", "de", "hi", "id", "it", "ja", "ko", "pl",
+             "pt-BR", "ru", "es", "th", "tr", "uk", "vi"].map { Locale.Language(identifier: $0) }
+        }
+    }
+
+    /// Whether `source` can be translated to `target` (the viewer's language when nil).
+    public func status(from source: Locale.Language, to target: Locale.Language?) async throws -> Status {
+        try await Self.ask(source: source, target: target, text: nil)
+    }
+
+    /// Whether `text`, whose language the page detects, can be translated to
+    /// `target`. Fails with `unableToIdentifyLanguage` when it cannot tell.
+    public func status(for text: String, to target: Locale.Language?) async throws -> Status {
+        try await Self.ask(source: nil, target: target, text: text)
+    }
+
+    static func ask(source: Locale.Language?, target: Locale.Language?, text: String?) async throws -> Status {
+        var params: [String: _JSON] = [
+            "action": .string("availability"),
+            "source": source.map { .string(_TranslationHost.tag($0)) } ?? .null,
+            "target": .string(_TranslationHost.tag(target ?? _TranslationHost.defaultTarget)),
+        ]
+        if let text { params["text"] = .string(text) }
+        do {
+            return _TranslationHost.status(try await _TranslationHost.transport(.object(params)))
+        } catch {
+            let error = _TranslationHost.error(error)
+            if error == .unableToIdentifyLanguage { throw error }
+            return .unsupported
+        }
+    }
+}
+
+// MARK: - Sessions
+
+/// Translates text between two languages. SwiftUI hands one to the action of
+/// `.translationTask`; iOS 26's `init(installedSource:target:)` makes one
+/// directly, which never downloads a model.
+public final class TranslationSession: @unchecked Sendable {
+    /// A text to translate in a batch, with an identifier to match its response.
+    public struct Request: Sendable, Hashable {
+        public var sourceText: String
+        public var clientIdentifier: String?
+
+        public init(sourceText: String, clientIdentifier: String? = nil) {
+            self.sourceText = sourceText
+            self.clientIdentifier = clientIdentifier
+        }
+    }
+
+    /// A translated text.
+    public struct Response: Sendable, Hashable {
+        public var sourceLanguage: Locale.Language
+        public var targetLanguage: Locale.Language
+        public var sourceText: String
+        public var targetText: String
+        public var clientIdentifier: String?
+    }
+
+    /// The languages of a `.translationTask`: nil source means detected, nil
+    /// target the viewer's language. `invalidate()` makes the task run again
+    /// with the same languages.
+    public struct Configuration: Sendable, Hashable {
+        public var source: Locale.Language?
+        public var target: Locale.Language?
+        public private(set) var version = 0
+
+        public init(source: Locale.Language? = nil, target: Locale.Language? = nil) {
+            self.source = source
+            self.target = target
+        }
+
+        /// Runs the configuration's translation task again.
+        public mutating func invalidate() { version += 1 }
+    }
+
+    /// The responses of `translate(batch:)`, in the order of the requests.
+    public struct BatchResponse: AsyncSequence, Sendable {
+        public typealias Element = Response
+        let responses: @Sendable () async throws -> [Response]
+
+        public struct AsyncIterator: AsyncIteratorProtocol {
+            let load: @Sendable () async throws -> [Response]
+            var loaded: [Response]?
+            var index = 0
+
+            public mutating func next() async throws -> Response? {
+                if loaded == nil { loaded = try await load() }
+                guard let loaded, index < loaded.count else { return nil }
+                defer { index += 1 }
+                return loaded[index]
+            }
+        }
+
+        public func makeAsyncIterator() -> AsyncIterator { AsyncIterator(load: responses) }
+    }
+
+    /// The language translated from; nil when each text's language is detected.
+    public let sourceLanguage: Locale.Language?
+    /// The language translated to; nil for the viewer's language.
+    public let targetLanguage: Locale.Language?
+    /// Whether the session may download a pair's model (the page asks the
+    /// browser to, which Chrome allows within a tap).
+    public let canRequestDownloads: Bool
+    private var cancelled = false
+
+    init(source: Locale.Language?, target: Locale.Language?, canRequestDownloads: Bool) {
+        sourceLanguage = source
+        targetLanguage = target
+        self.canRequestDownloads = canRequestDownloads
+    }
+
+    /// A session for a pair whose model is already on the device: it never
+    /// downloads one, and fails with `notInstalled` when it would have to.
+    public convenience init(installedSource: Locale.Language, target: Locale.Language? = nil) {
+        self.init(source: installedSource, target: target, canRequestDownloads: false)
+    }
+
+    /// Whether the pair's model is on the device.
+    public var isReady: Bool {
+        get async {
+            guard let sourceLanguage else { return false }
+            return (try? await LanguageAvailability().status(from: sourceLanguage, to: targetLanguage)) == .installed
+        }
+    }
+
+    /// Downloads the pair's model ahead of the first translation, when it is
+    /// supported and not yet installed.
+    public func prepareTranslation() async throws {
+        guard let sourceLanguage else { return }
+        switch try await LanguageAvailability().status(from: sourceLanguage, to: targetLanguage) {
+        case .installed: return
+        case .unsupported: throw TranslationError.unsupportedLanguagePairing
+        case .supported:
+            guard canRequestDownloads else { throw TranslationError.notInstalled }
+            _ = try await translate(texts: [""])
+        }
+    }
+
+    /// Translates one text.
+    public func translate(_ string: String) async throws -> Response {
+        guard !string.isEmpty else { throw TranslationError.nothingToTranslate }
+        return try await translations(from: [Request(sourceText: string)])[0]
+    }
+
+    /// Translates the requests together, answering in their order.
+    public func translations(from batch: [Request]) async throws -> [Response] {
+        guard !batch.isEmpty else { return [] }
+        let (source, texts) = try await translate(texts: batch.map(\.sourceText))
+        let target = targetLanguage ?? _TranslationHost.defaultTarget
+        return zip(batch, texts).map { request, text in
+            Response(sourceLanguage: source, targetLanguage: target, sourceText: request.sourceText,
+                     targetText: text, clientIdentifier: request.clientIdentifier)
+        }
+    }
+
+    /// Translates the requests, delivering each response as a sequence.
+    public func translate(batch: [Request]) -> BatchResponse {
+        BatchResponse { [self] in try await translations(from: batch) }
+    }
+
+    /// Stops the session: later translations fail.
+    public func cancel() { cancelled = true }
+
+    private func translate(texts: [String]) async throws -> (Locale.Language, [String]) {
+        if cancelled || Task.isCancelled { throw CancellationError() }
+        let params: _JSON = .object([
+            "action": .string("translate"),
+            "source": sourceLanguage.map { .string(_TranslationHost.tag($0)) } ?? .null,
+            "target": .string(_TranslationHost.tag(targetLanguage ?? _TranslationHost.defaultTarget)),
+            "texts": .array(texts.map { .string($0) }),
+            "allowDownload": .bool(canRequestDownloads),
+        ])
+        let value: _JSON
+        do {
+            value = try await _TranslationHost.transport(params)
+        } catch {
+            throw _TranslationHost.error(error)
+        }
+        guard case .object(let fields) = value, case .array(let items)? = fields["texts"] else {
+            throw _TranslationHost.status(value) == .unsupported ? TranslationError.unsupportedLanguagePairing
+                                                                       : TranslationError.internalError
+        }
+        let translated = items.map { item -> String in
+            if case .string(let text) = item { return text }
+            return ""
+        }
+        guard translated.count == texts.count else { throw TranslationError.internalError }
+        var source = sourceLanguage
+        if source == nil, case .string(let detected)? = fields["source"] { source = Locale.Language(identifier: detected) }
+        guard let source else { throw TranslationError.unableToIdentifyLanguage }
+        return (source, translated)
+    }
+}
+
+// MARK: - SwiftUI
+
+nonisolated extension View {
+    /// Runs `action` with a session for `configuration` when the view appears
+    /// with one, and again each time it changes (`invalidate()` included). A
+    /// nil configuration runs nothing. The session may download a model.
+    public func translationTask(_ configuration: TranslationSession.Configuration?,
+                                @_inheritActorContext action: @escaping @Sendable (TranslationSession) async -> Void) -> some View {
+        task(id: configuration) {
+            guard let configuration else { return }
+            await action(TranslationSession(source: configuration.source, target: configuration.target,
+                                            canRequestDownloads: true))
+        }
+    }
+
+    /// Runs `action` with a session from `source` to `target` when the view appears.
+    public func translationTask(source: Locale.Language? = nil, target: Locale.Language? = nil,
+                                @_inheritActorContext action: @escaping @Sendable (TranslationSession) async -> Void) -> some View {
+        task {
+            await action(TranslationSession(source: source, target: target, canRequestDownloads: true))
+        }
+    }
+
+    /// The system translation overlay for `text`. On an iPhone it is a sheet;
+    /// here too: the original, its translation into the viewer's language
+    /// (or why there is none), a Done button and, with `replacementAction`,
+    /// "Replace with Translation". The popover's anchor and arrow edge are ignored.
+    @MainActor
+    public func translationPresentation(isPresented: Binding<Bool>, text: String,
+                                        attachmentAnchor: PopoverAttachmentAnchor = .rect(.bounds),
+                                        arrowEdge: Edge = .top,
+                                        replacementAction: ((String) -> Void)? = nil) -> some View {
+        sheet(isPresented: isPresented) {
+            _TranslationPresentation(text: text, replacementAction: replacementAction)
+        }
+    }
+}
+
+/// The sheet of `.translationPresentation`.
+struct _TranslationPresentation: View {
+    let text: String
+    let replacementAction: ((String) -> Void)?
+    @Environment(\.dismiss) private var dismiss
+    @State private var translation: String?
+    @State private var failure: TranslationError?
+
+    var body: some View {
+        NavigationStack {
+            List {
+                Section {
+                    Text(text)
+                }
+                Section {
+                    if let translation {
+                        Text(translation)
+                    } else if let failure {
+                        Text(failure == .unsupportedLanguagePairing || failure == .unableToIdentifyLanguage
+                             ? "Translation is not available in this browser for this text."
+                             : failure.errorDescription ?? "The translation failed.")
+                            .foregroundStyle(.secondary)
+                    } else {
+                        ProgressView()
+                    }
+                }
+                if let translation, let replacementAction {
+                    Section {
+                        Button("Replace with Translation") {
+                            replacementAction(translation)
+                            dismiss()
+                        }
+                    }
+                }
+            }
+            .navigationTitle("Translate")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .confirmationAction) {
+                    Button("Done") { dismiss() }
+                }
+            }
+        }
+        .translationTask(source: nil, target: nil) { session in
+            do {
+                let response = try await session.translate(text)
+                await MainActor.run { translation = response.targetText }
+            } catch {
+                let failure = error as? TranslationError ?? .internalError
+                await MainActor.run { self.failure = failure }
+            }
+        }
+    }
+}

package/Sources/UIKit/Activity.swift

@@ -0,0 +1,213 @@
+// UIKit's share sheet in the browser. Presenting a `UIActivityViewController`
+// (any controller's `present`, or a `UIViewControllerRepresentable` that
+// shows one in a sheet) shares its items through the page, as SwiftUI's
+// `ShareLink` does: a `share` host request, which the page performs with the
+// Web Share API, or as downloads where the browser has none
+// (docs/ops-protocol.md, "Sharing"). Strings become the text, the first URL
+// the link, images their files; an item source gives its item for no
+// particular activity, and its link metadata's title becomes the share's
+// title. The controller is done once the page answers: it dismisses itself
+// and reports to `completionWithItemsHandler` (shared or not, with no
+// activity type, since the browser does not say where the items went).
+// Custom `UIActivity`s are kept; the browser's sheet cannot show them.
+
+import Foundation
+import FoundationBridge
+import SwiftUI
+
+// MARK: - Activities
+
+/// A service the share sheet offers. Kept: the browser's share sheet lists
+/// its own targets, so an app's activities are never shown or performed.
+open class UIActivity: @unchecked Sendable {
+    public struct ActivityType: RawRepresentable, Hashable, Sendable {
+        public let rawValue: String
+        public init(rawValue: String) { self.rawValue = rawValue }
+        public init(_ rawValue: String) { self.rawValue = rawValue }
+
+        public static let postToFacebook = ActivityType("com.apple.UIKit.activity.PostToFacebook")
+        public static let postToTwitter = ActivityType("com.apple.UIKit.activity.PostToTwitter")
+        public static let postToWeibo = ActivityType("com.apple.UIKit.activity.PostToWeibo")
+        public static let message = ActivityType("com.apple.UIKit.activity.Message")
+        public static let mail = ActivityType("com.apple.UIKit.activity.Mail")
+        public static let print = ActivityType("com.apple.UIKit.activity.Print")
+        public static let copyToPasteboard = ActivityType("com.apple.UIKit.activity.CopyToPasteboard")
+        public static let assignToContact = ActivityType("com.apple.UIKit.activity.AssignToContact")
+        public static let saveToCameraRoll = ActivityType("com.apple.UIKit.activity.SaveToCameraRoll")
+        public static let addToReadingList = ActivityType("com.apple.UIKit.activity.AddToReadingList")
+        public static let postToFlickr = ActivityType("com.apple.UIKit.activity.PostToFlickr")
+        public static let postToVimeo = ActivityType("com.apple.UIKit.activity.PostToVimeo")
+        public static let postToTencentWeibo = ActivityType("com.apple.UIKit.activity.TencentWeibo")
+        public static let airDrop = ActivityType("com.apple.UIKit.activity.AirDrop")
+        public static let openInIBooks = ActivityType("com.apple.UIKit.activity.OpenInIBooks")
+        public static let markupAsPDF = ActivityType("com.apple.UIKit.activity.MarkupAsPDF")
+        public static let sharePlay = ActivityType("com.apple.UIKit.activity.SharePlay")
+        public static let collaborationInviteWithLink = ActivityType("com.apple.UIKit.activity.CollaborationInviteWithLink")
+        public static let collaborationCopyLink = ActivityType("com.apple.UIKit.activity.CollaborationCopyLink")
+        public static let addToHomeScreen = ActivityType("com.apple.UIKit.activity.AddToHomeScreen")
+    }
+
+    public enum Category: Int, Sendable { case action, share }
+
+    public init() {}
+
+    open class var activityCategory: Category { .action }
+    open var activityType: ActivityType? { nil }
+    open var activityTitle: String? { nil }
+    open var activityImage: UIImage? { nil }
+    open var activityViewController: UIViewController? { nil }
+    open func canPerform(withActivityItems activityItems: [Any]) -> Bool { false }
+    open func prepare(withActivityItems activityItems: [Any]) {}
+    open func perform() { activityDidFinish(false) }
+    open func activityDidFinish(_ completed: Bool) {}
+}
+
+/// An object that gives the share sheet an item on demand. On iOS the
+/// methods after the first two are optional; here they have defaults.
+@MainActor
+public protocol UIActivityItemSource: AnyObject {
+    func activityViewControllerPlaceholderItem(_ activityViewController: UIActivityViewController) -> Any
+    func activityViewController(_ activityViewController: UIActivityViewController,
+                                itemForActivityType activityType: UIActivity.ActivityType?) -> Any?
+    func activityViewController(_ activityViewController: UIActivityViewController,
+                                subjectForActivityType activityType: UIActivity.ActivityType?) -> String
+    func activityViewController(_ activityViewController: UIActivityViewController,
+                                dataTypeIdentifierForActivityType activityType: UIActivity.ActivityType?) -> String
+    func activityViewControllerLinkMetadata(_ activityViewController: UIActivityViewController) -> LPLinkMetadata?
+}
+
+extension UIActivityItemSource {
+    public func activityViewController(_ activityViewController: UIActivityViewController,
+                                       subjectForActivityType activityType: UIActivity.ActivityType?) -> String { "" }
+    public func activityViewController(_ activityViewController: UIActivityViewController,
+                                       dataTypeIdentifierForActivityType activityType: UIActivity.ActivityType?) -> String { "" }
+    public func activityViewControllerLinkMetadata(_ activityViewController: UIActivityViewController) -> LPLinkMetadata? { nil }
+}
+
+/// An item source that makes its item when asked (an `Operation` on iOS):
+/// the share sheet takes `item`, which defaults to the placeholder.
+@MainActor
+open class UIActivityItemProvider: UIActivityItemSource {
+    public let placeholderItem: Any?
+    public private(set) var activityType: UIActivity.ActivityType?
+
+    public init(placeholderItem: Any) { self.placeholderItem = placeholderItem }
+
+    open var item: Any { placeholderItem as Any }
+
+    public func activityViewControllerPlaceholderItem(_ activityViewController: UIActivityViewController) -> Any { placeholderItem as Any }
+    public func activityViewController(_ activityViewController: UIActivityViewController,
+                                       itemForActivityType activityType: UIActivity.ActivityType?) -> Any? {
+        self.activityType = activityType
+        return item
+    }
+}
+
+/// A link's title, address and pictures, for a share sheet's header or a
+/// link preview. LinkPresentation re-exports it (Sources/LinkPresentation);
+/// it lives here so that `UIActivityItemSource` can name it, as on iOS.
+open class LPLinkMetadata: NSObject, @unchecked Sendable {
+    /// The URL the metadata was asked for.
+    open var originalURL: URL?
+    /// The URL the metadata describes (after redirects).
+    open var url: URL?
+    open var title: String?
+    open var iconProvider: NSItemProvider?
+    open var imageProvider: NSItemProvider?
+    open var videoProvider: NSItemProvider?
+    open var remoteVideoURL: URL?
+
+    public override init() { super.init() }
+}
+
+// MARK: - The share sheet
+
+/// The share sheet: presenting it shares its items through the page (see
+/// the top of this file).
+@MainActor
+open class UIActivityViewController: UIViewController {
+    public typealias CompletionWithItemsHandler = (UIActivity.ActivityType?, Bool, [Any]?, (any Error)?) -> Void
+
+    /// Shares a request through the page; tests replace it.
+    static var shareOnPage: @MainActor (_JSON) async -> Bool = { params in
+        guard let answer = try? await _Runtime.shared._hostRequest(kind: "share", params: params) else { return false }
+        if case .object(let fields) = answer, case .string(let outcome)? = fields["outcome"] { return outcome != "cancelled" }
+        return true
+    }
+
+    public let activityItems: [Any]
+    public let applicationActivities: [UIActivity]?
+    open var excludedActivityTypes: [UIActivity.ActivityType]?
+    open var completionWithItemsHandler: CompletionWithItemsHandler?
+    open var allowsProminentActivity = true
+    private var shared = false
+
+    public init(activityItems: [Any], applicationActivities: [UIActivity]?) {
+        self.activityItems = activityItems
+        self.applicationActivities = applicationActivities
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    public required init?(coder: NSCoder) { nil }
+
+    /// Presented: the items go to the page's share sheet; once it answers,
+    /// the controller dismisses itself and reports.
+    open override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        guard !shared else { return }
+        shared = true
+        let params = sharePayload
+        let items = resolvedItems
+        Task { @MainActor in
+            let completed = await Self.shareOnPage(params)
+            self.dismiss(animated: animated)
+            self.completionWithItemsHandler?(nil, completed, completed ? items : nil, nil)
+        }
+    }
+
+    /// The items as shared: an item source's item for no particular activity.
+    var resolvedItems: [Any] {
+        activityItems.compactMap { item in
+            if let source = item as? any UIActivityItemSource { return source.activityViewController(self, itemForActivityType: nil) }
+            return item
+        }
+    }
+
+    /// The `share` request's fields: `title` (an item source's link metadata
+    /// or subject), `text`, `url`, and the images as `files`, `bitmaps` or
+    /// `images`, as `ShareLink` sends them.
+    var sharePayload: _JSON {
+        var title: String?
+        var texts: [String] = []
+        var url: String?
+        var picture: [String: [_JSON]] = [:]
+        for item in activityItems {
+            if let source = item as? any UIActivityItemSource {
+                if title == nil { title = source.activityViewControllerLinkMetadata(self)?.title }
+                let subject = source.activityViewController(self, subjectForActivityType: nil)
+                if title == nil, !subject.isEmpty { title = subject }
+            }
+        }
+        for item in resolvedItems {
+            switch item {
+            case let string as String: texts.append(string)
+            case let attributed as NSAttributedString: texts.append(attributed.string)
+            case let link as URL:
+                if url == nil { url = link.absoluteString } else { texts.append(link.absoluteString) }
+            case let image as UIImage:
+                for (key, value) in _PageFiles.fields(for: image, name: title ?? "Image") {
+                    if case .array(let entries) = value { picture[key, default: []] += entries }
+                }
+            case let data as Data:
+                picture["files", default: []].append(_PageFiles.entry(name: title ?? "Shared", type: "application/octet-stream", data: data))
+            default: break
+            }
+        }
+        var fields: [String: _JSON] = [:]
+        if let title { fields["title"] = .string(title) }
+        if !texts.isEmpty { fields["text"] = .string(texts.joined(separator: "\n")) }
+        if let url { fields["url"] = .string(url) }
+        for (key, entries) in picture { fields[key] = .array(entries) }
+        return .object(fields)
+    }
+}