What's new in PaperKit

public struct ImageMarkup : Markup, Identifiable {

    /// Stable unique identity of the markup.
    public var id: MarkupID<ImageMarkup>

    /// Initializes and returns a new image markup from the specified parameters.
    /// - Parameters:
    ///   - image: The image content to display.
    ///   - frame: The frame of the image.
    ///   - rotation: The rotation in radians of the image. Defaults to `0.0` (no rotation).
    ///   - image: The image content to display.
    ///   - orientation: The orientation of the image content. Defaults to `.up` (no rotation).
    ///   - opacity: The opacity of the image, ranging from `0.0` (fully transparent) to `1.0` (fully opaque). Defaults to `1.0`.
    ///   - contentsBounds: The portion of the image to display, in normalized coordinates from `0.0` to `1.0`. Defaults to `CGRect(x: 0, y: 0, width: 1, height: 1)` (full image).
    ///   - accessibilityDescription: The accessibility description of the image for assistive technologies. Defaults to `nil`.
    ///   - allowedInteractions: The flags controlling the interactions users can perform. Defaults to `.all`.
    ///   - id: The identity of the image. Defaults to a unique id.
    ///
    /// Image content is shown scaled to fill.
    public init(image: CGImage, frame: CGRect, rotation: CGFloat = 0.0, orientation: CGImagePropertyOrientation = .up, opacity: CGFloat = 1.0, contentsBounds: CGRect = CGRect(x: 0, y: 0, width: 1, height: 1), accessibilityDescription: String? = nil, allowedInteractions: MarkupInteractions = .all, id: MarkupID<ImageMarkup> = MarkupID())

    /// Initializes and returns a new image markup from the specified parameters.
    /// - Parameters:
    ///   - image: The image content to display.
    ///   - frame: The frame of the image.
    ///   - rotation: The rotation in radians of the image. Defaults to `0.0` (no rotation).
    ///   - opacity: The opacity of the image, ranging from `0.0` (fully transparent) to `1.0` (fully opaque). Defaults to `1.0`.
    ///   - contentsBounds: The portion of the image to display, in normalized coordinates from `0.0` to `1.0`. Defaults to `CGRect(x: 0, y: 0, width: 1, height: 1)` (full image).
    ///   - accessibilityDescription: The accessibility description of the image for assistive technologies. Defaults to `nil`.
    ///   - allowedInteractions: The flags controlling the interactions users can perform. Defaults to `.all`.
    ///   - id: The identity of the image. Defaults to a unique id.
    ///
    /// Image content is shown scaled to fill.
    public init?(image: UIImage, frame: CGRect, rotation: CGFloat = 0.0, opacity: CGFloat = 1.0, contentsBounds: CGRect = CGRect(x: 0, y: 0, width: 1, height: 1), accessibilityDescription: String? = nil, allowedInteractions: MarkupInteractions = .all, id: MarkupID<ImageMarkup> = MarkupID())

    /// The element's unrotated frame.
    ///
    /// Together with `rotation` this defines the element's position in its parent. This won't
    /// necessarily contain all the contents of an element, rotation and styling may cause the
    /// element to extend beyond this frame. Use `renderFrame` for an unrotated frame that
    /// contains the entire element.
    public var frame: CGRect

    /// The unrotated frame that tightly fits the rendered contents of the element.
    ///
    /// This frame includes padding around `frame` to ensure it includes all the rendered
    /// aspects of the content. For example, this frame will include the strokes, and
    /// shadows of any contents.
    public var renderFrame: CGRect { get }

    /// The element's rotation around the center of its frame.
    ///
    /// Together with `frame` this defines the element's position in its parent.
    public var rotation: CGFloat

    /// The image content displayed by this markup.
    ///
    /// Image content is shown scaled to fill.
    ///
    /// This property is async because an in-memory `CGImage` is not always loaded from disk. The image property can
    /// be `nil` when streaming the data model and the image asset has not yet been received.
    public var image: CGImage? { get async }

    /// Replaces the contents of this image markup with an image file.
    ///
    /// - Parameter url: The URL of the image file to load and display.
    /// - Throws: An error if the image file cannot be loaded or is in an unsupported format.
    ///
    /// Image content is shown scaled to fill.
    public mutating func replaceImage(with url: URL) throws

    /// Replaces the contents of this image markup with a `CGImage`.
    ///
    /// - Parameter image: The new image to display.
    ///
    /// Image content is shown scaled to fill.
    public mutating func replaceImage(with image: CGImage)

    /// The opacity of the image.
    ///

Truncated.

public struct LinkMarkup : Markup, Identifiable {

    /// Stable unique identity of the markup.
    public var id: MarkupID<LinkMarkup>

    /// Initializes and returns a new link markup from the specified parameters.
    /// - Parameters:
    ///   - url: The URL that the link navigates to when activated.
    ///   - frame: The frame of the link.
    ///   - allowedInteractions: The flags controlling the interactions people can perform. Defaults to `.all`.
    ///   - id: The identity of the link. Defaults to a unique id.
    public init(url: URL, frame: CGRect, allowedInteractions: MarkupInteractions = .all, id: MarkupID<LinkMarkup> = MarkupID())

    /// The URL that the link navigates to when activated.
    public var url: URL

    /// The element identifier for use in a markup ordered set.
    public var elementID: MarkupOrderedSet.ElementID { get }

    /// The unrotated frame that tightly fits the rendered contents of the element.
    ///
    /// This frame includes padding around `frame` to ensure it includes all the rendered
    /// aspects of the content. For example, this frame will include the strokes, and
    /// shadows of any contents.
    public var renderFrame: CGRect { get }

    /// The set of features used by this markup.
    public var featureSet: FeatureSet { get }

