PaperKit

Combine freeform PencilKit drawings with structured markup elements (shapes, text boxes, images, connectors) using PaperKit (PaperMarkupViewController, PaperMarkup). Targets Swift 6.3 / 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.

Contents

• 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

Persistence and Feature Sets

1. Serialization: Save and restore PaperMarkup using markup.dataRepresentation().
2. FeatureSet Compatibility: Initialize view controllers with explicit feature sets (e.g. FeatureSet.latest or targeted subsets) to prevent forward-compatibility loading errors.
3. 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

References

• PaperKit extended recipes and SwiftUI wrappers
• PaperKit documentation
• PencilKit documentation