@tobyt/expo-pdf-markup 2.0.0 → 2.1.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.
Files changed (47) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +58 -0
  3. package/android/src/main/java/dev/terhoeven/expopdfmarkup/AnnotationModel.kt +12 -0
  4. package/android/src/main/java/dev/terhoeven/expopdfmarkup/AnnotationSerializer.kt +92 -15
  5. package/android/src/main/java/dev/terhoeven/expopdfmarkup/AnnotationsChangeEmitter.kt +31 -0
  6. package/android/src/main/java/dev/terhoeven/expopdfmarkup/ExpoPdfMarkupModule.kt +4 -0
  7. package/android/src/main/java/dev/terhoeven/expopdfmarkup/ExpoPdfMarkupView.kt +10 -13
  8. package/build/ExpoPdfMarkup.types.d.ts +24 -0
  9. package/build/ExpoPdfMarkup.types.d.ts.map +1 -1
  10. package/build/ExpoPdfMarkup.types.js.map +1 -1
  11. package/build/ExpoPdfMarkupView.web.d.ts.map +1 -1
  12. package/build/ExpoPdfMarkupView.web.js +5 -5
  13. package/build/ExpoPdfMarkupView.web.js.map +1 -1
  14. package/build/index.d.ts +1 -0
  15. package/build/index.d.ts.map +1 -1
  16. package/build/index.js +1 -0
  17. package/build/index.js.map +1 -1
  18. package/build/parseAnnotations.d.ts +11 -0
  19. package/build/parseAnnotations.d.ts.map +1 -0
  20. package/build/parseAnnotations.js +49 -0
  21. package/build/parseAnnotations.js.map +1 -0
  22. package/build/web/annotationUtils.d.ts +12 -3
  23. package/build/web/annotationUtils.d.ts.map +1 -1
  24. package/build/web/annotationUtils.js +57 -12
  25. package/build/web/annotationUtils.js.map +1 -1
  26. package/fixtures/annotations-v1-array.json +124 -0
  27. package/fixtures/ink-cleanup-expected-array.json +95 -0
  28. package/fixtures/ink-cleanup-expected-object.json +95 -0
  29. package/fixtures/ink-cleanup-input.json +99 -0
  30. package/ios/AnnotationModels.swift +159 -0
  31. package/ios/AnnotationSerializer.swift +4 -2
  32. package/ios/ExpoPdfMarkupModule.swift +4 -0
  33. package/ios/ExpoPdfMarkupView.swift +8 -2
  34. package/ios/Tests/AnnotationCoordinateTests.swift +87 -0
  35. package/ios/Tests/AnnotationSerializerTests.swift +158 -1
  36. package/ios/Tests/BookModeTests.swift +11 -7
  37. package/ios/Tests/ExpoPdfMarkupViewTests.swift +122 -0
  38. package/package.json +40 -25
  39. package/src/ExpoPdfMarkup.types.ts +26 -0
  40. package/src/ExpoPdfMarkupView.web.tsx +5 -4
  41. package/src/index.ts +1 -0
  42. package/src/parseAnnotations.ts +52 -0
  43. package/src/web/annotationUtils.ts +70 -11
  44. package/docs/agents/domain.md +0 -51
  45. package/docs/agents/issue-tracker.md +0 -46
  46. package/docs/agents/triage-labels.md +0 -15
  47. package/tsconfig.test.json +0 -10
@@ -44,6 +44,128 @@ final class ExpoPdfMarkupViewTests: XCTestCase {
44
44
  window.isHidden = true
45
45
  }
46
46
 
