@swiftbrowser/native 0.19.0 → 0.21.0

package/swift/Packages/SwiftBrowserShader/Sources/SwiftBrowserShader/ShaderView.swift

@@ -0,0 +1,168 @@
+#if canImport(MetalKit) && canImport(SwiftUI)
+import MetalKit
+import SwiftBrowserNative
+import SwiftBrowserProtocol
+import SwiftUI
+
+/// The native side of @swiftbrowser/shader: installs `ShaderView`'s view, an
+/// `MTKView` that draws the shader's Metal over its box.
+///
+/// ```swift
+/// import SwiftBrowserShader
+///
+/// init() {
+///     SwiftBrowserShader.install()
+/// }
+/// ```
+@MainActor
+public enum SwiftBrowserShader {
+    /// The name `ShaderView` is registered under, on both platforms (view.ts `SHADER_VIEW`).
+    public static let viewName = "SwiftBrowserShader.view"
+
+    /// Registers `ShaderView`'s SwiftUI view; call at launch, before the bundle loads.
+    public static func install() {
+        ViewRegistry.register(viewName) { context in
+            ShaderSurface(props: ShaderProps(props: context.props), send: context.send)
+        }
+    }
+}
+
+/// `ShaderView` (@swiftbrowser/shader): the shader drawn when its props or its size change, or every display frame
+/// when `animated`. A shader its device does not compile draws nothing and says why (`onError`), once.
+struct ShaderSurface: View {
+    let props: ShaderProps
+    let send: (JSONValue) -> Void
+
+    var body: some View {
+        if let device = SharedDevice.device {
+            MetalShaderView(device: device, props: props, send: send)
+        } else {
+            Color.clear
+        }
+    }
+}
+
+@MainActor
+private enum SharedDevice {
+    static let device: MTLDevice? = MTLCreateSystemDefaultDevice()
+}
+
+/// Draws for an `MTKView`: on demand (`setNeedsDisplay`) unless animated.
+@MainActor
+final class ShaderDrawing: NSObject, MTKViewDelegate {
+    let renderer: ShaderRenderer
+    let queue: MTLCommandQueue?
+    var props: ShaderProps
+    var send: (JSONValue) -> Void
+    private var reported = ""
+    private var started = Date()
+
+    init(device: MTLDevice, props: ShaderProps, send: @escaping (JSONValue) -> Void) {
+        renderer = ShaderRenderer(device: device)
+        queue = device.makeCommandQueue()
+        self.props = props
+        self.send = send
+    }
+
+    func configure(_ view: MTKView) {
+        view.device = renderer.device
+        view.colorPixelFormat = renderer.pixelFormat
+        view.clearColor = MTLClearColor(red: 0, green: 0, blue: 0, alpha: 0)
+        view.framebufferOnly = true
+        view.delegate = self
+        #if os(macOS)
+        view.layer?.isOpaque = false
+        #else
+        view.isOpaque = false
+        view.backgroundColor = .clear
+        #endif
+        update(view)
+    }
+
+    /// New props: drawn at once, or from now on every frame when animated.
+    func update(_ view: MTKView) {
+        if !props.animated { started = Date() }
+        view.isPaused = !props.animated
+        view.enableSetNeedsDisplay = !props.animated
+        view.preferredFramesPerSecond = 60
+        redraw(view)
+    }
+
+    private func redraw(_ view: MTKView) {
+        #if os(macOS)
+        view.needsDisplay = true
+        #else
+        view.setNeedsDisplay()
+        #endif
+    }
+
+    func mtkView(_ view: MTKView, drawableSizeWillChange size: CGSize) {
+        redraw(view)
+    }
+
+    func draw(in view: MTKView) {
+        do {
+            try renderer.prepare(props)
+        } catch {
+            let message = String(describing: error)
+            if message != reported {
+                reported = message
+                send(.object(["error": .string(message)]))
+            }
+        }
+        let bounds = view.bounds.size
+        guard bounds.width > 0, bounds.height > 0, let pass = view.currentRenderPassDescriptor, let drawable = view.currentDrawable,
+              let buffer = queue?.makeCommandBuffer(), let encoder = buffer.makeRenderCommandEncoder(descriptor: pass) else { return }
+        // The scale the drawable has, so that a point's rows and its pixels line up.
+        let scale = view.drawableSize.height / bounds.height
+        renderer.draw(props, into: encoder, width: bounds.width, height: bounds.height, scale: scale, time: Date().timeIntervalSince(started))
+        encoder.endEncoding()
+        buffer.present(drawable)
+        buffer.commit()
+    }
+}
+
+#if os(macOS)
+private struct MetalShaderView: NSViewRepresentable {
+    let device: MTLDevice
+    let props: ShaderProps
+    let send: (JSONValue) -> Void
+
+    func makeCoordinator() -> ShaderDrawing { ShaderDrawing(device: device, props: props, send: send) }
+
+    func makeNSView(context: Context) -> MTKView {
+        let view = MTKView(frame: .zero, device: device)
+        context.coordinator.configure(view)
+        return view
+    }
+
+    func updateNSView(_ view: MTKView, context: Context) {
+        context.coordinator.send = send
+        guard context.coordinator.props != props else { return }
+        context.coordinator.props = props
+        context.coordinator.update(view)
+    }
+}
+#else
+private struct MetalShaderView: UIViewRepresentable {
+    let device: MTLDevice
+    let props: ShaderProps
+    let send: (JSONValue) -> Void
+
+    func makeCoordinator() -> ShaderDrawing { ShaderDrawing(device: device, props: props, send: send) }
+
+    func makeUIView(context: Context) -> MTKView {
+        let view = MTKView(frame: .zero, device: device)
+        context.coordinator.configure(view)
+        return view
+    }
+
+    func updateUIView(_ view: MTKView, context: Context) {
+        context.coordinator.send = send
+        guard context.coordinator.props != props else { return }
+        context.coordinator.props = props
+        context.coordinator.update(view)
+    }
+}
+#endif
+#endif

