@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/pencilkit-drawing/SKILL.md

@@ -1,483 +1,367 @@
 ---
 name: pencilkit-drawing
-description: "Add Apple Pencil drawing with PKCanvasView, PKToolPicker, PKDrawing serialization/export, stroke inspection, and PencilKit/PaperKit handoffs. Use when building drawing apps, annotation features, handwriting capture, signature fields, content-version-safe ink workflows, or Apple Pencil-powered experiences on iOS/iPadOS/visionOS."
+description: "PencilKit drawing with Apple Pencil or finger: PKCanvasView, PKToolPicker and custom items, PKDrawing persistence and export, stroke inspection and construction, content-version safe ink, SwiftUI wrapping, PaperKit handoffs. Use for drawing apps, annotation, signatures or handwriting capture on iOS, iPadOS or visionOS."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # PencilKit
 
-Capture Apple Pencil and finger input using `PKCanvasView`, manage drawing
-tools with `PKToolPicker`, serialize drawings with `PKDrawing`, and wrap
-PencilKit in SwiftUI. Targets Swift 6.3 / iOS 26+.
-
-## Contents
-
-- [Setup](#setup)
-- [PKCanvasView Basics](#pkcanvasview-basics)
-- [PKToolPicker](#pktoolpicker)
-- [PKDrawing Serialization](#pkdrawing-serialization)
-- [Content Version Compatibility](#content-version-compatibility)
-- [Exporting to Image](#exporting-to-image)
-- [Stroke Inspection](#stroke-inspection)
-- [SwiftUI Integration](#swiftui-integration)
-- [PaperKit Relationship](#paperkit-relationship)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+PencilKit gives you three pieces: `PKCanvasView` turns Pencil and touch input
+into strokes, `PKToolPicker` is the floating palette that picks the tool, and
+`PKDrawing` is the value type you save, load and render. The code assumes
+Swift 6.3 and an iOS 26 deployment target unless an availability note says
+otherwise.
 
 ## Setup
 
-PencilKit requires no entitlements or Info.plist entries. Import `PencilKit`
-and create a `PKCanvasView`.
+Nothing to configure: no entitlement, no Info.plist key. `import PencilKit`
+is enough. The framework exists from iOS and iPadOS 13, from Mac Catalyst
+13.1 and from visionOS 1.0.
 
-```swift
-import PencilKit
-```
+## The canvas
 
-**Platform availability:** iOS 13+, iPadOS 13+, Mac Catalyst 13.1+, visionOS 1.0+.
-
-## PKCanvasView Basics
-
-`PKCanvasView` is a `UIScrollView` subclass that captures Apple Pencil and
-finger input and renders strokes.
+`PKCanvasView` inherits from `UIScrollView`. It records input, renders the
+strokes and reports every edit to its delegate.
 
 ```swift
 import PencilKit
 import UIKit
 
-class DrawingViewController: UIViewController, PKCanvasViewDelegate {
-    let canvasView = PKCanvasView()
+final class SketchViewController: UIViewController, PKCanvasViewDelegate {
+    private let board = PKCanvasView()
 
     override func viewDidLoad() {
         super.viewDidLoad()
-        canvasView.delegate = self
-        canvasView.drawingPolicy = .anyInput
-        canvasView.tool = PKInkingTool(.pen, color: .black, width: 5)
-        canvasView.frame = view.bounds
-        canvasView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
-        view.addSubview(canvasView)
+        board.delegate = self
+        board.drawingPolicy = .anyInput
+        board.tool = PKInkingTool(.marker, color: .systemTeal, width: 12)
+        board.frame = view.bounds
+        board.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        view.addSubview(board)
     }
 
     func canvasViewDrawingDidChange(_ canvasView: PKCanvasView) {
-        // Drawing changed -- save or process
+        scheduleAutosave(canvasView.drawing)   // persist or post-process here
     }
+
+    private func scheduleAutosave(_ drawing: PKDrawing) { }
 }
 ```
 
-### Drawing Policies
+### Who is allowed to draw
 
-| Policy | Behavior |
+| Policy | Behaviour |
 |---|---|
-| `.default` | Respects `UIPencilInteraction.prefersPencilOnlyDrawing` when the tool picker is visible; otherwise Pencil-only |
-| `.anyInput` | Both pencil and finger draw |
-| `.pencilOnly` | Only Apple Pencil touches draw on the canvas |
+| `.default` | While the tool picker is showing, follows the user's `UIPencilInteraction.prefersPencilOnlyDrawing` setting. With no picker, only Pencil draws. |
+| `.anyInput` | Fingers and Pencil both draw. |
+| `.pencilOnly` | Only Pencil touches draw; fingers never make strokes. |
+
+Pick `.default` for a Pencil-first canvas that should respect the system
+setting, `.anyInput` for signature boxes, whiteboards or an explicit
+"draw with finger" mode, and `.pencilOnly` when finger touches must stay
+reserved for scrolling or selection. Do not describe `.default` as
+"Pencil only": it tracks the user's preference whenever the picker is up.
+
+### Canvas options
 
 ```swift
-canvasView.drawingPolicy = .pencilOnly
+board.contentSize = CGSize(width: 2400, height: 3600)   // large scrollable page
+board.isRulerActive = true
+board.tool = PKInkingTool(.pencil, color: .darkGray, width: 3)
+board.tool = PKEraserTool(.vector)
 ```
 
-Use `.default` for system-standard Pencil-primary canvases when the tool
-picker's drawing-policy control should follow the user's Pencil preference. Use
-`.anyInput` for signature pads, whiteboards, or explicit finger-drawing modes.
-Use `.pencilOnly` when finger input should never create strokes.
+## Tool picker
 
-### Configuring the Canvas
+`PKToolPicker` floats over the content. Every canvas registered as an
+observer adopts whatever tool the user selects. Keep one picker per canvas as
+a stored property, and show it once the view is on screen:
 
 ```swift
-// Set a large drawing area (scrollable)
-canvasView.contentSize = CGSize(width: 2000, height: 3000)
-
-// Enable/disable the ruler
-canvasView.isRulerActive = true
+private let palette = PKToolPicker()
 
-// Set the current tool programmatically
-canvasView.tool = PKInkingTool(.pencil, color: .blue, width: 3)
-canvasView.tool = PKEraserTool(.vector)
+override func viewDidAppear(_ isAnimated: Bool) {
+    super.viewDidAppear(isAnimated)
+    palette.addObserver(board)
+    palette.setVisible(true, forFirstResponder: board)
+    board.becomeFirstResponder()
+}
 ```
 
-## PKToolPicker
+### Curated palettes
 
-`PKToolPicker` displays a floating palette of drawing tools. The canvas
-automatically adopts the selected tool.
+`PKToolPicker(toolItems:)` and the item classes need iOS or iPadOS 18,
+visionOS 2, or Mac Catalyst 18; on macOS the item classes arrive with
+macOS 26. `PKToolPickerRulerItem` is the exception: visionOS has no ruler
+item, so add it only on the other platforms.
 
 ```swift
-class DrawingViewController: UIViewController {
-    let canvasView = PKCanvasView()
-    let toolPicker = PKToolPicker()
-
-    override func viewDidAppear(_ animated: Bool) {
-        super.viewDidAppear(animated)
-        toolPicker.addObserver(canvasView)
-        toolPicker.setVisible(true, forFirstResponder: canvasView)
-        canvasView.becomeFirstResponder()
-    }
+if #available(iOS 18.0, visionOS 2.0, *) {
+    var items: [PKToolPickerItem] = [
+        PKToolPickerInkingItem(type: .fountainPen, color: .black, width: 4),
+        PKToolPickerEraserItem(type: .vector),
+        PKToolPickerLassoItem()
+    ]
+    #if !os(visionOS)
+    items.append(PKToolPickerRulerItem())
+    #endif
+    let limited = PKToolPicker(toolItems: items)
+    limited.addObserver(board)
 }
 ```
 
-### Custom Tool Picker Items
+### Ink catalogue
 
-Create a tool picker with specific tools. `PKToolPicker(toolItems:)` and
-custom tool picker item classes require iOS/iPadOS 18+, Mac Catalyst 18+, and
-visionOS 2+; those item classes are available on macOS starting in macOS 26.
+| Ink | Look |
+|---|---|
+| `.pen` | Smooth line that responds to pressure |
+| `.pencil` | Grainy line with tilt shading |
+| `.marker` | Translucent highlighter |
+| `.monoline` | Constant width |
+| `.fountainPen` | Width varies like a calligraphy nib |
+| `.watercolor` | Colours blend into each other |
+| `.crayon` | Waxy texture |
+| `.reed` | Reed nib; version 26 of iOS, iPadOS, macOS and visionOS |
 
-```swift
-let toolPicker = PKToolPicker(toolItems: [
-    PKToolPickerInkingItem(type: .pen, color: .black, width: 5),
-    PKToolPickerInkingItem(type: .pencil, color: .gray, width: 5),
-    PKToolPickerInkingItem(type: .marker, color: .yellow, width: 12),
-    PKToolPickerEraserItem(type: .vector),
-    PKToolPickerLassoItem(),
-    PKToolPickerRulerItem()
-])
-```
+## Content versions
 
-### Ink Types
+Newer inks and stroke data cannot be read by older systems: loading such a
+drawing throws there. `PKContentVersion` names each step:
 
-| Type | Description |
+| Version | What it adds |
 |---|---|
-| `.pen` | Smooth, pressure-sensitive pen |
-| `.pencil` | Textured pencil with tilt shading |
-| `.marker` | Semi-transparent highlighter |
-| `.monoline` | Uniform-width pen |
-| `.fountainPen` | Variable-width calligraphy pen |
-| `.watercolor` | Blendable watercolor brush |
-| `.crayon` | Textured crayon |
-| `.reed` | Reed pen (iOS/iPadOS/macOS/visionOS 26+) |
-
-### Content Versions
-
-When drawings sync to older OS versions, check `requiredContentVersion` before
-uploading or cap new content by setting `maximumSupportedContentVersion` on
-both the `PKCanvasView` and `PKToolPicker`.
-
-| Version | Content |
-|---|---|
-| `.version1` | iPadOS 14-era inks: marker, pen, pencil |
-| `.version2` | iPadOS 17 inks: monoline, fountain pen, watercolor, crayon |
-| `.version3` | Barrel-roll angle data |
+| `.version1` | Original inks: pen, pencil, marker (iPadOS 14 era) |
+| `.version2` | Inks added in iPadOS 17: `.monoline`, `.fountainPen`, `.watercolor`, `.crayon` |
+| `.version3` | Barrel-roll angle data on strokes |
 | `.version4` | Reed pen |
 
-In compatibility reviews, state the complete version map before recommending a
-cap. If the plan exposes a curated picker or specific ink choices, also mention
-the availability of `PKToolPicker(toolItems:)` and custom picker item APIs.
-When existing content exceeds the target OS version, sync a verified fallback
-`PKDrawing` or restrict editing up front; do not rely only on a warning.
+When reviewing compatibility, lay out this whole table before recommending a
+cap, and if the fix is a curated picker, say that `PKToolPicker(toolItems:)`
+needs iOS 18 or visionOS 2.
 
-## PKDrawing Serialization
+### The gate
 
-`PKDrawing` is a value type (struct) that holds all stroke data. Serialize
-it to `Data` for persistence.
+`drawing.requiredContentVersion` is what decides whether a drawing may go to
+a given device, whether through sync, a migration, a downgrade or another
+device. When
+older clients must keep editing, cap new input by setting
+`maximumSupportedContentVersion` on the picker **and** on the canvas;
+capping only the canvas still lets the picker hand out newer inks.
+`PKContentVersion` and both properties are iOS 17 API; an app that still
+deploys below 17 wraps this whole block in `if #available(iOS 17.0, *)`.
 
 ```swift
-// Save
-func saveDrawing(_ drawing: PKDrawing) throws {
-    let data = drawing.dataRepresentation()
-    try data.write(to: fileURL)
-}
+let oldestClient: PKContentVersion = .version1
+board.maximumSupportedContentVersion = oldestClient
+palette.maximumSupportedContentVersion = oldestClient
 
-// Load
-func loadDrawing() throws -> PKDrawing {
-    let data = try Data(contentsOf: fileURL)
-    return try PKDrawing(data: data)
+switch sketch.requiredContentVersion {
+case .version1:
+    queueForSync(sketch)                       // everyone can open and edit it
+case .version2:
+    if recipientsHandleVersion2 { queueForSync(sketch) }
+case .version3, .version4:
+    keepForCurrentClientsOnly(sketch)
+@unknown default:
+    showReadOnlyPreview(sketch)
 }
 ```
 
-When loading synced or user-provided drawings, handle decode failures explicitly
-instead of suppressing them with `try?`:
+If a recipient cannot load the version, keep the full drawing for clients
+that can, and give the others a read-only preview or a separately built
+fallback. Never overwrite the original silently, and do not stop at showing a
+warning: either sync a checked fallback `PKDrawing` or restrict editing before
+the user draws. A fallback builder is in
+[pencilkit patterns](references/pencilkit-patterns.md).
 
-```swift
-do {
-    canvasView.drawing = try PKDrawing(data: data)
-} catch {
-    showReadOnlyPreview(for: document, loadError: error)
-}
-```
+## Saving and loading
 
-### Combining Drawings
+`PKDrawing` is a struct that owns every stroke.
 
 ```swift
-var drawing1 = PKDrawing()
-let drawing2 = PKDrawing()
-drawing1.append(drawing2)
+func store(_ sketch: PKDrawing, at url: URL) throws {
+    try sketch.dataRepresentation().write(to: url, options: .atomic)
+}
 
-// Non-mutating
-let combined = drawing1.appending(drawing2)
+func restore(from url: URL) throws -> PKDrawing {
+    try PKDrawing(data: Data(contentsOf: url))
+}
 ```
 
-### Transforming Drawings
+For data that came from sync or from the user, catch the decoding error and
+react to it (for example switch to a read-only preview) instead of hiding it
+behind `try?`.
 
 ```swift
-let scaled = drawing.transformed(using: CGAffineTransform(scaleX: 2, y: 2))
-let translated = drawing.transformed(using: CGAffineTransform(translationX: 100, y: 0))
+var page = firstLayer
+page.append(secondLayer)                        // mutates page
+let merged = firstLayer.appending(secondLayer)  // returns a new drawing
+let shrunk = merged.transformed(using: CGAffineTransform(scaleX: 0.75, y: 0.75)
+                                    .translatedBy(x: 40, y: 0))
 ```
 
-## Content Version Compatibility
-
-For sync, migration, downgrade, or cross-device editing tasks, use
-`requiredContentVersion` as the compatibility gate and choose an explicit
-`maximumSupportedContentVersion` when old clients must keep editing.
+## Rendering to an image
 
 ```swift
-let targetVersion: PKContentVersion = .version1
-canvasView.maximumSupportedContentVersion = targetVersion
-toolPicker.maximumSupportedContentVersion = targetVersion
-
-switch drawing.requiredContentVersion {
-case .version1:
-    // Older marker, pen, and pencil ink set
-    syncEditable(drawing)
-case .version2:
-    // iPadOS 17-era inks: monoline, fountain pen, watercolor, crayon
-    syncIfRecipientsSupportVersion2(drawing)
-case .version3, .version4:
-    // Later features such as barrel-roll data and Reed Pen
-    syncEditableOnlyToCurrentClients(drawing)
-@unknown default:
-    showReadOnlyPreview(for: drawing)
-}
-```
-
-If a drawing requires a newer version than a recipient can load, preserve the
-full-fidelity `PKDrawing` for capable clients and provide a read-only preview or
-separate fallback instead of silently overwriting it. See
-[references/pencilkit-patterns.md](references/pencilkit-patterns.md) for the
-deeper compatibility table.
-
-## Exporting to Image
-
-Generate a `UIImage` from a drawing.
-
-```swift
-func exportImage(from drawing: PKDrawing, scale: CGFloat = 2.0) -> UIImage {
-    drawing.image(from: drawing.bounds, scale: scale)
-}
-
-// Export a specific region
-let region = CGRect(x: 0, y: 0, width: 500, height: 500)
 let scale = UITraitCollection.current.displayScale
-let croppedImage = drawing.image(from: region, scale: scale)
+guard !sketch.bounds.isEmpty else { return nil }        // empty drawings report .zero
+let full = sketch.image(from: sketch.bounds, scale: scale)
+let corner = sketch.image(from: CGRect(origin: .zero, size: CGSize(width: 300, height: 300)), scale: 2.0)
 ```
 
-## Stroke Inspection
-
-Access individual strokes, their ink, and control points.
+## Looking inside strokes
 
 ```swift
-for stroke in drawing.strokes {
-    let ink = stroke.ink
-    print("Ink type: \(ink.inkType), color: \(ink.color)")
-    print("Bounds: \(stroke.renderBounds)")
-
-    // Access path points
-    let path = stroke.path
-    print("Points: \(path.count), created: \(path.creationDate)")
-
-    // Interpolate along the path
-    for point in path.interpolatedPoints(by: .distance(10)) {
-        print("Location: \(point.location), force: \(point.force)")
+for mark in sketch.strokes {
+    let ink = mark.ink
+    print(ink.inkType, ink.color, mark.renderBounds)
+    print(mark.path.count, "points, started", mark.path.creationDate)
+
+    for sample in mark.path.interpolatedPoints(by: .distance(8)) {
+        print(sample.location, sample.force)
     }
 }
 ```
 
-### Constructing Strokes Programmatically
+### Building strokes in code
 
 ```swift
-let points = [
-    PKStrokePoint(location: CGPoint(x: 0, y: 0), timeOffset: 0,
-                  size: CGSize(width: 5, height: 5), opacity: 1,
-                  force: 0.5, azimuth: 0, altitude: .pi / 2),
-    PKStrokePoint(location: CGPoint(x: 100, y: 100), timeOffset: 0.1,
-                  size: CGSize(width: 5, height: 5), opacity: 1,
-                  force: 0.5, azimuth: 0, altitude: .pi / 2)
-]
-let path = PKStrokePath(controlPoints: points, creationDate: Date())
-let stroke = PKStroke(ink: PKInk(.pen, color: .black), path: path,
-                      transform: .identity, mask: nil)
-let drawing = PKDrawing(strokes: [stroke])
+let samples = [CGPoint(x: 20, y: 20), CGPoint(x: 120, y: 60), CGPoint(x: 220, y: 20)]
+    .enumerated()
+    .map { index, point in
+        PKStrokePoint(location: point,
+                      timeOffset: TimeInterval(index) * 0.05,
+                      size: CGSize(width: 6, height: 6),
+                      opacity: 1,
+                      force: 1,
+                      azimuth: 0,
+                      altitude: .pi / 2)
+    }
+let path = PKStrokePath(controlPoints: samples, creationDate: .now)
+let zigzag = PKStroke(ink: PKInk(.pen, color: .systemIndigo),
+                      path: path,
+                      transform: .identity,
+                      mask: nil)
+let generated = PKDrawing(strokes: [zigzag])
 ```
 
-## SwiftUI Integration
+## SwiftUI
 
-Wrap `PKCanvasView` in a `UIViewRepresentable` for SwiftUI.
+Wrap the canvas in `UIViewRepresentable`. The picker lives in the
+coordinator so it survives view updates, and `updateUIView` only assigns the
+drawing when it actually differs; without that check the delegate and the
+binding feed each other forever.
 
 ```swift
-import SwiftUI
 import PencilKit
+import SwiftUI
 
-struct CanvasView: UIViewRepresentable {
+struct InkCanvas: UIViewRepresentable {
     @Binding var drawing: PKDrawing
-    @Binding var toolPickerVisible: Bool
+    @Binding var paletteShown: Bool
+
+    func makeCoordinator() -> Coordinator { Coordinator(drawing: $drawing) }
 
     func makeUIView(context: Context) -> PKCanvasView {
         let canvas = PKCanvasView()
         canvas.delegate = context.coordinator
         canvas.drawingPolicy = .anyInput
         canvas.drawing = drawing
-        context.coordinator.toolPicker.addObserver(canvas)
+        context.coordinator.palette.addObserver(canvas)
         return canvas
     }
 
-    func updateUIView(_ canvas: PKCanvasView, context: Context) {
-        if canvas.drawing != drawing {
-            canvas.drawing = drawing
+    func updateUIView(_ uiView: PKCanvasView, context: Context) {
+        if uiView.drawing != drawing {   // unchanged: skip, or delegate and binding loop
+            uiView.drawing = drawing
         }
-        let toolPicker = context.coordinator.toolPicker
-        toolPicker.setVisible(toolPickerVisible, forFirstResponder: canvas)
-        if toolPickerVisible { canvas.becomeFirstResponder() }
+        let palette = context.coordinator.palette
+        palette.setVisible(paletteShown, forFirstResponder: uiView)
+        if paletteShown { uiView.becomeFirstResponder() }
     }
 
-    func makeCoordinator() -> Coordinator { Coordinator(self) }
-
-    class Coordinator: NSObject, PKCanvasViewDelegate {
-        let parent: CanvasView
-        let toolPicker = PKToolPicker()
+    final class Coordinator: NSObject, PKCanvasViewDelegate {
+        let palette = PKToolPicker()
+        private var drawing: Binding<PKDrawing>
 
-        init(_ parent: CanvasView) {
-            self.parent = parent
-            super.init()
-        }
+        init(drawing: Binding<PKDrawing>) { self.drawing = drawing }
 
         func canvasViewDrawingDidChange(_ canvasView: PKCanvasView) {
-            parent.drawing = canvasView.drawing
+            drawing.wrappedValue = canvasView.drawing
         }
     }
 }
-```
-
-For SwiftUI wrappers, call out the input-policy choice in the wrapper guidance.
-Use `.anyInput` when finger drawing is part of the product. Use `.pencilOnly`
-when touch should stay reserved for scrolling or selection. Use `.default` when
-you want PencilKit's system behavior: with the tool picker visible, it follows
-the user's Pencil-only drawing setting; otherwise only Apple Pencil draws.
 
-### Usage in SwiftUI
-
-```swift
-struct DrawingScreen: View {
-    @State private var drawing = PKDrawing()
-    @State private var showToolPicker = true
+struct NotePage: View {
+    @State private var ink = PKDrawing()
+    @State private var paletteShown = true
 
     var body: some View {
-        CanvasView(drawing: $drawing, toolPickerVisible: $showToolPicker)
+        InkCanvas(drawing: $ink, paletteShown: $paletteShown)
             .ignoresSafeArea()
     }
 }
 ```
 
-## PaperKit Relationship
+Whenever you hand out a wrapper, state which input policy it uses and why:
+`.anyInput` so fingers draw, `.pencilOnly` so touch stays free for scrolling
+and selection, `.default` for system behaviour.
+
+## PencilKit and PaperKit
 
-PaperKit (iOS 26+) extends PencilKit with a complete markup experience
-including shapes, text boxes, images, stickers, and loupes. Use the sibling
-`paperkit` skill when you need structured markup rather than only freeform
-drawing.
+PaperKit (iOS 26+) layers structured markup on top of PencilKit. This skill
+set has no dedicated PaperKit skill, so for markup work use Apple's PaperKit
+documentation and keep this skill for the freeform ink.
 
 | Capability | PencilKit | PaperKit |
 |---|---|---|
-| Freeform drawing | Yes | Yes |
-| Shapes & lines | No | Yes |
-| Text boxes | No | Yes |
-| Images & stickers | No | Yes |
-| Loupes | No | Yes |
-| Markup toolbar | No | Yes |
-| Markup insertion UI | No | `MarkupEditViewController`, `MarkupToolbarViewController` |
-| Data model | `PKDrawing` | `PaperMarkup` |
-
-PaperKit uses PencilKit under the hood: `PaperMarkupViewController` accepts
-`PKTool` for its `drawingTool` property, and `PaperMarkup` can append a
-`PKDrawing`.
-
-## Common Mistakes
-
-### DON'T: Forget to call becomeFirstResponder for the tool picker
-
-The tool picker only appears when its associated responder is first responder.
-
-```swift
-// WRONG: Tool picker never shows
-toolPicker.setVisible(true, forFirstResponder: canvasView)
-
-// CORRECT: Also become first responder
-toolPicker.setVisible(true, forFirstResponder: canvasView)
-canvasView.becomeFirstResponder()
-```
-
-### DON'T: Oversimplify `.default` drawing policy
-
-When explaining input behavior, `.default` is system-setting aware. If the tool
-picker is visible, it respects the user's Pencil-only drawing preference;
-otherwise only Apple Pencil draws.
-
-### DON'T: Create multiple tool pickers for the same canvas
-
-One `PKToolPicker` per canvas. Creating extras causes visual conflicts.
-
-```swift
-// WRONG
-func viewDidAppear(_ animated: Bool) {
-    let picker = PKToolPicker()  // New picker every appearance
-    picker.setVisible(true, forFirstResponder: canvasView)
-}
-
-// CORRECT: Store picker as a property
-let toolPicker = PKToolPicker()
-```
-
-### DON'T: Ignore content versions for backward compatibility
-
-Earlier OS versions throw when loading `PKDrawing` data that uses unsupported
-inks. Check `requiredContentVersion` before syncing, or set
-`maximumSupportedContentVersion` on both the canvas and tool picker to restrict
-new content.
-
-```swift
-// WRONG: only limits the canvas; picker can still expose newer inks
-canvasView.tool = PKInkingTool(.watercolor, color: .blue)
-canvasView.maximumSupportedContentVersion = .version1
-
-// CORRECT: limit both surfaces for iPadOS 14-era ink compatibility
-if #available(iOS 17.0, *) {
-    canvasView.maximumSupportedContentVersion = .version1
-    toolPicker.maximumSupportedContentVersion = .version1
-}
-```
-
-### DON'T: Compare drawings by data representation
-
-`dataRepresentation()` is for persistence and interchange, not comparison.
-Use `PKDrawing` equality for exact value checks, and inspect strokes or rendered
-images for visual/approximate comparisons.
-
-```swift
-// WRONG
-if drawing1.dataRepresentation() == drawing2.dataRepresentation() { }
-
-// CORRECT
-if drawing1 == drawing2 { }
-```
-
-## Review Checklist
-
-- [ ] `PKCanvasView.drawingPolicy` set appropriately and `.default` explained as system-setting aware
-- [ ] `PKToolPicker` stored as a property, not recreated each appearance
-- [ ] `canvasView.becomeFirstResponder()` called to show the tool picker
-- [ ] Canvas added as a `PKToolPicker` observer before showing the picker
-- [ ] Drawing serialized via `dataRepresentation()` and loaded via `PKDrawing(data:)`
-- [ ] `canvasViewDrawingDidChange` delegate method used to track changes
-- [ ] `maximumSupportedContentVersion` set on both canvas and tool picker if backward compatibility is needed
-- [ ] Custom tool picker item code guarded for iOS/iPadOS 18+ and visionOS 2+
-- [ ] Exported images use appropriate scale factor for the device
-- [ ] SwiftUI wrapper avoids infinite update loops by checking `drawing != binding`
-- [ ] Drawing bounds checked before image export (empty drawings have `.zero` bounds)
+| Freeform ink | yes | yes |
+| Shapes and lines, arrows | no | yes |
+| Text boxes | no | yes |
+| Images and stickers | no | yes |
+| Loupes | no | yes |
+| Markup toolbar and insertion UI | no | yes: `MarkupEditViewController` on iOS, `MarkupToolbarViewController` on macOS |
+| Model type | `PKDrawing` | `PaperMarkup` |
+
+Where they meet: `PaperMarkupViewController.drawingTool` takes any `PKTool`,
+and `PaperMarkup.append(contentsOf:)` accepts a `PKDrawing`.
+
+## Common mistakes
+
+- **Picker never shows.** It is tied to a responder; call
+  `becomeFirstResponder()` on the canvas after `setVisible(_:forFirstResponder:)`.
+- **Calling `.default` Pencil-only.** It follows the system setting while the
+  picker is visible.
+- **A new picker on every appearance.** Store one per canvas; extra pickers
+  fight over the screen.
+- **Capping only the canvas.** Older systems throw on inks they do not know.
+  Set `maximumSupportedContentVersion` on the canvas and on the picker, inside
+  `if #available(iOS 17.0, *)`.
+- **Comparing `dataRepresentation()` bytes.** Use `==` on `PKDrawing` for
+  exact equality; compare strokes or rendered images for "close enough".
+
+## Review checklist
+
+- [ ] `drawingPolicy` chosen on purpose; `.default` described as following the system setting
+- [ ] Tool picker kept in a stored property
+- [ ] `becomeFirstResponder()` called on the canvas
+- [ ] Canvas added as picker observer before the picker is shown
+- [ ] Saved with `dataRepresentation()`, loaded with `PKDrawing(data:)`
+- [ ] Edits tracked through `canvasViewDrawingDidChange(_:)`
+- [ ] `maximumSupportedContentVersion` set on canvas and picker when older clients matter
+- [ ] Custom picker items wrapped in an availability check (iOS/iPadOS 18, visionOS 2)
+- [ ] Images rendered at the display scale
+- [ ] SwiftUI wrapper skips assignment when the drawing is unchanged
+- [ ] Bounds checked before export; an empty drawing has `.zero` bounds
 
 ## References
 
-- Extended PencilKit patterns (advanced strokes, content versions, delegates): [references/pencilkit-patterns.md](references/pencilkit-patterns.md)
-- [PencilKit framework](https://sosumi.ai/documentation/pencilkit)
-- [PKCanvasView](https://sosumi.ai/documentation/pencilkit/pkcanvasview)
-- [PKDrawing](https://sosumi.ai/documentation/pencilkit/pkdrawing-swift.struct)
-- [PKToolPicker](https://sosumi.ai/documentation/pencilkit/pktoolpicker)
-- [PKInkingTool](https://sosumi.ai/documentation/pencilkit/pkinkingtool-swift.struct)
-- [PKStroke](https://sosumi.ai/documentation/pencilkit/pkstroke-swift.struct)
-- [Drawing with PencilKit](https://sosumi.ai/documentation/pencilkit/drawing-with-pencilkit)
-- [Configuring the PencilKit tool picker](https://sosumi.ai/documentation/pencilkit/configuring-the-pencilkit-tool-picker)
+- [pencilkit patterns](references/pencilkit-patterns.md): picker observer, custom items, delegate lifecycle, undo, thumbnails, comparison, version fallback, configurable SwiftUI wrapper
+- https://developer.apple.com/documentation/pencilkit
+- https://developer.apple.com/documentation/pencilkit/pkcanvasview
+- https://developer.apple.com/documentation/pencilkit/pkdrawing
+- https://developer.apple.com/documentation/pencilkit/pktoolpicker
+- https://developer.apple.com/documentation/pencilkit/pkinkingtool
+- https://developer.apple.com/documentation/pencilkit/pkstroke
+- Apple articles: "Drawing with PencilKit" and "Configuring the PencilKit tool picker", both under the PencilKit documentation