    /// Removes all content not supported by the provided feature set.
    /// - Parameter featureSet: The feature set to limit this markup to.
    /// - Returns: True if this was successful and the feature set is now supported.
    ///
    /// If the returned value is `true` then `self.featureSet.isSubset(of: featureSet)` will be `true`.
    public mutating func removeContentUnsupported(by featureSet: FeatureSet) -> Bool

    /// The element's unrotated frame.
    ///
    /// Together with `rotation` this defines the element's position in its parent. This won't
    /// necessarily contain all the contents of an element, rotation and styling may cause the
    /// element to extend beyond this frame. Use `renderFrame` for an unrotated frame that
    /// contains the entire element.
    public var frame: CGRect

    /// The element's rotation around the center of its frame.
    ///
    /// Together with `frame` this defines the element's position in its parent.
    public var rotation: CGFloat

    /// Interactions that people can perform on this markup.
    ///
    /// Use this to configure how people can interact with the markup, such as
    /// preventing resizing, rotation, or deletion. The default is `.all`, which
    /// allows all interactions. Set to `.readOnly` to prevent all modifications.
    public var allowedInteractions: MarkupInteractions

    /// A type representing the stable identity of the entity associated with
    /// an instance.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias ID = MarkupID<LinkMarkup>
}

public struct LoupeMarkup : Markup, Identifiable {

    /// Stable unique identity of the markup.
    public var id: MarkupID<LoupeMarkup>

    /// Initializes and returns a new loupe markup from the specified parameters.
    /// - Parameters:
    ///   - frame: The frame of the shape.
    ///   - magnification: The magnification level used to zoom the content below the loupe. Defaults to `1.5`.
    ///   - strokeColor: The color of the loupe's border. Defaults to `nil` for no border.
    ///   - lineWidth: The width of the loupe's border in points. Defaults to `2.0`.
    ///   - allowedInteractions: The flags controlling the interactions people can perform. Defaults to `.all`.
    ///   - id: The identity of the loupe. Defaults to a unique id.
    public init(frame: CGRect, magnification: CGFloat = 1.5, strokeColor: CGColor? = nil, lineWidth: CGFloat = 2.0, allowedInteractions: MarkupInteractions = .all, id: MarkupID<LoupeMarkup> = MarkupID())

    /// The magnification level applied to the content displayed within the loupe.
    public var magnification: CGFloat

    /// The color of the loupe's border.
    ///
    /// Set this to `nil` for no border.
    public var strokeColor: CGColor?

    /// The width of the loupe's border in points.
    public var lineWidth: CGFloat

    /// The element identifier for use in a markup ordered set.
    public var elementID: MarkupOrderedSet.ElementID { get }

    /// The unrotated frame that tightly fits the rendered contents of the element.
    ///
    /// This frame includes padding around `frame` to ensure it includes all the rendered
    /// aspects of the content. For example, this frame will include the strokes, and
    /// shadows of any contents.
    public var renderFrame: CGRect { get }

    /// The set of features used by this markup.
    public var featureSet: FeatureSet { get }

    /// Removes all content not supported by the provided feature set.
    /// - Parameter featureSet: The feature set to limit this markup to.
    /// - Returns: True if this was successful and the feature set is now supported.
    ///
    /// If the returned value is `true` then `self.featureSet.isSubset(of: featureSet)` will be `true`.
    public mutating func removeContentUnsupported(by featureSet: FeatureSet) -> Bool

    /// The element's unrotated frame.
    ///
    /// Together with `rotation` this defines the element's position in its parent. This won't
    /// necessarily contain all the contents of an element, rotation and styling may cause the
    /// element to extend beyond this frame. Use `renderFrame` for an unrotated frame that
    /// contains the entire element.
    public var frame: CGRect

    /// The element's rotation around the center of its frame.
    ///
    /// Together with `frame` this defines the element's position in its parent.
    public var rotation: CGFloat

    /// Interactions that people can perform on this markup.
    ///
    /// Use this to configure how people can interact with the markup, such as
    /// preventing resizing, rotation, or deletion. The default is `.all`, which
    /// allows all interactions. Set to `.readOnly` to prevent all modifications.
    public var allowedInteractions: MarkupInteractions

    /// A type representing the stable identity of the entity associated with
    /// an instance.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias ID = MarkupID<LoupeMarkup>
}

public protocol Markup : Sendable {

    /// The element identifier for use in a markup ordered set.
    var elementID: MarkupOrderedSet.ElementID { get }

    /// The unrotated frame that tightly fits the rendered contents of the element.
    ///
    /// This frame includes padding around `frame` to ensure it includes all the rendered
    /// aspects of the content. For example, this frame will include the strokes, and
    /// shadows of any contents.
    var renderFrame: CGRect { get }

    /// Transforms this element with the specified transform.
    ///
    /// - Parameter transform: The transform applied to the element. Skew is ignored.
    mutating func applyTransform(_ transform: CGAffineTransform)

    /// The set of features used by this markup.
    var featureSet: FeatureSet { get }

    /// Removes all content not supported by the provided feature set.
    /// - Parameter featureSet: The feature set to limit this markup to.
    /// - Returns: True if this was successful and the feature set is now supported.
    ///
    /// If the returned value is `true` then `self.featureSet.isSubset(of: featureSet)` will be `true`.
    mutating func removeContentUnsupported(by featureSet: FeatureSet) -> Bool

    /// The element's unrotated frame.
    ///
    /// Together with `rotation` this defines the element's position in its parent. This won't
    /// necessarily contain all the contents of an element, rotation and styling may cause the
    /// element to extend beyond this frame. Use `renderFrame` for an unrotated frame that
    /// contains the entire element.
    var frame: CGRect { get set }

    /// The element's rotation around the center of its frame.
    ///
    /// Together with `frame` this defines the element's position in its parent.
    var rotation: CGFloat { get set }

