@hussmartinez/pdf-sdk 0.2.0 → 0.4.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.
package/dist/index.d.ts CHANGED
@@ -130,6 +130,60 @@ export declare function linkDestination(url: string): string | undefined;
130
130
  */
131
131
  export declare const PDF_MAX_CANVAS_PIXELS = 16777216;
132
132
 
133
+ /**
134
+ * The most Unicode code points in a form field's name.
135
+ *
136
+ * @public
137
+ */
138
+ export declare const PDF_MAX_FIELD_NAME_LENGTH = 1000;
139
+
140
+ /**
141
+ * The most Unicode code points in a page key, a source id or an annotation
142
+ * id. Lengths count code points, not UTF-16 units (sdk-core ADR 0045).
143
+ *
144
+ * @public
145
+ */
146
+ export declare const PDF_MAX_ID_LENGTH = 128;
147
+
148
+ /**
149
+ * The most points in one pen or highlighter stroke.
150
+ *
151
+ * @public
152
+ */
153
+ export declare const PDF_MAX_STROKE_POINTS = 10000;
154
+
155
+ /**
156
+ * The most Unicode code points in a text note, or a form field's text value.
157
+ *
158
+ * @public
159
+ */
160
+ export declare const PDF_MAX_TEXT_LENGTH = 10000;
161
+
162
+ /**
163
+ * The name of the plan's portable format (sdk-core ADR 0045).
164
+ *
165
+ * @public
166
+ */
167
+ export declare const PDF_PLAN_FORMAT = "hm-pdf-plan";
168
+
169
+ /**
170
+ * The version of {@link PDF_PLAN_FORMAT} this release writes, and the latest
171
+ * it reads.
172
+ *
173
+ * @public
174
+ */
175
+ export declare const PDF_PLAN_VERSION = 1;
176
+
177
+ /**
178
+ * The grid positions and sizes on a page are kept on: millionths of the
179
+ * page (sdk-core ADR 0045, docs/adr/0003). Every position, size, stroke
180
+ * width and text size the session stores is a whole number of millionths,
181
+ * so a document saved in any language reproduces it exactly.
182
+ *
183
+ * @public
184
+ */
185
+ export declare const PDF_POSITION_GRID = 1000000;
186
+
133
187
  /**
134
188
  * Adds an annotation to a page.
135
189
  *
@@ -144,6 +198,19 @@ export declare interface PdfAddAnnotationCommand {
144
198
  readonly index?: number;
145
199
  }
146
200
 
201
+ /**
202
+ * `pdf.addAnnotation` as `hm-pdf-command` writes it, with the annotation's
203
+ * positions and sizes in whole millionths of the page.
204
+ *
205
+ * @public
206
+ */
207
+ export declare interface PdfAddAnnotationCommandDocument {
208
+ readonly type: "pdf.addAnnotation";
209
+ readonly page: string;
210
+ readonly annotation: PdfAnnotationDocument;
211
+ readonly index?: number;
212
+ }
213
+
147
214
  /**
148
215
  * Anything the editor draws on top of a page until it's flattened on export
149
216
  * (ADR 0003). Annotations are plain data, so they can be stored in commands
@@ -153,6 +220,29 @@ export declare interface PdfAddAnnotationCommand {
153
220
  */
154
221
  export declare type PdfAnnotation = PdfStrokeAnnotation | PdfTextAnnotation | PdfImageAnnotation;
155
222
 
223
+ /**
224
+ * An annotation in a plan document. Version 1 has no signatures: their image
225
+ * needs an asset, whose design comes with the signature tool (docs/adr/0003).
226
+ *
227
+ * @public
228
+ */
229
+ export declare type PdfAnnotationDocument = PdfStrokeAnnotationDocument | PdfTextAnnotationDocument;
230
+
231
+ /**
232
+ * A content-addressed reference to binary data, such as a source's file
233
+ * (sdk-core ADR 0045). Documents never inline bytes.
234
+ *
235
+ * @public
236
+ */
237
+ export declare interface PdfAssetReference {
238
+ /** `sha256:` and the lowercase hex SHA-256 of the bytes. */
239
+ readonly asset: string;
240
+ /** The bytes' media type, such as `application/pdf`, in lowercase. */
241
+ readonly mediaType: string;
242
+ /** The size of the bytes. */
243
+ readonly size: number;
244
+ }
245
+
156
246
  /**
157
247
  * Everything needed to build an output document from the page plan, in one
158
248
  * call to the processor (ADR 0003): the sources, the pages in order, and the
@@ -252,7 +342,7 @@ export declare interface PdfCallOptions {
252
342
  }
253
343
 
254
344
  /**
255
- * A colour as `#rrggbb`.
345
+ * A colour as `#rrggbb`, in lowercase.
256
346
  *
257
347
  * @public
258
348
  */
