@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/PhotosUI/PhotosPicker.swift

@@ -0,0 +1,248 @@
+// `PhotosPicker` and `.photosPicker(isPresented:)`: the page's file chooser
+// in place of the photo library. A pick is a `pickFiles` host request
+// (Phase 13's channel; docs/ops-protocol.md, "Photos picker") with the
+// filter's `accept` and whether several files may be chosen. The page opens
+// an `<input type="file">` from the tap that sent it (the request goes out
+// within the same click, which a browser requires to show a chooser) and
+// answers with each chosen file's bytes, type and, for a picture, an object
+// URL and pixel size. A dismissed chooser answers with no files, which
+// leaves the selection as it was, as on iOS.
+
+import SwiftUI
+
+/// One pick: what to offer, how many, and what to do with the result.
+struct _PhotosPick: Sendable {
+    let filter: PHPickerFilter?
+    /// At most this many items (nil: no limit).
+    let limit: Int?
+    /// Whether the chooser lets the viewer pick several files.
+    let multiple: Bool
+    /// Whether picked items expose an `itemIdentifier` (a `photoLibrary` was given).
+    let exposesIdentifiers: Bool
+
+    /// The request's params: `{accept, multiple}`. No filter offers pictures and movies, the library's contents.
+    var params: _JSON {
+        .object([
+            "accept": .string((filter ?? .any(of: [.images, .videos])).accept),
+            "multiple": .bool(multiple),
+        ])
+    }
+
+    /// Asks the page and waits for the viewer. Empty when the chooser was
+    /// dismissed, or the page could not open one.
+    @MainActor func run() async -> [PhotosPickerItem] {
+        guard let value = try? await _Runtime.shared._hostRequest(kind: "pickFiles", params: params) else { return [] }
+        return items(from: value)
+    }
+
+    /// The items of a `pickFiles` answer (`{items: [...]}`): files the
+    /// filter rejects are dropped (a chooser's "All files" lets any through),
+    /// then the list is cut to the limit.
+    @MainActor func items(from value: _JSON) -> [PhotosPickerItem] {
+        guard case .object(let fields) = value, case .array(let entries)? = fields["items"] else { return [] }
+        let matching = filter ?? .any(of: [.images, .videos])
+        var items: [PhotosPickerItem] = []
+        for entry in entries {
+            guard let file = _PickedFile(entry), matching.matches(mimeType: file.effectiveMIMEType) else { continue }
+            if let limit, limit > 0, items.count >= limit { break }
+            _PhotosPick.picked += 1
+            items.append(PhotosPickerItem(file: file, key: "picked-\(_PhotosPick.picked)", exposesIdentifier: exposesIdentifiers))
+        }
+        return items
+    }
+
+    /// Items picked so far in this run: each new one gets the next key.
+    @MainActor static var picked = 0
+
+    /// Runs the pick in a task (a tap's executor run, so the request leaves
+    /// within the click) and hands a non-empty result to `apply`.
+    @MainActor func start(_ apply: @escaping @MainActor ([PhotosPickerItem]) -> Void, finished: @escaping @MainActor () -> Void = {}) {
+        Task { @MainActor in
+            let items = await run()
+            if !items.isEmpty { apply(items) }
+            finished()
+        }
+    }
+}
+
+// MARK: PhotosPicker
+
+/// A button that opens the photo picker (the browser's file chooser) and
+/// puts what the viewer picks into `selection`.
+public struct PhotosPicker<Label: View>: View {
+    let pick: _PhotosPick
+    let apply: @MainActor ([PhotosPickerItem]) -> Void
+    let label: Label
+
+    init(pick: _PhotosPick, apply: @escaping @MainActor ([PhotosPickerItem]) -> Void, label: Label) {
+        self.pick = pick
+        self.apply = apply
+        self.label = label
+    }
+
+    public var body: some View {
+        let pick = pick
+        let apply = apply
+        return Button {
+            pick.start(apply)
+        } label: {
+            label
+        }
+    }
+
+    // One item.
+
+    public init(selection: Binding<PhotosPickerItem?>, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                @ViewBuilder label: () -> Label) {
+        self.init(pick: _PhotosPick(filter: filter, limit: 1, multiple: false, exposesIdentifiers: false),
+                  apply: { selection.wrappedValue = $0.first }, label: label())
+    }
+
+    public init(selection: Binding<PhotosPickerItem?>, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                photoLibrary: PHPhotoLibrary, @ViewBuilder label: () -> Label) {
+        self.init(pick: _PhotosPick(filter: filter, limit: 1, multiple: false, exposesIdentifiers: true),
+                  apply: { selection.wrappedValue = $0.first }, label: label())
+    }
+
+    // Several items.
+
+    public init(selection: Binding<[PhotosPickerItem]>, maxSelectionCount: Int? = nil,
+                selectionBehavior: PhotosPickerSelectionBehavior = .default, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                @ViewBuilder label: () -> Label) {
+        self.init(pick: _PhotosPick(filter: filter, limit: maxSelectionCount, multiple: maxSelectionCount != 1, exposesIdentifiers: false),
+                  apply: { selection.wrappedValue = $0 }, label: label())
+    }
+
+    public init(selection: Binding<[PhotosPickerItem]>, maxSelectionCount: Int? = nil,
+                selectionBehavior: PhotosPickerSelectionBehavior = .default, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                photoLibrary: PHPhotoLibrary, @ViewBuilder label: () -> Label) {
+        self.init(pick: _PhotosPick(filter: filter, limit: maxSelectionCount, multiple: maxSelectionCount != 1, exposesIdentifiers: true),
+                  apply: { selection.wrappedValue = $0 }, label: label())
+    }
+}
+
+extension PhotosPicker where Label == Text {
+    // One item, with a title.
+
+    public init(_ titleKey: LocalizedStringKey, selection: Binding<PhotosPickerItem?>, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic) {
+        self.init(selection: selection, matching: filter, preferredItemEncoding: preferredItemEncoding) { Text(titleKey) }
+    }
+
+    @_disfavoredOverload
+    public init<S: StringProtocol>(_ title: S, selection: Binding<PhotosPickerItem?>, matching filter: PHPickerFilter? = nil,
+                                   preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic) {
+        self.init(selection: selection, matching: filter, preferredItemEncoding: preferredItemEncoding) { Text(title) }
+    }
+
+    public init(_ titleKey: LocalizedStringKey, selection: Binding<PhotosPickerItem?>, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic, photoLibrary: PHPhotoLibrary) {
+        self.init(selection: selection, matching: filter, preferredItemEncoding: preferredItemEncoding, photoLibrary: photoLibrary) { Text(titleKey) }
+    }
+
+    @_disfavoredOverload
+    public init<S: StringProtocol>(_ title: S, selection: Binding<PhotosPickerItem?>, matching filter: PHPickerFilter? = nil,
+                                   preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                                   photoLibrary: PHPhotoLibrary) {
+        self.init(selection: selection, matching: filter, preferredItemEncoding: preferredItemEncoding, photoLibrary: photoLibrary) { Text(title) }
+    }
+
+    // Several items, with a title.
+
+    public init(_ titleKey: LocalizedStringKey, selection: Binding<[PhotosPickerItem]>, maxSelectionCount: Int? = nil,
+                selectionBehavior: PhotosPickerSelectionBehavior = .default, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic) {
+        self.init(selection: selection, maxSelectionCount: maxSelectionCount, selectionBehavior: selectionBehavior,
+                  matching: filter, preferredItemEncoding: preferredItemEncoding) { Text(titleKey) }
+    }
+
+    @_disfavoredOverload
+    public init<S: StringProtocol>(_ title: S, selection: Binding<[PhotosPickerItem]>, maxSelectionCount: Int? = nil,
+                                   selectionBehavior: PhotosPickerSelectionBehavior = .default, matching filter: PHPickerFilter? = nil,
+                                   preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic) {
+        self.init(selection: selection, maxSelectionCount: maxSelectionCount, selectionBehavior: selectionBehavior,
+                  matching: filter, preferredItemEncoding: preferredItemEncoding) { Text(title) }
+    }
+
+    public init(_ titleKey: LocalizedStringKey, selection: Binding<[PhotosPickerItem]>, maxSelectionCount: Int? = nil,
+                selectionBehavior: PhotosPickerSelectionBehavior = .default, matching filter: PHPickerFilter? = nil,
+                preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic, photoLibrary: PHPhotoLibrary) {
+        self.init(selection: selection, maxSelectionCount: maxSelectionCount, selectionBehavior: selectionBehavior,
+                  matching: filter, preferredItemEncoding: preferredItemEncoding, photoLibrary: photoLibrary) { Text(titleKey) }
+    }
+
+    @_disfavoredOverload
+    public init<S: StringProtocol>(_ title: S, selection: Binding<[PhotosPickerItem]>, maxSelectionCount: Int? = nil,
+                                   selectionBehavior: PhotosPickerSelectionBehavior = .default, matching filter: PHPickerFilter? = nil,
+                                   preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                                   photoLibrary: PHPhotoLibrary) {
+        self.init(selection: selection, maxSelectionCount: maxSelectionCount, selectionBehavior: selectionBehavior,
+                  matching: filter, preferredItemEncoding: preferredItemEncoding, photoLibrary: photoLibrary) { Text(title) }
+    }
+}
+
+// MARK: .photosPicker(isPresented:)
+
+/// Opens the picker when `isPresented` becomes true (or is true when the
+/// view appears) and sets it back to false once the viewer is done. Opening
+/// the chooser needs a tap, so set `isPresented` from a button's action.
+struct _PhotosPickerPresenter<Content: View>: View {
+    let content: Content
+    let isPresented: Binding<Bool>
+    let pick: _PhotosPick
+    let apply: @MainActor ([PhotosPickerItem]) -> Void
+
+    var body: some View {
+        let isPresented = isPresented
+        let pick = pick
+        let apply = apply
+        return content.onChange(of: isPresented.wrappedValue, initial: true) { _, presented in
+            guard presented else { return }
+            MainActor.assumeIsolated {
+                pick.start(apply) { isPresented.wrappedValue = false }
+            }
+        }
+    }
+}
+
+extension View {
+    public func photosPicker(isPresented: Binding<Bool>, selection: Binding<PhotosPickerItem?>,
+                             matching filter: PHPickerFilter? = nil,
+                             preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic) -> some View {
+        _PhotosPickerPresenter(content: self, isPresented: isPresented,
+                               pick: _PhotosPick(filter: filter, limit: 1, multiple: false, exposesIdentifiers: false),
+                               apply: { selection.wrappedValue = $0.first })
+    }
+
+    public func photosPicker(isPresented: Binding<Bool>, selection: Binding<PhotosPickerItem?>,
+                             matching filter: PHPickerFilter? = nil,
+                             preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                             photoLibrary: PHPhotoLibrary) -> some View {
+        _PhotosPickerPresenter(content: self, isPresented: isPresented,
+                               pick: _PhotosPick(filter: filter, limit: 1, multiple: false, exposesIdentifiers: true),
+                               apply: { selection.wrappedValue = $0.first })
+    }
+
+    public func photosPicker(isPresented: Binding<Bool>, selection: Binding<[PhotosPickerItem]>,
+                             maxSelectionCount: Int? = nil, selectionBehavior: PhotosPickerSelectionBehavior = .default,
+                             matching filter: PHPickerFilter? = nil,
+                             preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic) -> some View {
+        _PhotosPickerPresenter(content: self, isPresented: isPresented,
+                               pick: _PhotosPick(filter: filter, limit: maxSelectionCount, multiple: maxSelectionCount != 1, exposesIdentifiers: false),
+                               apply: { selection.wrappedValue = $0 })
+    }
+
+    public func photosPicker(isPresented: Binding<Bool>, selection: Binding<[PhotosPickerItem]>,
+                             maxSelectionCount: Int? = nil, selectionBehavior: PhotosPickerSelectionBehavior = .default,
+                             matching filter: PHPickerFilter? = nil,
+                             preferredItemEncoding: PhotosPickerItem.EncodingDisambiguationPolicy = .automatic,
+                             photoLibrary: PHPhotoLibrary) -> some View {
+        _PhotosPickerPresenter(content: self, isPresented: isPresented,
+                               pick: _PhotosPick(filter: filter, limit: maxSelectionCount, multiple: maxSelectionCount != 1, exposesIdentifiers: true),
+                               apply: { selection.wrappedValue = $0 })
+    }
+}

