paperkit

What this skill does

# 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 provides a unified markup experience — the same framework powering markup in Notes, Screenshots, QuickLook, and Journal. It combines PencilKit drawing with structured markup elements (shapes, text boxes, images, lines) in a single canvas managed by `PaperMarkupViewController`. Requires Swift 6.3 and the iOS 26+ SDK.

## Contents

- [Setup](#setup)
- [PaperMarkupViewController](#papermarkupviewcontroller)
- [PaperMarkup Data Model](#papermarkup-data-model)
- [Insertion Controllers](#insertion-controllers)
- [FeatureSet Configuration](#featureset-configuration)
- [Integration with PencilKit](#integration-with-pencilkit)
- [SwiftUI Integration](#swiftui-integration)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Setup

PaperKit requires no entitlements or special Info.plist entries.

```swift
import PaperKit
```

**Platform availability:** iOS 26.0+, iPadOS 26.0+, Mac Catalyst 26.0+, macOS 26.0+, visionOS 26.0+.

Three core components:

| 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 |

## PaperMarkupViewController

The primary view controller for interactive markup. Provides a scrollable canvas for freeform PencilKit drawing and structured markup elements. Conforms to `Observable` and `PKToolPickerObserver`.

### Basic UIKit Setup

```swift
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) }
    }
}
```

### Key Properties

| 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 |

### Touch Modes

`PaperMarkupViewController.TouchMode` has two cases: `.drawing` and `.selection`.

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

### Content Background

Set any view beneath the markup layer for templates, document pages, or images being annotated. Keep the `PaperMarkup(bounds:)` coordinate space aligned to the background content, such as a PDF page or rendered image size, so saved annotations restore in the right place:

```swift
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
```

### Delegate Callbacks

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

## PaperMarkup Data Model

`PaperMarkup` is a `Sendable` struct that stores all markup elements and PencilKit drawing data.

### Creating and Persisting

```swift
// 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)
}
```

### Inserting Content Programmatically

```swift
// 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
)
```

Shape types: `.rectangle`, `.roundedRectangle`, `.ellipse`, `.line`, `.arrowShape`, `.star`, `.chatBubble`, `.regularPolygon`.

### Other Operations

```swift
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 |

Use `suggestedFrameForInserting(contentInFrame:)` on the view controller to get a frame that avoids overlapping existing content.

## Insertion Controllers

### MarkupEditViewController (iOS, iPadOS, Mac Catalyst, visionOS)

Presents a popover menu for inserting shapes, text boxes, lines, and other elements.

```swift
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)
}
```

### Mark