paperkit

dpearson2699/swift-ios-skillsDeveloper ToolsAudit passedSnapshot 63e466d24391

Installs: 0

Summary

Add drawings, shapes, and a consistent markup experience using PaperKit. Use when integrating PaperMarkupViewController for markup editing, adding shape recognition, working with PaperMarkup data models, embedding markup tools in document editors, or building annotation features that need the system-standard markup toolbar. New in iOS 26.

SKILL.md

PaperKit

Beta-sensitive. PaperKit is new in iOS/iPadOS 26, macOS 26, and visionOS 26. API surface may change. Verify details against current Apple documentation before shipping.

PaperKit combines PencilKit drawing with structured markup elements such as shapes, text, images, and lines in a canvas managed by PaperMarkupViewController.

Setup
Workflow
PaperMarkupViewController
PaperMarkup Data Model
Insertion Controllers
FeatureSet Configuration
Integration with PencilKit
SwiftUI Integration
Common Mistakes
Review Checklist
References

Workflow

Choose the document bounds, supported FeatureSet, and persistence version before constructing UI.
Create PaperMarkup, embed PaperMarkupViewController, and keep the controller, tool picker, and insertion controller alive for the view lifetime.
Use the platform-appropriate insertion surface and keep PencilKit drawing inside the PaperKit document boundary.
Save off the main thread, retain a thumbnail for forward-incompatible content, and test round-trip loading with the same feature set.
On failure, restore the original document bytes, fix the feature-set/version/controller mismatch, and rerun edit, save, relaunch, load, thumbnail fallback, and undo checks.

import PaperKit

Component	Role
`PaperMarkupViewController`	Interactive canvas for creating and displaying markup and drawing
`PaperMarkup`	Data model for serializing all markup elements and PencilKit drawing
`MarkupEditViewController` / `MarkupToolbarViewController`	Insertion UI for adding markup elements

import PaperKit
import PencilKit
import UIKit

class MarkupViewController: UIViewController, PaperMarkupViewController.Delegate {
    var paperVC: PaperMarkupViewController!
    var toolPicker: PKToolPicker!

    override func viewDidLoad() {
        super.viewDidLoad()

        let pageBounds = CGRect(origin: .zero, size: CGSize(width: 612, height: 792))
        let markup = PaperMarkup(bounds: pageBounds)
        let features = FeatureSet.latest

        paperVC = PaperMarkupViewController(
            markup: markup,
            supportedFeatureSet: features
        )
        paperVC.delegate = self

        addChild(paperVC)
        paperVC.view.frame = view.bounds
        paperVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(paperVC.view)
        paperVC.didMove(toParent: self)

        toolPicker = PKToolPicker()
        toolPicker.addObserver(paperVC)
        paperVC.pencilKitResponderState.activeToolPicker = toolPicker
        paperVC.pencilKitResponderState.toolPickerVisibility = .visible
    }

    func paperMarkupViewControllerDidChangeMarkup(
        _ controller: PaperMarkupViewController
    ) {
        guard let markup = controller.markup else { return }
        Task { try await save(markup) }
    }
}

Property	Type	Description
`markup`	`PaperMarkup?`	The current data model
`selectedMarkup`	`PaperMarkup`	Currently selected content
`isEditable`	`Bool`	Whether the canvas accepts input
`isRulerActive`	`Bool`	Whether the ruler overlay is shown
`drawingTool`	`any PKTool`	Active PencilKit drawing tool
`contentView`	`UIView?` / `NSView?`	Background view rendered beneath markup
`zoomRange`	`ClosedRange<CGFloat>`	Min/max zoom scale
`supportedFeatureSet`	`FeatureSet`	Enabled PaperKit features

paperVC.directTouchMode = .drawing    // Finger draws
paperVC.directTouchMode = .selection  // Finger selects elements
paperVC.directTouchAutomaticallyDraws = true  // System decides based on Pencil state

let pageBounds = CGRect(origin: .zero, size: pageImage.size)
let imageView = UIImageView(image: pageImage)
imageView.frame = pageBounds