package/swift/Packages/SwiftBrowserShader/Sources/SwiftBrowserShaderCore/ShaderProps.swift

@@ -0,0 +1,120 @@
+import SwiftBrowserProtocol
+
+/// A compiled shader as `ShaderView` sends it natively (@swiftbrowser/shader's
+/// `CompiledShader` with only its Metal): where each uniform's floats are,
+/// how many floats a draw reads, its textures' names in slot order, and the
+/// Metal library (`sb_vertex`, `sb_fragment`).
+public struct ShaderLayout: Equatable, Sendable {
+    public struct Uniform: Equatable, Sendable {
+        public let name: String
+        public let offset: Int
+        public let size: Int
+        public let value: [Float]
+    }
+
+    public let uniforms: [Uniform]
+    public let floats: Int
+    public let textures: [String]
+    public let msl: String
+
+    /// The floats every shader starts with (shader.ts `BUILTIN_UNIFORMS`): width, height, scale, time.
+    public static let builtins = 4
+
+    public init?(json: JSONValue) {
+        guard let msl = json["msl"].string, let floats = json["floats"].int, floats >= Self.builtins, floats <= 1024 else { return nil }
+        var uniforms: [Uniform] = []
+        for entry in json["uniforms"].array ?? [] {
+            guard let name = entry["name"].string, let offset = entry["offset"].int, let size = entry["size"].int,
+                  (1...4).contains(size), offset >= Self.builtins, offset + size <= floats else { return nil }
+            let value = (entry["value"].array ?? []).map { Float($0.double ?? 0) }
+            uniforms.append(Uniform(name: name, offset: offset, size: size, value: value))
+        }
+        self.uniforms = uniforms
+        self.floats = floats
+        self.textures = (json["textures"].array ?? []).compactMap(\.string)
+        self.msl = msl
+    }
+}
+
+/// A float texture: `width` × `height` values, row by row (row 0 at the top).
+public struct ShaderTextureData: Equatable, Sendable {
+    public let width: Int
+    public let height: Int
+    public let data: [Float]
+
+    public init?(json: JSONValue) {
+        guard let width = json["width"].int, let height = json["height"].int, width > 0, height > 0,
+              let values = json["data"].array, values.count >= width * height else { return nil }
+        self.width = width
+        self.height = height
+        self.data = values.prefix(width * height).map { Float($0.double ?? 0) }
+    }
+}
+
+/// `ShaderView`'s props (packages/shader/src/view.ts): the shader, its uniforms by name, its textures by slot, and
+/// whether it draws every frame.
+public struct ShaderProps: Equatable, Sendable {
+    public let shader: ShaderLayout?
+    public let uniforms: JSONObject
+    public let textures: [ShaderTextureData?]
+    public let animated: Bool
+
+    public init(props: JSONValue) {
+        shader = ShaderLayout(json: props["shader"])
+        uniforms = props["uniforms"].object ?? [:]
+        textures = (props["textures"].array ?? []).map(ShaderTextureData.init(json:))
+        animated = props["animated"].bool ?? false
+    }
+
+    /**
+     * The floats a draw reads (shader.ts `packUniforms`): the view's size in points, its pixels a point and the
+     * seconds it has run, then each uniform as given (a number, a vector, or a `#rrggbb` color), its default when
+     * absent or of another size, a color of three components taking alpha 1 where four are wanted.
+     */
+    public func packedUniforms(width: Double, height: Double, scale: Double, time: Double) -> [Float] {
+        guard let shader else { return [] }
+        var floats = [Float](repeating: 0, count: shader.floats)
+        floats[0] = Float(width)
+        floats[1] = Float(height)
+        floats[2] = Float(scale)
+        floats[3] = Float(time)
+        for uniform in shader.uniforms {
+            var given = uniforms[uniform.name].flatMap(Self.floats(of:))
+            if let three = given, three.count == 3, uniform.size == 4 { given = three + [1] }
+            let value = given.flatMap { $0.count == uniform.size ? $0 : nil } ?? uniform.value
+            for i in 0..<uniform.size { floats[uniform.offset + i] = i < value.count ? value[i] : 0 }
+        }
+        return floats
+    }
+
+    /// A uniform's value as floats: a number, an array of numbers, or a color.
+    static func floats(of value: JSONValue) -> [Float]? {
+        switch value {
+        case .number(let number): return number.isFinite ? [Float(number)] : nil
+        case .string(let text): return parseColor(text)
+        case .array(let items):
+            let numbers = items.compactMap(\.double)
+            return numbers.count == items.count ? numbers.map { Float($0) } : nil
+        default: return nil
+        }
+    }
+}
+
+/// A `#rrggbb` or `#rrggbbaa` color as 0 … 1 components (shader.ts `parseColor`).
+public func parseColor(_ text: String) -> [Float]? {
+    var digits = Substring(text)
+    while let first = digits.first, first.isWhitespace { digits = digits.dropFirst() }
+    while let last = digits.last, last.isWhitespace { digits = digits.dropLast() }
+    guard digits.first == "#" else { return nil }
+    digits = digits.dropFirst()
+    guard digits.count == 6 || digits.count == 8 else { return nil }
+    var components: [Float] = []
+    var index = digits.startIndex
+    while index < digits.endIndex {
+        let next = digits.index(index, offsetBy: 2)
+        guard let byte = UInt8(digits[index..<next], radix: 16) else { return nil }
+        components.append(Float(byte) / 255)
+        index = next
+    }
+    return components
+}