47
+ /// Shows a one-page document with a cropped page and returns a function that maps
48
+ /// page points to view points for driving the ink overlay.
49
+ @MainActor private func showCroppedPage() throws -> (window: UIWindow, touch: (CGFloat, CGFloat) -> CGPoint) {
50
+ let renderer = UIGraphicsPDFRenderer(bounds: CGRect(x: 0, y: 0, width: 800, height: 1000))
51
+ let document = try XCTUnwrap(PDFDocument(data: renderer.pdfData { context in context.beginPage() }))
52
+ let page = try XCTUnwrap(document.page(at: 0))
53
+ page.setBounds(CGRect(x: 100, y: 80, width: 600, height: 840), for: .cropBox)
54
+ let window = UIWindow(frame: CGRect(x: 0, y: 0, width: 400, height: 700))
55
+ let controller = UIViewController()
56
+ window.rootViewController = controller
57
+ window.makeKeyAndVisible()
58
+ view.frame = controller.view.bounds
59
+ controller.view.addSubview(view)
60
+ view.pdfView.document = document
61
+ view.layoutIfNeeded()
62
+ view.pdfView.layoutDocumentView()
63
+ let view = view!
64
+ return (window, { x, y in view.convert(view.pdfView.convert(CGPoint(x: x, y: y), from: page), from: view.pdfView) })
65
+ }
66
+
67
+ /// Draws one stroke through the ink gesture path; visible points are the page points minus the
68
+ /// crop origin (100, 80), so it is written as (80, 120) -> (130.3, 170.7).
69
+ @MainActor private func drawUncleanStroke(_ touch: (CGFloat, CGFloat) -> CGPoint) throws {
70
+ view.setAnnotationMode("ink")
71
+ let overlay = try XCTUnwrap(view.inkOverlayView)
72
+ overlay.onBegan?(touch(180.0123, 200.0187))
73
+ overlay.onMoved?(touch(180.0391, 199.9822)) // same as the first point once rounded
74
+ overlay.onMoved?(touch(230.3317, 250.6871))
75
+ overlay.onEnded?()
76
+ }
77
+
78
+ private func writtenInkPoints(_ json: String) throws -> [Any] {
79
+ let written = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any])
80
+ let annotations = try XCTUnwrap(written["annotations"] as? [[String: Any]])
81
+ return annotations.filter { $0["type"] as? String == "ink" }.flatMap { annotation in
82
+ ((annotation["paths"] as? [[Any]]) ?? []).flatMap { $0 }
83
+ }
84
+ }
85
+
86
+ @MainActor func testDrawnInkStrokeIsCleanedUpInAnnotationsChange() throws {
87
+ let (window, touch) = try showCroppedPage()
88
+ defer { window.isHidden = true }
89
+
90
+ try drawUncleanStroke(touch)
91
+
92
+ let json = try XCTUnwrap(view.currentAnnotationsJSON)
93
+ XCTAssertEqual(try writtenInkPoints(json) as? [[String: Double]], [["x": 80, "y": 120], ["x": 130.3, "y": 170.7]])
94
+ XCTAssertTrue(json.contains(#""x":80"#) && json.contains(#""y":120"#), json)
95
+ XCTAssertTrue(json.contains(#""x":130.3"#) && json.contains(#""y":170.7"#), json)
96
+ }
97
+
98
+ @MainActor func testDrawnInkStrokeIsWrittenInArrayFormWithInkPointFormatArray() throws {
99
+ let (window, touch) = try showCroppedPage()
100
+ defer { window.isHidden = true }
101
+ view.inkPointFormat = .array
102
+
103
+ try drawUncleanStroke(touch)
104
+
105
+ let json = try XCTUnwrap(view.currentAnnotationsJSON)
106
+ XCTAssertEqual(try writtenInkPoints(json) as? [[Double]], [[80, 120], [130.3, 170.7]])
107
+ XCTAssertTrue(json.contains("[[80,120],[130.3,170.7]]"), json)
108
+ }
109
+
110
+ /// Records every payload actually dispatched through `onAnnotationsChanged`.
111
+ private func recordAnnotationsChangedEvents() -> () -> [[String: Any]] {
112
+ var events: [[String: Any]] = []
113
+ view.onAnnotationsChanged.onEventSent = { events.append($0) }
114
+ return { events }
115
+ }
116
+
117
+ @MainActor func testChangingInkPointFormatAloneWritesNothing() throws {
118
+ let (window, touch) = try showCroppedPage()
119
+ defer { window.isHidden = true }
120
+ let events = recordAnnotationsChangedEvents()
121
+
122
+ view.inkPointFormat = .array
123
+ view.inkPointFormat = .object
124
+ XCTAssertEqual(events().count, 0)
125
+
126
+ try drawUncleanStroke(touch)
127
+ XCTAssertEqual(events().count, 1)
128
+ let written = view.currentAnnotationsJSON
129
+
130
+ view.inkPointFormat = .array
131
+ XCTAssertEqual(events().count, 1)
132
+ XCTAssertEqual(view.currentAnnotationsJSON, written)
133
+ }
134
+
135
+ @MainActor func testLoadingAnAnnotationSetWritesNothing() throws {
136
+ let (window, _) = try showCroppedPage()
137
+ defer { window.isHidden = true }
138
+ let events = recordAnnotationsChangedEvents()
139
+ view.inkPointFormat = .array
140
+
141
+ for fixture in ["ink-cleanup-input", "annotations-v1-array"] {
142
+ let url = try XCTUnwrap(Bundle(for: type(of: self)).url(forResource: fixture, withExtension: "json"))
143
+ try view.loadAnnotations(from: String(contentsOf: url, encoding: .utf8))
144
+ }
145
+
146
+ XCTAssertEqual(events().count, 0)
147
+ }
148
+
149
+ @MainActor func testSetsLoadedInEitherFormAreWrittenInTheChosenFormOnTheNextEdit() throws {
150
+ for (fixture, format) in [("annotations-v1", InkPointFormat.array), ("annotations-v1-array", .object)] {
151
+ let (window, touch) = try showCroppedPage()
152
+ defer { window.isHidden = true }
153
+ let url = try XCTUnwrap(Bundle(for: type(of: self)).url(forResource: fixture, withExtension: "json"))
154
+ try view.loadAnnotations(from: String(contentsOf: url, encoding: .utf8))
155
+ view.inkPointFormat = format
156
+
157
+ try drawUncleanStroke(touch)
158
+
159
+ let points = try writtenInkPoints(XCTUnwrap(view.currentAnnotationsJSON))
160
+ XCTAssertGreaterThan(points.count, 2, fixture)
161
+ for point in points {
162
+ XCTAssertEqual(point is [Double], format == .array, "\(fixture): \(point)")
163
+ }
164
+ view.removeFromSuperview()
165
+ view = ExpoPdfMarkupView(appContext: nil)
166
+ }
167
+ }
168
+
47
169
  // MARK: - Initial state
48
170
 
49
171
  func testInitialState() {
package/package.json CHANGED
@@ -1,40 +1,40 @@
1
1
  {
2
2
  "name": "@tobyt/expo-pdf-markup",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "description": "An Expo module for displaying and annotating PDFs",
5
5
  "main": "build/index.js",
6
6
  "types": "build/index.d.ts",
7
7
  "scripts": {
8
- "build": "expo-module build",
9
- "clean": "expo-module clean",
10
- "lint": "expo-module lint",
8
+ "build": "tsc -p tsconfig.json",
9
+ "clean": "node -e \"require('node:fs').rmSync('build', { recursive: true, force: true })\"",
10
+ "lint": "eslint src scripts/lib scripts/release scripts/repo-settings",
11
11
  "lint:swift": "swiftlint lint ios/",
12
12
  "lint:kotlin": "ktlint 'android/src/**/*.kt'",
13
- "format": "node ./node_modules/prettier/bin/prettier.cjs --write \"src/**/*.{ts,tsx}\"",
14
- "format:check": "node ./node_modules/prettier/bin/prettier.cjs --check \"src/**/*.{ts,tsx}\"",
13
+ "lint:workflows": "bash scripts/lint-workflows.sh",
14
+ "format": "node ./node_modules/prettier/bin/prettier.cjs --write \"src/**/*.{ts,tsx}\" \"scripts/{lib,release,repo-settings}/**/*.ts\"",
15
+ "format:check": "node ./node_modules/prettier/bin/prettier.cjs --check \"src/**/*.{ts,tsx}\" \"scripts/{lib,release,repo-settings}/**/*.ts\"",
15
16
  "format:swift": "swiftformat ios/",
16
17
  "format:swift:check": "swiftformat --lint ios/",
17
18
  "format:kotlin": "ktlint --format 'android/src/**/*.kt'",
18
19
  "format:kotlin:check": "ktlint 'android/src/**/*.kt'",
19
- "test": "expo-module test",
20
+ "test": "jest",
20
21
  "test:swift": "bash scripts/test-swift.sh",
21
22
  "test:kotlin": "cd example/android && ./gradlew :tobyt-expo-pdf-markup:testDebugUnitTest",
22
- "typecheck": "expo-module typecheck",
23
+ "typecheck": "tsc -p tsconfig.json --noEmit",
23
24
  "typecheck:tests": "tsc -p tsconfig.test.json",
24
- "qa:ts": "export EXPO_NONINTERACTIVE=1 && npm run typecheck && npm run typecheck:tests && npm run format && npm run lint && npm run test",
25
+ "qa:ts": "npm run typecheck && npm run typecheck:tests && npm run format && npm run lint && npm run lint:workflows && npm run test",
25
26
  "qa:ios": "npm run format:swift && npm run lint:swift && npm run test:swift",
26
27
  "qa:android": "npm run format:kotlin && npm run lint:kotlin && npm run test:kotlin",
27
28
  "qa": "npm run qa:ts && npm run qa:ios && npm run qa:android",
28
- "prepare": "expo-module prepare",
29
- "prepublishOnly": "expo-module prepublishOnly",
30
- "expo-module": "expo-module",
29
+ "prepublishOnly": "npm run clean && npm run build",
31
30
  "open:ios": "xed example/ios",
32
31
  "open:android": "open -a \"Android Studio\" example/android",
33
32
  "docs": "typedoc",
33
+ "settings:check": "node scripts/repo-settings/settings.cli.ts --check",
34
+ "settings:apply": "node scripts/repo-settings/settings.cli.ts apply",
34
35
  "changeset": "changeset",
35
36
  "changeset:add": "changeset add",
36
- "changeset:version": "changeset version",
37
- "release": "bash scripts/release.sh"
37
+ "changeset:version": "changeset version"
38
38
  },
39
39
  "keywords": [
40
40
  "react-native",
@@ -42,7 +42,10 @@
42
42
  "@tobyt/expo-pdf-markup",
43
43
  "ExpoPdfMarkup"
44
44
  ],
45
- "repository": "https://github.com/tobyt42/expo-pdf-markup",
45
+ "repository": {
46
+ "type": "git",
47
+ "url": "git+https://github.com/tobyt42/expo-pdf-markup.git"
48
+ },
46
49
  "bugs": {
47
50
  "url": "https://github.com/tobyt42/expo-pdf-markup/issues"
48
51
  },
@@ -54,17 +57,29 @@
54
57
  },
55
58
  "devDependencies": {
56
59
  "@changesets/cli": "^3.0.1",
57
- "@types/react": "~19.2.17",
58
- "@types/react-test-renderer": "^19.1.0",
59
- "expo": "~56.0.16",
60
- "expo-module-scripts": "^56.0.3",
60
+ "@changesets/read": "^1.0.1",
61
+ "@react-native/jest-preset": "^0.88.1",
62
+ "@types/jest": "^30.0.0",
63
+ "@types/node": "^24.0.0",
64
+ "@types/react": "~19.3.0",
65
+ "@types/semver": "^7.8.0",
66
+ "eslint": "^9.39.5",
67
+ "eslint-config-expo": "~58.0.4",
68
+ "expo": "~58.0.26",
69
+ "expo-modules-core": "~58.1.0",
70
+ "globals": "^16.5.0",
71
+ "jest": "^30.5.2",
72
+ "jest-environment-jsdom": "^30.5.2",
73
+ "jest-expo": "~58.0.15",
61
74
  "pdfjs-dist": "^6.1.200",
62
- "react-native": "^0.85.3",
63
- "react-native-web": "^0.21.2",
64
- "typedoc": "^0.28.17"
65
- },
66
- "jest": {
67
- "preset": "expo-module-scripts"
75
+ "prettier": "^3.9.5",
76
+ "react": "19.3.0",
77
+ "react-dom": "19.3.0",
78
+ "react-native": "0.88.1",
79
+ "react-native-web": "^0.21.4",
80
+ "semver": "^7.8.6",
81
+ "typedoc": "^0.28.17",
82
+ "typescript": "~5.9.3"
68
83
  },
69
84
  "peerDependencies": {
70
85
  "expo": "*",
@@ -3,6 +3,20 @@ import type { StyleProp, ViewStyle } from 'react-native';
3
3
  /** Zero-origin visible-page points after page rotation, in PDF points with y increasing upward. */
4
4
  export type AnnotationPoint = { x: number; y: number };
5
5
 
6
+ /**
7
+ * An ink point in array form (`[x, y]`), as it may appear in raw annotation set JSON.
8
+ * Use `parseAnnotations` to read raw JSON; it always returns ink points as {@link AnnotationPoint}.
9
+ */
10
+ export type AnnotationPointArray = [number, number];
11
+
12
+ /**
13
+ * How ink points are written in annotation set JSON:
14
+ * - `'object'`: `{"x": 12.3, "y": 45.6}`, readable by every release of this library.
15
+ * - `'array'`: `[12.3, 45.6]`, shorter, but only readable by releases that include the
16
+ * array-form readers (see {@link ExpoPdfMarkupViewProps.inkPointFormat}).
17
+ */
18
+ export type InkPointFormat = 'object' | 'array';
19
+
6
20
  /** Visible-page rectangle; x/y locate its bottom-left corner. See docs/annotation-coordinates.md. */
7
21
  export type AnnotationBounds = { x: number; y: number; width: number; height: number };
8
22
 
@@ -116,6 +130,18 @@ export type ExpoPdfMarkupViewProps = {
116
130
  backgroundColor?: string;
117
131
  /** Serialised {@link AnnotationsData} JSON string to load when the document opens. */
118
132
  annotations?: string;
133
+ /**
134
+ * How ink points are written in the annotation set JSON passed to `onAnnotationsChanged`:
135
+ * `'object'` (`{"x": …, "y": …}`, the default) or `'array'` (`[x, y]`, smaller). Ink points are
136
+ * rounded to 0.1 pt and consecutive duplicates dropped in both forms, and `version` stays 1.
137
+ *
138
+ * Rollout rule: only choose `'array'` once every version of your app that might read the
139
+ * annotation set includes the release of this library with the array-form readers. Older
140
+ * releases can't read array form (iOS rejects the whole set, Android throws, web draws `NaN`).
141
+ *
142
+ * Changing this prop writes nothing by itself; it applies from the next edit.
143
+ */
144
+ inkPointFormat?: InkPointFormat;
119
145
  /**
120
146
  * Active annotation tool. Defaults to `'none'` (view-only).
121
147
  * On iOS, highlight/underline use a one-finger area drag on scanned and text-bearing pages.
@@ -16,7 +16,7 @@ import {
16
16
  drawAnnotationsOnCanvas,
17
17
  hitTestAnnotation,
18
18
  newAnnotationId,
19
- parseAnnotations,
19
+ parseAnnotationsOrEmpty,
20
20
  serializeAnnotations,
21
21
  translateAnnotation,
22
22
  } from './web/annotationUtils';
@@ -485,6 +485,7 @@ export default function ExpoPdfMarkupView(props: ExpoPdfMarkupViewProps) {
485
485
  page: propPage,
486
486
  backgroundColor = '#f0f0f0',
487
487
  annotations: annotationsProp,
488
+ inkPointFormat = 'object',
488
489
  annotationMode = 'none',
489
490
  annotationColor = '#FF0000',
490
491
  annotationLineWidth = 2,
@@ -559,13 +560,13 @@ export default function ExpoPdfMarkupView(props: ExpoPdfMarkupViewProps) {
559
560
  (updater: (prev: Annotation[]) => Annotation[]) => {
560
561
  setAnnotations((prev) => {
561
562
  const next = updater(prev);
562
- const json = serializeAnnotations({ version: 1, annotations: next });
563
+ const json = serializeAnnotations({ version: 1, annotations: next }, { inkPointFormat });
563
564
  lastAnnotationsJsonRef.current = json;
564
565
  onAnnotationsChanged?.({ nativeEvent: { annotations: json } });
565
566
  return next;
566
567
  });
567
568
  },
568
- [onAnnotationsChanged]
569
+ [onAnnotationsChanged, inkPointFormat]
569
570
  );
570
571
 
571
572
  // ResizeObserver → containerSize
@@ -732,7 +733,7 @@ export default function ExpoPdfMarkupView(props: ExpoPdfMarkupViewProps) {
732
733
  React.useEffect(() => {
733
734
  if (annotationsProp === lastAnnotationsJsonRef.current) return;
734
735
  lastAnnotationsJsonRef.current = annotationsProp;
735
- const parsed = parseAnnotations(annotationsProp);
736
+ const parsed = parseAnnotationsOrEmpty(annotationsProp);
736
737
  setAnnotations(parsed.annotations);
737
738
  }, [annotationsProp]);
738
739
 
package/src/index.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export { default as ExpoPdfMarkupView } from './ExpoPdfMarkupView';
2
2
  export { setPdfJsWorkerSrc, setPdfJsWasmUrl } from './pdfjs';
3
3
  export * from './ExpoPdfMarkup.types';
4
+ export { parseAnnotations } from './parseAnnotations';
@@ -0,0 +1,52 @@
1
+ import type { Annotation, AnnotationPoint, AnnotationsData } from './ExpoPdfMarkup.types';
2
+
3
+ // Platform-neutral: this module is exported from the package entry point on every
4
+ // platform, so it must not import anything web-only (e.g. pdfjs).
5
+
6
+ function isFiniteNumber(value: unknown): value is number {
7
+ return typeof value === 'number' && Number.isFinite(value);
8
+ }
9
+
10
+ /** Reads one ink point in object form or array form; returns null if it is malformed. */
11
+ function readInkPoint(raw: unknown): AnnotationPoint | null {
12
+ if (Array.isArray(raw)) {
13
+ if (raw.length !== 2 || !isFiniteNumber(raw[0]) || !isFiniteNumber(raw[1])) return null;
14
+ return { x: raw[0], y: raw[1] };
15
+ }
16
+ if (raw !== null && typeof raw === 'object') {
17
+ const { x, y } = raw as { x?: unknown; y?: unknown };
18
+ if (!isFiniteNumber(x) || !isFiniteNumber(y)) return null;
19
+ return { x, y };
20
+ }
21
+ return null;
22
+ }
23
+
24
+ function readAnnotation(raw: unknown): Annotation {
25
+ if (raw === null || typeof raw !== 'object') return raw as Annotation;
26
+ const { type, paths } = raw as { type?: unknown; paths?: unknown };
27
+ if (type !== 'ink' || !Array.isArray(paths)) return raw as Annotation;
28
+ // A stroke that is not an array is malformed and skipped entirely.
29
+ const strokes = paths.filter((stroke): stroke is unknown[] => Array.isArray(stroke));
30
+ return {
31
+ ...(raw as Annotation),
32
+ paths: strokes.map((stroke) =>
33
+ stroke.map(readInkPoint).filter((point): point is AnnotationPoint => point !== null)
34
+ ),
35
+ } as Annotation;
36
+ }
37
+
38
+ /**
39
+ * Parses a serialised annotation set, accepting ink points in object form
40
+ * (`{"x": …, "y": …}`), array form (`[x, y]`) or a mix of both, and returns
41
+ * every ink point in object form. Malformed ink points, and strokes that are not
42
+ * arrays, are skipped. Values are not rounded.
43
+ *
44
+ * @throws If `json` cannot be parsed or has no `annotations` array.
45
+ */
46
+ export function parseAnnotations(json: string): AnnotationsData {
47
+ const data = JSON.parse(json) as { annotations?: unknown } | null;
48
+ if (!Array.isArray(data?.annotations)) {
49
+ throw new Error('Annotation set JSON has no "annotations" array');
50
+ }
51
+ return { version: 1, annotations: data.annotations.map(readAnnotation) };
52
+ }
@@ -2,8 +2,11 @@ import type {
2
2
  Annotation,
3
3
  AnnotationBounds,
4
4
  AnnotationPoint,
5
+ AnnotationPointArray,
5
6
  AnnotationsData,
7
+ InkPointFormat,
6
8
  } from '../ExpoPdfMarkup.types';
9
+ import { parseAnnotations } from '../parseAnnotations';
7
10
  import type { PdfPageMeta } from './types';
8
11
 
9
12
  // ---------------------------------------------------------------------------
@@ -365,24 +368,80 @@ export function drawAnnotationsOnCanvas(
365
368
  // Serialization
366
369
  // ---------------------------------------------------------------------------
367
370
 
368
- export function parseAnnotations(json?: string): AnnotationsData {
371
+ /** Forgiving variant of the public parser: malformed input becomes an empty set. */
372
+ export function parseAnnotationsOrEmpty(json?: string): AnnotationsData {
369
373
  if (!json) return { version: 1, annotations: [] };
374
+ let data: AnnotationsData;
370
375
  try {
371
- const data = JSON.parse(json) as AnnotationsData;
372
- if (!Array.isArray(data?.annotations)) return { version: 1, annotations: [] };
373
- // Deduplicate by id — last wins
374
- const seen = new Map<string, Annotation>();
375
- for (const a of data.annotations) {
376
- seen.set(a.id, a);
377
- }
378
- return { version: 1, annotations: Array.from(seen.values()) };
376
+ data = parseAnnotations(json);
379
377
  } catch {
380
378
  return { version: 1, annotations: [] };
381
379
  }
380
+ // Deduplicate by id — last wins
381
+ const seen = new Map<string, Annotation>();
382
+ for (const a of data.annotations) {
383
+ seen.set(a.id, a);
384
+ }
385
+ return { version: 1, annotations: Array.from(seen.values()) };
382
386
  }
383
387
 
384
- export function serializeAnnotations(data: AnnotationsData): string {
385
- return JSON.stringify(data);
388
+ /**
389
+ * Round a coordinate to the nearest 0.1 pt, matching the iOS and Android writers:
390
+ * scale by 10 in double precision, round half away from zero, divide by 10.
391
+ * Negative zero becomes zero so it is written as `0`.
392
+ */
393
+ function roundInkCoordinate(value: number): number {
394
+ const scaled = value * 10;
395
+ const rounded = Math.sign(scaled) * Math.round(Math.abs(scaled));
396
+ return rounded / 10 + 0;
397
+ }
398
+
399
+ /**
400
+ * Round each ink point to 0.1 pt and drop consecutive duplicates (compared after
401
+ * rounding). A stroke that collapses to one point keeps two identical points so it
402
+ * still draws as a dot; strokes that started with fewer points are left that short.
403
+ */
404
+ function cleanUpInkStroke(stroke: AnnotationPoint[]): AnnotationPoint[] {
405
+ const cleaned: AnnotationPoint[] = [];
406
+ for (const point of stroke) {
407
+ const rounded = { x: roundInkCoordinate(point.x), y: roundInkCoordinate(point.y) };
408
+ const previous = cleaned[cleaned.length - 1];
409
+ if (previous && previous.x === rounded.x && previous.y === rounded.y) continue;
410
+ cleaned.push(rounded);
411
+ }
412
+ if (stroke.length >= 2 && cleaned.length === 1) {
413
+ cleaned.push({ ...cleaned[0]! });
414
+ }
415
+ return cleaned;
416
+ }
417
+
418
+ export type SerializeOptions = {
419
+ /** How ink points are written; defaults to object form. */
420
+ inkPointFormat?: InkPointFormat;
421
+ };
422
+
423
+ /**
424
+ * Write an annotation set. Ink points are cleaned up here, and only here: in memory
425
+ * they keep full precision. Bounds and every non-ink field are written unchanged.
426
+ */
427
+ export function serializeAnnotations(
428
+ data: AnnotationsData,
429
+ { inkPointFormat = 'object' }: SerializeOptions = {}
430
+ ): string {
431
+ const writeStroke = (stroke: AnnotationPoint[]): (AnnotationPoint | AnnotationPointArray)[] => {
432
+ const cleaned = cleanUpInkStroke(stroke);
433
+ return inkPointFormat === 'array'
434
+ ? cleaned.map((p): AnnotationPointArray => [p.x, p.y])
435
+ : cleaned;
436
+ };
437
+ return JSON.stringify({
438
+ ...data,
439
+ annotations: data.annotations.map((annotation) =>
440
+ annotation.type === 'ink'
441
+ ? { ...annotation, paths: (annotation.paths ?? []).map(writeStroke) }
442
+ : annotation
443
+ ),
444
+ });
386
445
  }
387
446
 
388
447
  export function newAnnotationId(): string {
@@ -1,51 +0,0 @@
1
- # Domain Docs
2
-
3
- How the engineering skills should consume this repo's domain documentation when exploring the codebase.
4
-
5
- ## Before exploring, read these
6
-
7
- - **`GLOSSARY.md`** at the repo root, or
8
- - **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
9
- - **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
10
-
11
- If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
12
-
13
- ## File structure
14
-
15
- Single-context repo (most repos):
16
-
17
- ```
18
- /
19
- ├── GLOSSARY.md
20
- ├── docs/adr/
21
- │ ├── 0001-event-sourced-orders.md
22
- │ └── 0002-postgres-for-write-model.md
23
- └── src/
24
- ```
25
-
26
- Multi-context repo (presence of `GLOSSARY-MAP.md` at the root):
27
-
28
- ```
29
- /
30
- ├── GLOSSARY-MAP.md
31
- ├── docs/adr/ ← system-wide decisions
32
- └── src/
33
- ├── ordering/
34
- │ ├── GLOSSARY.md
35
- │ └── docs/adr/ ← context-specific decisions
36
- └── billing/
37
- ├── GLOSSARY.md
38
- └── docs/adr/
39
- ```
40
-
41
- ## Use the glossary's vocabulary
42
-
43
- When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
44
-
45
- If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
46
-
47
- ## Flag ADR conflicts
48
-
49
- If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
50
-
51
- > _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
@@ -1,46 +0,0 @@
1
- # Issue tracker: GitHub
2
-
3
- Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
4
-
5
- ## Conventions
6
-
7
- - **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
8
- - **Read an issue**: `gh issue view <number> --json number,title,body,labels,comments`.
9
- - **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
10
- - **Make an issue a sub-issue of a parent**: `gh issue create --parent <parent> ...`, or `gh issue edit <parent> --add-sub-issue <child>` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` (database id, as in **Blocking** below). Without sub-issues, put `Part of #<parent>` at the top of the child body.
11
- - **Comment on an issue**: `gh issue comment <number> --body "..."`
12
- - **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
13
- - **Close**: `gh issue close <number> --comment "..."`
14
-
15
- Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
16
-
17
- ## Pull requests as a triage surface
18
-
19
- **PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
20
-
21
- When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
22
-
23
- - **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
24
- - **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
25
- - **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
26
-
27
- GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
28
-
29
- ## When a skill says "publish to the issue tracker"
30
-
31
- Create a GitHub issue.
32
-
33
- ## When a skill says "fetch the relevant ticket"
34
-
35
- Read it as in **Read an issue** above.
36
-
37
- ## Wayfinding operations
38
-
39
- Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
40
-
41
- - **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
42
- - **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
43
- - **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
44
- - **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
45
- - **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
46
- - **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
@@ -1,15 +0,0 @@
1
- # Triage Labels
2
-
3
- The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
4
-
5
- | Label in mattpocock/skills | Label in our tracker | Meaning |
6
- | -------------------------- | -------------------- | ---------------------------------------- |
7
- | `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
8
- | `needs-info` | `needs-info` | Waiting on reporter for more information |
9
- | `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
10
- | `ready-for-human` | `ready-for-human` | Requires human implementation |
11
- | `wontfix` | `wontfix` | Will not be actioned |
12
-
13
- When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
14
-
15
- Edit the "Label in our tracker" column to match whatever vocabulary you actually use.
@@ -1,10 +0,0 @@
1
- // Type-checks the test suites, including the compile-time type tests, which
2
- // Jest (Babel) and `expo-module typecheck` (tests excluded) never type-check.
3
- {
4
- "extends": "./tsconfig.json",
5
- "compilerOptions": {
6
- "noEmit": true
7
- },
8
- "include": ["./src"],
9
- "exclude": []
10
- }