@hussmartinez/image-sdk 0.3.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
@@ -16,6 +16,19 @@ import type { Reducer } from '@hussmartinez/sdk-core';
16
16
  import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
17
17
  import { SdkError } from '@hussmartinez/sdk-core';
18
18
 
19
+ /**
20
+ * Where a point goes under a transform.
21
+ *
22
+ * @public
23
+ */
24
+ export declare function applyMatrix(matrix: ImageMatrix, point: {
25
+ readonly x: number;
26
+ readonly y: number;
27
+ }): {
28
+ readonly x: number;
29
+ readonly y: number;
30
+ };
31
+
19
32
  /**
20
33
  * The crop panel's presets, landscape then portrait (docs/adr/0007).
21
34
  *
@@ -63,6 +76,21 @@ export declare function checkOutputLimits(policy: ImageFilePolicy, size: {
63
76
  readonly height: number;
64
77
  }): void;
65
78
 
79
+ /**
80
+ * Refuses a plan that holds something a renderer or processor can't draw
81
+ * (ADR 0009). Nothing may be drawn or exported without a part of its plan:
82
+ * an export that left out a redaction would show what it was meant to hide.
83
+ * Every renderer and processor calls this, with the parts it draws, before
84
+ * it draws anything.
85
+ *
86
+ * @param plan - The plan to draw.
87
+ * @param supported - The parts this renderer or processor draws.
88
+ * @throws `ImageError` with `UNSUPPORTED_PLAN`, and the first part it can't
89
+ * draw as `details.reason`.
90
+ * @public
91
+ */
92
+ export declare function checkPlanSupport(plan: ImagePlan, supported: readonly ImagePlanPart[]): void;
93
+
66
94
  /**
67
95
  * A distance in the composition of the whole source, as a distance in the
68
96
  * oriented source: what a pointer drag on the stage moves the crop by.
@@ -74,6 +102,14 @@ export declare function compositionDeltaToSource(dx: number, dy: number, orienta
74
102
  readonly dy: number;
75
103
  };
76
104
 
105
+ /**
106
+ * The inverse of {@link sceneRectToComposition}: a rectangle drawn on the
107
+ * composition, such as a region dragged out on screen, in scene pixels.
108
+ *
109
+ * @public
110
+ */
111
+ export declare function compositionRectToScene(rect: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2): ImageRect;
112
+
77
113
  /**
78
114
  * The size of the composition: the cropped source, turned by the plan's own
79
115
  * rotation (ADR 0003).
@@ -121,6 +157,20 @@ export declare function compositionToSource(point: ImagePoint, crop: ImageCrop,
121
157
  */
122
158
  export declare function createImageEngine(options?: ImageEngineOptions): ImageEngine;
123
159
 
160
+ /**
161
+ * A new key for a layer, a redaction or a frame (ADR 0009): 24 hexadecimal
162
+ * digits from the platform's random source, so a key is never reused, even
163
+ * one a removed item had and the history may put back.
164
+ *
165
+ * Commands carry their keys, so the reducer stays pure: whatever builds an
166
+ * `image.insertRedactions` command calls this first.
167
+ *
168
+ * @param used - Keys to avoid, such as the plan's. A clash is not expected:
169
+ * it's checked so that a broken random source can't produce one.
170
+ * @public
171
+ */
172
+ export declare function createImageKey(used?: ReadonlySet<string>): string;
173
+
124
174
  /**
125
175
  * Creates the SDK's image processor over an engine from
126
176
  * {@link createImageEngine}, sharing its render worker, where the sources
@@ -203,7 +253,8 @@ export declare function createImageSession(options: ImageSessionOptions): ImageS
203
253
 
204
254
  /**
205
255
  * The plan for a newly opened source: the whole image, upright, undeveloped
206
- * and unfiltered, at full size, keeping no metadata.
256
+ * and unfiltered, with no layers or redactions, at full size, keeping no
257
+ * metadata.
207
258
  *
208
259
  * @public
209
260
  */