package/Sources/PhotosUI/PhotosPickerItem.swift

@@ -0,0 +1,261 @@
+// PhotosUI's model types: the picked item, the filter and the library. The
+// browser has no photo library; the page's file chooser stands in for it
+// (docs/ops-protocol.md, "Photos picker"). A pick delivers every chosen
+// file's bytes with the selection, so `loadTransferable` answers at once.
+
+import Foundation
+import FoundationBridge
+// As on iOS, PhotosUI brings Photos along (`PHPhotoLibrary`, `PHAsset`).
+@_exported import Photos
+import SwiftUI
+import UniformTypeIdentifiers
+
+/// One picked photo or video. Two items are equal when they come from the
+/// same pick of the same file; picking the same file again makes a new item,
+/// so `onChange(of:)` sees every pick.
+public struct PhotosPickerItem: Equatable, Hashable, Sendable {
+    /// How the picker hands over a photo with several encodings. Accepted for
+    /// source compatibility: the browser delivers the file as it is.
+    public enum EncodingDisambiguationPolicy: Equatable, Hashable, Sendable {
+        case automatic
+        case current
+        case compatible
+    }
+
+    /// The asset's identifier in the photo library: like iOS, nil unless the
+    /// picker was given a `photoLibrary`.
+    public let itemIdentifier: String?
+    /// The file's type (from its MIME type, else its extension).
+    public let supportedContentTypes: [UTType]
+
+    /// Identity: unique per picked file per pick.
+    let key: String
+    let file: _PickedFile?
+
+    /// An item for an asset you already know the identifier of. The browser
+    /// has no library to load it from: `loadTransferable` returns nil.
+    public init(itemIdentifier: String) {
+        self.itemIdentifier = itemIdentifier
+        supportedContentTypes = []
+        key = "id:\(itemIdentifier)"
+        file = nil
+    }
+
+    init(file: _PickedFile, key: String, exposesIdentifier: Bool) {
+        itemIdentifier = exposesIdentifier ? key : nil
+        supportedContentTypes = file.contentType.map { [$0] } ?? []
+        self.key = key
+        self.file = file
+    }
+
+    public static func == (lhs: PhotosPickerItem, rhs: PhotosPickerItem) -> Bool { lhs.key == rhs.key }
+    public func hash(into hasher: inout Hasher) { hasher.combine(key) }
+
+    /// The item as `type`. `Data` is the file's bytes; `Image` shows the
+    /// picture (a still image the browser could decode). Any other type
+    /// imports through its first representation that takes the file's type
+    /// (a `FileRepresentation(importedContentType: .image)` receives a copy
+    /// of the file); nil when none does.
+    nonisolated(nonsending) public func loadTransferable<T: Transferable>(type: T.Type) async throws -> T? {
+        if let known = try loadKnown(type) { return known }
+        return try await loadImported(type)
+    }
+
+    /// The completion-handler form. For `Data` and `Image` the handler runs
+    /// before this returns; other types load in a task.
+    @discardableResult
+    public func loadTransferable<T: Transferable>(type: T.Type,
+                                                  completionHandler: @escaping @Sendable (Result<T?, any Error>) -> Void) -> Progress {
+        let progress = Progress(totalUnitCount: 1)
+        do {
+            if let known = try loadKnown(type) {
+                completionHandler(.success(known))
+                progress.completedUnitCount = 1
+                return progress
+            }
+        } catch {
+            completionHandler(.failure(error))
+            progress.completedUnitCount = 1
+            return progress
+        }
+        let item = self
+        let job = _PhotosLoadJob(progress: progress, work: { try await item.loadImported(type) },
+                                 done: { result in completionHandler(result.map { $0 as? T }) })
+        job.start()
+        return progress
+    }
+
+    /// `Data` and `Image`, answered from the pick at once: `.some(value)`;
+    /// nil for the other types.
+    private func loadKnown<T: Transferable>(_ type: T.Type) throws -> T?? {
+        guard T.self == Data.self || T.self == Image.self else { return nil }
+        guard let file else { return .some(nil) }
+        if T.self == Data.self {
+            guard let data = Data(base64Encoded: file.base64) else {
+                throw CocoaError(.fileReadCorruptFile)
+            }
+            return .some(data as? T)
+        }
+        guard let url = file.url, let width = file.pixelWidth, let height = file.pixelHeight else { return .some(nil) }
+        return .some(Image(_url: url, pixelWidth: width, pixelHeight: height, scale: 1) as? T)
+    }
+
+    /// Any other type, through its importing representations.
+    nonisolated(nonsending) func loadImported<T: Transferable>(_ type: T.Type) async throws -> T? {
+        guard let file, let contentType = file.contentType else { return nil }
+        guard _Transfer.canImport(T.self, contentType: contentType) else { return nil }
+        guard let data = Data(base64Encoded: file.base64) else { throw CocoaError(.fileReadCorruptFile) }
+        let name = file.name.isEmpty ? nil : (file.name as NSString).deletingPathExtension
+        return try await _Transfer.import(T.self, from: _TransferContent(contentType: contentType, data: data, suggestedName: name))
+    }
+}
+
+/// One completion-handler load of a type that imports through its
+/// representations (type-erased, so the task carries no generic context).
+final class _PhotosLoadJob: @unchecked Sendable {
+    let work: () async throws -> Any?
+    let done: (Result<Any?, any Error>) -> Void
+    let progress: Progress
+
+    init(progress: Progress, work: @escaping () async throws -> Any?, done: @escaping (Result<Any?, any Error>) -> Void) {
+        self.work = work
+        self.done = done
+        self.progress = progress
+    }
+
+    func start() {
+        Task { await self.run() }
+    }
+
+    func run() async {
+        var result: Result<Any?, any Error>
+        do {
+            let value = try await work()
+            result = .success(value)
+        } catch {
+            result = .failure(error)
+        }
+        progress.completedUnitCount = 1
+        done(result)
+    }
+}
+
+/// A file the page picked: its bytes (base64), type and, for a picture the
+/// browser could decode, an object URL it can show and its pixel size.
+struct _PickedFile: Sendable {
+    let name: String
+    let mimeType: String
+    let base64: String
+    let url: String?
+    let pixelWidth: Double?
+    let pixelHeight: Double?
+
+    /// From one entry of a `pickFiles` answer: `{name, type, data, url?, width?, height?}`.
+    init?(_ json: _JSON) {
+        guard case .object(let fields) = json, case .string(let data)? = fields["data"] else { return nil }
+        if case .string(let name)? = fields["name"] { self.name = name } else { name = "" }
+        if case .string(let type)? = fields["type"] { mimeType = type.lowercased() } else { mimeType = "" }
+        base64 = data
+        if case .string(let url)? = fields["url"] { self.url = url } else { url = nil }
+        if case .number(let width)? = fields["width"], case .number(let height)? = fields["height"], width > 0, height > 0 {
+            pixelWidth = width
+            pixelHeight = height
+        } else {
+            pixelWidth = nil
+            pixelHeight = nil
+        }
+    }
+
+    /// The file's type: its MIME type when the browser knows it, else its extension.
+    var contentType: UTType? {
+        if !mimeType.isEmpty, let type = UTType(mimeType: mimeType) { return type }
+        guard let dot = name.lastIndex(of: "."), dot != name.index(before: name.endIndex) else { return nil }
+        return UTType(filenameExtension: String(name[name.index(after: dot)...]))
+    }
+
+    /// The MIME type the filter is matched against (from the extension when the browser reported none).
+    var effectiveMIMEType: String {
+        mimeType.isEmpty ? (contentType?.preferredMIMEType ?? "") : mimeType
+    }
+}
+
+
+// MARK: Filter
+
+/// Which assets the picker offers. In the browser it becomes the file
+/// chooser's `accept` (`image/*`, `video/*`); the picked files are matched
+/// against it again, since a chooser lets the viewer pick any file.
+public struct PHPickerFilter: Hashable, Sendable {
+    indirect enum Rule: Hashable, Sendable {
+        case media(Media)
+        case any([PHPickerFilter])
+        case all([PHPickerFilter])
+        case not(PHPickerFilter)
+    }
+
+    /// What a kind of asset is made of, as far as a file's MIME type tells.
+    enum Media: Hashable, Sendable {
+        case image, video, imageOrVideo
+    }
+
+    let rule: Rule
+
+    public static let images = PHPickerFilter(rule: .media(.image))
+    public static let videos = PHPickerFilter(rule: .media(.video))
+    public static let livePhotos = PHPickerFilter(rule: .media(.image))
+    public static let depthEffectPhotos = PHPickerFilter(rule: .media(.image))
+    public static let panoramas = PHPickerFilter(rule: .media(.image))
+    public static let screenshots = PHPickerFilter(rule: .media(.image))
+    public static let bursts = PHPickerFilter(rule: .media(.image))
+    public static let screenRecordings = PHPickerFilter(rule: .media(.video))
+    public static let slomoVideos = PHPickerFilter(rule: .media(.video))
+    public static let timelapseVideos = PHPickerFilter(rule: .media(.video))
+    public static let cinematicVideos = PHPickerFilter(rule: .media(.video))
+    public static let spatialMedia = PHPickerFilter(rule: .media(.imageOrVideo))
+
+    public static func any(of subfilters: [PHPickerFilter]) -> PHPickerFilter { PHPickerFilter(rule: .any(subfilters)) }
+    public static func all(of subfilters: [PHPickerFilter]) -> PHPickerFilter { PHPickerFilter(rule: .all(subfilters)) }
+    public static func not(_ filter: PHPickerFilter) -> PHPickerFilter { PHPickerFilter(rule: .not(filter)) }
+
+    /// Whether a file of this MIME type passes. A photo library holds only
+    /// pictures and movies, so nothing else ever does.
+    func matches(mimeType: String) -> Bool {
+        let isImage = mimeType.hasPrefix("image/")
+        let isVideo = mimeType.hasPrefix("video/")
+        guard isImage || isVideo else { return false }
+        return evaluate(isImage: isImage)
+    }
+
+    private func evaluate(isImage: Bool) -> Bool {
+        switch rule {
+        case .media(.image): return isImage
+        case .media(.video): return !isImage
+        case .media(.imageOrVideo): return true
+        case .any(let filters): return filters.contains { $0.evaluate(isImage: isImage) }
+        case .all(let filters): return filters.allSatisfy { $0.evaluate(isImage: isImage) }
+        case .not(let filter): return !filter.evaluate(isImage: isImage)
+        }
+    }
+
+    /// The file chooser's `accept`: the media kinds that can pass.
+    var accept: String {
+        [(evaluate(isImage: true), "image/*"), (evaluate(isImage: false), "video/*")]
+            .filter(\.0).map(\.1).joined(separator: ",")
+    }
+}
+
+// MARK: Library
+
+// `PHPhotoLibrary`, `PHAccessLevel` and `PHAuthorizationStatus` are Photos'
+// (Sources/Photos), which PhotosUI re-exports, as on iOS.
+
+/// How a multiple-selection picker orders and updates its selection.
+/// Accepted for source compatibility: the browser's chooser returns the
+/// files in its own order, once.
+public struct PhotosPickerSelectionBehavior: Equatable, Hashable, Sendable {
+    let name: String
+    public static let `default` = PhotosPickerSelectionBehavior(name: "default")
+    public static let ordered = PhotosPickerSelectionBehavior(name: "ordered")
+    public static let continuous = PhotosPickerSelectionBehavior(name: "continuous")
+    public static let continuousAndOrdered = PhotosPickerSelectionBehavior(name: "continuousAndOrdered")
+}

