@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/SwiftUI/API/Animation.swift

@@ -0,0 +1,285 @@
+/// How a change is animated. Encoded for the renderer as documented in
+/// docs/ops-protocol.md (Phase 3).
+public struct Animation: Equatable, Sendable {
+    enum Kind: String, Sendable {
+        case `default`, linear, easeIn, easeOut, easeInOut, spring
+    }
+
+    var kind: Kind
+    var duration: Double
+    var bounce: Double
+    var delayBy: Double
+    /// `.repeatCount` / `.repeatForever`: `count` nil with `forever` false means once.
+    var repeatCount: Int?
+    var repeatForever = false
+    var autoreverses = true
+
+    init(kind: Kind, duration: Double = 0.35, bounce: Double = 0, delay: Double = 0) {
+        self.kind = kind
+        self.duration = duration
+        self.bounce = bounce
+        self.delayBy = delay
+    }
+
+    public static let `default` = Animation(kind: .default)
+    public static let linear = Animation(kind: .linear)
+    public static let easeIn = Animation(kind: .easeIn)
+    public static let easeOut = Animation(kind: .easeOut)
+    public static let easeInOut = Animation(kind: .easeInOut)
+    public static let spring = Animation(kind: .spring, duration: 0.5, bounce: 0)
+    public static let bouncy = Animation(kind: .spring, duration: 0.5, bounce: 0.3)
+    public static let smooth = Animation(kind: .spring, duration: 0.5, bounce: 0)
+    public static let snappy = Animation(kind: .spring, duration: 0.5, bounce: 0.15)
+
+    public static func linear(duration: Double) -> Animation { Animation(kind: .linear, duration: duration) }
+    public static func easeIn(duration: Double) -> Animation { Animation(kind: .easeIn, duration: duration) }
+    public static func easeOut(duration: Double) -> Animation { Animation(kind: .easeOut, duration: duration) }
+    public static func easeInOut(duration: Double) -> Animation { Animation(kind: .easeInOut, duration: duration) }
+    public static func spring(duration: Double = 0.5, bounce: Double = 0) -> Animation {
+        Animation(kind: .spring, duration: duration, bounce: bounce)
+    }
+    /// The pre-iOS 17 spring: `response` is the duration, the damping fraction
+    /// maps onto bounce (`1` is a smooth spring, lower values overshoot).
+    public static func spring(response: Double = 0.5, dampingFraction: Double = 0.825,
+                              blendDuration: Double = 0) -> Animation {
+        Animation(kind: .spring, duration: response, bounce: max(0, min(1, 1 - dampingFraction)))
+    }
+    public static func interactiveSpring(response: Double = 0.15, dampingFraction: Double = 0.86,
+                                         blendDuration: Double = 0.25) -> Animation {
+        spring(response: response, dampingFraction: dampingFraction, blendDuration: blendDuration)
+    }
+    public static func bouncy(duration: Double = 0.5, extraBounce: Double = 0) -> Animation {
+        Animation(kind: .spring, duration: duration, bounce: 0.3 + extraBounce)
+    }
+    public static func smooth(duration: Double = 0.5, extraBounce: Double = 0) -> Animation {
+        Animation(kind: .spring, duration: duration, bounce: extraBounce)
+    }
+    public static func snappy(duration: Double = 0.5, extraBounce: Double = 0) -> Animation {
+        Animation(kind: .spring, duration: duration, bounce: 0.15 + extraBounce)
+    }
+
+    public func delay(_ delay: Double) -> Animation {
+        var copy = self
+        copy.delayBy = delay
+        return copy
+    }
+
+    public func speed(_ speed: Double) -> Animation {
+        var copy = self
+        copy.duration = speed > 0 ? duration / speed : duration
+        return copy
+    }
+
+    /// Repeats the animation `repeatCount` times, reversing on alternate runs
+    /// when `autoreverses`.
+    public func repeatCount(_ repeatCount: Int, autoreverses: Bool = true) -> Animation {
+        var copy = self
+        copy.repeatCount = repeatCount
+        copy.repeatForever = false
+        copy.autoreverses = autoreverses
+        return copy
+    }
+
+    public func repeatForever(autoreverses: Bool = true) -> Animation {
+        var copy = self
+        copy.repeatCount = nil
+        copy.repeatForever = true
+        copy.autoreverses = autoreverses
+        return copy
+    }
+
+    var _json: _JSON {
+        var object: [String: _JSON] = ["type": .string(kind.rawValue), "duration": .number(duration)]
+        if bounce != 0 { object["bounce"] = .number(bounce) }
+        if delayBy != 0 { object["delay"] = .number(delayBy) }
+        if repeatForever || repeatCount != nil {
+            object["repeat"] = .object([
+                "count": repeatForever ? .string("forever") : .number(Double(repeatCount ?? 1)),
+                "autoreverses": .bool(autoreverses),
+            ])
+        }
+        return .object(object)
+    }
+}
+
+extension Binding {
+    /// A binding whose writes animate the view changes they cause.
+    public func animation(_ animation: Animation? = .default) -> Binding<Value> {
+        let setter = self.setter
+        return Binding(get: getter) { value in
+            // Bindings are written from the main actor (event handlers, bodies).
+            let outer = MainActor.assumeIsolated { _Runtime.shared.beginTransaction(animation) }
+            setter(value)
+            MainActor.assumeIsolated { _Runtime.shared.endTransaction(outer) }
+        }
+    }
+}
+
+/// Runs `body` and animates the view changes it causes.
+@MainActor
+public func withAnimation<Result>(_ animation: Animation? = .default,
+                                  _ body: () throws -> Result) rethrows -> Result {
+    try _Runtime.shared.runInTransaction(animation, body)
+}
+
+/// Runs `body` in `transaction`: its animation (none when it disables
+/// animations) animates the view changes `body` causes.
+@MainActor
+public func withTransaction<Result>(_ transaction: Transaction, _ body: () throws -> Result) rethrows -> Result {
+    try _Runtime.shared.runInTransaction(transaction.disablesAnimations ? nil : transaction.animation, body)
+}
+
+/// `withTransaction` with one property of a fresh transaction set.
+@MainActor
+public func withTransaction<Result, Value>(_ keyPath: WritableKeyPath<Transaction, Value>, _ value: Value,
+                                           _ body: () throws -> Result) rethrows -> Result {
+    var transaction = Transaction()
+    transaction[keyPath: keyPath] = value
+    return try withTransaction(transaction, body)
+}
+
+// MARK: - Transitions
+
+/// How a view appears and disappears when inserted or removed with animation.
+public struct AnyTransition: Sendable {
+    struct Part: Sendable {
+        var kind: String
+        var edge: Edge?
+        var scale: Double?
+        var offset: CGSize?
+        /// `asymmetric`: the transitions for insertion and removal.
+        var insertion: [Part]?
+        var removal: [Part]?
+
+        var _json: _JSON {
+            var object: [String: _JSON] = ["kind": .string(kind)]
+            if let edge { object["edge"] = .string(edge.name) }
+            if let scale { object["scale"] = .number(scale) }
+            if let offset {
+                object["x"] = .number(offset.width)
+                object["y"] = .number(offset.height)
+            }
+            if let insertion { object["insertion"] = AnyTransition(parts: insertion)._json }
+            if let removal { object["removal"] = AnyTransition(parts: removal)._json }
+            return .object(object)
+        }
+    }
+
+    public static func asymmetric(insertion: AnyTransition, removal: AnyTransition) -> AnyTransition {
+        AnyTransition(parts: [Part(kind: "asymmetric", insertion: insertion.parts, removal: removal.parts)])
+    }
+
+    var parts: [Part]
+
+    public static let identity = AnyTransition(parts: [Part(kind: "identity")])
+    public static let opacity = AnyTransition(parts: [Part(kind: "opacity")])
+    public static let slide = AnyTransition(parts: [Part(kind: "slide")])
+    public static let scale = AnyTransition(parts: [Part(kind: "scale", scale: 0.5)])
+
+    public static func scale(scale: Double) -> AnyTransition {
+        AnyTransition(parts: [Part(kind: "scale", scale: scale)])
+    }
+
+    /// The anchor is accepted for source compatibility; scaling is about the center.
+    public static func scale(scale: Double, anchor: UnitPoint) -> AnyTransition {
+        AnyTransition(parts: [Part(kind: "scale", scale: scale)])
+    }
+
+    /// iOS 17's spelling, `.scale(0.5)`.
+    public static func scale(_ scale: Double, anchor: UnitPoint = .center) -> AnyTransition {
+        AnyTransition(parts: [Part(kind: "scale", scale: scale)])
+    }
+
+    /// Slides in from / out to the given offset (points).
+    public static func offset(x: CGFloat = 0, y: CGFloat = 0) -> AnyTransition {
+        AnyTransition(parts: [Part(kind: "offset", offset: CGSize(width: x, height: y))])
+    }
+
+    public static func offset(_ offset: CGSize) -> AnyTransition {
+        AnyTransition(parts: [Part(kind: "offset", offset: offset)])
+    }
+
+    public static func move(edge: Edge) -> AnyTransition {
+        AnyTransition(parts: [Part(kind: "move", edge: edge)])
+    }
+
+    public func combined(with other: AnyTransition) -> AnyTransition {
+        AnyTransition(parts: parts + other.parts)
+    }
+
+    /// A transition between two states of a `ViewModifier`. The shim cannot
+    /// diff arbitrary modifiers, so it is accepted and rendered as `opacity`
+    /// (docs/ops-protocol.md, Phase 8).
+    public static func modifier<E: ViewModifier>(active: E, identity: E) -> AnyTransition {
+        .opacity
+    }
+
+    var _json: _JSON {
+        parts.count == 1 ? parts[0]._json : .array(parts.map(\._json))
+    }
+}
+
+extension Edge {
+    var name: String {
+        switch self {
+        case .top: "top"
+        case .leading: "leading"
+        case .bottom: "bottom"
+        case .trailing: "trailing"
+        }
+    }
+}
+
+// MARK: - Modifiers
+
+/// Views whose subtree animates when `value` changes.
+protocol _AnimatedView: _TraitBearing {
+    var _animation: Animation? { get }
+    /// Whether the tracked value differs from a previously stored one.
+    func _changed(since previous: Any?) -> Bool
+    var _value: Any { get }
+    var _content: [any View] { get }
+}
+
+struct _AnimationView<Content: View, Value: Equatable> {
+    let content: Content
+    let animation: Animation?
+    let value: Value
+}
+extension _AnimationView: _PrimitiveView {}
+extension _AnimationView: _HostView {
+    var _kind: String { "styled" }
+    func _props(in environment: EnvironmentValues) -> _JSON { .object(["style": .object([:])]) }
+    var _content: [any View] { [content] }
+}
+extension _AnimationView: _AnimatedView {
+    var _animation: Animation? { animation }
+    var _value: Any { value }
+    func _changed(since previous: Any?) -> Bool {
+        guard let previous = previous as? Value else { return true }
+        return previous != value
+    }
+}
+
+nonisolated extension View {
+    /// Animates changes to this view whenever `value` changes.
+    public func animation<V: Equatable>(_ animation: Animation?, value: V) -> some View {
+        _AnimationView(content: self, animation: animation, value: value)
+    }
+
+    /// The transition to use when this view is inserted or removed with animation.
+    public func transition(_ transition: AnyTransition) -> some View {
+        _styled { $0.transition = transition }
+    }
+}
+
+// MARK: - Transaction
+
+/// The context of a state change. Accepted where SwiftUI takes one
+/// (`AsyncImage(url:transaction:content:)`); the renderer animates what
+/// `withAnimation` asked for, so the value itself is not consulted.
+public struct Transaction: Sendable {
+    public var animation: Animation?
+    public var disablesAnimations: Bool = false
+    public init(animation: Animation? = nil) { self.animation = animation }
+}