@@ -280,6 +331,17 @@ export declare const FILTER_PRESETS: readonly ["vivid", "warm", "cool", "fade",
280
331
  */
281
332
  export declare function fitAspect(within: ImageCrop, ratio: number | undefined): ImageCrop;
282
333
 
334
+ /**
335
+ * A rectangle as a redaction's region: whole pixels, rounded outward so it
336
+ * covers everything the rectangle touched, at least 1 × 1, and within
337
+ * `MAX_SCENE_COORDINATE` of the scene's origin. The editor fits what's
338
+ * dragged or typed with it before it builds a command, so the reducer never
339
+ * has to refuse it.
340
+ *
341
+ * @public
342
+ */
343
+ export declare function fitRedactionRegion(rect: ImageRect): ImageRect;
344
+
283
345
  /**
284
346
  * The view for a stage of this size: fitted, centred, at this ratio.
285
347
  *
@@ -287,6 +349,33 @@ export declare function fitAspect(within: ImageCrop, ratio: number | undefined):
287
349
  */
288
350
  export declare function fittedView(width: number, height: number, pixelRatio?: number): ImageView;
289
351
 
352
+ /**
353
+ * Where a text layer's lines go: the block of lines scaled uniformly to the
354
+ * largest size that fits the box, centred in its height, and each line
355
+ * placed by the alignment (ADR 0009). The layout is in the box's own
356
+ * pixels, so it's the same for the preview and for every export.
357
+ *
358
+ * @param lines - Each line's advance, at the size they were measured at.
359
+ * @param lineHeight - The height of one line at that size: the font's ascent
360
+ * and descent.
361
+ * @param ascent - The font's ascent at that size: from a line's top to its baseline.
362
+ * @param box - The layer's box: its width and height.
363
+ * @param align - `start`, `center` or `end`, by the text's direction.
364
+ * @param rightToLeft - Whether the text's direction is right to left, so
365
+ * `start` is the box's right edge.
366
+ * @returns The scale from the measured size to the drawn size, and for each
367
+ * line the x of its left edge and the y of its baseline, in the box's
368
+ * pixels. `null` when there's nothing to draw: no line has a width.
369
+ * @public
370
+ */
371
+ export declare function fitTextLines(lines: readonly ImageTextLine[], lineHeight: number, ascent: number, box: ImageSize, align: "start" | "center" | "end", rightToLeft: boolean): {
372
+ readonly scale: number;
373
+ readonly lines: readonly {
374
+ readonly x: number;
375
+ readonly baseline: number;
376
+ }[];
377
+ } | null;
378
+
290
379
  /**
291
380
  * The export at full size.
292
381
  *
@@ -315,7 +404,7 @@ export declare const IMAGE_PLAN_FORMAT = "hm-image-plan";
315
404
  *
316
405
  * @public
317
406
  */
318
- export declare const IMAGE_PLAN_VERSION = 1;
407
+ export declare const IMAGE_PLAN_VERSION = 2;
319
408
 
320
409
  /**
321
410
  * The crop frame's geometry (docs/adr/0007): pure functions over crops in
@@ -378,11 +467,11 @@ export declare interface ImageCallOptions {
378
467
 
379
468
  /**
380
469
  * Every edit to an {@link ImagePlan}: plain, structured-cloneable data
381
- * (ADR 0003). Feature pull requests add their own commands to this union.
470
+ * (ADR 0003, ADR 0009).
382
471
  *
383
472
  * @public
384
473
  */
385
- export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand;
474
+ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
386
475
 
387
476
  /**
388
477
  * Why a command was refused, as a stable token: `details.reason` on the
@@ -392,7 +481,8 @@ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetO
392
481
  * such as a missing field, a field of the wrong type, an unknown field, or
393
482
  * a crop that isn't whole pixels of at least 1 × 1.
394
483
  * - `unknown-command`: a `type` the reducer doesn't know.
395
- * - `unknown-source`: a crop for a plan whose source isn't registered.
484
+ * - `unknown-source`: a crop for a plan whose source isn't registered, or
485
+ * an image layer whose source isn't.
396
486
  * - `crop-outside-source`: a crop that doesn't fit inside its source.
397
487
  * - `invalid-orientation`: a rotation other than 0, 90, 180 or 270.
398
488
  * - `invalid-output`: a scale outside (0, 1], or a box under 1 pixel.
@@ -403,10 +493,39 @@ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetO
403
493
  * - `invalid-level`: a develop value that isn't a whole number from -100 to 100.
404
494
  * - `unknown-preset`: a filter that isn't one of `FILTER_PRESETS`.
405
495
  * - `invalid-strength`: a filter strength that isn't a whole number from 0 to 100.
406
- *
407
- * @public
408
- */
409
- export declare type ImageCommandRejection = "malformed-command" | "unknown-command" | "unknown-source" | "crop-outside-source" | "invalid-orientation" | "invalid-output" | "unknown-metadata-field" | "metadata-too-long" | "unknown-adjustment" | "invalid-level" | "unknown-preset" | "invalid-strength";
496
+ * - `invalid-key`: a key that's empty or over `MAX_KEY_LENGTH` code points.
497
+ * - `duplicate-key`: a new item with a key the plan already uses, or two
498
+ * new items or two updates with the same key.
499
+ * - `invalid-index`: an index past the end of the list.
500
+ * - `invalid-order`: an order that doesn't list every key.
501
+ * - `unknown-layer`: a key no layer has.
502
+ * - `unknown-layer-kind`: a kind other than `text`, `shape` and `image`.
503
+ * - `invalid-box`: a layer's box under 1 × 1 pixel, further than
504
+ * `MAX_SCENE_COORDINATE` from the scene's origin, or turned by other than
505
+ * 0 to 3599 tenths of a degree.
506
+ * - `invalid-opacity`: an opacity that isn't from 0 to 100.
507
+ * - `invalid-text`: text or a name with a control character other than a
508
+ * line feed, or a bidirectional embedding, override or isolate control.
509
+ * - `text-too-long`: text over `MAX_LAYER_TEXT_LENGTH` code points, or a
510
+ * name over `MAX_LAYER_NAME_LENGTH`.
511
+ * - `empty-shape`: a shape with neither a fill nor a stroke.
512
+ * - `wrong-kind`: an update that sets a field another kind of layer has.
513
+ * - `unknown-redaction`: a key no redaction has.
514
+ * - `unknown-redaction-mode`: a mode other than `solid` and `pixelate`.
515
+ * - `invalid-region`: a redaction under 1 × 1 pixel, or further than
516
+ * `MAX_SCENE_COORDINATE` from the scene's origin.
517
+ * - `invalid-colour`: a colour that isn't `#rrggbb` in lower case.
518
+ * - `unexpected-colour`: an update that sets a colour on a pixelated
519
+ * redaction, which has none.
520
+ * - `missing-colour`: an update that sets a redaction to solid without a
521
+ * colour.
522
+ * - `too-many-layers`: more layers and redactions than `MAX_PLAN_ITEMS`,
523
+ * the format's ceiling. The file policy's `maxLayers` is checked by the
524
+ * session, with its own error code.
525
+ *
526
+ * @public
527
+ */
528
+ export declare type ImageCommandRejection = "malformed-command" | "unknown-command" | "unknown-source" | "crop-outside-source" | "invalid-orientation" | "invalid-output" | "unknown-metadata-field" | "metadata-too-long" | "unknown-adjustment" | "invalid-level" | "unknown-preset" | "invalid-strength" | "invalid-key" | "duplicate-key" | "invalid-index" | "invalid-order" | "unknown-layer" | "unknown-layer-kind" | "invalid-box" | "invalid-opacity" | "invalid-text" | "text-too-long" | "empty-shape" | "wrong-kind" | "unknown-redaction" | "unknown-redaction-mode" | "invalid-region" | "invalid-colour" | "unexpected-colour" | "missing-colour" | "too-many-layers";
410
529
 
411
530
  /**
412
531
  * A rectangle in whole pixels of the oriented source: `x` and `y` from its
@@ -451,14 +570,18 @@ export declare interface ImageDevelop {
451
570
  * reads.
452
571
  * - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
453
572
  * shaped as the schema says; `unknown-source`, a base whose source the
454
- * document doesn't list; and, as for commands, `crop-outside-source`,
455
- * `invalid-orientation`, `invalid-output`, `metadata-too-long`,
456
- * `unknown-adjustment`, `invalid-level`, `unknown-preset` and
457
- * `invalid-strength`.
573
+ * document doesn't list; `duplicate-key`, a key two items share; and, as
574
+ * for commands, `crop-outside-source`, `invalid-orientation`,
575
+ * `invalid-output`, `metadata-too-long`, `unknown-adjustment`,
576
+ * `invalid-level`, `unknown-preset`, `invalid-strength`, `invalid-key`,
577
+ * `unknown-redaction-mode`, `invalid-region`, `invalid-colour`,
578
+ * `unknown-layer-kind`, `invalid-box`, `invalid-opacity`, `invalid-text`,
579
+ * `text-too-long`, `empty-shape` and `too-many-layers`. `unknown-source`
580
+ * and `crop-outside-source` apply to an image layer too.
458
581
  *
459
582
  * @public
460
583
  */
461
- export declare type ImageDocumentRejection = "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "crop-outside-source" | "invalid-orientation" | "invalid-output" | "metadata-too-long" | "unknown-adjustment" | "invalid-level" | "unknown-preset" | "invalid-strength";
584
+ export declare type ImageDocumentRejection = "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "crop-outside-source" | "invalid-orientation" | "invalid-output" | "metadata-too-long" | "unknown-adjustment" | "invalid-level" | "unknown-preset" | "invalid-strength" | "duplicate-key" | "invalid-key" | "unknown-redaction-mode" | "invalid-region" | "invalid-colour" | "unknown-layer-kind" | "invalid-box" | "invalid-opacity" | "invalid-text" | "text-too-long" | "empty-shape" | "too-many-layers";
462
585
 
463
586
  /**
464
587
  * The port for reading images: probe a file's headers, decode it into a
@@ -570,6 +693,10 @@ export declare class ImageError extends SdkError<ImageErrorCode> {
570
693
  * valid in its format. `details.reason` says why (`ImageDocumentRejection`).
571
694
  * A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
572
695
  * instead, with `details.reason` `unknown-format` or `unknown-format-version`.
696
+ * - `UNSUPPORTED_PLAN`: a plan holds something the renderer or processor
697
+ * can't draw, such as a layer kind from a later release. Nothing is drawn
698
+ * or exported without it (ADR 0009). `details.reason` names the part:
699
+ * `layers`, `redactions` or `animation`.
573
700
  * - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
574
701
  * the `maxImagePixels` limit.
575
702
  * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
@@ -585,7 +712,7 @@ export declare class ImageError extends SdkError<ImageErrorCode> {
585
712
  *
586
713
  * @public
587
714
  */
588
- export declare type ImageErrorCode = SdkCoreErrorCode | "INVALID_IMAGE" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "IMAGE_TOO_LARGE" | "IMAGE_DIMENSION_TOO_LARGE" | "TOO_MANY_FRAMES" | "SESSION_TOO_LARGE" | "TOO_MANY_LAYERS";
715
+ export declare type ImageErrorCode = SdkCoreErrorCode | "INVALID_IMAGE" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "UNSUPPORTED_PLAN" | "IMAGE_TOO_LARGE" | "IMAGE_DIMENSION_TOO_LARGE" | "TOO_MANY_FRAMES" | "SESSION_TOO_LARGE" | "TOO_MANY_LAYERS";
589
716
 
590
717
  /**
591
718
  * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
@@ -681,6 +808,43 @@ export declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
681
808
  */
682
809
  export declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
683
810
 
811
+ /**
812
+ * Another image, drawn to fill its box (ADR 0009).
813
+ *
814
+ * @public
815
+ */
816
+ export declare interface ImageImageLayer extends ImageLayerCommon, ImageLayerBox {
817
+ readonly kind: "image";
818
+ /** The id of a registered source. */
819
+ readonly source: string;
820
+ /** The part of that source to draw, in its own pixels, or `null` for all of it. */
821
+ readonly crop: ImageCrop | null;
822
+ }
823
+
824
+ /**
825
+ * Options for {@link ImageSession.insertImage}.
826
+ *
827
+ * @public
828
+ */
829
+ declare interface ImageInsertOptions {
830
+ readonly signal?: AbortSignal;
831
+ /**
832
+ * The commands that add the image to the plan, instead of the default
833
+ * layer: given the new source and the plan as it is.
834
+ */
835
+ readonly place?: (source: ImageSessionSource, plan: ImagePlan) => ImageCommand | readonly ImageCommand[];
836
+ }
837
+
838
+ /**
839
+ * The commands that exist only to undo others. The reducer applies them, and
840
+ * they're plain data like every command, but the `hm-image-command` format
841
+ * doesn't include them: an inverse's shape may change between releases
842
+ * (sdk-core ADR 0045).
843
+ *
844
+ * @public
845
+ */
846
+ export declare type ImageInverseCommand = RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
847
+
684
848
  /**
685
849
  * The metadata fields a user may keep on export (ADR 0005). Empty strings
686
850
  * mean the field isn't written.
@@ -694,6 +858,71 @@ export declare interface ImageKeepableMetadata {
694
858
  readonly copyright: string;
695
859
  }
696
860
 
861
+ /**
862
+ * A layer over the base: text, a shape or another image (ADR 0009). Layers
863
+ * are drawn bottom to top, in the plan's order, and redactions over all of
864
+ * them.
865
+ *
866
+ * @public
867
+ */
868
+ export declare type ImageLayer = ImageTextLayer | ImageShapeLayer | ImageImageLayer;
869
+
870
+ /**
871
+ * Where a positioned layer is: a box in whole pixels of the scene, the
872
+ * base's oriented source, mirrored or not, then turned about its centre
873
+ * (ADR 0009). The box stays
874
+ * on the pixels it covers when the image is cropped or turned.
875
+ *
876
+ * @public
877
+ */
878
+ export declare interface ImageLayerBox {
879
+ /** The box's left edge, before its rotation. May be negative. */
880
+ readonly x: number;
881
+ /** The box's top edge, before its rotation. May be negative. */
882
+ readonly y: number;
883
+ /** At least 1. */
884
+ readonly width: number;
885
+ /** At least 1. */
886
+ readonly height: number;
887
+ /** Tenths of a degree, clockwise about the box's centre: 0 to 3599. */
888
+ readonly rotation: number;
889
+ /**
890
+ * Whether the layer is mirrored left to right, about the box's own
891
+ * vertical axis, before it's turned. With a half turn, that's a mirror top
892
+ * to bottom, so one flip is all a box needs.
893
+ */
894
+ readonly flipX: boolean;
895
+ }
896
+
897
+ /**
898
+ * What every layer has (ADR 0009).
899
+ *
900
+ * @public
901
+ */
902
+ export declare interface ImageLayerCommon {
903
+ /**
904
+ * Its identity: 1 to `MAX_KEY_LENGTH` code points, unique among the plan's
905
+ * layers and redactions.
906
+ */
907
+ readonly key: string;
908
+ /**
909
+ * What the layers list calls it: up to `MAX_LAYER_NAME_LENGTH` code
910
+ * points. Empty means the editor's own label for the kind.
911
+ */
912
+ readonly name: string;
913
+ /** Whether it's drawn. */
914
+ readonly visible: boolean;
915
+ /** A whole number from 0, transparent, to 100, opaque. */
916
+ readonly opacity: number;
917
+ }
918
+
919
+ /**
920
+ * A layer's kind.
921
+ *
922
+ * @public
923
+ */
924
+ export declare type ImageLayerKind = ImageLayer["kind"];
925
+
697
926
  /**
698
927
  * The type of {@link imageLimitDefinitions}.
699
928
  *
@@ -797,6 +1026,21 @@ export declare type ImageLimitName = keyof ImageLimitDefinitions;
797
1026
  */
798
1027
  export declare const imageLimits: Limits<ImageLimitDefinitions>;
799
1028
 
1029
+ /**
1030
+ * A 2D affine transform, as the canvas takes it: `x' = a·x + c·y + e` and
1031
+ * `y' = b·x + d·y + f`.
1032
+ *
1033
+ * @public
1034
+ */
1035
+ export declare type ImageMatrix = readonly [
1036
+ a: number,
1037
+ b: number,
1038
+ c: number,
1039
+ d: number,
1040
+ e: number,
1041
+ f: number
1042
+ ];
1043
+
800
1044
  /**
801
1045
  * The type of {@link imageMessages}, for typing a host's overrides with
802
1046
  * `MessageOverrides<ImageMessageCatalogue>`.
@@ -806,11 +1050,16 @@ export declare const imageLimits: Limits<ImageLimitDefinitions>;
806
1050
  export declare type ImageMessageCatalogue = typeof imageMessages;
807
1051
 
808
1052
  /**
809
- * The image SDK's English message catalogue: sdk-core's and ui's messages, and text
810
- * for every {@link ImageErrorCode} and every limit's warning. Pass it to
811
- * `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
812
- * overrides. It also has the editor's text: its labels, states,
813
- * announcements and tool names.
1053
+ * The image SDK's English message catalogue for the server-safe entry:
1054
+ * sdk-core's messages, and text for every {@link ImageErrorCode} and every
1055
+ * limit's warning, which the headless session produces and a host shows.
1056
+ * Pass it to `createMessages` from `@hussmartinez/sdk-core`, with the host's
1057
+ * locale and overrides.
1058
+ *
1059
+ * It holds no interface text: the editor's labels, states, announcements
1060
+ * and tool names are in `imageEditorMessages`, from the React entry, so
1061
+ * hosts of this entry, servers included, don't carry text nothing here
1062
+ * shows (docs/adr/0012).
814
1063
  *
815
1064
  * Error text is looked up by code, with the error's `details` as
816
1065
  * parameters, and never taken from `error.message` (ADR 0019).
@@ -825,12 +1074,12 @@ export declare type ImageMessageCatalogue = typeof imageMessages;
825
1074
  * @public
826
1075
  */
827
1076
  export declare const imageMessages: {
828
- readonly "editor.engineUnavailable": "Image processing stopped. Reload this page or reopen the editor, then choose the image again. Unsaved edits will be lost unless your application has saved them.";
829
1077
  readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
830
1078
  readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
831
1079
  readonly "errors.DECODE_FAILED": "This browser can't open this kind of image. Try another browser, or convert the file to PNG or JPEG.";
832
1080
  readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
833
1081
  readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
1082
+ readonly "errors.UNSUPPORTED_PLAN": "This image has edits this version can't show. Update the application and try again.";
834
1083
  readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
835
1084
  readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
836
1085
  readonly "errors.TOO_MANY_FRAMES": {
@@ -861,155 +1110,6 @@ export declare const imageMessages: {
861
1110
  readonly one: "This image has {actual} layer.";
862
1111
  readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
863
1112
  };
864
- readonly "editor.label": "Image editor";
865
- readonly "editor.preview": "Edited image preview, {width, number} × {height, number}";
866
- readonly "editor.empty": "Open an image to start editing. It stays on this device.";
867
- readonly "editor.choose": "Choose an image";
868
- readonly "editor.dropHint": "or drop it here";
869
- readonly "editor.opening": "Opening the image…";
870
- readonly "editor.cancel": "Cancel";
871
- readonly "editor.opened": "Image opened, {width, number} × {height, number}.";
872
- readonly "editor.undid": "Undid {action}.";
873
- readonly "editor.redid": "Redid {action}.";
874
- readonly "actions.image.setCrop": "crop";
875
- readonly "actions.image.setOrientation": "rotate or flip";
876
- readonly "actions.image.setOutput": "size";
877
- readonly "actions.image.setMetadata": "metadata";
878
- readonly "actions.image.setDevelop": "adjustment";
879
- readonly "actions.image.setFilter": "filter";
880
- readonly "toolbar.label": "Image tools";
881
- readonly "toolbar.groups.file": "File";
882
- readonly "toolbar.groups.history": "History";
883
- readonly "toolbar.groups.orientation": "Rotate";
884
- readonly "toolbar.groups.zoom": "Zoom";
885
- readonly "toolbar.groups.other": "More tools";
886
- readonly "tools.open": "Open image";
887
- readonly "tools.undo": "Undo";
888
- readonly "tools.redo": "Redo";
889
- readonly "tools.rotate-left": "Rotate left";
890
- readonly "tools.rotate-right": "Rotate right";
891
- readonly "tools.zoom-in": "Zoom in";
892
- readonly "tools.zoom-out": "Zoom out";
893
- readonly "tools.zoom-fit": "Fit to the stage";
894
- readonly "tools.crop": "Crop";
895
- readonly "tools.flip-horizontal": "Flip horizontally";
896
- readonly "tools.flip-vertical": "Flip vertically";
897
- readonly "toolbar.groups.crop": "Crop";
898
- readonly "crop.frame": "Crop area";
899
- readonly "crop.frameDescription": "{width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; with Alt, they resize it; Enter applies and Escape cancels.";
900
- readonly "crop.size": "{width, number} × {height, number}, from {x, number}, {y, number}";
901
- readonly "crop.panel": "Crop";
902
- readonly "crop.x": "Left";
903
- readonly "crop.y": "Top";
904
- readonly "crop.width": "Width";
905
- readonly "crop.height": "Height";
906
- readonly "crop.aspect": "Aspect ratio";
907
- readonly "crop.aspects.free": "Free";
908
- readonly "crop.aspects.original": "Original";
909
- readonly "crop.aspects.ratio": "{width}:{height}";
910
- readonly "crop.apply": "Apply crop";
911
- readonly "crop.cancel": "Cancel";
912
- readonly "crop.reset": "Whole image";
913
- readonly "crop.applied": "Cropped to {width, number} × {height, number}.";
914
- readonly "inspector.label": "Panels";
915
- readonly "inspector.adjust": "Adjust";
916
- readonly "inspector.filters": "Filters";
917
- readonly "inspector.info": "Info";
918
- readonly "notices.label": "Notices";
919
- readonly "notices.dismiss": "Dismiss";
920
- readonly "notices.colourProfile": "This image has a colour profile. Colours outside sRGB will be clipped in the exported file.";
921
- readonly "info.panel": "Image info";
922
- readonly "info.size": "Size";
923
- readonly "info.sizeValue": "{width, number} × {height, number} pixels";
924
- readonly "info.format": "Format";
925
- readonly "info.formats.png": "PNG";
926
- readonly "info.formats.jpeg": "JPEG";
927
- readonly "info.formats.webp": "WebP";
928
- readonly "info.formats.gif": "GIF";
929
- readonly "info.formats.avif": "AVIF";
930
- readonly "info.formats.heif": "HEIF";
931
- readonly "info.formats.bmp": "BMP";
932
- readonly "info.frames": "Frames";
933
- readonly "info.fileSize": "File size";
934
- readonly "info.fileSizeValue": "{size, fileSize}";
935
- readonly "info.metadata": "Metadata in the file";
936
- readonly "info.metadataNone": "None";
937
- readonly "info.kept": "Kept on export";
938
- readonly "info.keptNone": "Nothing";
939
- readonly "develop.panel": "Adjust";
940
- readonly "develop.temperature": "Temperature";
941
- readonly "develop.tint": "Tint";
942
- readonly "develop.exposure": "Exposure";
943
- readonly "develop.highlights": "Highlights";
944
- readonly "develop.shadows": "Shadows";
945
- readonly "develop.contrast": "Contrast";
946
- readonly "develop.saturation": "Saturation";
947
- readonly "develop.vibrance": "Vibrance";
948
- readonly "develop.reset": "Reset {name}";
949
- readonly "develop.resetAll": "Reset all";
950
- readonly "develop.wasReset": "All adjustments reset.";
951
- readonly "filters.panel": "Filters";
952
- readonly "filters.label": "Filter";
953
- readonly "filters.none": "None";
954
- readonly "filters.vivid": "Vivid";
955
- readonly "filters.warm": "Warm";
956
- readonly "filters.cool": "Cool";
957
- readonly "filters.fade": "Fade";
958
- readonly "filters.mono": "Mono";
959
- readonly "filters.noir": "Noir";
960
- readonly "filters.sepia": "Sepia";
961
- readonly "filters.strength": "Strength";
962
- readonly "toolbar.groups.export": "Export";
963
- readonly "tools.export": "Export";
964
- readonly "export.title": "Export image";
965
- readonly "export.description": "The file is made on this device, and nothing is uploaded.";
966
- readonly "export.format": "Format";
967
- readonly "export.formats.png": "PNG";
968
- readonly "export.formats.jpeg": "JPEG";
969
- readonly "export.formats.webp": "WebP";
970
- readonly "export.quality": "Quality";
971
- readonly "export.qualityValue": "{quality, number}%";
972
- readonly "export.size": "Size";
973
- readonly "export.sizes.scale": "Scale";
974
- readonly "export.sizes.fit": "Fit in a box";
975
- readonly "export.scale": "Scale, in percent";
976
- readonly "export.fitWidth": "Largest width";
977
- readonly "export.fitHeight": "Largest height";
978
- readonly "export.fields": "Details to include";
979
- readonly "export.fieldsHint": "Only what you fill in is written to the file.";
980
- readonly "export.field.title": "Title";
981
- readonly "export.field.description": "Description";
982
- readonly "export.field.artist": "Artist";
983
- readonly "export.field.copyright": "Copyright";
984
- readonly "export.summary": "Summary";
985
- readonly "export.output": "{width, number} × {height, number} pixels, {format}";
986
- readonly "export.removed": "Removed from the file";
987
- readonly "export.removedNone": "The image had no other details to remove.";
988
- readonly "export.kind.location": "Location";
989
- readonly "export.kind.camera": "Camera details";
990
- readonly "export.kind.timestamps": "Dates and times";
991
- readonly "export.kind.thumbnail": "Embedded thumbnail";
992
- readonly "export.kind.colourProfile": "Colour profile: colours outside sRGB are clipped";
993
- readonly "export.kind.other": "Other metadata";
994
- readonly "export.kept": "Kept in the file";
995
- readonly "export.confirm": "Export";
996
- readonly "export.cancel": "Cancel";
997
- readonly "export.progress": "Exporting the image";
998
- readonly "export.stop": "Stop exporting";
999
- readonly "export.cancelled": "Export stopped.";
1000
- readonly "export.done": "Exported a {format} of {size, fileSize}.";
1001
- readonly "export.ready": "{width, number} × {height, number} pixels, {format}, {size, fileSize}";
1002
- readonly "export.download": "Download";
1003
- readonly "export.close": "Done";
1004
- readonly "dialog.close": "Close";
1005
- readonly "fileDropZone.choose": "Choose a file";
1006
- readonly "fileDropZone.chooseMultiple": "Choose files";
1007
- readonly "fileDropZone.hint": "or drop it here";
1008
- readonly "fileDropZone.hintMultiple": "or drop them here";
1009
- readonly "progress.label": "Progress";
1010
- readonly "spinner.label": "Loading";
1011
- readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
1012
- readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
1013
1113
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
1014
1114
  readonly "errors.ABORTED": "The operation was cancelled.";
1015
1115
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -1106,20 +1206,27 @@ export declare type ImageOutput = {
1106
1206
 
1107
1207
  /**
1108
1208
  * The session's document: a description of the edits over an immutable
1109
- * source, rendered to pixels only for display and export (ADR 0003).
1209
+ * source, rendered to pixels only for display and export (ADR 0003, ADR
1210
+ * 0009).
1110
1211
  *
1111
1212
  * @public
1112
1213
  */
1113
1214
  export declare interface ImagePlan {
1114
1215
  readonly base: ImageBase;
1216
+ /** The layers over the base, bottom to top, placed in the scene (ADR 0009). */
1217
+ readonly layers: readonly ImageLayer[];
1218
+ /** The redactions, applied over every layer (ADR 0010). */
1219
+ readonly redactions: readonly ImageRedaction[];
1220
+ /** The animation (ADR 0011). Always `null` until format version 4. */
1221
+ readonly animation: null;
1115
1222
  readonly output: ImageOutput;
1116
1223
  /** The fields the user chose to keep on export. Never a location (ADR 0005). */
1117
1224
  readonly metadata: ImageKeepableMetadata;
1118
1225
  }
1119
1226
 
1120
1227
  /**
1121
- * The plan as portable JSON: `hm-image-plan` version 1, which
1122
- * `formats/hm-image-plan/v1.schema.json` describes
1228
+ * The plan as portable JSON: `hm-image-plan` version 2, which
1229
+ * `formats/hm-image-plan/v2.schema.json` describes
1123
1230
  * (docs/formats/hm-image-plan.md). Positions are whole pixels of the
1124
1231
  * oriented source, and the base names its source by an id the document
1125
1232
  * lists.
@@ -1143,6 +1250,13 @@ export declare interface ImagePlanDocumentSource extends ImageSize {
1143
1250
  readonly asset?: ImageAssetReference;
1144
1251
  }
1145
1252
 
1253
+ /**
1254
+ * A part of a plan that a renderer or processor may not know how to draw.
1255
+ *
1256
+ * @public
1257
+ */
1258
+ export declare type ImagePlanPart = "layers" | "redactions" | "animation";
1259
+
1146
1260
  /**
1147
1261
  * A point in pixels, which may be fractional.
1148
1262
  *
@@ -1223,6 +1337,83 @@ export declare interface ImageProgressOptions extends ImageCallOptions {
1223
1337
  readonly onProgress?: (fraction: number) => void;
1224
1338
  }
1225
1339
 
1340
+ /**
1341
+ * A rectangle in whole pixels.
1342
+ *
1343
+ * @public
1344
+ */
1345
+ export declare interface ImageRect {
1346
+ readonly x: number;
1347
+ readonly y: number;
1348
+ readonly width: number;
1349
+ readonly height: number;
1350
+ }
1351
+
1352
+ /**
1353
+ * A region of the image that an export doesn't show (ADR 0010): a rectangle
1354
+ * in whole pixels of the scene, the base's oriented source, so it stays on
1355
+ * the pixels it covers when the image is cropped or turned (ADR 0009).
1356
+ *
1357
+ * A redaction has no opacity, visibility or rotation, and is drawn over
1358
+ * every layer. Only exports are redacted: the plan describes the redaction,
1359
+ * and the source is unchanged.
1360
+ *
1361
+ * @public
1362
+ */
1363
+ export declare type ImageRedaction = (ImageRedactionRegion & {
1364
+ readonly mode: "solid";
1365
+ /** The fill, as `#rrggbb` in lower case. */
1366
+ readonly colour: string;
1367
+ }) | (ImageRedactionRegion & {
1368
+ readonly mode: "pixelate";
1369
+ });
1370
+
1371
+ /**
1372
+ * How a redaction replaces what it covers (ADR 0010): `solid` fills the
1373
+ * region with one colour, and `pixelate` with coarse blocks of the average
1374
+ * colour beneath each. Only `solid` destroys what was there.
1375
+ *
1376
+ * @public
1377
+ */
1378
+ export declare type ImageRedactionMode = "solid" | "pixelate";
1379
+
1380
+ /**
1381
+ * The fields of a redaction that `image.updateRedactions` may set: any but
1382
+ * its key. Setting `mode` to `pixelate` drops the colour, and setting it to
1383
+ * `solid` needs one in the same update.
1384
+ *
1385
+ * @public
1386
+ */
1387
+ export declare interface ImageRedactionProps {
1388
+ readonly mode?: ImageRedaction["mode"];
1389
+ readonly x?: number;
1390
+ readonly y?: number;
1391
+ readonly width?: number;
1392
+ readonly height?: number;
1393
+ readonly colour?: string;
1394
+ }
1395
+
1396
+ /**
1397
+ * What every redaction has, whatever its mode: its identity and its region.
1398
+ *
1399
+ * @public
1400
+ */
1401
+ export declare interface ImageRedactionRegion {
1402
+ /**
1403
+ * Its identity: 1 to {@link MAX_KEY_LENGTH} code points, unique among the
1404
+ * plan's layers and redactions.
1405
+ */
1406
+ readonly key: string;
1407
+ /** The region's left edge, in whole pixels of the scene. May be negative. */
1408
+ readonly x: number;
1409
+ /** The region's top edge, in whole pixels of the scene. May be negative. */
1410
+ readonly y: number;
1411
+ /** At least 1. */
1412
+ readonly width: number;
1413
+ /** At least 1. */
1414
+ readonly height: number;
1415
+ }
1416
+
1226
1417
  /**
1227
1418
  * Options for registering a source.
1228
1419
  *
@@ -1321,6 +1512,29 @@ export declare interface ImageSession {
1321
1512
  open(file: Blob, options?: {
1322
1513
  readonly signal?: AbortSignal;
1323
1514
  }): Promise<ImageSessionSource>;
1515
+ /**
1516
+ * Probes, checks and decodes another file, and adds it to the document as
1517
+ * an image layer, as one undoable step (ADR 0003, ADR 0004).
1518
+ *
1519
+ * - **Limits:** the file's own, as for `open`; `maxFiles`, counting every
1520
+ * source the session holds; and `maxSessionSize`, counting their decoded
1521
+ * bytes. When the image doesn't fit, the session first drops the oldest
1522
+ * undo steps that alone keep another image, and marks the history as
1523
+ * trimmed. If that isn't enough, nothing is dropped and it fails with
1524
+ * `SESSION_TOO_LARGE`.
1525
+ * - **Placement:** by default the image is centred on what's shown, at
1526
+ * its own size or half the composition's, whichever is smaller, over
1527
+ * every layer, and turned and mirrored back against the plan's
1528
+ * rotation and flips, so it's seen as the file is. `place` returns other commands; they must refer to the
1529
+ * source, or it's released.
1530
+ * - **Lifetime:** the session holds the source while the plan, an undo
1531
+ * or redo step, or an export in progress refers to it, and releases it
1532
+ * then.
1533
+ *
1534
+ * A failure, a cancellation, or another file opened meanwhile adds
1535
+ * nothing and releases the source.
1536
+ */
1537
+ insertImage(file: Blob, options?: ImageInsertOptions): Promise<ImageSessionSource>;
1324
1538
  /**
1325
1539
  * Applies commands as one undoable step. They're checked by the reducer,
1326
1540
  * then the output against `maxImageDimension` and `maxImagePixels`; a
@@ -1331,7 +1545,9 @@ export declare interface ImageSession {
1331
1545
  * Makes the document's plan equal to `plan`, as one undoable step of the
1332
1546
  * commands that reach it, checked as `execute` checks them (ADR 0003). A
1333
1547
  * plan equal to the current one changes nothing. A plan over another
1334
- * source is `INVALID_COMMAND`. For editors whose host holds the plan.
1548
+ * source is `INVALID_COMMAND`, and so is one without `layers`,
1549
+ * `redactions` and `animation`, such as a plan stored before format
1550
+ * version 2. For editors whose host holds the plan.
1335
1551
  */
1336
1552
  applyPlan(plan: ImagePlan): void;
1337
1553
  /**
@@ -1355,7 +1571,7 @@ export declare interface ImageSession {
1355
1571
  readonly signal?: AbortSignal;
1356
1572
  readonly onProgress?: (fraction: number) => void;
1357
1573
  }): Promise<ImageSessionExport>;
1358
- /** Releases the source the session holds. Later calls throw. */
1574
+ /** Releases every source the session holds. Later calls throw. */
1359
1575
  destroy(): Promise<void>;
1360
1576
  }
1361
1577
 
@@ -1366,7 +1582,7 @@ export declare interface ImageSession {
1366
1582
  * @public
1367
1583
  */
1368
1584
  export declare interface ImageSessionEvent {
1369
- readonly type: "open" | "execute" | "undo" | "redo" | "export";
1585
+ readonly type: "open" | "insert" | "execute" | "undo" | "redo" | "export";
1370
1586
  readonly outcome: "done" | "failed" | "cancelled";
1371
1587
  /** The types of the commands applied or undone. */
1372
1588
  readonly commands: readonly ImageCommand["type"][];
@@ -1420,8 +1636,20 @@ export declare interface ImageSessionSnapshot {
1420
1636
  readonly plan: ImagePlan | null;
1421
1637
  /** The document's source, or `null` before a file is open. */
1422
1638
  readonly source: ImageSessionSource | null;
1639
+ /**
1640
+ * Every source the session holds: the document's, then those of image
1641
+ * layers, including ones only the history still refers to (ADR 0004).
1642
+ */
1643
+ readonly sources: readonly ImageSessionSource[];
1423
1644
  readonly canUndo: boolean;
1424
1645
  readonly canRedo: boolean;
1646
+ /**
1647
+ * Whether undo steps were dropped to make room for an image, since the
1648
+ * document was opened: they can no longer be undone.
1649
+ */
1650
+ readonly historyTrimmed: boolean;
1651
+ /** Whether an image is being added as a layer. */
1652
+ readonly inserting: boolean;
1425
1653
  /** Whether a file is being opened. The current document stays until it's ready. */
1426
1654
  readonly opening: boolean;
1427
1655
  /** Whether an export is in progress. */
@@ -1448,6 +1676,25 @@ export declare interface ImageSessionSource extends ImageSourceInfo {
1448
1676
  readonly keepable: ImageKeepableMetadata;
1449
1677
  }
1450
1678
 
1679
+ /**
1680
+ * A rectangle or an ellipse that fills its box, with a fill, a stroke drawn
1681
+ * inside the box, or both (ADR 0009).
1682
+ *
1683
+ * @public
1684
+ */
1685
+ export declare interface ImageShapeLayer extends ImageLayerCommon, ImageLayerBox {
1686
+ readonly kind: "shape";
1687
+ readonly shape: (typeof LAYER_SHAPES)[number];
1688
+ /** The fill, as `#rrggbb` in lower case, or `null` for none. */
1689
+ readonly fill: string | null;
1690
+ /** The stroke, or `null` for none. A shape has a fill or a stroke. */
1691
+ readonly stroke: {
1692
+ readonly colour: string;
1693
+ /** In whole scene pixels, from 1 to `MAX_STROKE_WIDTH`. */
1694
+ readonly width: number;
1695
+ } | null;
1696
+ }
1697
+
1451
1698
  /**
1452
1699
  * A width and a height, in whole pixels.
1453
1700
  *
@@ -1475,6 +1722,37 @@ export declare interface ImageSourceInfo {
1475
1722
  readonly decodedBytes: number;
1476
1723
  }
1477
1724
 
1725
+ /**
1726
+ * Text, drawn as large as fits inside its box, never distorted (ADR 0009).
1727
+ * Lines break only at line feeds. Emoji are text.
1728
+ *
1729
+ * @public
1730
+ */
1731
+ export declare interface ImageTextLayer extends ImageLayerCommon, ImageLayerBox {
1732
+ readonly kind: "text";
1733
+ /**
1734
+ * Up to `MAX_LAYER_TEXT_LENGTH` code points. Control characters other
1735
+ * than a line feed, and the bidirectional embedding, override and isolate
1736
+ * controls, are refused.
1737
+ */
1738
+ readonly text: string;
1739
+ readonly font: (typeof LAYER_FONTS)[number];
1740
+ readonly bold: boolean;
1741
+ /** The text's colour, as `#rrggbb` in lower case. */
1742
+ readonly colour: string;
1743
+ readonly align: (typeof LAYER_ALIGNMENTS)[number];
1744
+ }
1745
+
1746
+ /**
1747
+ * What a line of text measures at the size it's laid out at.
1748
+ *
1749
+ * @public
1750
+ */
1751
+ export declare interface ImageTextLine {
1752
+ /** Its advance: how far the pen moves. */
1753
+ readonly width: number;
1754
+ }
1755
+
1478
1756
  /**
1479
1757
  * A small rendering of a source for lists and frame strips. An `ImageBitmap`
1480
1758
  * is one; tests can supply their own. Close it when it's no longer shown.
@@ -1517,6 +1795,40 @@ export declare interface ImageView {
1517
1795
  readonly inset?: number;
1518
1796
  }
1519
1797
 
1798
+ /**
1799
+ * Inserts layers at an index of the plan's layers, which are drawn bottom
1800
+ * to top (ADR 0009). Each needs a key no layer or redaction of the plan has.
1801
+ *
1802
+ * @public
1803
+ */
1804
+ export declare interface InsertLayersCommand {
1805
+ readonly type: "image.insertLayers";
1806
+ /** From 0, under every layer, to the number of layers, over them all. */
1807
+ readonly at: number;
1808
+ readonly layers: readonly ImageLayer[];
1809
+ }
1810
+
1811
+ /**
1812
+ * Inserts redactions at an index of the plan's redactions (ADR 0010). Each
1813
+ * needs a key no layer or redaction of the plan has.
1814
+ *
1815
+ * @public
1816
+ */
1817
+ export declare interface InsertRedactionsCommand {
1818
+ readonly type: "image.insertRedactions";
1819
+ /** From 0 to the number of redactions. */
1820
+ readonly at: number;
1821
+ readonly redactions: readonly ImageRedaction[];
1822
+ }
1823
+
1824
+ /**
1825
+ * The inverse of a transform that has one: every transform here does, since
1826
+ * a box and an output have at least one pixel.
1827
+ *
1828
+ * @public
1829
+ */
1830
+ export declare function invertMatrix(matrix: ImageMatrix): ImageMatrix;
1831
+
1520
1832
  /**
1521
1833
  * Checks whether a value is an {@link ImageError}, optionally with a given
1522
1834
  * code.
@@ -1533,6 +1845,85 @@ export declare function isImageError<Code extends ImageErrorCode = ImageErrorCod
1533
1845
  readonly code: Code;
1534
1846
  };
1535
1847
 
1848
+ /**
1849
+ * Whether text reads right to left: whether its first strongly directional
1850
+ * character is from a right-to-left script, such as Hebrew or Arabic. Text
1851
+ * with no such character reads left to right.
1852
+ *
1853
+ * @public
1854
+ */
1855
+ export declare function isRightToLeft(text: string): boolean;
1856
+
1857
+ /**
1858
+ * How a text layer's lines sit in its box, by the text's own direction.
1859
+ *
1860
+ * @public
1861
+ */
1862
+ export declare const LAYER_ALIGNMENTS: readonly ["start", "center", "end"];
1863
+
1864
+ /**
1865
+ * The fonts a text layer can use: the generic families, which every device
1866
+ * has, so the SDK ships and fetches none (ADR 0009). Names are part of the
1867
+ * document format.
1868
+ *
1869
+ * @public
1870
+ */
1871
+ export declare const LAYER_FONTS: readonly ["sans-serif", "serif", "monospace"];
1872
+
1873
+ /**
1874
+ * The kinds of layer. Names are part of the document format.
1875
+ *
1876
+ * @public
1877
+ */
1878
+ export declare const LAYER_KINDS: readonly ["text", "shape", "image"];
1879
+
1880
+ /**
1881
+ * The shapes a shape layer can be.
1882
+ *
1883
+ * @public
1884
+ */
1885
+ export declare const LAYER_SHAPES: readonly ["rectangle", "ellipse"];
1886
+
1887
+ /**
1888
+ * The transform from a layer's own box to an output: {@link layerToScene},
1889
+ * then {@link sceneToOutput}. The renderer sets it on the canvas and draws
1890
+ * the layer in its box's own pixels.
1891
+ *
1892
+ * @public
1893
+ */
1894
+ export declare function layerToOutput(box: ImageLayerBox, crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageMatrix;
1895
+
1896
+ /**
1897
+ * The transform from a layer's own box to the scene: the box's top-left
1898
+ * corner is the origin, one unit is one scene pixel, and the box is mirrored
1899
+ * left to right when it's flipped, then turned about its centre by its
1900
+ * rotation, clockwise, in tenths of a degree (ADR 0009).
1901
+ *
1902
+ * @public
1903
+ */
1904
+ export declare function layerToScene(box: ImageLayerBox): ImageMatrix;
1905
+
1906
+ /**
1907
+ * The most Unicode code points in a key.
1908
+ *
1909
+ * @public
1910
+ */
1911
+ export declare const MAX_KEY_LENGTH = 64;
1912
+
1913
+ /**
1914
+ * The most Unicode code points in a layer's name.
1915
+ *
1916
+ * @public
1917
+ */
1918
+ export declare const MAX_LAYER_NAME_LENGTH = 100;
1919
+
1920
+ /**
1921
+ * The most Unicode code points in a text layer's text (ADR 0009).
1922
+ *
1923
+ * @public
1924
+ */
1925
+ export declare const MAX_LAYER_TEXT_LENGTH = 1000;
1926
+
1536
1927
  /**
1537
1928
  * The longest a kept metadata value may be, in Unicode code points, as JSON
1538
1929
  * Schema and every language count them (ADR 0005, sdk-core ADR 0045).
@@ -1550,6 +1941,30 @@ export declare const MAX_METADATA_LENGTH = 2000;
1550
1941
  */
1551
1942
  export declare const MAX_PIXEL_RATIO = 4;
1552
1943
 
1944
+ /**
1945
+ * The most layers and redactions a plan holds, together: the format's
1946
+ * ceiling, which the file policy's `maxLayers` applies below (ADR 0009).
1947
+ *
1948
+ * @public
1949
+ */
1950
+ export declare const MAX_PLAN_ITEMS = 1024;
1951
+
1952
+ /**
1953
+ * How far from the scene's origin a position may be, in pixels, either way:
1954
+ * four times the longest side `maxImageDimension` allows by default (ADR
1955
+ * 0009).
1956
+ *
1957
+ * @public
1958
+ */
1959
+ export declare const MAX_SCENE_COORDINATE = 65536;
1960
+
1961
+ /**
1962
+ * The widest stroke of a shape, in scene pixels.
1963
+ *
1964
+ * @public
1965
+ */
1966
+ export declare const MAX_STROKE_WIDTH = 1024;
1967
+
1553
1968
  /**
1554
1969
  * A crop moved by whole pixels, kept inside the source.
1555
1970
  *
@@ -1557,6 +1972,30 @@ export declare const MAX_PIXEL_RATIO = 4;
1557
1972
  */
1558
1973
  export declare function moveCrop(crop: ImageCrop, dx: number, dy: number, source: ImageSize): ImageCrop;
1559
1974
 
1975
+ /**
1976
+ * Moves layers to an index of the list without them, keeping the order they
1977
+ * had: up or down the stack.
1978
+ *
1979
+ * @public
1980
+ */
1981
+ export declare interface MoveLayersCommand {
1982
+ readonly type: "image.moveLayers";
1983
+ readonly keys: readonly string[];
1984
+ readonly to: number;
1985
+ }
1986
+
1987
+ /**
1988
+ * Moves redactions to an index of the list without them, keeping the order
1989
+ * they had. The order only decides how overlapping redactions look.
1990
+ *
1991
+ * @public
1992
+ */
1993
+ export declare interface MoveRedactionsCommand {
1994
+ readonly type: "image.moveRedactions";
1995
+ readonly keys: readonly string[];
1996
+ readonly to: number;
1997
+ }
1998
+
1560
1999
  /**
1561
2000
  * Every adjustment at 0: the base as it was decoded.
1562
2001
  *
@@ -1635,8 +2074,11 @@ export declare function placement(composition: {
1635
2074
  /**
1636
2075
  * Reads a plan document, such as one parsed from JSON, checking it as
1637
2076
  * {@link ImagePlanDocument}'s schema does and more: the base's source must
1638
- * be one the document lists, and its crop must fit inside it. Unknown fields
1639
- * are refused, never dropped.
2077
+ * be one the document lists, as must an image layer's, their crops must fit
2078
+ * inside them, and no two items share a key. Unknown fields are refused, never dropped.
2079
+ *
2080
+ * A document of an earlier version is migrated, so every version stays
2081
+ * readable: version 1 reads as a plan with no layers or redactions.
1640
2082
  *
1641
2083
  * @param value - The parsed JSON.
1642
2084
  * @returns The plan, and its sources by id.
@@ -1650,6 +2092,144 @@ export declare function readImagePlanDocument(value: unknown): {
1650
2092
  readonly sources: Readonly<Record<string, ImagePlanDocumentSource>>;
1651
2093
  };
1652
2094
 
2095
+ /**
2096
+ * The redaction modes. Names are part of the document format.
2097
+ *
2098
+ * @public
2099
+ */
2100
+ export declare const REDACTION_MODES: readonly ["solid", "pixelate"];
2101
+
2102
+ /**
2103
+ * A pixelated region's blocks in the output: the scene's block boundaries
2104
+ * mapped as {@link redactionRectInOutput} maps the region. The region's own
2105
+ * edges are rounded outward and the boundaries between blocks to the
2106
+ * nearest pixel, so the blocks tile exactly the pixels the region covers. A
2107
+ * block with no output pixel is left out. They're listed row by row.
2108
+ *
2109
+ * @public
2110
+ */
2111
+ export declare function redactionBlocksInOutput(region: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageRect[];
2112
+
2113
+ /**
2114
+ * A pixelated region's blocks in the scene, each clipped to `within`: the
2115
+ * part of the source that's rendered, its crop. Blocks are aligned to the
2116
+ * region's top-left corner, and one that falls wholly outside `within` is
2117
+ * left out. They're listed row by row.
2118
+ *
2119
+ * @public
2120
+ */
2121
+ export declare function redactionBlocksInScene(region: ImageRect, within: ImageRect): ImageRect[];
2122
+
2123
+ /**
2124
+ * The side of a pixelated region's square blocks, in scene pixels: the
2125
+ * larger of 8 and a twelfth of the region's longer side, rounded up (ADR
2126
+ * 0010). So a region has at most 12 blocks along its longer side, and a
2127
+ * strip over a line of text is one row of them. It isn't a setting.
2128
+ *
2129
+ * @public
2130
+ */
2131
+ export declare function redactionBlockSize(region: ImageSize): number;
2132
+
2133
+ /**
2134
+ * The output pixels a region covers: the region mapped through the crop,
2135
+ * the rotation, the flips and the output's scale, rounded outward so that
2136
+ * every pixel it touches is covered whole, and clipped to the output (ADR
2137
+ * 0010). `null` when it covers none.
2138
+ *
2139
+ * @param region - The region, in scene pixels.
2140
+ * @param crop - The crop, or the whole source: `cropRect(plan.base.crop, source)`.
2141
+ * @param orientation - The plan's rotation and flips.
2142
+ * @param output - The size being rendered.
2143
+ * @public
2144
+ */
2145
+ export declare function redactionRectInOutput(region: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageRect | null;
2146
+
2147
+ /**
2148
+ * Removes layers, by key.
2149
+ *
2150
+ * @public
2151
+ */
2152
+ export declare interface RemoveLayersCommand {
2153
+ readonly type: "image.removeLayers";
2154
+ readonly keys: readonly string[];
2155
+ }
2156
+
2157
+ /**
2158
+ * Removes redactions, by key.
2159
+ *
2160
+ * @public
2161
+ */
2162
+ export declare interface RemoveRedactionsCommand {
2163
+ readonly type: "image.removeRedactions";
2164
+ readonly keys: readonly string[];
2165
+ }
2166
+
2167
+ /**
2168
+ * Puts removed layers back, each at its index, by rising index. It's what
2169
+ * undoes {@link RemoveLayersCommand}: the reducer applies it, but it isn't
2170
+ * part of the portable command format (ADR 0009).
2171
+ *
2172
+ * @public
2173
+ */
2174
+ export declare interface RestoreLayersCommand {
2175
+ readonly type: "image.restoreLayers";
2176
+ readonly entries: readonly {
2177
+ readonly at: number;
2178
+ readonly layer: ImageLayer;
2179
+ }[];
2180
+ }
2181
+
2182
+ /**
2183
+ * Puts removed redactions back, each at its index, by rising index. It's
2184
+ * what undoes {@link RemoveRedactionsCommand}: the reducer applies it, but
2185
+ * it isn't part of the portable command format (ADR 0009).
2186
+ *
2187
+ * @public
2188
+ */
2189
+ export declare interface RestoreRedactionsCommand {
2190
+ readonly type: "image.restoreRedactions";
2191
+ readonly entries: readonly {
2192
+ readonly at: number;
2193
+ readonly redaction: ImageRedaction;
2194
+ }[];
2195
+ }
2196
+
2197
+ /**
2198
+ * A rectangle of the scene as the composition shows it: through the crop,
2199
+ * the rotation and the flips, in composition pixels, without clipping. The
2200
+ * plan turns by quarters, so it's still a rectangle in whole pixels. The
2201
+ * editor places a region's frame with it.
2202
+ *
2203
+ * @public
2204
+ */
2205
+ export declare function sceneRectToComposition(rect: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2): ImageRect;
2206
+
2207
+ /**
2208
+ * The transform from the scene to an image layer's source pixels: where a
2209
+ * point of the scene falls in the bitmap the layer draws. The renderer uses
2210
+ * it to replace, in a copy of that bitmap, the pixels a redaction covers
2211
+ * (ADR 0010).
2212
+ *
2213
+ * @param crop - The part of the source the layer draws: its crop, or all of it.
2214
+ * @public
2215
+ */
2216
+ export declare function sceneToLayerSource(box: ImageLayerBox, crop: ImageCrop): ImageMatrix;
2217
+
2218
+ /**
2219
+ * The transform from the scene to an output of the given size: through the
2220
+ * crop, the rotation and the flips, then the output's scale (ADR 0009). The
2221
+ * renderer draws layers through it, and the base through the same mapping,
2222
+ * so a layer stays on the pixels it was placed on.
2223
+ *
2224
+ * It's built from three points mapped by `sourceToComposition`, so it can't
2225
+ * disagree with the geometry the editor places frames with. Its entries are
2226
+ * exact for an output at the composition's own size.
2227
+ *
2228
+ * @param crop - The crop, or the whole source: `cropRect(plan.base.crop, source)`.
2229
+ * @public
2230
+ */
2231
+ export declare function sceneToOutput(crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageMatrix;
2232
+
1653
2233
  /**
1654
2234
  * Sets or removes the base's crop, in whole pixels of the oriented source.
1655
2235
  *
@@ -1681,6 +2261,18 @@ export declare interface SetFilterCommand {
1681
2261
  readonly filter: ImageFilter | null;
1682
2262
  }
1683
2263
 
2264
+ /**
2265
+ * Sets the whole order of the layers: every key, once. It's what undoes
2266
+ * {@link MoveLayersCommand}: the reducer applies it, but it isn't part of
2267
+ * the portable command format (ADR 0009).
2268
+ *
2269
+ * @public
2270
+ */
2271
+ export declare interface SetLayerOrderCommand {
2272
+ readonly type: "image.setLayerOrder";
2273
+ readonly keys: readonly string[];
2274
+ }
2275
+
1684
2276
  /**
1685
2277
  * Sets one metadata field to keep on export. An empty value keeps nothing.
1686
2278
  *
@@ -1712,6 +2304,18 @@ export declare interface SetOutputCommand {
1712
2304
  readonly output: ImageOutput;
1713
2305
  }
1714
2306
 
2307
+ /**
2308
+ * Sets the whole order of the redactions: every key, once. It's what undoes
2309
+ * {@link MoveRedactionsCommand}: the reducer applies it, but it isn't part
2310
+ * of the portable command format (ADR 0009).
2311
+ *
2312
+ * @public
2313
+ */
2314
+ export declare interface SetRedactionOrderCommand {
2315
+ readonly type: "image.setRedactionOrder";
2316
+ readonly keys: readonly string[];
2317
+ }
2318
+
1715
2319
  /**
1716
2320
  * Maps a point in the cropped source to the composition, through the plan's
1717
2321
  * rotation and then its flips. Points are continuous coordinates, so the
@@ -1732,6 +2336,34 @@ export declare function sourceToComposition(point: ImagePoint, crop: ImageCrop,
1732
2336
  */
1733
2337
  export declare function toImagePlanDocument(plan: ImagePlan, sources: Readonly<Record<string, ImagePlanDocumentSource>>): ImagePlanDocument;
1734
2338
 
2339
+ /**
2340
+ * Sets some fields of some layers: their boxes after a move, their opacity,
2341
+ * a text layer's text. `props` may hold any field of the layer's kind except
2342
+ * `key` and `kind`.
2343
+ *
2344
+ * @public
2345
+ */
2346
+ export declare interface UpdateLayersCommand {
2347
+ readonly type: "image.updateLayers";
2348
+ readonly updates: readonly {
2349
+ readonly key: string;
2350
+ readonly props: Readonly<Record<string, unknown>>;
2351
+ }[];
2352
+ }
2353
+
2354
+ /**
2355
+ * Sets some fields of some redactions, such as their regions after a move.
2356
+ *
2357
+ * @public
2358
+ */
2359
+ export declare interface UpdateRedactionsCommand {
2360
+ readonly type: "image.updateRedactions";
2361
+ readonly updates: readonly {
2362
+ readonly key: string;
2363
+ readonly props: ImageRedactionProps;
2364
+ }[];
2365
+ }
2366
+
1735
2367
  /**
1736
2368
  * No rotation and no flips.
1737
2369
  *