@@ -267,6 +357,56 @@ export declare type PdfColor = `#${string}`;
267
357
  */
268
358
  export declare type PdfCommand = PdfRotatePagesCommand | PdfDeletePagesCommand | PdfRestorePagesCommand | PdfMovePagesCommand | PdfReorderPagesCommand | PdfInsertPagesCommand | PdfSetFieldValueCommand | PdfAddAnnotationCommand | PdfRemoveAnnotationCommand;
269
359
 
360
+ /**
361
+ * A user-level command as portable JSON: `hm-pdf-command` version 1, which
362
+ * `formats/hm-pdf-command/v1.schema.json` describes. Every command but
363
+ * `pdf.restorePages`, an inverse that carries whole pages; only
364
+ * `pdf.addAnnotation` differs from the command in memory.
365
+ *
366
+ * @public
367
+ */
368
+ export declare type PdfCommandDocument = Exclude<PdfCommand, PdfRestorePagesCommand | PdfAddAnnotationCommand> | PdfAddAnnotationCommandDocument;
369
+
370
+ /**
371
+ * Why a command was refused, as a stable token: `details.reason` on the
372
+ * `INVALID_COMMAND` error (sdk-core ADR 0045).
373
+ *
374
+ * - `malformed-command`: not shaped as a command of its type, such as a
375
+ * missing field, a field of the wrong type, an unknown field, an empty
376
+ * list of pages, or an id that's empty or over `PDF_MAX_ID_LENGTH` code
377
+ * points.
378
+ * - `unknown-command`: a `type` the session doesn't know.
379
+ * - `unknown-page`: a page key the plan doesn't have.
380
+ * - `duplicate-page`: a page named twice in one command.
381
+ * - `last-page`: deleting every page; a document keeps at least one.
382
+ * - `invalid-position`: a position outside the plan, or outside a page's
383
+ * annotations.
384
+ * - `invalid-rotation`: an angle that isn't a multiple of 90 degrees from
385
+ * -360 to 360, or a page rotation other than 0, 90, 180 or 270.
386
+ * - `invalid-order`: a new order that doesn't list every page exactly once.
387
+ * - `invalid-keys`: an insert without one key per page.
388
+ * - `duplicate-key`: a new page key the plan already has, or one given twice.
389
+ * - `unknown-source`: a source the session doesn't hold.
390
+ * - `page-out-of-range`: a page index its source doesn't have.
391
+ * - `field-name-too-long`: a form field's name over
392
+ * `PDF_MAX_FIELD_NAME_LENGTH` code points.
393
+ * - `text-too-long`: a text note, or a field's text value, over
394
+ * `PDF_MAX_TEXT_LENGTH` code points.
395
+ * - `unknown-annotation`: an annotation id the page doesn't have.
396
+ * - `duplicate-annotation`: an annotation id the page already has.
397
+ * - `unsupported-annotation`: an annotation type the session doesn't edit,
398
+ * such as `signature`, whose image the portable format can't carry yet.
399
+ * - `outside-page`: a position outside the page, 0 to 1 on each axis.
400
+ * - `invalid-size`: a stroke width or text size that isn't more than 0 and
401
+ * at most 1, after snapping to `PDF_POSITION_GRID`.
402
+ * - `too-many-points`: a stroke with no points, or over
403
+ * `PDF_MAX_STROKE_POINTS`.
404
+ * - `invalid-color`: a colour that isn't `#rrggbb` in lowercase.
405
+ *
406
+ * @public
407
+ */
408
+ export declare type PdfCommandRejection = "malformed-command" | "unknown-command" | "unknown-page" | "duplicate-page" | "last-page" | "invalid-position" | "invalid-rotation" | "invalid-order" | "invalid-keys" | "duplicate-key" | "unknown-source" | "page-out-of-range" | "field-name-too-long" | "text-too-long" | "unknown-annotation" | "duplicate-annotation" | "unsupported-annotation" | "outside-page" | "invalid-size" | "too-many-points" | "invalid-color";
409
+
270
410
  /**
271
411
  * How to compress the output. Compression is lossless unless `images` is set.
272
412
  *
@@ -330,6 +470,37 @@ export declare interface PdfDocumentHandle {
330
470
  destroy(): Promise<void>;
331
471
  }
332
472
 
473
+ /**
474
+ * A point in a plan document: whole millionths of the page, from 0 to
475
+ * {@link PDF_POSITION_GRID}.
476
+ *
477
+ * @public
478
+ */
479
+ export declare interface PdfDocumentPoint {
480
+ readonly x: number;
481
+ readonly y: number;
482
+ }
483
+
484
+ /**
485
+ * Why a plan document was refused, as a stable token: `details.reason` on
486
+ * the error (sdk-core ADR 0045).
487
+ *
488
+ * - With `UNSUPPORTED_FORMAT`: `unknown-format`, a document of another
489
+ * format, and `unknown-format-version`, a later version than this release
490
+ * reads.
491
+ * - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
492
+ * shaped as the schema says; `unknown-source`, a page or form values for a
493
+ * source the document doesn't list; `page-out-of-range`, a page index its
494
+ * source doesn't have; `duplicate-key`, two pages with one key;
495
+ * `duplicate-annotation`, two annotations with one id on a page; and, as
496
+ * for commands, `invalid-rotation`, `outside-page`, `invalid-size`,
497
+ * `too-many-points`, `invalid-color`, `unsupported-annotation`,
498
+ * `field-name-too-long` and `text-too-long`.
499
+ *
500
+ * @public
501
+ */
502
+ export declare type PdfDocumentRejection = "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "page-out-of-range" | "duplicate-key" | "duplicate-annotation" | "invalid-rotation" | "outside-page" | "invalid-size" | "too-many-points" | "invalid-color" | "unsupported-annotation" | "field-name-too-long" | "text-too-long";
503
+
333
504
  /**
334
505
  * How to encrypt the output. Encryption is always AES-256.
335
506
  *
@@ -406,13 +577,21 @@ export declare class PdfError extends SdkError<PdfErrorCode> {
406
577
  * - `IMAGE_TOO_LARGE`: an image exceeds the `maxImagePixels` limit. It's
407
578
  * reported as a warning, because the image is skipped rather than the
408
579
  * document failing (ADR 0004).
580
+ * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as
581
+ * one naming a page the plan doesn't have. `details.reason` says why, as
582
+ * a stable token (`PdfCommandRejection`, sdk-core ADR 0045).
583
+ * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
584
+ * valid in its format. `details.reason` says why (`PdfDocumentRejection`).
585
+ * - `UNSUPPORTED_FORMAT`: a plan document of another format, or of a later
586
+ * version than this release reads, with `details.reason`
587
+ * `unknown-format` or `unknown-format-version`.
409
588
  *
410
589
  * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
411
590
  * value and the `unit`.
412
591
  *
413
592
  * @public
414
593
  */
