@tobyt/expo-pdf-markup 1.2.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,45 @@
1
+ # Annotation coordinates
2
+
3
+ All platforms exchange `AnnotationsData` version 1 using the same visible-page coordinate system:
4
+
5
+ - Units are PDF points, independent of screen density, zoom and scrolling.
6
+ - The origin `(0, 0)` is the bottom-left of the visible page after its PDF rotation.
7
+ - `x` increases rightward; `y` increases upward.
8
+ - Ink `paths` contain visible-page points. Rectangular `bounds` use the same space: `x` and `y` locate the bottom-left, with positive `width` and `height`.
9
+ - The contract applies to ink, highlight, underline, text/freeText, stamps, and text-input-request points. `page` remains a zero-based page index.
10
+
11
+ For example, a PDF with MediaBox `[0,0,800,1000]` and CropBox `[100,80,700,920]` has a visible size of 600 by 840 points at rotation 0. A model point `(80,120)` covers native PDF page point `(180,200)`. With clockwise rotation 90, visible size is 840 by 600 and the same model point covers native page point `(580,160)`.
12
+
13
+ ## iOS boundaries
14
+
15
+ PDFKit touch conversion and native annotation rectangles use unrotated PDF page coordinates, including the crop origin. `AnnotationCoordinates` converts these coordinates to/from the interchange model. Loading and serialization apply this adapter in opposite directions, including page rotation.
16
+
17
+ PDFKit ink paths are local to their annotation rectangle. The module converts native page points to local path points when constructing an annotation, and adds the rectangle origin before serializing, outlining or hit-testing it. Live ink uses the same construction path as loaded ink. Custom stamps and area underlines draw in visible-page coordinates. A shared drawing adapter accounts for the different clips PDFKit supplies when recording a live appearance and rendering a whole page or thumbnail. Transparent native appearance padding stays separate from serialized content bounds and editing/hit geometry, including for full-page annotations and scaled thumbnails. Underlines retain their public `underline` model type while using a custom native appearance so PDFKit renders the selected lower edge in the live view too.
18
+
19
+ Live text creation and editing also measure and place text in visible-page coordinates, using the same integral dimensions as the loader. Editing preserves the annotation ID, timestamp, color, font and model type; reopening does not remeasure text along a different axis.
20
+
21
+ Moving annotations operates in visible-page coordinates and clamps to the visible page dimensions. Outlines and eraser/move hit targets use the rendered native geometry. Neither zooming nor scrolling alters saved coordinates.
22
+
23
+ ## Existing v1 data
24
+
25
+ Valid web/Android v1 coordinates keep their existing placement; no schema change or automatic migration is applied. IDs, page indices, content, color and styling survive load/save cycles. `text` and `freeText` both render as native free text while retaining their interchange type.
26
+
27
+ Historical native v1 records do not reliably identify their originating platform or coordinate convention. A record containing native page coordinates can be indistinguishable from an intentional visible-page placement. The module does not guess the original intent, subtract an offset from every stored record, or rewrite a host application's store. Back up existing records and review affected documents when upgrading. Recovery of ambiguous historical data requires application-specific information about how that data was created.
28
+
29
+ Consumers must rebuild their native iOS application to adopt the Swift correction. Updating JavaScript or delivering an OTA update alone does not replace compiled native code. Package publication is a separate maintainer action.
30
+
31
+ ## Regression coverage
32
+
33
+ `ios/Tests/AnnotationCoordinateTests.swift` generates project-owned raster-only PDF fixtures with asymmetric anchors, with optional selectable text. Coverage includes nonzero x/y crop origins, zero-origin media-box and right/top-only crop controls, rotations 0/90/180/270, live ink commitment, rendered thumbnails, zoom/scroll movement, editing outlines, hit targets and live stamp snapshots before/after reloading.
34
+
35
+ `fixtures/annotations-v1.json` supplies the same marks to iOS, web and Android model tests, including ink, highlight/underline, text/freeText and music/star/emoji stamps. Repeated round trips assert placement and metadata preservation.
36
+
37
+ Native interaction tests drive the existing overlay callbacks and gesture-handler seam. They exercise the real PDFKit view and rendering, but do not synthesize physical finger/Pencil events. Simulator results and outstanding physical-device checks are recorded separately in the implementation's validation report.
38
+
39
+ ## Area markup on iOS
40
+
41
+ The highlight and underline tools capture a one-finger rectangular drag on both scanned and text-bearing PDFs. No text selection or OCR is required, and rectangles do not snap to text lines. A highlight fills the chosen area; an underline marks its displayed lower edge. The same visible-page bounds are emitted through `onAnnotationsChanged` and retained after reloading.
42
+
43
+ Touch scrolling, pinch zoom and book-mode touch turns are suspended while the tool is active. Select `annotationMode="none"` for touch navigation and zoom, then reselect the desired markup tool. The `page` prop and book-mode hardware keys remain available during markup. Page/source/display changes, cancelled gestures and tool switches discard an unfinished drag; a drag cannot transfer its mark to another page. Leaving the tool restores the previous scrolling and gesture state.
44
+
45
+ `ios/Tests/AreaMarkupTests.swift` covers the input-to-render-to-serialization path with raster-only and selectable-text controls, crop controls, all rotations, zoom/scroll, fresh-view reopen, movement/hit geometry, cancellation, tool switching and explicit navigation. Tests use each simulator's screen dimensions. As with the coordinate suite, callback-driven tests do not replace physical finger/Pencil validation.
@@ -0,0 +1,117 @@
1
+ # Annotation validation for spec #126
2
+
3
+ ## Manual regression PDFs in the example app
4
+
5
+ The example's horizontal document picker includes **Scan regression (6 pages)** and
6
+ **Text regression (4 pages)**. Scroll the document row to find them. Both files are
7
+ bundled in `example/assets/`; no external document or download is required.
8
+
9
+ | Sample | Pages | Purpose |
10
+ | --- | --- | --- |
11
+ | Scan regression | 1–4 | Image-only MediaBox `[0,0,800,1000]`, CropBox `[100,80,700,920]`, rotations 0/90/180/270 |
12
+ | Scan regression | 5 | Image-only uncropped, zero-origin control |
13
+ | Scan regression | 6 | Image-only zero-origin CropBox `[0,0,600,840]` with different right/top edges |
14
+ | Text regression | 1–4 | The same nonzero crop and rotations, with an actual selectable-text sentence |
15
+
16
+ The scan's labels, lines and asymmetric blue/green anchors are raster pixels; the PDF
17
+ contains no selectable text. On the text controls, the sentence beginning “Selectable
18
+ text” is real PDF text, while the surrounding visual guides remain rasterized.
19
+
20
+ 1. Select **Scan regression**, then **Ink**. Trace an anchor or staff line; the stroke
21
+ must stay in place when you lift your finger.
22
+ 2. Select **Highlight** or **Underline** and drag a rectangle over a guide. The page
23
+ must stay still; highlighting fills the area and underlining follows its lower edge.
24
+ 3. Try **Text**, then **Stamp** with **Note**, **Star** and **Emoji**, including near the
25
+ visible edges. Check placement and clipping on all four rotated pages.
26
+ 4. Select **Move** or **Eraser**. Blue outlines and touch targets must agree with the
27
+ marks. Switch to **View** to navigate/pinch, then repeat after zooming and scrolling.
28
+ 5. Repeat with **Text regression**, and compare the scan's zero-origin controls. Book
29
+ mode makes it easy to review each rotation separately.
30
+ 6. Open **Annotations → Show raw JSON** to inspect the saved paths and bounds. The
31
+ example keeps annotations in memory and clears them when changing documents or
32
+ restarting; this UI does not itself test persistent save/reopen or thumbnails.
33
+
34
+ Regenerate both checked-in PDFs with `python3 scripts/generate_annotation_pdfs.py`
35
+ (requires Pillow >= 10.1 and PyMuPDF; installation is documented in the script).
36
+ All fixture content is generated for this project and is redistributable.
37
+
38
+ ## Coordinate slice (#127), 2026-11-15
39
+
40
+ All repository changes and native builds ran in a task-specific linked worktree.
41
+
42
+ | Check | Result |
43
+ | --- | --- |
44
+ | `npm run qa:ts` | Passed; 25 suites, 282 tests passed, 72 tests skipped by the existing platform configuration |
45
+ | `npm run qa:ios` | Passed; formatting, SwiftLint (no serious violations), 95 XCTest cases |
46
+ | iPhone 13 mini, iOS 26.4 simulator (locally named `cramped`) | 95 XCTest cases passed |
47
+ | iPad Pro 13-inch (M5), iOS 26.4 simulator | 95 XCTest cases passed |
48
+ | `npm run format:swift:check` and `git diff --check` | Passed |
49
+ | Android shared-fixture QA | Run independently with the shared-fixture implementation; see PR validation for the result |
50
+
51
+ The iPhone result bundle is `build/test-results/ios-1794753626.xcresult`; the iPad result bundle is `build/test-results/ios-1794753664.xcresult` in the integration worktree. Live PDFView stamp screenshots are retained as XCTest attachments. Result bundles are build artifacts, not checked-in fixtures.
52
+
53
+ ### Failure evidence before correction
54
+
55
+ - Live ink committed on CropBox `[100,80,700,920]` serialized native points `(180,200)` and `(280,200)` instead of visible points `(80,120)` and `(180,120)`. The regression passed after routing live creation through the coordinate adapter and shared serializer.
56
+ - Native thumbnail rendering placed zero pixels of each music-note, star and emoji stamp within the expected visible rectangle. The same pixel regression passed after correcting the custom annotation drawing-context origin.
57
+ - Highlight, underline, text and stamp import used `(80,120)` as native bounds instead of `(180,200)` on that cropped page. The load-boundary regression passed after applying the shared coordinate adapter.
58
+ - Rotated free-text loading expanded the rectangle along the wrong axis, changing visible bounds `(80,120,240,40)` to `(80,29,240,131)`. Normalizing text dimensions before transforming into native space made repeated round trips stable.
59
+
60
+ The final suite covers crop controls, rotations, live ink, rendered pixels, shared v1 fixture preservation, zoom/scroll movement, outline geometry, hit targets and live glyph rendering before/after annotation reload. Synthetic raster PDF fixtures are generated in the tests; their text-bearing variant adds project-owned text.
61
+
62
+ ### Remaining manual validation
63
+
64
+ Automated input tests drive overlay callbacks and native gesture handlers. They do not synthesize physical finger or Apple Pencil events. Real-device checks with finger/Pencil on iPhone and iPad remain outstanding. This is distinct from the completed simulator view/rendering checks. Package publication remains a maintainer action.
65
+
66
+ ### Reproduction
67
+
68
+ Prepare the example project's XCTest target with `ruby scripts/add_test_target.rb`, run CocoaPods installation, then use:
69
+
70
+ ```sh
71
+ npm run qa:ios
72
+ IOS_TEST_DESTINATION='platform=iOS Simulator,name=iPad Pro 13-inch (M5)' npm run test:swift
73
+ npm run qa:ts
74
+ ```
75
+
76
+ Use an installed simulator name or ID when the devices above are unavailable. `scripts/test-swift.sh` writes a fresh `.xcresult` bundle for each invocation.
77
+
78
+ ## Area-markup slice (#128), 2026-11-15
79
+
80
+ | Check | Result |
81
+ | --- | --- |
82
+ | `npm run qa:ts` | Passed; 25 suites, 282 tests passed, 72 existing platform skips |
83
+ | `npm run qa:ios` | Passed; formatting, SwiftLint, 101 XCTest cases on iPhone 13 mini / iOS 26.4 |
84
+ | iPad Pro 13-inch (M5), iOS 26.4 | 101 XCTest cases passed, with area tests using the tablet screen dimensions |
85
+ | Android | The unchanged shared-fixture implementation passed its 97 JVM tests and ktlint; no Android source changes were required in this slice |
86
+
87
+ The final iPhone result bundle is `build/test-results/ios-1794769031.xcresult`; the iPad result bundle is `build/test-results/ios-1794769069.xcresult`. The integration worktree retains these bundles alongside the coordinate-slice artifacts.
88
+
89
+ ### Failure evidence and corrected behavior
90
+
91
+ - Before the area overlay, the image-only highlight regression left scrolling enabled and had no input overlay capable of producing markup. The same drag now produces a visible rectangle and serialized visible bounds `(80,120,100,40)` without moving the scroll offset.
92
+ - Native PDFKit underline rendering selected the wrong edge at 90/180/270 degrees. Ordered quadrilaterals corrected the edge but still left the 180-degree baseline outside the selected rectangle. At a crop-edge rectangle `(80,1,100,40)`, no underline pixels remained visible. A small native underline renderer now draws the visible lower edge directly; rendering, reopened marks and their hit targets agree at every rotation, including that crop edge.
93
+ - The final area suite exercises both tools on raster-only and selectable-text PDFs across nonzero-origin, zero-origin and right/top crop controls. It checks serialized geometry, zoom/scroll input, movement, rendered output and fresh-view reopen. Cancellation, all tool switches, prior scrolling/gesture-state restoration, source changes, the `page` prop and book-mode hardware keys discard stale drags and leave navigation usable.
94
+
95
+ These are simulator PDFKit/view tests driven through the existing overlay callbacks and native gesture handlers. Physical finger/Pencil input on real iPhone/iPad devices remains a separate outstanding manual check. No package was published.
96
+
97
+ ## Final review corrections, 2026-11-15
98
+
99
+ | Check | Result |
100
+ | --- | --- |
101
+ | `npm run qa:ts` | Passed; 25 suites, 282 tests passed, 72 existing platform skips |
102
+ | `npm run qa:ios` | Passed; formatting, SwiftLint with no serious violations, and all 105 XCTest cases on iPhone 13 mini / iOS 26.4 |
103
+ | iPad Pro 13-inch (M5), iOS 26.4 | All 105 XCTest cases passed |
104
+ | `npm run format:swift:check` and `git diff --check` | Passed |
105
+ | Android | Source unchanged by the final review fixes; the earlier 97 passing JVM tests and ktlint result still apply |
106
+
107
+ The final retained iPhone bundle is `build/test-results/ios-1794771326.xcresult`; the final iPad bundle is `build/test-results/ios-1794771374.xcresult` in the integration worktree. Live rotated-text and stamp snapshots are retained as XCTest attachments.
108
+
109
+ The review corrections close the remaining live-input and custom-rendering boundaries:
110
+
111
+ - Live text creation and editing now measure integral dimensions in shared visible-page space and reuse the serializer for native construction. The first live regression reproduced bounds changing from approximately `141.28 × 26.4` to `142 × 27` on reload even at rotation 0; the native/shared axis mismatch also affected rotated pages. Final tests drive text taps, creation, editing to a longer string and fresh-document reload at all four rotations, asserting stable bounds, IDs, timestamps, color, font, content and actual horizontal text pixels in thumbnails and the live view.
112
+ - Before the drawing correction, all three music/star/emoji stamps painted zero changed thumbnail pixels in their intended rectangles at rotations 90/180/270, before and after annotation reload. Live appearance recording and whole-page rendering use different PDFKit clips. The shared adapter now draws the same visible content in both contexts; transparent native appearance padding remains separate from model bounds, outlines and hit targets. Full-size and scaled thumbnails, live snapshots, and a full-page rotated `L` orientation control pass.
113
+ - A live underline regression found the wrong edge at rotations 90/180/270 even though the existing thumbnail checks passed. PDFKit bypassed the custom draw override for its built-in live underline presentation. Underlines now use a custom native appearance while retaining the public `underline` model type. Final tests check the visible lower edge in live views and thumbnails, then reload and move the mark while preserving its metadata and matching hit geometry.
114
+
115
+ Early hosted-suite attempts stalled in UIKit window presentation after PDFKit/Vision analysis occupied the dispatch worker pool. Stack sampling identified `UIWindow.makeKeyAndVisible` waiting for corner-bitmap work, rather than a rendering assertion failure. The new rendering harness now attaches temporary views to the existing app window, explicitly clears documents/removes its views between rotations, and preserves the app's window/root state. The final complete suite passes on both simulator configurations; no private PDFKit flags or swizzling are used.
116
+
117
+ Physical finger/Pencil validation remains outstanding, separately from these completed simulator rendering and callback-driven interaction checks. No package was published.
@@ -0,0 +1,130 @@
1
+ {
2
+ "version": 1,
3
+ "annotations": [
4
+ {
5
+ "id": "shared-ink",
6
+ "type": "ink",
7
+ "color": "#CC2244",
8
+ "lineWidth": 3,
9
+ "paths": [
10
+ [
11
+ {
12
+ "x": 40,
13
+ "y": 100
14
+ },
15
+ {
16
+ "x": 120,
17
+ "y": 160
18
+ },
19
+ {
20
+ "x": 180,
21
+ "y": 130
22
+ }
23
+ ]
24
+ ],
25
+ "page": 0,
26
+ "createdAt": 1741340000
27
+ },
28
+ {
29
+ "id": "shared-highlight",
30
+ "type": "highlight",
31
+ "color": "#FFCC00",
32
+ "alpha": 0.5,
33
+ "bounds": {
34
+ "x": 60,
35
+ "y": 300,
36
+ "width": 180,
37
+ "height": 24
38
+ },
39
+ "page": 0,
40
+ "createdAt": 1741340001
41
+ },
42
+ {
43
+ "id": "shared-underline",
44
+ "type": "underline",
45
+ "color": "#2244CC",
46
+ "bounds": {
47
+ "x": 80,
48
+ "y": 380,
49
+ "width": 160,
50
+ "height": 20
51
+ },
52
+ "page": 0,
53
+ "createdAt": 1741340002
54
+ },
55
+ {
56
+ "id": "shared-text",
57
+ "type": "text",
58
+ "color": "#114422",
59
+ "bounds": {
60
+ "x": 100,
61
+ "y": 450,
62
+ "width": 240,
63
+ "height": 40
64
+ },
65
+ "contents": "Shared note",
66
+ "fontSize": 16,
67
+ "fontFamily": "Helvetica",
68
+ "page": 0,
69
+ "createdAt": 1741340003
70
+ },
71
+ {
72
+ "id": "shared-free-text",
73
+ "type": "freeText",
74
+ "color": "#442211",
75
+ "bounds": {
76
+ "x": 100,
77
+ "y": 520,
78
+ "width": 240,
79
+ "height": 40
80
+ },
81
+ "contents": "Visible page",
82
+ "fontSize": 18,
83
+ "fontFamily": "Helvetica",
84
+ "page": 0,
85
+ "createdAt": 1741340004
86
+ },
87
+ {
88
+ "id": "shared-music",
89
+ "type": "stamp",
90
+ "color": "#332299",
91
+ "bounds": {
92
+ "x": 20,
93
+ "y": 700,
94
+ "width": 48,
95
+ "height": 48
96
+ },
97
+ "text": "♫",
98
+ "page": 0,
99
+ "createdAt": 1741340005
100
+ },
101
+ {
102
+ "id": "shared-star",
103
+ "type": "stamp",
104
+ "color": "#BB5500",
105
+ "bounds": {
106
+ "x": 270,
107
+ "y": 700,
108
+ "width": 48,
109
+ "height": 48
110
+ },
111
+ "text": "★",
112
+ "page": 0,
113
+ "createdAt": 1741340006
114
+ },
115
+ {
116
+ "id": "shared-emoji",
117
+ "type": "stamp",
118
+ "color": "#222222",
119
+ "bounds": {
120
+ "x": 530,
121
+ "y": 700,
122
+ "width": 48,
123
+ "height": 48
124
+ },
125
+ "text": "🎵",
126
+ "page": 0,
127
+ "createdAt": 1741340007
128
+ }
129
+ ]
130
+ }
@@ -156,12 +156,13 @@ extension ExpoPdfMarkupView {
156
156
  annotation: PDFAnnotation?
157
157
  ) -> [String: Any] {
158
158
  let pageIndex = pdfView.document?.index(for: page) ?? 0
159
+ let visiblePoint = point.applying(AnnotationCoordinates(page: page).nativeToVisible)
159
160
  var payload: [String: Any] = [
160
161
  "mode": annotation == nil ? "create" : "edit",
161
162
  "page": pageIndex,
162
163
  "point": [
163
- "x": point.x,
164
- "y": point.y,
164
+ "x": visiblePoint.x,
165
+ "y": visiblePoint.y,
165
166
  ],
166
167
  ]
167
168
  if let contents = annotation?.contents {
@@ -177,7 +178,7 @@ extension ExpoPdfMarkupView {
177
178
  replacing annotation: PDFAnnotation?
178
179
  ) {
179
180
  if let annotation {
180
- updateFreeTextAnnotation(annotation, text: text)
181
+ updateFreeTextAnnotation(annotation, text: text, on: page)
181
182
  } else {
182
183
  addFreeTextAnnotation(text: text, at: point, on: page)
183
184
  }
@@ -186,36 +187,33 @@ extension ExpoPdfMarkupView {
186
187
  private func addFreeTextAnnotation(text: String, at point: CGPoint, on page: PDFPage) {
187
188
  let fontSize: CGFloat = 16.0
188
189
  let font = UIFont(name: annotationFontFamily ?? "", size: fontSize) ?? UIFont.systemFont(ofSize: fontSize)
189
- let color = AnnotationSerializer.colorFromHex(annotationColor) ?? .red
190
- let bounds = measuredTextBounds(text: text, font: font, at: point)
191
-
192
- let annotation = PDFAnnotation(bounds: bounds, forType: .freeText, withProperties: nil)
193
- annotation.font = font
194
- annotation.fontColor = color
195
- annotation.color = .clear
196
- annotation.contents = text
197
-
198
- let id = UUID().uuidString
199
- AnnotationSerializer.tagAsModuleManaged(annotation, id: id, createdAt: Date().timeIntervalSince1970)
190
+ let coordinates = AnnotationCoordinates(page: page)
191
+ let visiblePoint = point.applying(coordinates.nativeToVisible)
192
+ let model = AnnotationModel(
193
+ id: UUID().uuidString, type: "freeText", page: pdfView.document?.index(for: page) ?? 0,
194
+ color: annotationColor,
195
+ bounds: AnnotationBounds(measuredTextBounds(text: text, font: font, at: visiblePoint)),
196
+ contents: text, fontSize: fontSize, fontFamily: font.fontName,
197
+ createdAt: Date().timeIntervalSince1970
198
+ )
199
+ guard let annotation = AnnotationSerializer.toPDFAnnotation(
200
+ model, pageBounds: page.bounds(for: .cropBox), pageRotation: page.rotation
201
+ ) else { return }
200
202
  page.addAnnotation(annotation)
201
203
  emitAnnotationsChanged()
202
204
  }
203
205
 
204
- private func updateFreeTextAnnotation(_ annotation: PDFAnnotation, text: String) {
205
- let fontSize = annotation.font?.pointSize ?? 16.0
206
- let font = annotation.font ??
207
- UIFont(name: annotationFontFamily ?? "", size: fontSize) ??
208
- UIFont.systemFont(ofSize: fontSize)
209
- let bounds = measuredTextBounds(text: text, font: font, replacing: annotation.bounds)
210
-
211
- annotation.font = font
212
- annotation.bounds = bounds
213
- annotation.contents = text
214
- annotation.color = .clear
215
- if annotation.fontColor == nil {
216
- annotation.fontColor = AnnotationSerializer.colorFromHex(annotationColor) ?? .red
217
- }
218
-
206
+ private func updateFreeTextAnnotation(_ annotation: PDFAnnotation, text: String, on page: PDFPage) {
207
+ guard var model = AnnotationSerializer.toModel(from: annotation, page: pdfView.document?.index(for: page) ?? 0),
208
+ let bounds = model.bounds else { return }
209
+ let font = annotation.font ?? UIFont.systemFont(ofSize: model.fontSize ?? 16)
210
+ model.contents = text
211
+ model.bounds = AnnotationBounds(measuredTextBounds(text: text, font: font, replacing: bounds.cgRect))
212
+ guard let replacement = AnnotationSerializer.toPDFAnnotation(
213
+ model, pageBounds: page.bounds(for: .cropBox), pageRotation: page.rotation
214
+ ) else { return }
215
+ page.removeAnnotation(annotation)
216
+ page.addAnnotation(replacement)
219
217
  emitAnnotationsChanged()
220
218
  }
221
219
 
@@ -243,7 +241,8 @@ extension ExpoPdfMarkupView {
243
241
  }
244
242
 
245
243
  private func measuredTextSize(text: String, font: UIFont) -> CGSize {
246
- (text as NSString).size(withAttributes: [.font: font])
244
+ let size = (text as NSString).size(withAttributes: [.font: font])
245
+ return CGSize(width: ceil(size.width), height: ceil(size.height))
247
246
  }
248
247
 
249
248
  private func findViewController() -> UIViewController? {
@@ -18,7 +18,20 @@ enum AnnotationSerializer {
18
18
 
19
19
  // MARK: - PDFAnnotation ↔ AnnotationModel
20
20
 
21
- static func toPDFAnnotation(_ model: AnnotationModel, pageBounds: CGRect? = nil) -> PDFAnnotation? {
21
+ static func toPDFAnnotation(_ model: AnnotationModel, pageBounds: CGRect? = nil,
22
+ pageRotation: Int = 0) -> PDFAnnotation? {
23
+ let coordinates = AnnotationCoordinates(bounds: pageBounds ?? .zero, rotation: pageRotation)
24
+ var visibleModel = model
25
+ if model.type == "text" || model.type == "freeText", let bounds = model.bounds {
26
+ let size = model.fontSize ?? 16
27
+ let font = UIFont(name: model.fontFamily ?? "", size: size) ?? UIFont.systemFont(ofSize: size)
28
+ visibleModel.bounds = AnnotationBounds(normalizedFreeTextBounds(
29
+ bounds: bounds.cgRect,
30
+ text: model.contents ?? "",
31
+ font: font
32
+ ))
33
+ }
34
+ let model = coordinates.transform(visibleModel, using: coordinates.visibleToNative)
22
35
  let color = colorFromHex(model.color) ?? .red
23
36
 
24
37
  switch model.type {
@@ -46,7 +59,8 @@ enum AnnotationSerializer {
46
59
  forAnnotationKey: PDFAnnotationKey(rawValue: "_createdAt")
47
60
  ) as? Double ?? Date().timeIntervalSince1970
48
61
 
49
- guard let type = modelType(for: annotation.type) else { return nil }
62
+ guard let nativeType = modelType(for: annotation.type) else { return nil }
63
+ let type = annotation.value(forAnnotationKey: PDFAnnotationKey(rawValue: "_modelType")) as? String ?? nativeType
50
64
  var model = AnnotationModel(
51
65
  id: id,
52
66
  type: type,
@@ -56,8 +70,8 @@ enum AnnotationSerializer {
56
70
  )
57
71
 
58
72
  populateModelDetails(&model, from: annotation)
59
-
60
- return model
73
+ let coordinates = annotation.page.map { AnnotationCoordinates(page: $0) } ?? AnnotationCoordinates(bounds: .zero)
74
+ return coordinates.transform(model, using: coordinates.nativeToVisible)
61
75
  }
62
76
 
63
77
  private static func modelType(for annotationType: String?) -> String? {
@@ -101,12 +115,12 @@ enum AnnotationSerializer {
101
115
  // type declares it non-optional, and `JSONEncoder` drops nil keys entirely, so a
102
116
  // nil here reaches consumers as a missing property rather than an empty stroke list.
103
117
  model.paths = (annotation.paths ?? []).map { path in
104
- pointsFromBezierPath(path).map { ["x": $0.x, "y": $0.y] }
118
+ pointsFromBezierPath(path).map { ["x": $0.x + annotation.bounds.minX, "y": $0.y + annotation.bounds.minY] }
105
119
  }
106
120
  case "highlight", "underline":
107
- model.bounds = AnnotationBounds(annotation.bounds)
121
+ model.bounds = AnnotationBounds((annotation as? AreaUnderlinePDFAnnotation)?.contentBounds ?? annotation.bounds)
108
122
  if model.type == "highlight" {
109
- model.alpha = 0.5
123
+ model.alpha = annotation.color.cgColor.alpha
110
124
  }
111
125
  case "text", "freeText":
112
126
  model.bounds = AnnotationBounds(annotation.bounds)
@@ -116,7 +130,7 @@ enum AnnotationSerializer {
116
130
  model.fontFamily = font.fontName
117
131
  }
118
132
  case "stamp":
119
- model.bounds = AnnotationBounds(annotation.bounds)
133
+ model.bounds = AnnotationBounds((annotation as? StampPDFAnnotation)?.contentBounds ?? annotation.bounds)
120
134
  if let stamp = annotation as? StampPDFAnnotation {
121
135
  model.text = stamp.stampText
122
136
  }
@@ -221,9 +235,9 @@ enum AnnotationSerializer {
221
235
  let bezierPath = UIBezierPath()
222
236
  for (index, point) in path.enumerated() {
223
237
  if index == 0 {
224
- bezierPath.move(to: CGPoint(x: point.x, y: point.y))
238
+ bezierPath.move(to: CGPoint(x: point.x - annotationBounds.minX, y: point.y - annotationBounds.minY))
225
239
  } else {
226
- bezierPath.addLine(to: CGPoint(x: point.x, y: point.y))
240
+ bezierPath.addLine(to: CGPoint(x: point.x - annotationBounds.minX, y: point.y - annotationBounds.minY))
227
241
  }
228
242
  }
229
243
  annotation.add(bezierPath)
@@ -240,7 +254,14 @@ enum AnnotationSerializer {
240
254
  subtype: PDFAnnotationSubtype
241
255
  ) -> PDFAnnotation? {
242
256
  guard let bounds = model.bounds else { return nil }
243
- let annotation = PDFAnnotation(bounds: bounds.cgRect, forType: subtype, withProperties: nil)
257
+ let annotation: PDFAnnotation = subtype == .underline
258
+ ? AreaUnderlinePDFAnnotation(bounds: bounds.cgRect, forType: .stamp, withProperties: nil)
259
+ : PDFAnnotation(bounds: bounds.cgRect, forType: subtype, withProperties: nil)
260
+ if subtype == .underline {
261
+ // PDFKit's live underline view bypasses draw(with:in:). A custom stamp
262
+ // appearance invokes our renderer while the shared model remains underline.
263
+ annotation.setValue("underline", forAnnotationKey: PDFAnnotationKey(rawValue: "_modelType"))
264
+ }
244
265
  let alpha = model.alpha ?? (subtype == .highlight ? 0.5 : 1.0)
245
266
  annotation.color = color.withAlphaComponent(alpha)
246
267
 
@@ -255,7 +276,7 @@ enum AnnotationSerializer {
255
276
  let font = UIFont(name: model.fontFamily ?? "", size: fontSize) ?? UIFont.systemFont(ofSize: fontSize)
256
277
  let contents = model.contents ?? ""
257
278
  let annotation = PDFAnnotation(
258
- bounds: normalizedFreeTextBounds(bounds: bounds.cgRect, text: contents, font: font),
279
+ bounds: bounds.cgRect,
259
280
  forType: .freeText,
260
281
  withProperties: nil
261
282
  )
@@ -263,6 +284,7 @@ enum AnnotationSerializer {
263
284
  annotation.fontColor = color
264
285
  annotation.color = .clear
265
286
  annotation.contents = contents
287
+ annotation.setValue(model.type, forAnnotationKey: PDFAnnotationKey(rawValue: "_modelType"))
266
288
 
267
289
  let createdAt = model.createdAt ?? Date().timeIntervalSince1970
268
290
  tagAsModuleManaged(annotation, id: model.id, createdAt: createdAt, colorHex: model.color)
@@ -316,3 +338,68 @@ enum AnnotationSerializer {
316
338
  return points
317
339
  }
318
340
  }
341
+
342
+ /// Interchange coordinates are zero-origin, y-up points on the visible, rotated page.
343
+ /// PDFKit uses unrotated page coordinates; ink paths additionally use annotation-local points.
344
+ struct AnnotationCoordinates {
345
+ /// Separate the live appearance clip from its content, including full-page marks.
346
+ static let appearancePadding: CGFloat = 2
347
+ private let nativeBounds: CGRect
348
+ let nativeToVisible: CGAffineTransform
349
+ var visibleToNative: CGAffineTransform {
350
+ nativeToVisible.inverted()
351
+ }
352
+
353
+ let visibleBounds: CGRect
354
+
355
+ init(page: PDFPage) {
356
+ self.init(bounds: page.bounds(for: .cropBox), rotation: page.rotation)
357
+ }
358
+
359
+ init(bounds: CGRect, rotation: Int = 0) {
360
+ nativeBounds = bounds
361
+ switch (rotation % 360 + 360) % 360 {
362
+ case 90:
363
+ nativeToVisible = CGAffineTransform(a: 0, b: -1, c: 1, d: 0, tx: -bounds.minY, ty: bounds.maxX)
364
+ visibleBounds = CGRect(x: 0, y: 0, width: bounds.height, height: bounds.width)
365
+ case 180:
366
+ nativeToVisible = CGAffineTransform(a: -1, b: 0, c: 0, d: -1, tx: bounds.maxX, ty: bounds.maxY)
367
+ visibleBounds = CGRect(origin: .zero, size: bounds.size)
368
+ case 270:
369
+ nativeToVisible = CGAffineTransform(a: 0, b: 1, c: -1, d: 0, tx: bounds.maxY, ty: -bounds.minX)
370
+ visibleBounds = CGRect(x: 0, y: 0, width: bounds.height, height: bounds.width)
371
+ default:
372
+ nativeToVisible = CGAffineTransform(translationX: -bounds.minX, y: -bounds.minY)
373
+ visibleBounds = CGRect(origin: .zero, size: bounds.size)
374
+ }
375
+ }
376
+
377
+ /// PDFKit clips a recorded live appearance to the native, crop-relative annotation
378
+ /// rectangle. Whole-page renderers instead clip to the visible page. Match that
379
+ /// geometry before adapting custom drawing; do not call bitmap-only context APIs
380
+ /// on PDFKit's vector appearance contexts.
381
+ func prepareForDrawing(in context: CGContext, annotationBounds: CGRect) {
382
+ let clip = context.boundingBoxOfClipPath
383
+ let localBounds = annotationBounds.offsetBy(dx: -nativeBounds.minX, dy: -nativeBounds.minY)
384
+ let tolerance: CGFloat = 1
385
+ guard localBounds.insetBy(dx: -tolerance, dy: -tolerance).contains(clip),
386
+ clip.insetBy(dx: -tolerance, dy: -tolerance).contains(localBounds) else { return }
387
+ context.concatenate(visibleToNative.concatenating(
388
+ CGAffineTransform(translationX: -nativeBounds.minX, y: -nativeBounds.minY)
389
+ ))
390
+ }
391
+
392
+ func transform(_ model: AnnotationModel, using transform: CGAffineTransform) -> AnnotationModel {
393
+ var result = model
394
+ if let bounds = model.bounds { result.bounds = AnnotationBounds(bounds.cgRect.applying(transform)) }
395
+ if model.paths != nil {
396
+ result.paths = model.encodedPaths(from: model.decodedPaths.map { stroke in
397
+ stroke.map { point in
398
+ let converted = CGPoint(x: point.x, y: point.y).applying(transform)
399
+ return AnnotationPoint(x: converted.x, y: converted.y)
400
+ }
401
+ })
402
+ }
403
+ return result
404
+ }
405
+ }
@@ -84,35 +84,20 @@ extension ExpoPdfMarkupView {
84
84
  let pdfViewMidPoint = pdfView.convert(midPoint, from: self)
85
85
  guard let page = pdfView.page(for: pdfViewMidPoint, nearest: true) else { return }
86
86
 
87
- // Convert all display points to PDF page coordinates
88
- let pdfPoints = inkPoints.map { displayPoint -> CGPoint in
89
- let pdfViewPoint = pdfView.convert(displayPoint, from: self)
90
- return pdfView.convert(pdfViewPoint, to: page)
87
+ let coordinates = AnnotationCoordinates(page: page)
88
+ let points = inkPoints.map { displayPoint -> [String: CGFloat] in
89
+ let location = pdfView.convert(displayPoint, from: self)
90
+ let point = pdfView.convert(location, to: page).applying(coordinates.nativeToVisible)
91
+ return ["x": point.x, "y": point.y]
91
92
  }
92
-
93
- // Use the full page bounds — PDFKit clips ink rendering to annotation bounds,
94
- // and tight bounds calculations are fragile with coordinate transforms.
95
- let annotationBounds = page.bounds(for: pdfView.displayBox)
96
-
97
- let annotation = PDFAnnotation(bounds: annotationBounds, forType: .ink, withProperties: nil)
98
- annotation.color = AnnotationSerializer.colorFromHex(annotationColor) ?? .red
99
-
100
- let border = PDFBorder()
101
- border.lineWidth = annotationLineWidth
102
- annotation.border = border
103
-
104
- let bezierPath = UIBezierPath()
105
- for (index, point) in pdfPoints.enumerated() {
106
- if index == 0 {
107
- bezierPath.move(to: point)
108
- } else {
109
- bezierPath.addLine(to: point)
110
- }
111
- }
112
- annotation.add(bezierPath)
113
-
114
- let id = UUID().uuidString
115
- AnnotationSerializer.tagAsModuleManaged(annotation, id: id, createdAt: Date().timeIntervalSince1970)
93
+ let model = AnnotationModel(id: UUID().uuidString, type: "ink", page: 0,
94
+ color: annotationColor, lineWidth: annotationLineWidth, paths: [points],
95
+ createdAt: Date().timeIntervalSince1970)
96
+ guard let annotation = AnnotationSerializer.toPDFAnnotation(
97
+ model,
98
+ pageBounds: page.bounds(for: .cropBox),
99
+ pageRotation: page.rotation
100
+ ) else { return }
116
101
  page.addAnnotation(annotation)
117
102
 
118
103
  emitAnnotationsChanged()