package/Sources/SwiftUI/API/App.swift

@@ -0,0 +1,87 @@
+/// A part of an app's user interface with a life cycle managed by the system.
+@MainActor @preconcurrency
+public protocol Scene {
+    associatedtype Body: Scene
+    @SceneBuilder var body: Self.Body { get }
+}
+
+extension Never: Scene {}
+
+/// Scenes the runtime can mount directly.
+protocol _RootScene {
+    @MainActor var _rootView: any View { get }
+}
+
+@resultBuilder
+public enum SceneBuilder {
+    public static func buildBlock<Content: Scene>(_ content: Content) -> Content { content }
+}
+
+/// A scene that presents a view hierarchy in a window (on the web, the screen).
+public struct WindowGroup<Content: View> {
+    let content: Content
+
+    public init(@ViewBuilder content: () -> Content) {
+        self.content = content()
+    }
+
+    public init(_ title: String, @ViewBuilder content: () -> Content) {
+        self.content = content()
+    }
+}
+
+extension WindowGroup: Scene {
+    public typealias Body = Never
+    public var body: Never { fatalError("WindowGroup is a primitive scene") }
+}
+
+extension WindowGroup: _RootScene {
+    var _rootView: any View { content }
+}
+
+/// A scene whose root view is wrapped in a view modifier: how another module
+/// adds a scene modifier (SwiftData's `.modelContainer`) that applies to the
+/// whole window's content.
+public struct _RootModifiedScene<Content: Scene, Modifier: ViewModifier> {
+    let content: Content
+    let modifier: Modifier
+}
+
+extension _RootModifiedScene: Scene {
+    public typealias Body = Never
+    public var body: Never { fatalError("_RootModifiedScene is a primitive scene") }
+}
+
+extension _RootModifiedScene: _RootScene {
+    var _rootView: any View {
+        guard let root = content as? any _RootScene else {
+            fatalError("\(Content.self) is not a scene the runtime can present. Use WindowGroup.")
+        }
+        func wrap<V: View>(_ view: V) -> any View { view.modifier(modifier) }
+        return wrap(root._rootView)
+    }
+}
+
+extension Scene {
+    /// Applies `modifier` to the scene's root view.
+    public func _modifyingRootView<M: ViewModifier>(_ modifier: M) -> _RootModifiedScene<Self, M> {
+        _RootModifiedScene(content: self, modifier: modifier)
+    }
+}
+
+/// The structure and behavior of an app. Mark the conforming type `@main`.
+@MainActor @preconcurrency
+public protocol App {
+    associatedtype Body: Scene
+    @SceneBuilder var body: Self.Body { get }
+    init()
+}
+
+extension App {
+    /// Entry point used by `@main`. Mounts the app's root view and, in the
+    /// browser, returns while the module stays alive to receive events.
+    public static func main() {
+        _installHostExecutor()
+        _Runtime.shared.launch(Self())
+    }
+}

