PaperKit

Combine freeform PencilKit drawings with structured markup elements (shapes, text boxes, images, connectors) using PaperKit (PaperMarkupViewController, PaperMarkup). Targets Swift 6.4 / iOS 26+.

Beta-sensitive: PaperKit is new in iOS/iPadOS 26, macOS 26, and visionOS 26. Verify availability guards and SDK versions before production release.

PaperKit Architecture
PencilKit vs PaperKit Boundary
Core Components
Persistence and Feature Sets
Route by Task
Common Mistakes
Review Checklist
References

PaperKit Architecture

PaperKit provides an interactive document canvas hosting both vector PencilKit strokes and structured document annotations.

┌────────────────────────────────────────────────────────┐
│            PaperMarkupViewController                   │
│  ┌───────────────────────┐  ┌────────────────────────┐ │
│  │   PKToolPicker        │  │ MarkupEditController   │ │
│  │  (PencilKit Inking)   │  │ (Shapes, Text, Images) │ │
│  └───────────────────────┘  └────────────────────────┘ │
│                                                        │
│  Canvas: PaperMarkup (Strokes + Shapes + Text Objects) │
└────────────────────────────────────────────────────────┘

PencilKit vs PaperKit Boundary

pencilkit: Use for pure freehand sketchbooks, drawing-only canvases, raw vector stroke analysis, or when supporting iOS 17 and earlier.
paperkit: Use when users need to place shapes, typed text, sticky notes, or signature annotations alongside freehand drawings in document editors.

Core Components

Component	Role
`PaperMarkupViewController`	Scrollable interactive markup canvas hosting drawings and elements
`PaperMarkup`	Serializable document model representing canvas elements and bounds
`MarkupEditViewController`	System UI for inserting shapes, text, arrows, and signatures
`MarkupToolbarViewController`	Toolbar controller coordinating tools on desktop and iPad
`FeatureSet`	Capability configuration declaring supported tools and element types

Persistence and Feature Sets

Serialization: Save and restore PaperMarkup using markup.dataRepresentation().
FeatureSet Compatibility: Initialize view controllers with explicit feature sets (e.g. FeatureSet.latest or targeted subsets) to prevent forward-compatibility loading errors.
Thumbnail Rendering: Generate raster thumbnail previews off the main thread for fast document list loading.

Route by Task

For full UIKit setup, delegate lifecycle, and embedding in parent controllers, read PaperMarkupViewController Setup.
For SwiftUI integration with UIViewControllerRepresentable, read SwiftUI PaperKit Integration.
For custom tool picker coordination and first-responder management, read Tool Picker Coordination.
For document serialization, thumbnail generation, and backward compatibility, read Persistence and Thumbnails.

Common Mistakes

Presenting markup insertion controllers without anchoring to a valid bar button or source rect.
Recreating PaperMarkupViewController on every SwiftUI view update rather than using coordinator pattern.
Performing PaperMarkup serialization synchronously on the main thread for large multi-element documents.
Omitting availability checks (@available(iOS 26.0, *)) when deploying to earlier OS versions.
Failing to synchronize document bounds between PaperMarkup and the hosting view layout.

Review Checklist

PaperMarkupViewController hosted in a stable UIKit container or SwiftUI Coordinator
Availability guarded for iOS 26+
Insertion controllers properly anchored to source views or bar button items
PKToolPicker added as observer to the paper markup controller
Document serialization performed asynchronously in background tasks
Undo and redo actions integrated with the canvas UndoManager

paperkit