package/swift/Sources/SwiftBrowserNative/Host/BodyStream.swift

@@ -0,0 +1,166 @@
+#if canImport(SwiftUI)
+import Foundation
+
+/// A request body streamed from its parts: bytes the page sent beside the
+/// request, and ranges of files on disk (a picked file, a dropped one, one in
+/// the app's directories), read a piece at a time through a `FileHandle` as
+/// `URLSession` asks for them, so a body of gigabytes costs no memory. The
+/// files are those the app may read (`FilesBridge.readable`); a folder opened
+/// in place keeps its security scope for the read.
+enum BodyPart: Sendable {
+    case bytes(Data)
+    case file(URL, start: Int, end: Int)
+
+    var length: Int {
+        switch self {
+        case .bytes(let data): return data.count
+        case .file(_, let start, let end): return max(0, end - start)
+        }
+    }
+
+    /// `{ "$bytes": n }` (the nth view beside the request) or `{ url, start, end }` of a file the app may read.
+    init(part: JSONValue, bytes: [HostBytes]) throws {
+        if let index = part["$bytes"].int {
+            guard bytes.indices.contains(index) else { throw HostRequestFailure("unsupported: body part \(index) was not sent") }
+            self = .bytes(bytes[index].data)
+            return
+        }
+        guard let urlString = part["url"].string, let start = part["start"].int, let end = part["end"].int else {
+            throw HostRequestFailure("unsupported: a body part is neither bytes nor a file range")
+        }
+        #if !canImport(FoundationBridge)
+        guard let url = FilesBridge.readableURL(urlString) else { throw HostRequestFailure("unsupported: \(urlString) is not a file the app may read") }
+        self = .file(url, start: max(0, start), end: max(0, end))
+        #else
+        throw HostRequestFailure("unsupported: a body streamed from a file needs the native files bridge")
+        #endif
+    }
+}
+
+#if !canImport(FoundationBridge)
+/// An `InputStream` over the parts in order, for `URLRequest.httpBodyStream`.
+final class PartsInputStream: InputStream, @unchecked Sendable {
+    private let parts: [BodyPart]
+    private var index = 0
+    private var offset = 0
+    private var handle: FileHandle?
+    private var stopAccess: (() -> Void)?
+    private var status: Stream.Status = .notOpen
+    private var error: Error?
+    private weak var delegate_: StreamDelegate?
+
+    init(parts: [BodyPart]) {
+        self.parts = parts
+        super.init(data: Data())
+    }
+
+    override var streamStatus: Stream.Status { status }
+    override var streamError: Error? { error }
+    override var delegate: StreamDelegate? {
+        get { delegate_ }
+        set { delegate_ = newValue }
+    }
+    override var hasBytesAvailable: Bool { status == .open && index < parts.count }
+
+    override func open() {
+        status = .open
+    }
+
+    override func close() {
+        try? handle?.close()
+        handle = nil
+        stopAccess?()
+        stopAccess = nil
+        status = .closed
+    }
+
+    override func property(forKey key: Stream.PropertyKey) -> Any? { nil }
+    override func setProperty(_ property: Any?, forKey key: Stream.PropertyKey) -> Bool { false }
+    override func schedule(in aRunLoop: RunLoop, forMode mode: RunLoop.Mode) {}
+    override func remove(from aRunLoop: RunLoop, forMode mode: RunLoop.Mode) {}
+
+    /// Fills `buffer` from the current part, moving to the next as each ends; 0 at the end, -1 on a read error.
+    override func read(_ buffer: UnsafeMutablePointer<UInt8>, maxLength: Int) -> Int {
+        guard status == .open else { return -1 }
+        while index < parts.count {
+            let part = parts[index]
+            let remaining = part.length - offset
+            if remaining <= 0 {
+                advance()
+                continue
+            }
+            let count = min(maxLength, remaining)
+            switch part {
+            case .bytes(let data):
+                _ = data.copyBytes(to: buffer, from: offset..<(offset + count))
+                offset += count
+                return count
+            case .file(let url, let start, _):
+                do {
+                    let handle = try openHandle(url, at: start + offset)
+                    guard let data = try handle.read(upToCount: count), !data.isEmpty else {
+                        throw HostRequestFailure("unavailable: \(url.lastPathComponent) ended before its range")
+                    }
+                    _ = data.copyBytes(to: buffer, count: data.count)
+                    offset += data.count
+                    return data.count
+                } catch {
+                    self.error = error
+                    status = .error
+                    return -1
+                }
+            }
+        }
+        status = .atEnd
+        return 0
+    }
+
+    private func openHandle(_ url: URL, at position: Int) throws -> FileHandle {
+        if let handle { return handle }
+        #if !canImport(FoundationBridge)
+        stopAccess = PickedFiles.shared.beginAccessing(url)
+        #endif
+        let handle = try FileHandle(forReadingFrom: url)
+        try handle.seek(toOffset: UInt64(position))
+        self.handle = handle
+        return handle
+    }
+
+    private func advance() {
+        try? handle?.close()
+        handle = nil
+        stopAccess?()
+        stopAccess = nil
+        index += 1
+        offset = 0
+    }
+}
+
+/// The session delegate that makes a fresh stream of a task's parts when
+/// `URLSession` must send the body again (a redirect, an authentication
+/// challenge): a stream cannot be rewound, its parts can be read again.
+final class BodyStreams: NSObject, URLSessionTaskDelegate, @unchecked Sendable {
+    private let lock = NSLock()
+    private var parts: [Int: [BodyPart]] = [:]
+
+    func register(_ task: URLSessionTask, parts: [BodyPart]) {
+        lock.lock()
+        self.parts[task.taskIdentifier] = parts
+        lock.unlock()
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, needNewBodyStream completionHandler: @escaping (InputStream?) -> Void) {
+        lock.lock()
+        let parts = parts[task.taskIdentifier]
+        lock.unlock()
+        completionHandler(parts.map { PartsInputStream(parts: $0) })
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        lock.lock()
+        parts[task.taskIdentifier] = nil
+        lock.unlock()
+    }
+}
+#endif
+#endif