package/Sources/SwiftUI/API/BindingCollections.swift

@@ -0,0 +1,35 @@
+// A binding to a mutable collection is a collection of bindings to its
+// elements, as in SwiftUI (iOS 15): `$items.isEmpty`, `$items.count` and
+// `$items[0]` read and write through the binding to the whole collection.
+
+extension Binding: Sequence where Value: MutableCollection {
+    public typealias Element = Binding<Value.Element>
+    public typealias Iterator = IndexingIterator<Binding<Value>>
+    public typealias SubSequence = Slice<Binding<Value>>
+}
+
+extension Binding: Collection where Value: MutableCollection {
+    public typealias Index = Value.Index
+    public typealias Indices = Value.Indices
+
+    public var startIndex: Value.Index { wrappedValue.startIndex }
+    public var endIndex: Value.Index { wrappedValue.endIndex }
+    public var indices: Value.Indices { wrappedValue.indices }
+
+    public func index(after i: Value.Index) -> Value.Index { wrappedValue.index(after: i) }
+
+    public func formIndex(after i: inout Value.Index) { wrappedValue.formIndex(after: &i) }
+
+    public subscript(position: Value.Index) -> Binding<Value.Element> {
+        let whole = self
+        return Binding<Value.Element>(get: { whole.wrappedValue[position] }, set: { whole.wrappedValue[position] = $0 })
+    }
+}
+
+extension Binding: BidirectionalCollection where Value: BidirectionalCollection, Value: MutableCollection {
+    public func index(before i: Value.Index) -> Value.Index { wrappedValue.index(before: i) }
+
+    public func formIndex(before i: inout Value.Index) { wrappedValue.formIndex(before: &i) }
+}
+
+extension Binding: RandomAccessCollection where Value: RandomAccessCollection, Value: MutableCollection {}