package/Sources/QuickLook/QuickLook.swift

@@ -0,0 +1,168 @@
+// `import QuickLook` for the browser: a preview is the browser's own viewer
+// in a new tab. `.quickLookPreview($url)` (and `(_:in:)`, which previews the
+// selection) opens the URL when the binding is set, then sets it back to nil,
+// as the preview's dismissal does on iOS: a web URL opens as a link would,
+// and a file of the app's (Ice Cubes saves the picture it previews into its
+// caches) is handed to the page, which opens it as a blob in a new tab, or
+// downloads it when the browser blocks the tab (a tab opened long after the
+// tap that asked for it). Both are a `media` host request with `action:
+// "open"` (docs/ops-protocol.md, "Video and audio").
+//
+// `QLPreviewController` does the same for its data source's current item when
+// presented, then dismisses itself, like SafariServices' controller.
+
+import Foundation
+import FoundationBridge
+import SwiftUI
+import UIKit
+
+/// The page's side of a preview; tests replace `open`.
+@MainActor
+public enum _QuickLookHost {
+    public static var open: @MainActor (URL) async -> Void = { url in
+        let params: _JSON
+        if url.isFileURL {
+            guard let data = try? Data(contentsOf: url) else { return }
+            params = .object([
+                "action": .string("open"),
+                "name": .string(url.lastPathComponent),
+                "type": .string(_mediaType(forPathExtension: url.pathExtension)),
+                "data": .string(_base64(Array(data))),
+            ])
+        } else {
+            params = .object(["action": .string("open"), "url": .string(url.absoluteString)])
+        }
+        _ = try? await _Runtime.shared._hostRequest(kind: "media", params: params)
+    }
+}
+
+/// The media type the page opens a file as, from its extension.
+func _mediaType(forPathExtension pathExtension: String) -> String {
+    switch pathExtension.lowercased() {
+    case "jpg", "jpeg": "image/jpeg"
+    case "png": "image/png"
+    case "gif": "image/gif"
+    case "webp": "image/webp"
+    case "heic", "heif": "image/heic"
+    case "avif": "image/avif"
+    case "svg": "image/svg+xml"
+    case "pdf": "application/pdf"
+    case "mp4", "m4v": "video/mp4"
+    case "mov": "video/quicktime"
+    case "webm": "video/webm"
+    case "mp3": "audio/mpeg"
+    case "m4a": "audio/mp4"
+    case "wav": "audio/wav"
+    case "txt", "md", "swift": "text/plain"
+    case "html", "htm": "text/html"
+    case "json": "application/json"
+    case "csv": "text/csv"
+    default: "application/octet-stream"
+    }
+}
+
+extension View {
+    /// Previews the URL in a new tab when `item` is set, then sets it to nil.
+    public func quickLookPreview(_ item: Binding<URL?>) -> some View {
+        modifier(_QuickLookPreviewModifier(item: item))
+    }
+
+    /// Previews the selected URL (the browser shows one file at a time; the
+    /// other items are not offered), then sets the selection to nil.
+    public func quickLookPreview<Items: RandomAccessCollection>(_ selection: Binding<Items.Element?>, in items: Items) -> some View
+    where Items.Element == URL {
+        modifier(_QuickLookPreviewModifier(item: selection))
+    }
+}
+
+struct _QuickLookPreviewModifier: ViewModifier {
+    @Binding var item: URL?
+
+    func body(content: Content) -> some View {
+        content.onChange(of: item, initial: true) { _, url in
+            guard let url else { return }
+            item = nil
+            Task { @MainActor in await _QuickLookHost.open(url) }
+        }
+    }
+}
+
+// MARK: - QLPreviewController
+
+/// Something a preview controller can show. `URL` conforms.
+public protocol QLPreviewItem {
+    var previewItemURL: URL? { get }
+    var previewItemTitle: String? { get }
+}
+
+extension QLPreviewItem {
+    public var previewItemTitle: String? { nil }
+}
+
+extension URL: QLPreviewItem {
+    public var previewItemURL: URL? { self }
+}
+
+extension NSURL: QLPreviewItem {
+    public var previewItemURL: URL? { self as URL }
+}
+
+@MainActor
+public protocol QLPreviewControllerDataSource: AnyObject {
+    func numberOfPreviewItems(in controller: QLPreviewController) -> Int
+    func previewController(_ controller: QLPreviewController, previewItemAt index: Int) -> any QLPreviewItem
+}
+
+/// What a preview controller tells its owner. Every method is optional.
+@MainActor
+public protocol QLPreviewControllerDelegate: AnyObject {
+    func previewControllerWillDismiss(_ controller: QLPreviewController)
+    func previewControllerDidDismiss(_ controller: QLPreviewController)
+    func previewController(_ controller: QLPreviewController, shouldOpen url: URL, for item: any QLPreviewItem) -> Bool
+}
+
+extension QLPreviewControllerDelegate {
+    public func previewControllerWillDismiss(_ controller: QLPreviewController) {}
+    public func previewControllerDidDismiss(_ controller: QLPreviewController) {}
+    public func previewController(_ controller: QLPreviewController, shouldOpen url: URL, for item: any QLPreviewItem) -> Bool { true }
+}
+
+/// Previews its data source's current item in a new tab when presented (see
+/// the top of the file), then dismisses itself.
+@MainActor
+open class QLPreviewController: UIViewController {
+    open weak var dataSource: (any QLPreviewControllerDataSource)?
+    open weak var delegate: (any QLPreviewControllerDelegate)?
+    open var currentPreviewItemIndex = 0
+    private var opened = false
+
+    public init() {
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    public required init?(coder: NSCoder) { nil }
+
+    /// Any URL the page can open, or a file it can hand over.
+    public static func canPreview(_ item: any QLPreviewItem) -> Bool { item.previewItemURL != nil }
+
+    open var currentPreviewItem: (any QLPreviewItem)? {
+        guard let dataSource, currentPreviewItemIndex >= 0,
+              currentPreviewItemIndex < dataSource.numberOfPreviewItems(in: self) else { return nil }
+        return dataSource.previewController(self, previewItemAt: currentPreviewItemIndex)
+    }
+
+    open func reloadData() {}
+    open func refreshCurrentPreviewItem() {}
+
+    open override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        guard !opened else { return }
+        opened = true
+        if let url = currentPreviewItem?.previewItemURL {
+            Task { @MainActor in await _QuickLookHost.open(url) }
+        }
+        delegate?.previewControllerWillDismiss(self)
+        dismiss(animated: animated)
+        delegate?.previewControllerDidDismiss(self)
+    }
+}