    /// Interactions that people can perform on this markup.
    ///
    /// Use this to configure how people can interact with the markup, such as
    /// preventing resizing, rotation, or deletion. The default is `.all`, which
    /// allows all interactions. Set to `.readOnly` to prevent all modifications.
    var allowedInteractions: MarkupInteractions { get set }
}

public struct MarkupAdornment : Equatable, Hashable, Identifiable, Sendable {

    /// A unique identifier for this adornment.
    public var id: UUID

    /// The anchor that positions the adornment.
    public var anchor: MarkupAdornment.Anchor

    /// The image to display as the adornment.
    public var imageConfiguration: MarkupAdornment.ImageConfiguration

    /// The constraints that define where a person can drag this adornment.
    ///
    /// - `.fixed`: A person cannot move the adornment.
    /// - `.canvas`: A person can move the adornment freely within the canvas.
    public var dragRegion: MarkupAdornment.DragRegion

    /// A Boolean value that indicates whether the adornment scales with the zoom level or remains fixed in the base coordinate system.
    ///
    /// When this value is `true`, the adornment image adjusts to the zoom scale of the `PaperMarkupViewController`.
    /// When `false`, the adornment image remains fixed in the base coordinate
    /// system.
    public var scalesWithZoom: Bool

    /// Creates a new markup adornment with the specified configuration.
    ///
    /// - Parameters:
    ///   - id: A unique identifier for the adornment. Defaults to a new UUID.
    ///   - anchor: The positioning anchor that determines where the adornment appears.
    ///   - imageConfiguration: The visual configuration for the adornment image. Defaults to a pin icon.
    ///   - dragRegion: The movement constraints for the adornment. Defaults to draggable within the canvas.
    ///   - scalesWithZoom: A Boolean value that indicates whether the adornment scales with the zoom level. Defaults to `false`.
    public init(id: UUID = UUID(), anchor: MarkupAdornment.Anchor, imageConfiguration: MarkupAdornment.ImageConfiguration = .default, dragRegion: MarkupAdornment.DragRegion = .canvas, scalesWithZoom: Bool = false)

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: MarkupAdornment, b: MarkupAdornment) -> Bool

    /// A type representing the stable identity of the entity associated with
    /// an instance.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias ID = UUID

    /// Hashes the essential components of this value by feeding them into the
    /// given hasher.
    ///
    /// Implement this method to conform to the `Hashable` protocol. The
    /// components used for hashing must be the same as the components compared
    /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
    /// with each of these components.
    ///
    /// - Important: In your implementation of `hash(into:)`,
    ///   don't call `finalize()` on the `hasher` instance provided,
    ///   or replace it with a different instance.
    ///   Doing so may become a compile-time error in the future.
    ///
    /// - Parameter hasher: The hasher to use when combining the components
    ///   of this instance.
    public func hash(into hasher: inout Hasher)

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }
}

public struct MarkupAutoresizing : OptionSet, Sendable {

    /// The corresponding value of the raw type.
    ///
    /// A new instance initialized with `rawValue` will be equivalent to this
    /// instance. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     let selectedSize = PaperSize.Letter
    ///     print(selectedSize.rawValue)
    ///     // Prints "Letter"
    ///
    ///     print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
    ///     // Prints "true"
    public let rawValue: Int

    /// Creates a new option set from the given raw value.
    ///
    /// This initializer always succeeds, even if the value passed as `rawValue`
    /// exceeds the static properties declared as part of the option set. This
    /// example creates an instance of `ShippingOptions` with a raw value beyond
    /// the highest element, with a bit mask that effectively contains all the
    /// declared static members.
    ///
    ///     let extraOptions = ShippingOptions(rawValue: 255)
    ///     print(extraOptions.isStrictSuperset(of: .all))
    ///     // Prints "true"
    ///
    /// - Parameter rawValue: The raw value of the option set to create. Each bit
    ///   of `rawValue` potentially represents an element of the option set,
    ///   though raw values may include bits that are not defined as distinct
    ///   values of the `OptionSet` type.
    public init(rawValue: Int)

    /// Automatically adjust width to fit content changes.
    public static let flexibleWidth: MarkupAutoresizing

    /// Automatically adjust height to fit content changes.
    public static let flexibleHeight: MarkupAutoresizing

    /// The type of the elements of an array literal.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias ArrayLiteralElement = MarkupAutoresizing

    /// The element type of the option set.
    ///
    /// To inherit all the default implementations from the `OptionSet` protocol,
    /// the `Element` type must be `Self`, the default.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias Element = MarkupAutoresizing

    /// The raw type that can be used to represent all values of the conforming
    /// type.
    ///
    /// Every distinct value of the conforming type has a corresponding unique
    /// value of the `RawValue` type, but there may be values of the `RawValue`
    /// type that don't have a corresponding value of the conforming type.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias RawValue = Int
}

public struct MarkupID<Element> : Sendable, Hashable, RawRepresentable, Codable {

    /// Creates a new unique ID.
    public init() where Element : Markup

    /// Creates a new instance with the specified raw value.
    ///
    /// If there is no value of the type that corresponds with the specified raw
    /// value, this initializer returns `nil`. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     print(PaperSize(rawValue: "Legal"))
    ///     // Prints "Optional(PaperSize.Legal)"
    ///
    ///     print(PaperSize(rawValue: "Tabloid"))
    ///     // Prints "nil"
    ///
    /// - Parameter rawValue: The raw value to use for the new instance.
    public init?(rawValue: Data)

    /// The corresponding value of the raw type.
    ///
    /// A new instance initialized with `rawValue` will be equivalent to this
    /// instance. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     let selectedSize = PaperSize.Letter
    ///     print(selectedSize.rawValue)
    ///     // Prints "Letter"
    ///
    ///     print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
    ///     // Prints "true"
    public var rawValue: Data { get }