package/Sources/SwiftUI/API/BindingForEach.swift

@@ -0,0 +1,27 @@
+/// `ForEach($items) { $item in … }` (iOS 15): a row per element, each with a
+/// binding to its element (`Binding(projectedValue:)`, in State.swift, lets
+/// the closure take its parameter as `$item`). Plus the older
+/// `Picker(selection:label:content:)`.
+
+extension ForEach where Content: View {
+    /// A row per element of the bound collection, identified by its `id`.
+    public init<C: MutableCollection & RandomAccessCollection>(
+        _ data: Binding<C>, @ViewBuilder content: @escaping (Binding<C.Element>) -> Content
+    ) where Data == [Binding<C.Element>], C.Element: Identifiable, ID == C.Element.ID {
+        self.init(_data: data.map { $0 }, id: { $0.wrappedValue.id }, content: content)
+    }
+
+    /// A row per element of the bound collection, identified by `id`.
+    public init<C: MutableCollection & RandomAccessCollection>(
+        _ data: Binding<C>, id: KeyPath<C.Element, ID>, @ViewBuilder content: @escaping (Binding<C.Element>) -> Content
+    ) where Data == [Binding<C.Element>] {
+        self.init(_data: data.map { $0 }, id: { $0.wrappedValue[keyPath: id] }, content: content)
+    }
+}
+
+extension Picker {
+    /// The pre-iOS 16 form, with the label first.
+    public init(selection: Binding<SelectionValue>, label: Label, @ViewBuilder content: () -> Content) {
+        self.init(selection: selection, content: content, label: { label })
+    }
+}