let markup = PaperMarkup(bounds: pageBounds)
paperVC = PaperMarkupViewController(markup: markup, supportedFeatureSet: features)
paperVC.contentView = imageView

Method	Called when
`paperMarkupViewControllerDidChangeMarkup(_:)`	Markup content changes
`paperMarkupViewControllerDidBeginDrawing(_:)`	User starts drawing
`paperMarkupViewControllerDidChangeSelection(_:)`	Selection changes
`paperMarkupViewControllerDidChangeContentVisibleFrame(_:)`	Visible frame changes

// New empty model. Bounds define the saved document coordinate space.
let markup = PaperMarkup(bounds: CGRect(x: 0, y: 0, width: 612, height: 792))

// Load from saved data
let markup = try PaperMarkup(dataRepresentation: savedData)

// Save — dataRepresentation() is async throws
func save(_ markup: PaperMarkup) async throws {
    let data = try await markup.dataRepresentation()
    try data.write(to: fileURL)
}

// Text box
markup.insertNewTextbox(
    attributedText: AttributedString("Annotation"),
    frame: CGRect(x: 50, y: 100, width: 200, height: 40),
    rotation: 0
)

// Image
markup.insertNewImage(cgImage, frame: CGRect(x: 50, y: 200, width: 300, height: 200), rotation: 0)

// Shape
let shapeConfig = ShapeConfiguration(
    type: .rectangle,
    fillColor: UIColor.systemBlue.withAlphaComponent(0.2).cgColor,
    strokeColor: UIColor.systemBlue.cgColor,
    lineWidth: 2
)
markup.insertNewShape(configuration: shapeConfig, frame: CGRect(x: 50, y: 420, width: 200, height: 100), rotation: 0)

// Line with arrow end marker
let lineConfig = ShapeConfiguration(type: .line, fillColor: nil, strokeColor: UIColor.red.cgColor, lineWidth: 3)
markup.insertNewLine(
    configuration: lineConfig,
    from: CGPoint(x: 50, y: 550), to: CGPoint(x: 250, y: 550),
    startMarker: false, endMarker: true
)

markup.append(contentsOf: otherMarkup)       // Merge another PaperMarkup
markup.append(contentsOf: pkDrawing)          // Merge a PKDrawing
markup.transformContent(CGAffineTransform(...)) // Apply affine transform
markup.removeContentUnsupported(by: featureSet) // Strip unsupported elements

Property	Description
`bounds`	Coordinate space of the markup
`contentsRenderFrame`	Tight bounding box of all content
`featureSet`	Features used by this data model's content
`indexableContent`	Extractable text for search indexing

func showInsertionMenu(from barButtonItem: UIBarButtonItem) {
    let editVC = MarkupEditViewController(
        supportedFeatureSet: paperVC.supportedFeatureSet,
        additionalActions: []
    )
    editVC.delegate = paperVC  // PaperMarkupViewController conforms to the delegate
    editVC.modalPresentationStyle = .popover
    editVC.popoverPresentationController?.barButtonItem = barButtonItem
    present(editVC, animated: true)
}

let toolbar = MarkupToolbarViewController(supportedFeatureSet: paperVC.supportedFeatureSet)
toolbar.delegate = paperVC
addChild(toolbar)
toolbar.view.frame = toolbarContainerView.bounds
toolbarContainerView.addSubview(toolbar.view)
toolbar.didMove(toParent: self)

Preset	Description
`.latest`	All current features — recommended starting point
`.version1`	Features from version 1
`.empty`	No features enabled

var features = FeatureSet.latest
features.remove(.stickers)
features.remove(.images)

// Or build up from empty
var features = FeatureSet.empty
features.insert(.drawing)
features.insert(.text)
features.insert(.shapeStrokes)

Feature	Description
`.drawing`	Freeform PencilKit drawing
`.text`	Text box insertion
`.images`	Image insertion
`.stickers`	Sticker insertion
`.links`	Link annotations
`.loupes`	Loupe/magnifier elements
`.shapeStrokes`	Shape outlines
`.shapeFills`	Shape fills
`.shapeOpacity`	Shape opacity control