    /// The raw type that can be used to represent all values of the conforming
    /// type.
    ///
    /// Every distinct value of the conforming type has a corresponding unique
    /// value of the `RawValue` type, but there may be values of the `RawValue`
    /// type that don't have a corresponding value of the conforming type.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias RawValue = Data

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws
}

public struct MarkupInteractions : OptionSet, Sendable {

    /// The corresponding value of the raw type.
    ///
    /// A new instance initialized with `rawValue` will be equivalent to this
    /// instance. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     let selectedSize = PaperSize.Letter
    ///     print(selectedSize.rawValue)
    ///     // Prints "Letter"
    ///
    ///     print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
    ///     // Prints "true"
    public let rawValue: Int

    /// Creates a new option set from the given raw value.
    ///
    /// This initializer always succeeds, even if the value passed as `rawValue`
    /// exceeds the static properties declared as part of the option set. This
    /// example creates an instance of `ShippingOptions` with a raw value beyond
    /// the highest element, with a bit mask that effectively contains all the
    /// declared static members.
    ///
    ///     let extraOptions = ShippingOptions(rawValue: 255)
    ///     print(extraOptions.isStrictSuperset(of: .all))
    ///     // Prints "true"
    ///
    /// - Parameter rawValue: The raw value of the option set to create. Each bit
    ///   of `rawValue` potentially represents an element of the option set,
    ///   though raw values may include bits that are not defined as distinct
    ///   values of the `OptionSet` type.
    public init(rawValue: Int)

    /// Allows rotation.
    public static let rotate: MarkupInteractions

    /// Allows resizing.
    ///
    /// This only controls manual resizing through direct interaction (drag handles, gestures).
    /// Programmatic resizing via the `frame` property always works. For `ShapeMarkup` elements,
    /// automatic content-driven resizing from the `autoresizing` property still occurs independently
    /// of this setting.
    public static let resize: MarkupInteractions

    /// Allows deletion.
    public static let delete: MarkupInteractions

    /// Allows moving.
    public static let move: MarkupInteractions

    /// Allows style changes.
    public static let style: MarkupInteractions

    /// Allows selection.
    public static let select: MarkupInteractions

    /// All interactions enabled (default).
    public static let all: MarkupInteractions

    /// Read-only: no interactions enabled.
    public static let readOnly: MarkupInteractions

    /// The type of the elements of an array literal.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias ArrayLiteralElement = MarkupInteractions

    /// The element type of the option set.
    ///
    /// To inherit all the default implementations from the `OptionSet` protocol,
    /// the `Element` type must be `Self`, the default.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias Element = MarkupInteractions

    /// The raw type that can be used to represent all values of the conforming
    /// type.
    ///

Truncated.

public struct MarkupOrderedSet : Sendable {

    /// The type of element in the set.
    public typealias Element = any Markup

    /// Creates a new, empty collection.
    public init()

    /// Appends a new member to the end of the set, if the set doesn’t already contain it.
    /// - Parameter item: The element to add to the set.
    /// - Returns: A pair (`inserted`, `index`), where inserted is a Boolean value indicating whether the
    ///   operation added a new element, and `index` is the index of `item` in the resulting set.
    @discardableResult
    public mutating func append(_ item: MarkupOrderedSet.Element) -> (inserted: Bool, index: Int)

    /// Appends the contents of a sequence to the end of the set, excluding elements that are already members.
    /// - Parameter elements: A finite sequence of elements to append.
    public mutating func append(contentsOf elements: some Sequence<any Markup>)

    /// Inserts a new member at the specified index, if the set doesn’t already contain it.
    /// - Parameters:
    ///   - item: The element to insert.
    ///   - index: The index to insert at.
    /// - Returns: A pair (`inserted`, `index`), where `inserted` is a Boolean value indicating whether the
    ///   operation added a new element, and `index` is the index of item in the resulting set. If
    ///   `inserted` is false, then the returned `index` may be different from the index requested.
    @discardableResult
    public mutating func insert(_ item: MarkupOrderedSet.Element, at index: Int) -> (inserted: Bool, index: Int)

    /// Returns a Boolean value that indicates whether the given element exists in the set.
    /// - Parameter element: An element to look for in the set.
    /// - Returns: `true` if member exists in the set; otherwise, `false`.
    public func contains(_ element: MarkupOrderedSet.Element) -> Bool

    /// Returns the index of the given element in the set, or `nil` if the element is not a member
    /// of the set.
    ///
    /// `MarkupOrderedSet` members are always unique, so the first index of an element is always the
    /// same as its last index.
    public func firstIndex(of element: MarkupOrderedSet.Element) -> Int?

    /// Removes the given element from the set.
    /// - Parameter member: The element of the set to remove.
    /// - Returns: The element equal to `member` if `member` is contained in the set; otherwise, `nil`.
    @discardableResult
    public mutating func remove(_ member: MarkupOrderedSet.Element) -> MarkupOrderedSet.Element?

    /// Adds the given element to the set unconditionally, either appending it to the set, or replacing
    /// an existing value if one with the same id is present.
    /// - Parameter item: The value to append or replace.
    /// - Returns: The element this operation replaced, or `nil` if the operation appended the value to the end of the collection.
    @discardableResult
    public mutating func updateOrAppend(_ item: MarkupOrderedSet.Element) -> MarkupOrderedSet.Element?

    /// Removes the associated element for the given id from the set.
    /// - Parameter id: The id of the element to remove.
    /// - Returns: The associated element for `id` if the set contains `id`; otherwise, `nil`.
    @discardableResult
    public mutating func removeElement(for id: MarkupOrderedSet.ElementID) -> MarkupOrderedSet.Element?