package/Sources/SwiftUI/API/Bitmaps.swift

@@ -0,0 +1,254 @@
+import Foundation
+
+// `UIImage` and `CGImage`, as far as SwiftUI apps use them: made from an
+// image file's bytes, from Core Image (Sources/CoreImage), from an SF Symbol
+// or a catalog name, and shown with `Image(uiImage:)`. On iOS SwiftUI
+// re-exports UIKit's `UIImage` and Core Graphics' `CGImage`, so a file that
+// imports SwiftUI alone uses both; here they live in the shim for the same
+// reason. Neither holds pixels: each is a recipe the page draws
+// (Runtime/ImageSource.swift, docs/ops-protocol.md, "Bitmaps and Core Image").
+
+/// A bitmap: `width` × `height` pixels the page produces from a recipe.
+public final class CGImage: @unchecked Sendable {
+    public let width: Int
+    public let height: Int
+    /// The recipe, ending at this image's pixel grid (extent `(0, 0, width, height)`).
+    public let _recipe: _ImageRecipe
+
+    /// Made by Core Image (`CIContext.createCGImage`) from a rendered recipe.
+    public init(_recipe recipe: _ImageRecipe) {
+        _recipe = recipe
+        let extent = recipe.extent.isNull || recipe.extent.isInfinite ? CGRect.zero : recipe.extent
+        width = Int(extent.width)
+        height = Int(extent.height)
+    }
+
+    public var bitsPerComponent: Int { 8 }
+    public var bitsPerPixel: Int { 32 }
+    public var bytesPerRow: Int { width * 4 }
+
+    /// The part of the image inside `rect` (pixels, origin at the top left),
+    /// clipped to the image; nil when they do not overlap.
+    public func cropping(to rect: CGRect) -> CGImage? {
+        let bounds = CGRect(x: 0, y: 0, width: Double(width), height: Double(height))
+        let box = rect.integral.intersection(bounds)
+        guard !box.isNull, box.width >= 1, box.height >= 1 else { return nil }
+        // Core Image's origin is at the bottom left.
+        let flipped = CGRect(x: box.minX, y: Double(height) - box.maxY, width: box.width, height: box.height)
+        return _recipe.rendered(in: flipped).map(CGImage.init(_recipe:))
+    }
+}
+
+/// UIKit's image: a bitmap with a scale (pixels per point), or an SF Symbol
+/// or asset-catalog image the page draws by name.
+public final class UIImage: Hashable, @unchecked Sendable {
+    public enum Orientation: Int, Sendable {
+        case up, down, left, right, upMirrored, downMirrored, leftMirrored, rightMirrored
+    }
+
+    enum Content {
+        case bitmap(_ImageRecipe)
+        case system(String)
+        case named(String)
+    }
+
+    let content: Content
+    /// The size in points: pixels ÷ `scale`.
+    public let size: CGSize
+    public let scale: CGFloat
+    /// Always `.up` for decoded files: the page draws them with their EXIF
+    /// rotation applied, and their size already accounts for it.
+    public let imageOrientation: Orientation
+    /// The `CIImage` a Core Image-backed image was made from (`UIImage(ciImage:)`).
+    public let _ciImage: AnyObject?
+    /// UIKit's `renderingMode`: 0 automatic, 1 always original, 2 always template.
+    public private(set) var _renderingMode = 0
+
+    private init(content: Content, size: CGSize, scale: CGFloat, orientation: Orientation, ciImage: AnyObject?) {
+        self.content = content
+        self.size = size
+        self.scale = scale
+        imageOrientation = orientation
+        _ciImage = ciImage
+    }
+
+    /// The same image with another rendering mode (UIKit's `withRenderingMode`),
+    /// or another bitmap of the same size (`withTintColor`).
+    public func _copy(recipe: _ImageRecipe? = nil, renderingMode: Int) -> UIImage {
+        let copy = UIImage(content: recipe.map(Content.bitmap) ?? content, size: size, scale: scale, orientation: imageOrientation,
+                           ciImage: recipe == nil ? _ciImage : nil)
+        copy._renderingMode = renderingMode
+        return copy
+    }
+
+    /// Whether the image is an SF Symbol (drawn by the page by name).
+    public var _isSymbol: Bool {
+        if case .system = content { return true }
+        return false
+    }
+
+    /// An empty image, 0 × 0.
+    public init() {
+        content = .bitmap(.empty)
+        size = .zero
+        scale = 1
+        imageOrientation = .up
+        _ciImage = nil
+    }
+
+    /// The image in a PNG, JPEG, GIF, WebP, BMP, HEIC or AVIF file; nil when
+    /// the data is not one. Only the header is read here; the page decodes
+    /// the file when it draws it. (Chromium and Firefox draw no HEIC.)
+    public convenience init?(data: Data) {
+        self.init(data: data, scale: 1)
+    }
+
+    public init?(data: Data, scale: CGFloat) {
+        guard let source = _ImageSource(encoded: [UInt8](data)) else { return nil }
+        let factor = scale > 0 ? scale : 1
+        content = .bitmap(_ImageRecipe(source: source))
+        size = CGSize(width: Double(source.width) / factor, height: Double(source.height) / factor)
+        self.scale = factor
+        imageOrientation = .up
+        _ciImage = nil
+    }
+
+    public convenience init(cgImage: CGImage) {
+        self.init(cgImage: cgImage, scale: 1, orientation: .up)
+    }
+
+    /// `orientation` is recorded, not applied: the page draws the bitmap upright.
+    public init(cgImage: CGImage, scale: CGFloat, orientation: Orientation) {
+        let factor = scale > 0 ? scale : 1
+        content = .bitmap(cgImage._recipe)
+        size = CGSize(width: Double(cgImage.width) / factor, height: Double(cgImage.height) / factor)
+        self.scale = factor
+        imageOrientation = orientation
+        _ciImage = nil
+    }
+
+    /// A bitmap from a recipe whose extent is its pixel grid, `(0, 0, w, h)`
+    /// (Core Image's `UIImage(ciImage:)`).
+    public init(_recipe recipe: _ImageRecipe, scale: CGFloat, ciImage: AnyObject?) {
+        let factor = scale > 0 ? scale : 1
+        let extent = recipe.extent.isNull || recipe.extent.isInfinite ? CGRect.zero : recipe.extent
+        content = .bitmap(recipe)
+        size = CGSize(width: extent.width / factor, height: extent.height / factor)
+        self.scale = factor
+        imageOrientation = .up
+        _ciImage = ciImage
+    }
+
+    /// An SF Symbol. Never nil: the shim cannot tell which names exist, and
+    /// the page draws a placeholder for one it does not know. The size is
+    /// that of a symbol at the body text style.
+    public init?(systemName: String) {
+        content = .system(systemName)
+        size = CGSize(width: 20, height: 20)
+        scale = 1
+        imageOrientation = .up
+        _ciImage = nil
+    }
+
+    /// An asset-catalog image. Never nil, and its size is zero: the catalog
+    /// is the page's (docs/ops-protocol.md, "Phase 5"), so only the page knows it.
+    public init?(named name: String) {
+        content = .named(name)
+        size = .zero
+        scale = 1
+        imageOrientation = .up
+        _ciImage = nil
+    }
+
+    /// The bitmap, for an image made from data or a `CGImage`; nil for a
+    /// symbol, a catalog image, an empty image or one backed by a `CIImage`
+    /// (as on iOS).
+    public var cgImage: CGImage? {
+        guard _ciImage == nil, case .bitmap(let recipe) = content, recipe.source != nil else { return nil }
+        return CGImage(_recipe: recipe)
+    }
+
+    /// The recipe the page draws; nil for a symbol or a catalog image.
+    public var _recipe: _ImageRecipe? {
+        if case .bitmap(let recipe) = content { return recipe }
+        return nil
+    }
+
+    public static func == (lhs: UIImage, rhs: UIImage) -> Bool { lhs === rhs }
+    public func hash(into hasher: inout Hasher) { hasher.combine(ObjectIdentifier(self)) }
+}
+
+extension Image {
+    /// The way `Image(_:scale:orientation:label:)` takes a `CGImage`.
+    /// Recorded, not applied: the page draws the bitmap upright.
+    public enum Orientation: UInt8, CaseIterable, Hashable, Sendable {
+        case up, upMirrored, down, downMirrored, left, leftMirrored, right, rightMirrored
+    }
+
+    /// A `UIImage`: its bitmap (drawn by the page from its recipe), or the
+    /// symbol or catalog image it names. The intrinsic size is the image's
+    /// size in points.
+    public init(uiImage: UIImage) {
+        switch uiImage.content {
+        case .system(let name): self.init(source: .system(name), isResizable: false)
+        case .named(let name): self.init(source: .named(name), isResizable: false)
+        case .bitmap(let recipe):
+            self.init(source: .bitmap(recipe, width: uiImage.size.width, height: uiImage.size.height), isResizable: false)
+        }
+    }
+
+    public init(_ cgImage: CGImage, scale: CGFloat, orientation: Orientation = .up, label: Text) {
+        let factor = scale > 0 ? scale : 1
+        self.init(source: .bitmap(cgImage._recipe, width: Double(cgImage.width) / factor, height: Double(cgImage.height) / factor),
+                  isResizable: false)
+    }
+
+    public init(decorative cgImage: CGImage, scale: CGFloat, orientation: Orientation = .up) {
+        self.init(cgImage, scale: scale, orientation: orientation, label: Text(""))
+    }
+
+    /// Sends the bitmap's source to the page once (an `imagedata` op), before
+    /// the element that draws it.
+    @MainActor func _sendBitmapSource(through runtime: _Runtime) {
+        if case .bitmap(let recipe, _, _) = source, let source = recipe.source { runtime._sendImageSource(source) }
+    }
+}
+
+// Core Graphics' rectangle helpers that Core Image's extents need.
+extension CGRect {
+    /// A rectangle covering the whole plane (a `clampedToExtent()` image's extent).
+    public static let infinite = CGRect(x: -Double.greatestFiniteMagnitude / 2, y: -Double.greatestFiniteMagnitude / 2,
+                                        width: Double.greatestFiniteMagnitude, height: Double.greatestFiniteMagnitude)
+    /// No rectangle at all (the intersection of two that do not meet).
+    public static let null = CGRect(x: Double.infinity, y: Double.infinity, width: 0, height: 0)
+
+    public var isInfinite: Bool { size.width >= Double.greatestFiniteMagnitude || size.height >= Double.greatestFiniteMagnitude }
+    public var isNull: Bool { origin.x == .infinity || origin.y == .infinity }
+
+    /// The overlap of two rectangles; `.null` when they do not overlap.
+    public func intersection(_ other: CGRect) -> CGRect {
+        if isNull || other.isNull { return .null }
+        if isInfinite { return other }
+        if other.isInfinite { return self }
+        let x0 = max(minX, other.minX), y0 = max(minY, other.minY)
+        let x1 = min(maxX, other.maxX), y1 = min(maxY, other.maxY)
+        guard x1 > x0, y1 > y0 else { return .null }
+        return CGRect(x: x0, y: y0, width: x1 - x0, height: y1 - y0)
+    }
+
+    /// The smallest rectangle containing both.
+    public func union(_ other: CGRect) -> CGRect {
+        if isNull { return other }
+        if other.isNull { return self }
+        if isInfinite || other.isInfinite { return .infinite }
+        let x0 = min(minX, other.minX), y0 = min(minY, other.minY)
+        return CGRect(x: x0, y: y0, width: max(maxX, other.maxX) - x0, height: max(maxY, other.maxY) - y0)
+    }
+
+    /// The smallest rectangle with integer coordinates containing this one.
+    public var integral: CGRect {
+        if isNull || isInfinite { return self }
+        let x0 = minX.rounded(.down), y0 = minY.rounded(.down)
+        return CGRect(x: x0, y: y0, width: maxX.rounded(.up) - x0, height: maxY.rounded(.up) - y0)
+    }
+}