var features = FeatureSet.latest
features.colorMaximumLinearExposure = 4.0
toolPicker.colorMaximumLinearExposure = features.colorMaximumLinearExposure

features.shapes = [.rectangle, .ellipse, .arrowShape, .line]
features.inks = [.pen, .pencil, .marker]
features.lineMarkerPositions = .all  // .single, .double, .plain, or .all

import PencilKit

// Set drawing tool
paperVC.drawingTool = PKInkingTool(.pen, color: .black, width: 3)

// Merge existing PKDrawing into markup
markup.append(contentsOf: existingPKDrawing)

let toolPicker = PKToolPicker()
toolPicker.addObserver(paperVC)
paperVC.pencilKitResponderState.activeToolPicker = toolPicker
paperVC.pencilKitResponderState.toolPickerVisibility = .visible

let pkVersion = features.contentVersion.pencilKitContentVersion

struct MarkupView: UIViewControllerRepresentable {
    @Binding var markup: PaperMarkup
    let features: FeatureSet

    func makeUIViewController(context: Context) -> PaperMarkupViewController {
        let vc = PaperMarkupViewController(markup: markup, supportedFeatureSet: features)
        vc.delegate = context.coordinator
        let toolPicker = PKToolPicker()
        toolPicker.addObserver(vc)
        vc.pencilKitResponderState.activeToolPicker = toolPicker
        vc.pencilKitResponderState.toolPickerVisibility = .visible
        context.coordinator.toolPicker = toolPicker
        return vc
    }

    func updateUIViewController(_ vc: PaperMarkupViewController, context: Context) {
        if vc.markup != markup { vc.markup = markup }
    }

    func makeCoordinator() -> Coordinator { Coordinator(parent: self) }

    class Coordinator: NSObject, PaperMarkupViewController.Delegate {
        let parent: MarkupView
        var toolPicker: PKToolPicker?
        init(parent: MarkupView) { self.parent = parent }

        func paperMarkupViewControllerDidChangeMarkup(
            _ controller: PaperMarkupViewController
        ) {
            if let markup = controller.markup { parent.markup = markup }
        }
    }
}

struct DocumentMarkupScreen: View {
    let pageSize: CGSize
    @State private var markup: PaperMarkup
    private let features = FeatureSet.latest

    init(pageSize: CGSize) {
        self.pageSize = pageSize
        _markup = State(
            initialValue: PaperMarkup(
                bounds: CGRect(origin: .zero, size: pageSize)
            )
        )
    }

    var body: some View {
        MarkupView(markup: $markup, features: features)
    }
}

Mistake	Fix
View, insertion UI, and saved document use mismatched feature sets	Choose one supported `FeatureSet` and use it across the editing session.
Loaded content is assigned without a version check	Verify `markup.featureSet.isSubset(of: supportedFeatureSet)` or show the saved thumbnail/fallback.
Serialization blocks UI or overlaps unsafely	Await `dataRepresentation()` off the interaction path and debounce autosaves.
Tool picker is a local variable	Retain it for the controller/view lifetime.
Wrong insertion surface for the platform	Use `MarkupToolbarViewController` on macOS; use `MarkupEditViewController` on UIKit, with Catalyst supporting either presentation.

paperkit

Summary

SKILL.md

PaperKit

Contents

Workflow

Setup

PaperMarkupViewController

Basic UIKit Setup

Key Properties

Touch Modes

Content Background

Delegate Callbacks

PaperMarkup Data Model

Creating and Persisting

Inserting Content Programmatically

Other Operations

Insertion Controllers

MarkupEditViewController (iOS, iPadOS, Mac Catalyst, visionOS)

MarkupToolbarViewController (macOS, Mac Catalyst)

FeatureSet Configuration

Customizing

Available Features

HDR Support

Shapes, Inks, and Line Markers

Integration with PencilKit

Tool Picker Setup

Content Version Compatibility

SwiftUI Integration

Common Mistakes

Review Checklist

References

Related skills