    /// Removes the associated element for the given id from the set.
    /// - Parameter id: The id of the element to remove.
    /// - Returns: The associated element for `id` if the set contains `id`; otherwise, `nil`.
    @discardableResult
    public mutating func removeElement<T>(for id: MarkupID<T>) -> T? where T : Markup

    /// Removes the associated stroke for the given id from the set.
    /// - Parameter id: The id of the stroke to remove.
    /// - Returns: The associated stroke for `id` if the set contains `id`; otherwise, `nil`.
    @discardableResult
    public mutating func removeStroke(for id: UUID) -> PKStroke?

    /// Accesses the element for the given id.
    public subscript(id: MarkupOrderedSet.ElementID) -> MarkupOrderedSet.Element?

    /// Accesses the element for the given id.
    public subscript<T>(id: MarkupID<T>) -> T? where T : Markup

    /// Accesses the stroke for the given id.
    public subscript(id: UUID) -> PKStroke?

Truncated.

extension MarkupOrderedSet {

    /// A view of a set’s ids.
    public struct ElementIDs : RandomAccessCollection {

        /// A type representing the sequence's elements.
        public typealias Element = MarkupOrderedSet.ElementID

        /// A type that represents a position in the collection.
        ///
        /// Valid indices consist of the position of every element and a
        /// "past the end" position that's not valid for use as a subscript
        /// argument.
        public typealias Index = Int

        /// The index of the first element ID.
        public var startIndex: MarkupOrderedSet.ElementIDs.Index { get }

        /// The index past the last element ID.
        public var endIndex: MarkupOrderedSet.ElementIDs.Index { get }

        /// Returns the index after the given index.
        public func index(after i: MarkupOrderedSet.ElementIDs.Index) -> MarkupOrderedSet.ElementIDs.Index

        /// Accesses the element ID at the specified position.
        public subscript(position: MarkupOrderedSet.ElementIDs.Index) -> MarkupOrderedSet.ElementIDs.Element { get }

        /// A type that represents the indices that are valid for subscripting the
        /// collection, in ascending order.
        @available(macOS 27.0, iOS 27.0, *)
        public typealias Indices = Range<MarkupOrderedSet.ElementIDs.Index>

        /// A type that provides the collection's iteration interface and
        /// encapsulates its iteration state.
        ///
        /// By default, a collection conforms to the `Sequence` protocol by
        /// supplying `IndexingIterator` as its associated `Iterator`
        /// type.
        @available(macOS 27.0, iOS 27.0, *)
        public typealias Iterator = IndexingIterator<MarkupOrderedSet.ElementIDs>

        /// A collection representing a contiguous subrange of this collection's
        /// elements. The subsequence shares indices with the original collection.
        ///
        /// The default subsequence type for collections that don't define their own
        /// is `Slice`.
        @available(macOS 27.0, iOS 27.0, *)
        public typealias SubSequence = Slice<MarkupOrderedSet.ElementIDs>
    }

    /// A view of the set's element ids.
    public var ids: MarkupOrderedSet.ElementIDs { get }

    /// The strokes in the set.
    public var strokes: [PKStroke] { get }
}

extension MarkupOrderedSet : BidirectionalCollection, RandomAccessCollection {

    /// An iterator over the elements of a markup ordered set.
    public struct Iterator : IteratorProtocol {

        /// Advances to the next element and returns it, or `nil` if no next element exists.
        public mutating func next() -> (any Markup)?

        /// The type of element traversed by the iterator.
        @available(macOS 27.0, iOS 27.0, *)
        public typealias Element = any Markup
    }

    /// Returns an iterator over the elements of the set.
    public func makeIterator() -> MarkupOrderedSet.Iterator

    /// A type that represents the indices that are valid for subscripting the
    /// collection, in ascending order.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias Indices = Range<MarkupOrderedSet.Index>

    /// A collection representing a contiguous subrange of this collection's
    /// elements. The subsequence shares indices with the original collection.
    ///
    /// The default subsequence type for collections that don't define their own
    /// is `Slice`.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias SubSequence = Slice<MarkupOrderedSet>
}

extension PaperMarkup : Identifiable {

    /// The unique identifier of the markup.
    public var id: MarkupID<PaperMarkup>

    /// The background color of the paper.
    ///
    /// Default is `nil`, which uses a default color based on the current user interface style.
    public var backgroundColor: CGColor?

    /// The subelements of the paper markup.
    ///
    /// Includes shapes, images, strokes, etc.
    public var subelements: MarkupOrderedSet

    /// A type representing the stable identity of the entity associated with
    /// an instance.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias ID = MarkupID<PaperMarkup>
}

extension PaperMarkupViewController.Delegate {

    /// Tells the delegate when a person taps an adornment.
    ///
    /// - Parameters:
    ///   - paperMarkupViewController: The `PaperMarkupViewController` containing the adornment.
    ///   - adornmentID: The ID of the adornment the person tapped.
    public func paperMarkupViewController(_ paperMarkupViewController: PaperMarkupViewController, didTapAdornmentWithID adornmentID: UUID)

    /// Asks the delegate to validate and potentially adjust an adornment's proposed anchor position.
    ///
    /// - Parameters:
    ///   - paperMarkupViewController: The `PaperMarkupViewController` containing the adornment.
    ///   - adornmentID: The unique identifier of the adornment being moved.
    ///   - proposedAnchor: The proposed new anchor position for the adornment.
    /// - Returns: The final anchor position to use for the adornment, or `nil` to deny the move.
    public func paperMarkupViewController(_ paperMarkupViewController: PaperMarkupViewController, willUpdateAdornmentWithID adornmentID: UUID, toProposedAnchor proposedAnchor: MarkupAdornment.Anchor) -> MarkupAdornment.Anchor?