415
- export declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE";
594
+ export declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "UNSUPPORTED_FORMAT";
416
595
 
417
596
  /**
418
597
  * Options for {@link PdfSession.export}.
@@ -481,6 +660,10 @@ export declare interface PdfFormField {
481
660
  /**
482
661
  * A drawn signature, or another image, placed on the page.
483
662
  *
663
+ * The session refuses it for now, with `INVALID_COMMAND` and
664
+ * `unsupported-annotation`: the portable format can't carry its image yet
665
+ * (docs/adr/0003). The editor's signature tool will bring it back.
666
+ *
484
667
  * @public
485
668
  */
486
669
  export declare interface PdfImageAnnotation {
@@ -513,7 +696,7 @@ export declare interface PdfImageCompression {
513
696
  *
514
697
  * @public
515
698
  */
516
- export declare interface PdfInsertOptions extends PdfCallOptions {
699
+ export declare interface PdfInsertOptions extends PdfOpenOptions {
517
700
  /** The position of the first inserted page. Defaults to the end. */
518
701
  readonly at?: number;
519
702
  /** Zero-based indexes of the pages to insert. Defaults to every page. */
@@ -672,10 +855,14 @@ export declare interface PdfLink {
672
855
  export declare type PdfMessageCatalogue = typeof pdfMessages;
673
856
 
674
857
  /**
675
- * The PDF SDK's English message catalogue: sdk-core's messages, and text for
676
- * every {@link PdfErrorCode} and every limit's warning. Pass it to
677
- * `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
678
- * overrides.
858
+ * The PDF SDK's English message catalogue for the server-safe entry:
859
+ * sdk-core's messages, and text for every {@link PdfErrorCode} and every
860
+ * limit's warning. Pass it to `createMessages` from `@hussmartinez/sdk-core`,
861
+ * with the host's locale and overrides.
862
+ *
863
+ * It holds no interface text: the editor's, the viewer's and the
864
+ * thumbnails' text is in `pdfEditorMessages`, from the React entry
865
+ * (docs/adr/0010).
679
866
  *
680
867
  * Error text is looked up by code, with the error's `details` as
681
868
  * parameters, and never taken from `error.message` (ADR 0019).
@@ -696,6 +883,9 @@ export declare const pdfMessages: {
696
883
  readonly "errors.TOO_MANY_PAGES": "This document has {actual, number} pages, which is over the {maximum, number}-page limit.";
697
884
  readonly "errors.SESSION_TOO_LARGE": "The open documents would use {actual, fileSize}, which is over the {maximum, fileSize} limit. Close a document, or clear the undo history, and try again.";
698
885
  readonly "errors.IMAGE_TOO_LARGE": "Some images are too large to show. They're kept unchanged in the document.";
886
+ readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
887
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't a PDF project.";
888
+ readonly "errors.UNSUPPORTED_FORMAT": "This project was saved by a newer version, or by another app. Update the app, and try again.";
699
889
  readonly "warnings.maxPages": {
700
890
  readonly $plural: "actual";
701
891
  } & {
@@ -704,46 +894,6 @@ export declare const pdfMessages: {
704
894
  };
705
895
  readonly "warnings.maxSessionSize": "The open documents use {actual, fileSize}. Clearing the undo history frees memory.";
706
896
  readonly "warnings.maxImagePixels": "Some images are very large and may be slow to show.";
707
- readonly "viewer.label": "Document";
708
- readonly "viewer.empty": "No document is open.";
709
- readonly "viewer.page": "Page {page} of {count}";
710
- readonly "viewer.webLink": "Link to {destination}, opens in a new tab";
711
- readonly "viewer.emailLink": "Email {destination}";
712
- readonly "thumbnails.label": "Pages";
713
- readonly "thumbnails.page": "Page {page} of {count}";
714
- readonly "thumbnails.number": "{page}";
715
- readonly "editor.label": "PDF editor";
716
- readonly "editor.start.title": "Open a PDF to get started";
717
- readonly "editor.start.retryTitle": "Try another PDF";
718
- readonly "editor.start.choose": "Choose a PDF";
719
- readonly "editor.start.retry": "Choose another PDF";
720
- readonly "editor.start.hint": "Or drop one here. Your file stays on this device and is never uploaded.";
721
- readonly "editor.opening": "Opening the PDF…";
722
- readonly "editor.opened": {
723
- readonly $plural: "count";
724
- } & {
725
- readonly one: "Opened a PDF with {count} page.";
726
- readonly other: "Opened a PDF with {count} pages.";
727
- };
728
- readonly "editor.closed": "The PDF was closed.";
729
- readonly "editor.undone": "Undone.";
730
- readonly "editor.redone": "Redone.";
731
- readonly "editor.rotated": {
732
- readonly $plural: "count";
733
- } & {
734
- readonly one: "Rotated {count} page.";
735
- readonly other: "Rotated {count} pages.";
736
- };
737
- readonly "toolbar.label": "PDF tools";
738
- readonly "toolbar.groups.file": "File";
739
- readonly "toolbar.groups.history": "History";
740
- readonly "toolbar.groups.pages": "Pages";
741
- readonly "toolbar.groups.other": "More tools";
742
- readonly "tools.open": "Open a PDF";
743
- readonly "tools.undo": "Undo";
744
- readonly "tools.redo": "Redo";
745
- readonly "tools.rotate-left": "Rotate left";
746
- readonly "tools.rotate-right": "Rotate right";
747
897
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
748
898
  readonly "errors.ABORTED": "The operation was cancelled.";
749
899
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -804,6 +954,19 @@ export declare interface PdfMovePagesCommand {
804
954
  readonly to: number;
805
955
  }
806
956
 
957
+ /**
958
+ * Options for {@link PdfSession.open}.
959
+ *
960
+ * @public
961
+ */
962
+ export declare interface PdfOpenOptions extends PdfCallOptions {
963
+ /**
964
+ * The file's name, for bytes or a `Blob` that isn't a `File`. It wins over
965
+ * `File.name`, and is cleaned before it's kept (docs/adr/0009).
966
+ */
967
+ readonly name?: string;
968
+ }
969
+
807
970
  /**
808
971
  * Facts about one page of a source document.
809
972
  *
@@ -831,6 +994,47 @@ export declare interface PdfPlan {
831
994
  readonly formValues: Readonly<Record<string, Readonly<Record<string, PdfFieldValue>>>>;
832
995
  }
833
996
 
997
+ /**
998
+ * The plan as portable JSON: `hm-pdf-plan` version 1, which
999
+ * `formats/hm-pdf-plan/v1.schema.json` describes
1000
+ * (docs/formats/hm-pdf-plan.md). Positions and sizes are whole millionths of
1001
+ * the page, and pages name their sources by ids the document lists.
1002
+ *
1003
+ * @public
1004
+ */
1005
+ export declare interface PdfPlanDocument {
1006
+ readonly format: typeof PDF_PLAN_FORMAT;
1007
+ readonly version: typeof PDF_PLAN_VERSION;
1008
+ readonly sources: Readonly<Record<string, PdfPlanDocumentSource>>;
1009
+ readonly pages: readonly PdfPlanDocumentPage[];
1010
+ readonly formValues: Readonly<Record<string, Readonly<Record<string, PdfFieldValue>>>>;
1011
+ }
1012
+
1013
+ /**
1014
+ * A page in a plan document.
1015
+ *
1016
+ * @public
1017
+ */
1018
+ export declare interface PdfPlanDocumentPage {
1019
+ readonly key: string;
1020
+ readonly source: string;
1021
+ readonly pageIndex: number;
1022
+ readonly rotation: PdfRotation;
1023
+ readonly annotations: readonly PdfAnnotationDocument[];
1024
+ }
1025
+
1026
+ /**
1027
+ * A source, as a plan document records it: its page count, which the pages
1028
+ * that use it must fit, and, once documents travel with their files, its
1029
+ * content.
1030
+ *
1031
+ * @public
1032
+ */
1033
+ export declare interface PdfPlanDocumentSource {
1034
+ readonly pageCount: number;
1035
+ readonly asset?: PdfAssetReference;
1036
+ }
1037
+
834
1038
  /**
835
1039
  * One page of the page plan (docs/adr/0003): a page of a source document,
836
1040
  * with a rotation added to its own, and the annotations drawn on it. The key
@@ -986,7 +1190,10 @@ export declare interface PdfRotatePagesCommand {
986
1190
  readonly type: "pdf.rotatePages";
987
1191
  /** The keys of the pages to rotate. */
988
1192
  readonly pages: readonly string[];
989
- /** Degrees, clockwise, in multiples of 90. Negative turns anticlockwise. */
1193
+ /**
1194
+ * Degrees, clockwise, in multiples of 90 from -360 to 360. Negative turns
1195
+ * anticlockwise.
1196
+ */
990
1197
  readonly angle: number;
991
1198
  }
992
1199
 
@@ -1016,7 +1223,7 @@ export declare interface PdfSession {
1016
1223
  * Rejects with a `PdfError`, which the snapshot also holds; the current
1017
1224
  * document, if any, stays open.
1018
1225
  */
1019
- open(file: Blob | PdfBytes, options?: PdfCallOptions): Promise<void>;
1226
+ open(file: Blob | PdfBytes, options?: PdfOpenOptions): Promise<void>;
1020
1227
  /**
1021
1228
  * Inserts the pages of another document, as one undoable step. If the
1022
1229
  * documents held would then exceed `maxSessionSize`, the session first
@@ -1027,9 +1234,11 @@ export declare interface PdfSession {
1027
1234
  */
1028
1235
  insert(file: Blob | PdfBytes, options?: PdfInsertOptions): Promise<void>;
1029
1236
  /**
1030
- * Runs one command, or several as one undoable step. Throws `TypeError`
1031
- * or `RangeError` for a command that doesn't fit the plan, and changes
1032
- * nothing then.
1237
+ * Runs one command, or several as one undoable step. Throws `PdfError`
1238
+ * with `INVALID_COMMAND` for a command that doesn't fit the plan, with a
1239
+ * `PdfCommandRejection` as `details.reason`, and changes nothing then.
1240
+ * Positions and sizes are snapped to millionths of the page
1241
+ * (`PDF_POSITION_GRID`).
1033
1242
  */
1034
1243
  execute(commands: PdfCommand | readonly PdfCommand[]): void;
1035
1244
  undo(): void;
@@ -1147,7 +1356,9 @@ export declare interface PdfSessionSnapshot {
1147
1356
  readonly historyTrimmed: boolean;
1148
1357
  /**
1149
1358
  * The keys of the selected pages, in plan order. Tools act on them, such as
1150
- * rotating the selection. View state: not undoable, and never in events.
1359
+ * rotating the selection. View state: not part of the plan and never in
1360
+ * events, but undo and redo bring back the selection and current page
1361
+ * that went with each step (docs/adr/0008).
1151
1362
  */
1152
1363
  readonly selection: readonly string[];
1153
1364
  /** The key of the page the user is looking at, if a document is open. */
@@ -1200,6 +1411,13 @@ export declare interface PdfSourceInfo {
1200
1411
  readonly pageCount: number;
1201
1412
  /** The size of its bytes. */
1202
1413
  readonly byteLength: number;
1414
+ /**
1415
+ * The file's name, from `File.name` or the `name` option, cleaned as
1416
+ * docs/adr/0009 describes: one path segment, without control or
1417
+ * bidirectional formatting characters, at most 128 code points. Absent
1418
+ * when there was none. Show it only as text; it never reaches `onEvent`.
1419
+ */
1420
+ readonly name?: string;
1203
1421
  }
1204
1422
 
1205
1423
  /**
@@ -1217,6 +1435,20 @@ export declare interface PdfStrokeAnnotation {
1217
1435
  readonly width: number;
1218
1436
  }
1219
1437
 
1438
+ /**
1439
+ * A pen or highlighter stroke in a plan document. Its points and width are
1440
+ * whole millionths of the page.
1441
+ *
1442
+ * @public
1443
+ */
1444
+ export declare interface PdfStrokeAnnotationDocument {
1445
+ readonly id: string;
1446
+ readonly type: "pen" | "highlight";
1447
+ readonly points: readonly PdfDocumentPoint[];
1448
+ readonly color: PdfColor;
1449
+ readonly width: number;
1450
+ }
1451
+
1220
1452
  /**
1221
1453
  * A text note placed on the page.
1222
1454
  *
@@ -1234,6 +1466,21 @@ export declare interface PdfTextAnnotation {
1234
1466
  readonly color: PdfColor;
1235
1467
  }
1236
1468
 
1469
+ /**
1470
+ * A text note in a plan document. Its position and size are whole
1471
+ * millionths of the page.
1472
+ *
1473
+ * @public
1474
+ */
1475
+ export declare interface PdfTextAnnotationDocument {
1476
+ readonly id: string;
1477
+ readonly type: "text";
1478
+ readonly at: PdfDocumentPoint;
1479
+ readonly text: string;
1480
+ readonly size: number;
1481
+ readonly color: PdfColor;
1482
+ }
1483
+
1237
1484
  /**
1238
1485
  * The text of one page, in reading order as the document stores it.
1239
1486
  *
@@ -1287,6 +1534,40 @@ export declare interface PdfWarning {
1287
1534
  readonly actual: number;
1288
1535
  }
1289
1536
 
1537
+ /**
1538
+ * Reads a command in its portable form, `hm-pdf-command` version 1, such as
1539
+ * one parsed from JSON, into the command the session executes: an
1540
+ * annotation's millionths become fractions of the page. The session's
1541
+ * reducer checks everything else when the command runs.
1542
+ *
1543
+ * @param value - The parsed JSON.
1544
+ * @throws `PdfError` with `INVALID_COMMAND` and `malformed-command` for a
1545
+ * position or size that isn't whole millionths, and `unknown-command` for
1546
+ * `pdf.restorePages`, which isn't part of the format.
1547
+ * @public
1548
+ */
1549
+ export declare function readPdfCommandDocument(value: unknown): PdfCommand;
1550
+
1551
+ /**
1552
+ * Reads a plan document, such as one parsed from JSON, checking it as
1553
+ * {@link PdfPlanDocument}'s schema does and more: every page's source must
1554
+ * be one the document lists, with the page's index, and page keys and each
1555
+ * page's annotation ids must be unique. Unknown fields are refused, never
1556
+ * dropped.
1557
+ *
1558
+ * @param value - The parsed JSON.
1559
+ * @returns The plan, with positions as fractions of the page, and its
1560
+ * sources by id.
1561
+ * @throws `PdfError` with `UNSUPPORTED_FORMAT` for another format or a later
1562
+ * version, and `INVALID_DOCUMENT` for anything else that's wrong, with a
1563
+ * {@link PdfDocumentRejection} as `details.reason`.
1564
+ * @public
1565
+ */
1566
+ export declare function readPdfPlanDocument(value: unknown): {
1567
+ readonly plan: PdfPlan;
1568
+ readonly sources: Readonly<Record<string, PdfPlanDocumentSource>>;
1569
+ };
1570
+
1290
1571
  /**
1291
1572
  * The URL, normalised, if it's an absolute `http`, `https` or `mailto` URL
1292
1573
  * without credentials (ADR 0012), and otherwise undefined. Every engine
@@ -1301,4 +1582,29 @@ export declare interface PdfWarning {
1301
1582
  */
1302
1583
  export declare function safeLinkUrl(url: string): string | undefined;
1303
1584
 
1585
+ /**
1586
+ * Writes a command in its portable form, `hm-pdf-command` version 1, with an
1587
+ * annotation's positions and sizes in whole millionths of the page.
1588
+ *
1589
+ * @param command - A command the session applied, so its values are on the
1590
+ * grid.
1591
+ * @throws `TypeError` for `pdf.restorePages`, which isn't part of the
1592
+ * format, and for a signature annotation, which version 1 can't hold.
1593
+ * @public
1594
+ */
1595
+ export declare function toPdfCommandDocument(command: PdfCommand): PdfCommandDocument;
1596
+
1597
+ /**
1598
+ * Writes a plan as a {@link PdfPlanDocument}, plain JSON-ready data, with
1599
+ * positions and sizes in whole millionths of the page.
1600
+ *
1601
+ * @param plan - The plan, such as a session snapshot's.
1602
+ * @param sources - The sources by id, with at least every one the plan's
1603
+ * pages and form values use. They're written as given.
1604
+ * @throws `TypeError` if a source the plan uses is missing from `sources`,
1605
+ * or the plan has a signature annotation, which version 1 can't hold.
1606
+ * @public
1607
+ */
1608
+ export declare function toPdfPlanDocument(plan: PdfPlan, sources: Readonly<Record<string, PdfPlanDocumentSource>>): PdfPlanDocument;
1609
+
1304
1610
  export { }