package/swift/Sources/SwiftBrowserNative/Host/FilesBridge.swift

@@ -49,6 +49,14 @@ struct FilesBridge: Sendable {
         return roots
     }
 
+    /// Whether `url` is in one of the app's directories, or a file the viewer picked or dropped (PickedFiles),
+    /// which the app may read and copy in (`readRange`, `importItem`, `attributes`) but not write.
+    private func readable(_ url: URL) -> Bool {
+        let path = url.path
+        if roots.contains(where: { path == $0.path || path.hasPrefix($0.path + "/") }) { return true }
+        return PickedFiles.shared.contains(url)
+    }
+
     /// Runs `body` on `url` under file coordination when the URL is in the iCloud container, else as it is.
     private func coordinated<T>(_ url: URL, writing: NSFileCoordinator.WritingOptions?, _ body: (URL) throws -> T) throws -> T {
         guard ICloudContainer.shared.contains(url) else { return try body(url) }
@@ -84,20 +92,43 @@ struct FilesBridge: Sendable {
         throw HostRequestFailure("unavailable: \(url.absoluteString) did not download from iCloud Drive")
     }
 
-    /// The file URL `params[key]` names, under today's container, inside the app's directories.
-    private func url(_ params: JSONObject, _ key: String) throws -> URL {
+    /// The file URL `params[key]` names, under today's container, inside the app's directories (or, `reading`, a picked file's).
+    private func url(_ params: JSONObject, _ key: String, reading: Bool = false) throws -> URL {
         guard let string = params[key]?.string, let parsed = URL(string: string) else {
             throw HostRequestFailure("unsupported: files: \(key) is not a URL")
         }
         guard parsed.isFileURL else { throw HostRequestFailure("unsupported: \(string) is not a file URL") }
         let url = AppFiles.current(parsed).standardizedFileURL
         let path = url.path
-        guard roots.contains(where: { path == $0.path || path.hasPrefix($0.path + "/") }) else {
+        let inApp = roots.contains(where: { path == $0.path || path.hasPrefix($0.path + "/") })
+        guard inApp || (reading && readable(url)) else {
             throw HostRequestFailure("unsupported: \(string) is not in the app's directories")
         }
         return url
     }
 
+    /// The file URL `string` names when the app may read it (in its directories, or picked or dropped); nil otherwise. For a body streamed from disk (BodyStream.swift).
+    static func readableURL(_ string: String) -> URL? {
+        let bridge = FilesBridge()
+        guard let parsed = URL(string: string), parsed.isFileURL else { return nil }
+        let url = AppFiles.current(parsed).standardizedFileURL
+        return bridge.readable(url) ? url : nil
+    }
+
+    /// The file's bytes from `start` up to `end` (clamped), through a `FileHandle`, so a large file is read a piece at a time.
+    private func readRange(_ url: URL, start: Int, end: Int?) throws -> Data {
+        try coordinated(url, writing: nil) { target in
+            let handle = try FileHandle(forReadingFrom: target)
+            defer { try? handle.close() }
+            let size = try handle.seekToEnd()
+            let from = min(UInt64(max(0, start)), size)
+            let to = min(end.map { UInt64(max(0, $0)) } ?? size, size)
+            guard from < to else { return Data() }
+            try handle.seek(toOffset: from)
+            return try handle.read(upToCount: Int(to - from)) ?? Data()
+        }
+    }
+
     private func isDirectory(_ url: URL) -> Bool? {
         var directory: ObjCBool = false
         if manager.fileExists(atPath: url.path, isDirectory: &directory) { return directory.boolValue }
@@ -128,15 +159,47 @@ struct FilesBridge: Sendable {
             try await ensureDownloaded(url)
             return .object(["url": .string(url.absoluteString)])
         case "read":
-            let url = try url(params, "url")
+            let url = try url(params, "url", reading: true)
             switch isDirectory(url) {
             case nil: throw HostRequestFailure("notFound: no file at \(url.absoluteString)")
             case true?: throw HostRequestFailure("isDirectory: \(url.absoluteString) is a directory")
             case false?: break
             }
             try await ensureDownloaded(url)
-            let data = try coordinated(url, writing: nil) { try Data(contentsOf: $0) }
+            let data = try PickedFiles.shared.accessing(url) { try coordinated(url, writing: nil) { try Data(contentsOf: $0) } }
             return .object(["data": RequestBytes.value(data)])
+        case "readRange":
+            // `fileManager.contents(url, { start, end })`: a piece of the file, `FileHandle`'s seek and read.
+            let url = try url(params, "url", reading: true)
+            switch isDirectory(url) {
+            case nil: throw HostRequestFailure("notFound: no file at \(url.absoluteString)")
+            case true?: throw HostRequestFailure("isDirectory: \(url.absoluteString) is a directory")
+            case false?: break
+            }
+            try await ensureDownloaded(url)
+            let start = params["start"]?.int ?? Int(params["start"]?.double ?? 0)
+            let end = params["end"]?.int ?? params["end"]?.double.map { Int($0) }
+            let data = try PickedFiles.shared.accessing(url) { try readRange(url, start: start, end: end) }
+            return .object(["data": RequestBytes.value(data)])
+        case "importItem":
+            // `fileManager.write(url, pickedFile)`: the picked file copied on disk into the app's directories, no bytes across the bridge.
+            let from = try url(params, "from", reading: true)
+            let to = try url(params, "to")
+            guard isDirectory(from) == false else { throw HostRequestFailure("notFound: no file at \(from.absoluteString)") }
+            if isDirectory(to) == true { throw HostRequestFailure("isDirectory: \(to.absoluteString) is a directory") }
+            try requireDirectory(to.deletingLastPathComponent(), for: to)
+            try await ensureDownloaded(from)
+            try PickedFiles.shared.accessing(from) {
+                try coordinated(to, writing: .forReplacing) { target in
+                    if manager.fileExists(atPath: target.path) { try manager.removeItem(at: target) }
+                    try manager.copyItem(at: from, to: target)
+                }
+            }
+            return .object([:])
+        case "release":
+            // The app is done with what it picked: the folder's security scope ends and the copies in tmp go.
+            PickedFiles.shared.release(params["urls"]?.array?.compactMap { $0.string.flatMap(URL.init(string:)) })
+            return .object([:])
         case "write":
             let url = try url(params, "url")
             guard let data = RequestBytes.data(params["data"]) else {
@@ -169,9 +232,9 @@ struct FilesBridge: Sendable {
             }).sorted { $0.localizedStandardCompare($1) == .orderedAscending }
             return .object(["urls": .array(names.map { .string(url.appendingPathComponent($0).absoluteString) })])
         case "attributes":
-            let url = try url(params, "url")
+            let url = try url(params, "url", reading: true)
             guard let directory = isDirectory(url) else { return .null }
-            let attributes = try manager.attributesOfItem(atPath: url.path)
+            let attributes = try PickedFiles.shared.accessing(url) { try manager.attributesOfItem(atPath: url.path) }
             let size = directory ? 0 : ((attributes[.size] as? NSNumber)?.doubleValue ?? 0)
             let modified = (attributes[.modificationDate] as? Date).map { JSONValue.number(($0.timeIntervalSince1970 * 1000).rounded()) } ?? .null
             let created = (attributes[.creationDate] as? Date).map { JSONValue.number(($0.timeIntervalSince1970 * 1000).rounded()) } ?? .null
@@ -203,6 +266,77 @@ struct FilesBridge: Sendable {
 
 #endif
 
+#if !canImport(FoundationBridge)
+/// The files and folders the viewer picked (`pickFiles`) or dropped: the page
+/// gets their URLs and sizes, not their bytes, and reads them through the
+/// files bridge (`readRange`, `importItem`) while they are registered here.
+/// A folder opened in place keeps its security scope until the app releases
+/// it (`files` `release`) or picks again; copies the pickers made in tmp are
+/// deleted then too.
+final class PickedFiles: @unchecked Sendable {
+    static let shared = PickedFiles()
+
+    private let lock = NSLock()
+    /// Files the app may read, by standardized path; the scoped folders they came from, if any.
+    private var files: [String: URL] = [:]
+    private var scopedFolders: [URL] = []
+    /// Folders in tmp the pickers copied into, removed on release.
+    private var temporaryFolders: [URL] = []
+
+    /// Registers files the app may read: `scoped` is a folder whose security scope is open (stopped on release).
+    func register(_ urls: [URL], scoped folder: URL? = nil, temporary: URL? = nil) {
+        lock.lock()
+        defer { lock.unlock() }
+        for url in urls { files[url.standardizedFileURL.path] = url }
+        if let folder { scopedFolders.append(folder) }
+        if let temporary { temporaryFolders.append(temporary) }
+    }
+
+    func contains(_ url: URL) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        let path = url.standardizedFileURL.path
+        if files[path] != nil { return true }
+        return scopedFolders.contains { path.hasPrefix($0.standardizedFileURL.path + "/") }
+    }
+
+    /// Runs `body` with the folder's security scope open where `url` is in a scoped folder.
+    func accessing<T>(_ url: URL, _ body: () throws -> T) rethrows -> T {
+        let stop = beginAccessing(url)
+        defer { stop?() }
+        return try body()
+    }
+
+    /// Opens the security scope of the folder `url` is in, if any, until the closure answered is called (a stream reading over time).
+    func beginAccessing(_ url: URL) -> (() -> Void)? {
+        lock.lock()
+        let path = url.standardizedFileURL.path
+        let folder = scopedFolders.first { path.hasPrefix($0.standardizedFileURL.path + "/") }
+        lock.unlock()
+        guard let folder, folder.startAccessingSecurityScopedResource() else { return nil }
+        return { folder.stopAccessingSecurityScopedResource() }
+    }
+
+    /// Forgets the given files (all of them when nil), ending scopes and deleting the pickers' copies no file still names.
+    func release(_ urls: [URL]?) {
+        lock.lock()
+        if let urls {
+            for url in urls { files[url.standardizedFileURL.path] = nil }
+        } else {
+            files.removeAll()
+        }
+        let stillNamed = Set(files.values.map { $0.standardizedFileURL.path })
+        let doneFolders = scopedFolders.filter { folder in !stillNamed.contains { $0.hasPrefix(folder.standardizedFileURL.path + "/") } }
+        scopedFolders.removeAll { doneFolders.contains($0) }
+        let doneTemporary = temporaryFolders.filter { folder in !stillNamed.contains { $0.hasPrefix(folder.standardizedFileURL.path + "/") } }
+        temporaryFolders.removeAll { doneTemporary.contains($0) }
+        lock.unlock()
+        for folder in doneFolders { folder.stopAccessingSecurityScopedResource() }
+        for folder in doneTemporary { try? FileManager.default.removeItem(at: folder) }
+    }
+}
+#endif
+
 /// Files the app keeps (a recording's, `fileManager`'s) are named by their
 /// URL, and iOS moves an app's container when it is installed again: a file
 /// URL into an old `Documents` that is not there anymore is the same path