    /// Tells the delegate when a drag session ends for an adornment.
    ///
    /// - Parameters:
    ///   - paperMarkupViewController: The `PaperMarkupViewController` containing the adornment.
    ///   - adornmentID: The ID of the adornment that moved.
    ///   - anchor: The updated anchor for the adornment.
    public func paperMarkupViewController(_ paperMarkupViewController: PaperMarkupViewController, didUpdateAdornmentWithID adornmentID: UUID, toAnchor anchor: MarkupAdornment.Anchor)
}

extension PaperMarkupViewController.ScrollConfiguration : nonisolated Observable {
}

extension PaperMarkupViewController.ScrollConfiguration {

    /// The axes you use to specify scroll view behavior.
    ///
    /// This struct mirrors UIKit's `UIAxis` type for cross-platform compatibility.
    public struct Axis : OptionSet {

        /// The raw bitmask that represents this set of axes.
        public let rawValue: Int

        /// Creates a new set of axes from the given raw value.
        /// - Parameter rawValue: The raw bitmask to use for the option set.
        public init(rawValue: Int)

        /// The horizontal axis.
        public static let horizontal: PaperMarkupViewController.ScrollConfiguration.Axis

        /// The vertical axis.
        public static let vertical: PaperMarkupViewController.ScrollConfiguration.Axis

        /// The combined horizontal and vertical axes.
        public static let both: PaperMarkupViewController.ScrollConfiguration.Axis

        /// The type of the elements of an array literal.
        @available(macOS 27.0, iOS 27.0, *)
        public typealias ArrayLiteralElement = PaperMarkupViewController.ScrollConfiguration.Axis

        /// The element type of the option set.
        ///
        /// To inherit all the default implementations from the `OptionSet` protocol,
        /// the `Element` type must be `Self`, the default.
        @available(macOS 27.0, iOS 27.0, *)
        public typealias Element = PaperMarkupViewController.ScrollConfiguration.Axis

        /// The raw type that can be used to represent all values of the conforming
        /// type.
        ///
        /// Every distinct value of the conforming type has a corresponding unique
        /// value of the `RawValue` type, but there may be values of the `RawValue`
        /// type that don't have a corresponding value of the conforming type.
        @available(macOS 27.0, iOS 27.0, *)
        public typealias RawValue = Int
    }
}

extension PKStroke : Markup {

    /// The element identifier for use in a markup ordered set.
    public var elementID: MarkupOrderedSet.ElementID { get }

    /// The unrotated frame that tightly fits the rendered contents of the element.
    ///
    /// This frame includes padding around `frame` to ensure it includes all the rendered
    /// aspects of the content. For example, this frame will include the strokes, and
    /// shadows of any contents.
    public var renderFrame: CGRect { get }

    /// The set of features used by this markup.
    public var featureSet: FeatureSet { get }

    /// Removes all content not supported by the provided feature set.
    /// - Parameter featureSet: The feature set to limit this markup to.
    /// - Returns: True if this was successful and the feature set is now supported.
    ///
    /// If the returned value is `true` then `self.featureSet.isSubset(of: featureSet)` will be `true`.
    public mutating func removeContentUnsupported(by featureSet: FeatureSet) -> Bool

    /// The element's unrotated frame.
    ///
    /// Together with `rotation` this defines the element's position in its parent. This won't
    /// necessarily contain all the contents of an element, rotation and styling may cause the
    /// element to extend beyond this frame. Use `renderFrame` for an unrotated frame that
    /// contains the entire element.
    public var frame: CGRect

    /// The element's rotation around the center of its frame.
    ///
    /// Together with `frame` this defines the element's position in its parent.
    public var rotation: CGFloat

    /// Transforms this element with the specified transform.
    ///
    /// - Parameter transform: The transform applied to the element. Skew is ignored.
    public mutating func applyTransform(_ transform: CGAffineTransform)

    /// Interactions that people can perform on this markup.
    ///
    /// Use this to configure how people can interact with the markup, such as
    /// preventing resizing, rotation, or deletion. The default is `.all`, which
    /// allows all interactions. Set to `.readOnly` to prevent all modifications.
    public var allowedInteractions: MarkupInteractions
}

public struct ShapeMarkup : Markup, Identifiable {

    /// Stable unique identity of the markup.
    public var id: MarkupID<ShapeMarkup>

    /// Initializes and returns a new shape markup from the specified parameters.
    /// - Parameters:
    ///   - configuration: The configuration of the shape.
    ///   - frame: The frame of the shape.
    ///   - rotation: The rotation in radians of the shape. Defaults to `0.0` (no rotation).
    public init(configuration: ShapeConfiguration, frame: CGRect, rotation: CGFloat = 0.0)

    /// Initializes and returns a new shape markup from the specified parameters.
    /// - Parameters:
    ///   - shape: The shape to create.
    ///   - frame: The frame of the shape.
    ///   - rotation: The rotation in radians of the shape. Defaults to `0.0` (no rotation).
    ///   - fillColor: The fill color of the shape. Defaults to `nil` (no fill).
    ///   - strokeColor: The stroke color of the shape's outline. Defaults to `nil` (no stroke).
    ///   - lineWidth: The width of the shape's stroke. Defaults to `1.0`.
    ///   - opacity: The opacity of the shape, ranging from `0.0` (fully transparent) to `1.0` (fully opaque). Defaults to `1.0`.
    ///   - startLineMarker: The marker style for the start of the line. Defaults to `.none`. Only applicable for open shape paths.
    ///   - endLineMarker: The marker style for the end of the line. Defaults to `.none`. Only applicable for open shape paths.
    ///   - attributedText: The attributed text displayed inside this shape. Defaults to the empty string.
    ///   - allowedInteractions: The flags controlling the interactions users can perform. Defaults to `.all`.
    ///   - autoresizing: The flags controlling autoresize behavior. Defaults to `[]`.
    ///   - id: The identity of the shape. Defaults to a unique id.
    public init(shape: ShapeMarkup.Shape, frame: CGRect, rotation: CGFloat = 0.0, fillColor: CGColor? = nil, strokeColor: CGColor? = nil, lineWidth: CGFloat = 1.0, opacity: CGFloat = 1.0, startLineMarker: ShapeMarkup.LineMarker = .none, endLineMarker: ShapeMarkup.LineMarker = .none, attributedText: AttributedString = Foundation.AttributedString(), allowedInteractions: MarkupInteractions = .all, autoresizing: MarkupAutoresizing = [], id: MarkupID<ShapeMarkup> = MarkupID())

    /// The element's unrotated frame.
    ///
    /// Together with `rotation` this defines the element's position in its parent. This won't
    /// necessarily contain all the contents of an element, rotation and styling may cause the
    /// element to extend beyond this frame. Use `renderFrame` for an unrotated frame that
    /// contains the entire element.
    public var frame: CGRect

    /// The unrotated frame that tightly fits the rendered contents of the element.
    ///
    /// This frame includes padding around `frame` to ensure it includes all the rendered
    /// aspects of the content. For example, this frame will include the strokes, and
    /// shadows of any contents.
    public var renderFrame: CGRect { get }

    /// The element's rotation around the center of its frame.
    ///
    /// Together with `frame` this defines the element's position in its parent.
    public var rotation: CGFloat

    /// The color used to fill the shape’s path.
    public var fillColor: CGColor?

    /// The color used to stroke the shape’s path.
    public var strokeColor: CGColor?

    /// The line width of the shape’s path.
    public var lineWidth: CGFloat

    /// The opacity of the shape.
    ///
    /// Ranges from `0.0` (fully transparent) to `1.0` (fully opaque). Defaults to `1.0`.
    public var opacity: CGFloat

    /// The type of the shape.
    ///
    /// The coordinate values of the shape type are relative to the unit coordinate space. For example a
    /// corner radius of `0.1` is equivalent to a radius of 10% of the minimum dimension of the shape.
    ///
    /// Use `shapeScaled` for a shape type with scaled values relative to the shape's `frame`.
    public var shape: ShapeMarkup.Shape

    /// The type of the shape with values scaled to the current frame.
    ///
    /// Coordinate values are specified in points relative to the shape's `frame`. When you resize
    /// the shape, this property's values automatically update to reflect the new dimensions.
    ///
    /// Use `shape` if you need consistent relative proportions that don't change when resizing.
    ///
    /// ```swift
    /// var shape = ShapeMarkup(

Truncated.

extension ShapeMarkup {

    @available(iOS 27.0, macOS 27.0, *)
    public enum Shape : Sendable, Hashable {

        /// A rectangle.
        case rectangle(ShapeMarkup.Shape.Rectangle)

        /// An ellipse.
        case ellipse(ShapeMarkup.Shape.Ellipse)

        /// A quadratic Bézier curve line.
        case line(ShapeMarkup.Shape.Line)

        /// A speech bubble with a tail pointing to a specific location.
        case chatBubble(ShapeMarkup.Shape.ChatBubble)

        /// A regular polygon with equal sides and angles.
        case regularPolygon(ShapeMarkup.Shape.RegularPolygon)

        /// A star shape with alternating inner and outer points.
        case star(ShapeMarkup.Shape.Star)

        /// An arrow shape pointing in a specific direction.
        case arrowShape(ShapeMarkup.Shape.ArrowShape)

        /// The category of shape.
        public var configurationType: ShapeConfiguration.Shape { get }

        /// Creates a default shape for a category of shape.
        public init(configurationType: ShapeConfiguration.Shape)

        /// A rectangle with square corners.
        public static var rectangle: ShapeMarkup.Shape { get }

        /// A rectangle with rounded corners.
        /// - Parameter cornerRadius: The corner radius in unit coordinate space (0.0 to 1.0).
        ///   A value of `0.1` represents 10% of the minimum dimension of the shape.
        public static func roundedRectangle(cornerRadius: CGFloat) -> ShapeMarkup.Shape

        /// An ellipse that fills the shape's bounds.
        public static var ellipse: ShapeMarkup.Shape { get }

        /// A quadratic Bézier curve line.
        /// - Parameters:
        ///   - start: The starting point in unit coordinate space.
        ///   - control: The control point that defines the curve in unit coordinate space.
        ///     Defaults to `nil` which creates a straight line without a middle control point.
        ///   - end: The ending point in unit coordinate space.
        public static func line(start: CGPoint, control: CGPoint? = nil, end: CGPoint) -> ShapeMarkup.Shape

        /// A speech bubble with a tail pointing to a specific location.
        /// - Parameters:
        ///   - tailLocation: The position of the tail tip in unit coordinate space.
        ///   - tailAngle: The angle of the tail in radians.
        public static func chatBubble(tailLocation: CGPoint, tailAngle: CGFloat) -> ShapeMarkup.Shape

        /// A regular polygon with equal sides and angles.
        /// - Parameter sides: The number of sides.
        public static func regularPolygon(sides: Int) -> ShapeMarkup.Shape

        /// A default 5-pointed star shape.
        public static var star: ShapeMarkup.Shape { get }

        /// A star shape with alternating inner and outer points.
        /// - Parameters:
        ///   - points: The number of points on the star.
        ///   - innerRadius: The radius of inner points relative to outer points, in unit coordinate space (0.0 to 1.0).
        ///     A value of `0.5` creates inner points halfway to the center.
        public static func star(points: Int, innerRadius: CGFloat) -> ShapeMarkup.Shape

        /// An arrow shape pointing in a specific direction.
        /// - Parameter cornerPoint: The location of the arrow's corner (where the two sides meet) in unit coordinate space.
        public static func arrowShape(cornerPoint: CGPoint) -> ShapeMarkup.Shape

        /// The path of the shape.
        public var path: CGPath { get }

        /// True if this shape supports the addition of line markers.
        public var supportsLineMarkers: Bool { get }

Truncated.

extension ShapeMarkup.LineMarker : Equatable {
}

extension ShapeMarkup.LineMarker : Hashable {
}

public enum ElementID : Sendable, Hashable, RawRepresentable, Codable {

    /// A shape markup element ID.
    case shape(MarkupID<ShapeMarkup>)

    /// An image markup element ID.
    case image(MarkupID<ImageMarkup>)

    /// A link markup element ID.
    case link(MarkupID<LinkMarkup>)

    /// A loupe markup element ID.
    case loupe(MarkupID<LoupeMarkup>)

    /// A stroke element ID.
    case stroke(UUID)

    /// Creates a new element ID from a markup ID.
    ///
    /// Supports all PaperKit types, will `fatalError` if used for an unsupported type.
    public init<T>(_ id: MarkupID<T>) where T : Markup

    /// Creates a new element ID from a stroke UUID.
    public init(_ id: UUID)

    /// Creates a new instance with the specified raw value.
    ///
    /// If there is no value of the type that corresponds with the specified raw
    /// value, this initializer returns `nil`. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     print(PaperSize(rawValue: "Legal"))
    ///     // Prints "Optional(PaperSize.Legal)"
    ///
    ///     print(PaperSize(rawValue: "Tabloid"))
    ///     // Prints "nil"
    ///
    /// - Parameter rawValue: The raw value to use for the new instance.
    public init?(rawValue: Data)

    /// The corresponding value of the raw type.
    ///
    /// A new instance initialized with `rawValue` will be equivalent to this
    /// instance. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     let selectedSize = PaperSize.Letter
    ///     print(selectedSize.rawValue)
    ///     // Prints "Letter"
    ///
    ///     print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
    ///     // Prints "true"
    public var rawValue: Data { get }

    /// The raw type that can be used to represent all values of the conforming
    /// type.
    ///
    /// Every distinct value of the conforming type has a corresponding unique
    /// value of the `RawValue` type, but there may be values of the `RawValue`
    /// type that don't have a corresponding value of the conforming type.
    @available(macOS 27.0, iOS 27.0, *)
    public typealias RawValue = Data

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

Truncated.

public enum Shape : Sendable, Hashable {

    /// A rectangle.
    case rectangle(ShapeMarkup.Shape.Rectangle)

    /// An ellipse.
    case ellipse(ShapeMarkup.Shape.Ellipse)

    /// A quadratic Bézier curve line.
    case line(ShapeMarkup.Shape.Line)

    /// A speech bubble with a tail pointing to a specific location.
    case chatBubble(ShapeMarkup.Shape.ChatBubble)

    /// A regular polygon with equal sides and angles.
    case regularPolygon(ShapeMarkup.Shape.RegularPolygon)

    /// A star shape with alternating inner and outer points.
    case star(ShapeMarkup.Shape.Star)

    /// An arrow shape pointing in a specific direction.
    case arrowShape(ShapeMarkup.Shape.ArrowShape)

    /// The category of shape.
    public var configurationType: ShapeConfiguration.Shape { get }

    /// Creates a default shape for a category of shape.
    public init(configurationType: ShapeConfiguration.Shape)

    /// A rectangle with square corners.
    public static var rectangle: ShapeMarkup.Shape { get }

    /// A rectangle with rounded corners.
    /// - Parameter cornerRadius: The corner radius in unit coordinate space (0.0 to 1.0).
    ///   A value of `0.1` represents 10% of the minimum dimension of the shape.
    public static func roundedRectangle(cornerRadius: CGFloat) -> ShapeMarkup.Shape

    /// An ellipse that fills the shape's bounds.
    public static var ellipse: ShapeMarkup.Shape { get }

    /// A quadratic Bézier curve line.
    /// - Parameters:
    ///   - start: The starting point in unit coordinate space.
    ///   - control: The control point that defines the curve in unit coordinate space.
    ///     Defaults to `nil` which creates a straight line without a middle control point.
    ///   - end: The ending point in unit coordinate space.
    public static func line(start: CGPoint, control: CGPoint? = nil, end: CGPoint) -> ShapeMarkup.Shape

    /// A speech bubble with a tail pointing to a specific location.
    /// - Parameters:
    ///   - tailLocation: The position of the tail tip in unit coordinate space.
    ///   - tailAngle: The angle of the tail in radians.
    public static func chatBubble(tailLocation: CGPoint, tailAngle: CGFloat) -> ShapeMarkup.Shape

    /// A regular polygon with equal sides and angles.
    /// - Parameter sides: The number of sides.
    public static func regularPolygon(sides: Int) -> ShapeMarkup.Shape

    /// A default 5-pointed star shape.
    public static var star: ShapeMarkup.Shape { get }

    /// A star shape with alternating inner and outer points.
    /// - Parameters:
    ///   - points: The number of points on the star.
    ///   - innerRadius: The radius of inner points relative to outer points, in unit coordinate space (0.0 to 1.0).
    ///     A value of `0.5` creates inner points halfway to the center.
    public static func star(points: Int, innerRadius: CGFloat) -> ShapeMarkup.Shape

    /// An arrow shape pointing in a specific direction.
    /// - Parameter cornerPoint: The location of the arrow's corner (where the two sides meet) in unit coordinate space.
    public static func arrowShape(cornerPoint: CGPoint) -> ShapeMarkup.Shape

    /// The path of the shape.
    public var path: CGPath { get }

    /// True if this shape supports the addition of line markers.
    public var supportsLineMarkers: Bool { get }

    public struct Ellipse : Sendable, Hashable {

Truncated.