@hussmartinez/image-sdk 0.3.0 → 0.5.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,58 @@ 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
+ * Appends strokes to a drawing layer (ADR 0009, docs/adr/0014): one stroke
21
+ * for each gesture, however many runs it has.
22
+ *
23
+ * @public
24
+ */
25
+ export declare interface AddStrokesCommand {
26
+ readonly type: "image.addStrokes";
27
+ /** The drawing's key. */
28
+ readonly key: string;
29
+ readonly strokes: readonly ImageStroke[];
30
+ }
31
+
32
+ /**
33
+ * Where a point goes under a transform.
34
+ *
35
+ * @public
36
+ */
37
+ export declare function applyMatrix(matrix: ImageMatrix, point: {
38
+ readonly x: number;
39
+ readonly y: number;
40
+ }): {
41
+ readonly x: number;
42
+ readonly y: number;
43
+ };
44
+
45
+ /**
46
+ * The smallest whole-pixel rectangle of the scene that holds an arrow's
47
+ * outline.
48
+ *
49
+ * @public
50
+ */
51
+ export declare function arrowBounds(arrow: Pick<ImageArrowLayer, "from" | "to" | "width">): ImageRect;
52
+
53
+ /**
54
+ * An arrow's outline (docs/adr/0014): seven points of a polygon, in scene
55
+ * pixels, which the renderer fills. Its tip is exactly on `to`. The head is
56
+ * a triangle `4 × width` long and `4 × width` across at its base; the shaft
57
+ * is a rectangle `width` across from `from` to the middle of the head's
58
+ * base. An arrow shorter than its head is all head: the triangle keeps its
59
+ * proportions, as long as the arrow, and the shaft's four points are on its
60
+ * base.
61
+ *
62
+ * In order: the shaft's tail, left then right as the arrow points; the
63
+ * shaft's end on the base, right; the head's right corner; the tip; the
64
+ * head's left corner; the shaft's end on the base, left.
65
+ *
66
+ * @throws `RangeError` when `from` equals `to`: there's no direction.
67
+ * @public
68
+ */
69
+ export declare function arrowOutline(from: ImageScenePoint, to: ImageScenePoint, width: number): ImageScenePoint[];
70
+
19
71
  /**
20
72
  * The crop panel's presets, landscape then portrait (docs/adr/0007).
21
73
  *
@@ -63,6 +115,21 @@ export declare function checkOutputLimits(policy: ImageFilePolicy, size: {
63
115
  readonly height: number;
64
116
  }): void;
65
117
 
118
+ /**
119
+ * Refuses a plan that holds something a renderer or processor can't draw
120
+ * (ADR 0009). Nothing may be drawn or exported without a part of its plan:
121
+ * an export that left out a redaction would show what it was meant to hide.
122
+ * Every renderer and processor calls this, with the parts it draws, before
123
+ * it draws anything.
124
+ *
125
+ * @param plan - The plan to draw.
126
+ * @param supported - The parts this renderer or processor draws.
127
+ * @throws `ImageError` with `UNSUPPORTED_PLAN`, and the first part it can't
128
+ * draw as `details.reason`.
129
+ * @public
130
+ */
131
+ export declare function checkPlanSupport(plan: ImagePlan, supported: readonly ImagePlanPart[]): void;
132
+
66
133
  /**
67
134
  * A distance in the composition of the whole source, as a distance in the
68
135
  * oriented source: what a pointer drag on the stage moves the crop by.
@@ -74,6 +141,14 @@ export declare function compositionDeltaToSource(dx: number, dy: number, orienta
74
141
  readonly dy: number;
75
142
  };
76
143
 
144
+ /**
145
+ * The inverse of {@link sceneRectToComposition}: a rectangle drawn on the
146
+ * composition, such as a region dragged out on screen, in scene pixels.
147
+ *
148
+ * @public
149
+ */
150
+ export declare function compositionRectToScene(rect: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2): ImageRect;
151
+
77
152
  /**
78
153
  * The size of the composition: the cropped source, turned by the plan's own
79
154
  * rotation (ADR 0003).
@@ -121,6 +196,20 @@ export declare function compositionToSource(point: ImagePoint, crop: ImageCrop,
121
196
  */
122
197
  export declare function createImageEngine(options?: ImageEngineOptions): ImageEngine;
123
198
 
199
+ /**
200
+ * A new key for a layer, a redaction or a frame (ADR 0009): 24 hexadecimal
201
+ * digits from the platform's random source, so a key is never reused, even
202
+ * one a removed item had and the history may put back.
203
+ *
204
+ * Commands carry their keys, so the reducer stays pure: whatever builds an
205
+ * `image.insertRedactions` command calls this first.
206
+ *
207
+ * @param used - Keys to avoid, such as the plan's. A clash is not expected:
208
+ * it's checked so that a broken random source can't produce one.
209
+ * @public
210
+ */
211
+ export declare function createImageKey(used?: ReadonlySet<string>): string;
212
+
124
213
  /**
125
214
  * Creates the SDK's image processor over an engine from
126
215
  * {@link createImageEngine}, sharing its render worker, where the sources
@@ -203,7 +292,8 @@ export declare function createImageSession(options: ImageSessionOptions): ImageS
203
292
 
204
293
  /**
205
294
  * The plan for a newly opened source: the whole image, upright, undeveloped
206
- * and unfiltered, at full size, keeping no metadata.
295
+ * and unfiltered, with no layers or redactions, at full size, keeping no
296
+ * metadata.
207
297
  *
208
298
  * @public
209
299
  */
@@ -249,6 +339,23 @@ export declare const DEVELOP_ADJUSTMENTS: readonly ["temperature", "tint", "expo
249
339
  */
250
340
  export declare function dragHandle(crop: ImageCrop, handle: CropHandle, dx: number, dy: number, source: ImageSize, ratio?: number): ImageCrop;
251
341
 
342
+ /**
343
+ * The smallest whole-pixel rectangle of the scene that holds everything a
344
+ * drawing draws: its points, and half of each stroke's width around them
345
+ * (docs/adr/0014). The editor places a drawing's frame with it.
346
+ *
347
+ * @public
348
+ */
349
+ export declare function drawingBounds(drawing: Pick<ImageDrawingLayer, "x" | "y" | "strokes">): ImageRect;
350
+
351
+ /**
352
+ * How many points a plan's drawings hold, across every run of every stroke:
353
+ * what `maxDrawingPoints` limits (ADR 0009).
354
+ *
355
+ * @public
356
+ */
357
+ export declare function drawingPoints(plan: Pick<ImagePlan, "layers">): number;
358
+
252
359
  /**
253
360
  * Keepable metadata with every field empty.
254
361
  *
@@ -280,6 +387,17 @@ export declare const FILTER_PRESETS: readonly ["vivid", "warm", "cool", "fade",
280
387
  */
281
388
  export declare function fitAspect(within: ImageCrop, ratio: number | undefined): ImageCrop;
282
389
 
390
+ /**
391
+ * A rectangle as a redaction's region: whole pixels, rounded outward so it
392
+ * covers everything the rectangle touched, at least 1 × 1, and within
393
+ * `MAX_SCENE_COORDINATE` of the scene's origin. The editor fits what's
394
+ * dragged or typed with it before it builds a command, so the reducer never
395
+ * has to refuse it.
396
+ *
397
+ * @public
398
+ */
399
+ export declare function fitRedactionRegion(rect: ImageRect): ImageRect;
400
+
283
401
  /**
284
402
  * The view for a stage of this size: fitted, centred, at this ratio.
285
403
  *
@@ -287,6 +405,33 @@ export declare function fitAspect(within: ImageCrop, ratio: number | undefined):
287
405
  */
288
406
  export declare function fittedView(width: number, height: number, pixelRatio?: number): ImageView;
289
407
 
408
+ /**
409
+ * Where a text layer's lines go: the block of lines scaled uniformly to the
410
+ * largest size that fits the box, centred in its height, and each line
411
+ * placed by the alignment (ADR 0009). The layout is in the box's own
412
+ * pixels, so it's the same for the preview and for every export.
413
+ *
414
+ * @param lines - Each line's advance, at the size they were measured at.
415
+ * @param lineHeight - The height of one line at that size: the font's ascent
416
+ * and descent.
417
+ * @param ascent - The font's ascent at that size: from a line's top to its baseline.
418
+ * @param box - The layer's box: its width and height.
419
+ * @param align - `start`, `center` or `end`, by the text's direction.
420
+ * @param rightToLeft - Whether the text's direction is right to left, so
421
+ * `start` is the box's right edge.
422
+ * @returns The scale from the measured size to the drawn size, and for each
423
+ * line the x of its left edge and the y of its baseline, in the box's
424
+ * pixels. `null` when there's nothing to draw: no line has a width.
425
+ * @public
426
+ */
427
+ export declare function fitTextLines(lines: readonly ImageTextLine[], lineHeight: number, ascent: number, box: ImageSize, align: "start" | "center" | "end", rightToLeft: boolean): {
428
+ readonly scale: number;
429
+ readonly lines: readonly {
430
+ readonly x: number;
431
+ readonly baseline: number;
432
+ }[];
433
+ } | null;
434
+
290
435
  /**
291
436
  * The export at full size.
292
437
  *
@@ -315,7 +460,26 @@ export declare const IMAGE_PLAN_FORMAT = "hm-image-plan";
315
460
  *
316
461
  * @public
317
462
  */
318
- export declare const IMAGE_PLAN_VERSION = 1;
463
+ export declare const IMAGE_PLAN_VERSION = 3;
464
+
465
+ /**
466
+ * An arrow from one point of the scene to another (ADR 0009,
467
+ * docs/adr/0014). Its head's size follows its width, and its tip is exactly
468
+ * on `to`.
469
+ *
470
+ * @public
471
+ */
472
+ export declare interface ImageArrowLayer extends ImageLayerCommon {
473
+ readonly kind: "arrow";
474
+ /** The tail. */
475
+ readonly from: ImageScenePoint;
476
+ /** The tip. It differs from `from`. */
477
+ readonly to: ImageScenePoint;
478
+ /** `#rrggbb`. */
479
+ readonly colour: string;
480
+ /** The shaft's width, in whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
481
+ readonly width: number;
482
+ }
319
483
 
320
484
  /**
321
485
  * The crop frame's geometry (docs/adr/0007): pure functions over crops in
@@ -362,6 +526,13 @@ export declare interface ImageBase {
362
526
  readonly filter: ImageFilter | null;
363
527
  }
364
528
 
529
+ /**
530
+ * A layer that has a box: text, a shape or an image.
531
+ *
532
+ * @public
533
+ */
534
+ export declare type ImageBoxedLayer = ImageTextLayer | ImageShapeLayer | ImageImageLayer;
535
+
365
536
  /**
366
537
  * Options every port call accepts.
367
538
  *
@@ -378,11 +549,11 @@ export declare interface ImageCallOptions {
378
549
 
379
550
  /**
380
551
  * Every edit to an {@link ImagePlan}: plain, structured-cloneable data
381
- * (ADR 0003). Feature pull requests add their own commands to this union.
552
+ * (ADR 0003, ADR 0009).
382
553
  *
383
554
  * @public
384
555
  */
385
- export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand;
556
+ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | AddStrokesCommand | RemoveStrokesCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
386
557
 
387
558
  /**
388
559
  * Why a command was refused, as a stable token: `details.reason` on the
@@ -392,7 +563,8 @@ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetO
392
563
  * such as a missing field, a field of the wrong type, an unknown field, or
393
564
  * a crop that isn't whole pixels of at least 1 × 1.
394
565
  * - `unknown-command`: a `type` the reducer doesn't know.
395
- * - `unknown-source`: a crop for a plan whose source isn't registered.
566
+ * - `unknown-source`: a crop for a plan whose source isn't registered, or
567
+ * an image layer whose source isn't.
396
568
  * - `crop-outside-source`: a crop that doesn't fit inside its source.
397
569
  * - `invalid-orientation`: a rotation other than 0, 90, 180 or 270.
398
570
  * - `invalid-output`: a scale outside (0, 1], or a box under 1 pixel.
@@ -403,10 +575,39 @@ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetO
403
575
  * - `invalid-level`: a develop value that isn't a whole number from -100 to 100.
404
576
  * - `unknown-preset`: a filter that isn't one of `FILTER_PRESETS`.
405
577
  * - `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";
578
+ * - `invalid-key`: a key that's empty or over `MAX_KEY_LENGTH` code points.
579
+ * - `duplicate-key`: a new item with a key the plan already uses, or two
580
+ * new items or two updates with the same key.
581
+ * - `invalid-index`: an index past the end of the list.
582
+ * - `invalid-order`: an order that doesn't list every key.
583
+ * - `unknown-layer`: a key no layer has.
584
+ * - `unknown-layer-kind`: a kind other than `text`, `shape` and `image`.
585
+ * - `invalid-box`: a layer's box under 1 × 1 pixel, further than
586
+ * `MAX_SCENE_COORDINATE` from the scene's origin, or turned by other than
587
+ * 0 to 3599 tenths of a degree.
588
+ * - `invalid-opacity`: an opacity that isn't from 0 to 100.
589
+ * - `invalid-text`: text or a name with a control character other than a
590
+ * line feed, or a bidirectional embedding, override or isolate control.
591
+ * - `text-too-long`: text over `MAX_LAYER_TEXT_LENGTH` code points, or a
592
+ * name over `MAX_LAYER_NAME_LENGTH`.
593
+ * - `empty-shape`: a shape with neither a fill nor a stroke.
594
+ * - `wrong-kind`: an update that sets a field another kind of layer has.
595
+ * - `unknown-redaction`: a key no redaction has.
596
+ * - `unknown-redaction-mode`: a mode other than `solid` and `pixelate`.
597
+ * - `invalid-region`: a redaction under 1 × 1 pixel, or further than
598
+ * `MAX_SCENE_COORDINATE` from the scene's origin.
599
+ * - `invalid-colour`: a colour that isn't `#rrggbb` in lower case.
600
+ * - `unexpected-colour`: an update that sets a colour on a pixelated
601
+ * redaction, which has none.
602
+ * - `missing-colour`: an update that sets a redaction to solid without a
603
+ * colour.
604
+ * - `too-many-layers`: more layers and redactions than `MAX_PLAN_ITEMS`,
605
+ * the format's ceiling. The file policy's `maxLayers` is checked by the
606
+ * session, with its own error code.
607
+ *
608
+ * @public
609
+ */
610
+ 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" | "empty-drawing" | "empty-arrow" | "invalid-points" | "too-many-strokes" | "wrong-kind" | "unknown-redaction" | "unknown-redaction-mode" | "invalid-region" | "invalid-colour" | "unexpected-colour" | "missing-colour" | "too-many-layers";
410
611
 
411
612
  /**
412
613
  * A rectangle in whole pixels of the oriented source: `x` and `y` from its
@@ -451,14 +652,38 @@ export declare interface ImageDevelop {
451
652
  * reads.
452
653
  * - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
453
654
  * 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`.
655
+ * document doesn't list; `duplicate-key`, a key two items share; and, as
656
+ * for commands, `crop-outside-source`, `invalid-orientation`,
657
+ * `invalid-output`, `metadata-too-long`, `unknown-adjustment`,
658
+ * `invalid-level`, `unknown-preset`, `invalid-strength`, `invalid-key`,
659
+ * `unknown-redaction-mode`, `invalid-region`, `invalid-colour`,
660
+ * `unknown-layer-kind`, `invalid-box`, `invalid-opacity`, `invalid-text`,
661
+ * `text-too-long`, `empty-shape`, `empty-drawing`, `empty-arrow`,
662
+ * `invalid-points` and `too-many-layers`. `unknown-source` and
663
+ * `crop-outside-source` apply to an image layer too. A drawing or an
664
+ * arrow in a document of version 2, which has neither, is
665
+ * `unknown-layer-kind`.
458
666
  *
459
667
  * @public
460
668
  */
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";
669
+ 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" | "empty-drawing" | "empty-arrow" | "invalid-points" | "too-many-layers";
670
+
671
+ /**
672
+ * Freehand strokes (ADR 0009, docs/adr/0014). A drawing has an origin and
673
+ * no box: moving it changes its origin, never its points. Its strokes are
674
+ * drawn opaque and the drawing composited as one, so strokes that cross
675
+ * don't darken each other.
676
+ *
677
+ * @public
678
+ */
679
+ export declare interface ImageDrawingLayer extends ImageLayerCommon {
680
+ readonly kind: "drawing";
681
+ /** Its origin, in whole scene pixels. May be negative. */
682
+ readonly x: number;
683
+ readonly y: number;
684
+ /** 1 to `MAX_DRAWING_STROKES` strokes, in the order they're drawn. */
685
+ readonly strokes: readonly ImageStroke[];
686
+ }
462
687
 
463
688
  /**
464
689
  * The port for reading images: probe a file's headers, decode it into a
@@ -570,6 +795,10 @@ export declare class ImageError extends SdkError<ImageErrorCode> {
570
795
  * valid in its format. `details.reason` says why (`ImageDocumentRejection`).
571
796
  * A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
572
797
  * instead, with `details.reason` `unknown-format` or `unknown-format-version`.
798
+ * - `UNSUPPORTED_PLAN`: a plan holds something the renderer or processor
799
+ * can't draw, such as a layer kind from a later release. Nothing is drawn
800
+ * or exported without it (ADR 0009). `details.reason` names the part:
801
+ * `layers`, `redactions` or `animation`.
573
802
  * - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
574
803
  * the `maxImagePixels` limit.
575
804
  * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
@@ -578,6 +807,8 @@ export declare class ImageError extends SdkError<ImageErrorCode> {
578
807
  * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
579
808
  * `maxSessionSize` limit.
580
809
  * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
810
+ * - `TOO_MANY_POINTS`: the plan's drawings hold more points than the
811
+ * `maxDrawingPoints` limit.
581
812
  *
582
813
  * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
583
814
  * value and the `unit`. Other codes' `details` name the format involved,
@@ -585,7 +816,7 @@ export declare class ImageError extends SdkError<ImageErrorCode> {
585
816
  *
586
817
  * @public
587
818
  */
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";
819
+ 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" | "TOO_MANY_POINTS";
589
820
 
590
821
  /**
591
822
  * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
@@ -681,6 +912,43 @@ export declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
681
912
  */
682
913
  export declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
683
914
 
915
+ /**
916
+ * Another image, drawn to fill its box (ADR 0009).
917
+ *
918
+ * @public
919
+ */
920
+ export declare interface ImageImageLayer extends ImageLayerCommon, ImageLayerBox {
921
+ readonly kind: "image";
922
+ /** The id of a registered source. */
923
+ readonly source: string;
924
+ /** The part of that source to draw, in its own pixels, or `null` for all of it. */
925
+ readonly crop: ImageCrop | null;
926
+ }
927
+
928
+ /**
929
+ * Options for {@link ImageSession.insertImage}.
930
+ *
931
+ * @public
932
+ */
933
+ declare interface ImageInsertOptions {
934
+ readonly signal?: AbortSignal;
935
+ /**
936
+ * The commands that add the image to the plan, instead of the default
937
+ * layer: given the new source and the plan as it is.
938
+ */
939
+ readonly place?: (source: ImageSessionSource, plan: ImagePlan) => ImageCommand | readonly ImageCommand[];
940
+ }
941
+
942
+ /**
943
+ * The commands that exist only to undo others. The reducer applies them, and
944
+ * they're plain data like every command, but the `hm-image-command` format
945
+ * doesn't include them: an inverse's shape may change between releases
946
+ * (sdk-core ADR 0045).
947
+ *
948
+ * @public
949
+ */
950
+ export declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
951
+
684
952
  /**
685
953
  * The metadata fields a user may keep on export (ADR 0005). Empty strings
686
954
  * mean the field isn't written.
@@ -694,6 +962,71 @@ export declare interface ImageKeepableMetadata {
694
962
  readonly copyright: string;
695
963
  }
696
964
 
965
+ /**
966
+ * A layer over the base: text, a shape, another image, a drawing or an
967
+ * arrow (ADR 0009). Layers are drawn bottom to top, in the plan's order, and
968
+ * redactions over all of them.
969
+ *
970
+ * @public
971
+ */
972
+ export declare type ImageLayer = ImageBoxedLayer | ImageDrawingLayer | ImageArrowLayer;
973
+
974
+ /**
975
+ * Where a positioned layer is: a box in whole pixels of the scene, the
976
+ * base's oriented source, mirrored or not, then turned about its centre
977
+ * (ADR 0009). The box stays
978
+ * on the pixels it covers when the image is cropped or turned.
979
+ *
980
+ * @public
981
+ */
982
+ export declare interface ImageLayerBox {
983
+ /** The box's left edge, before its rotation. May be negative. */
984
+ readonly x: number;
985
+ /** The box's top edge, before its rotation. May be negative. */
986
+ readonly y: number;
987
+ /** At least 1. */
988
+ readonly width: number;
989
+ /** At least 1. */
990
+ readonly height: number;
991
+ /** Tenths of a degree, clockwise about the box's centre: 0 to 3599. */
992
+ readonly rotation: number;
993
+ /**
994
+ * Whether the layer is mirrored left to right, about the box's own
995
+ * vertical axis, before it's turned. With a half turn, that's a mirror top
996
+ * to bottom, so one flip is all a box needs.
997
+ */
998
+ readonly flipX: boolean;
999
+ }
1000
+
1001
+ /**
1002
+ * What every layer has (ADR 0009).
1003
+ *
1004
+ * @public
1005
+ */
1006
+ export declare interface ImageLayerCommon {
1007
+ /**
1008
+ * Its identity: 1 to `MAX_KEY_LENGTH` code points, unique among the plan's
1009
+ * layers and redactions.
1010
+ */
1011
+ readonly key: string;
1012
+ /**
1013
+ * What the layers list calls it: up to `MAX_LAYER_NAME_LENGTH` code
1014
+ * points. Empty means the editor's own label for the kind.
1015
+ */
1016
+ readonly name: string;
1017
+ /** Whether it's drawn. */
1018
+ readonly visible: boolean;
1019
+ /** A whole number from 0, transparent, to 100, opaque. */
1020
+ readonly opacity: number;
1021
+ }
1022
+
1023
+ /**
1024
+ * A layer's kind.
1025
+ *
1026
+ * @public
1027
+ */
1028
+ export declare type ImageLayerKind = ImageLayer["kind"];
1029
+
697
1030
  /**
698
1031
  * The type of {@link imageLimitDefinitions}.
699
1032
  *
@@ -716,6 +1049,7 @@ export declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
716
1049
  * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
717
1050
  * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
718
1051
  * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
1052
+ * | `maxDrawingPoints` | `TOO_MANY_POINTS` | 200,000 | 100,000 |
719
1053
  *
720
1054
  * Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
721
1055
  * per pixel. `maxImagePixels` is the same limit, with the same name, code
@@ -758,6 +1092,12 @@ export declare const imageLimitDefinitions: {
758
1092
  readonly unit: "count";
759
1093
  readonly default: 256;
760
1094
  };
1095
+ readonly maxDrawingPoints: {
1096
+ readonly code: "TOO_MANY_POINTS";
1097
+ readonly unit: "count";
1098
+ readonly default: 200000;
1099
+ readonly warning: 100000;
1100
+ };
761
1101
  readonly maxFileSize: {
762
1102
  readonly code: "FILE_TOO_LARGE";
763
1103
  readonly unit: "bytes";
@@ -797,6 +1137,21 @@ export declare type ImageLimitName = keyof ImageLimitDefinitions;
797
1137
  */
798
1138
  export declare const imageLimits: Limits<ImageLimitDefinitions>;
799
1139
 
1140
+ /**
1141
+ * A 2D affine transform, as the canvas takes it: `x' = a·x + c·y + e` and
1142
+ * `y' = b·x + d·y + f`.
1143
+ *
1144
+ * @public
1145
+ */
1146
+ export declare type ImageMatrix = readonly [
1147
+ a: number,
1148
+ b: number,
1149
+ c: number,
1150
+ d: number,
1151
+ e: number,
1152
+ f: number
1153
+ ];
1154
+
800
1155
  /**
801
1156
  * The type of {@link imageMessages}, for typing a host's overrides with
802
1157
  * `MessageOverrides<ImageMessageCatalogue>`.
@@ -806,11 +1161,16 @@ export declare const imageLimits: Limits<ImageLimitDefinitions>;
806
1161
  export declare type ImageMessageCatalogue = typeof imageMessages;
807
1162
 
808
1163
  /**
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.
1164
+ * The image SDK's English message catalogue for the server-safe entry:
1165
+ * sdk-core's messages, and text for every {@link ImageErrorCode} and every
1166
+ * limit's warning, which the headless session produces and a host shows.
1167
+ * Pass it to `createMessages` from `@hussmartinez/sdk-core`, with the host's
1168
+ * locale and overrides.
1169
+ *
1170
+ * It holds no interface text: the editor's labels, states, announcements
1171
+ * and tool names are in `imageEditorMessages`, from the React entry, so
1172
+ * hosts of this entry, servers included, don't carry text nothing here
1173
+ * shows (docs/adr/0012).
814
1174
  *
815
1175
  * Error text is looked up by code, with the error's `details` as
816
1176
  * parameters, and never taken from `error.message` (ADR 0019).
@@ -825,12 +1185,12 @@ export declare type ImageMessageCatalogue = typeof imageMessages;
825
1185
  * @public
826
1186
  */
827
1187
  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
1188
  readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
830
1189
  readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
831
1190
  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
1191
  readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
833
1192
  readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
1193
+ readonly "errors.UNSUPPORTED_PLAN": "This image has edits this version can't show. Update the application and try again.";
834
1194
  readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
835
1195
  readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
836
1196
  readonly "errors.TOO_MANY_FRAMES": {
@@ -846,6 +1206,7 @@ export declare const imageMessages: {
846
1206
  readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
847
1207
  readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
848
1208
  };
1209
+ readonly "errors.TOO_MANY_POINTS": "This image's drawings would have {actual, number} points, which is over the limit of {maximum, number}. Remove some strokes, and try again.";
849
1210
  readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
850
1211
  readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
851
1212
  readonly "warnings.maxFrames": {
@@ -861,155 +1222,7 @@ export declare const imageMessages: {
861
1222
  readonly one: "This image has {actual} layer.";
862
1223
  readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
863
1224
  };
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}.";
1225
+ readonly "warnings.maxDrawingPoints": "This image has a lot of drawing, and may be slow to edit and export.";
1013
1226
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
1014
1227
  readonly "errors.ABORTED": "The operation was cancelled.";
1015
1228
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -1106,20 +1319,27 @@ export declare type ImageOutput = {
1106
1319
 
1107
1320
  /**
1108
1321
  * The session's document: a description of the edits over an immutable
1109
- * source, rendered to pixels only for display and export (ADR 0003).
1322
+ * source, rendered to pixels only for display and export (ADR 0003, ADR
1323
+ * 0009).
1110
1324
  *
1111
1325
  * @public
1112
1326
  */
1113
1327
  export declare interface ImagePlan {
1114
1328
  readonly base: ImageBase;
1329
+ /** The layers over the base, bottom to top, placed in the scene (ADR 0009). */
1330
+ readonly layers: readonly ImageLayer[];
1331
+ /** The redactions, applied over every layer (ADR 0010). */
1332
+ readonly redactions: readonly ImageRedaction[];
1333
+ /** The animation (ADR 0011). Always `null` until format version 4. */
1334
+ readonly animation: null;
1115
1335
  readonly output: ImageOutput;
1116
1336
  /** The fields the user chose to keep on export. Never a location (ADR 0005). */
1117
1337
  readonly metadata: ImageKeepableMetadata;
1118
1338
  }
1119
1339
 
1120
1340
  /**
1121
- * The plan as portable JSON: `hm-image-plan` version 1, which
1122
- * `formats/hm-image-plan/v1.schema.json` describes
1341
+ * The plan as portable JSON: `hm-image-plan` version 3, which
1342
+ * `formats/hm-image-plan/v3.schema.json` describes
1123
1343
  * (docs/formats/hm-image-plan.md). Positions are whole pixels of the
1124
1344
  * oriented source, and the base names its source by an id the document
1125
1345
  * lists.
@@ -1143,6 +1363,15 @@ export declare interface ImagePlanDocumentSource extends ImageSize {
1143
1363
  readonly asset?: ImageAssetReference;
1144
1364
  }
1145
1365
 
1366
+ /**
1367
+ * A part of a plan that a renderer or processor may not know how to draw.
1368
+ * `layers` is any layer; `drawings` is a drawing or an arrow layer, which a
1369
+ * renderer that draws the other kinds may not.
1370
+ *
1371
+ * @public
1372
+ */
1373
+ export declare type ImagePlanPart = "layers" | "drawings" | "redactions" | "animation";
1374
+
1146
1375
  /**
1147
1376
  * A point in pixels, which may be fractional.
1148
1377
  *
@@ -1223,6 +1452,83 @@ export declare interface ImageProgressOptions extends ImageCallOptions {
1223
1452
  readonly onProgress?: (fraction: number) => void;
1224
1453
  }
1225
1454
 
1455
+ /**
1456
+ * A rectangle in whole pixels.
1457
+ *
1458
+ * @public
1459
+ */
1460
+ export declare interface ImageRect {
1461
+ readonly x: number;
1462
+ readonly y: number;
1463
+ readonly width: number;
1464
+ readonly height: number;
1465
+ }
1466
+
1467
+ /**
1468
+ * A region of the image that an export doesn't show (ADR 0010): a rectangle
1469
+ * in whole pixels of the scene, the base's oriented source, so it stays on
1470
+ * the pixels it covers when the image is cropped or turned (ADR 0009).
1471
+ *
1472
+ * A redaction has no opacity, visibility or rotation, and is drawn over
1473
+ * every layer. Only exports are redacted: the plan describes the redaction,
1474
+ * and the source is unchanged.
1475
+ *
1476
+ * @public
1477
+ */
1478
+ export declare type ImageRedaction = (ImageRedactionRegion & {
1479
+ readonly mode: "solid";
1480
+ /** The fill, as `#rrggbb` in lower case. */
1481
+ readonly colour: string;
1482
+ }) | (ImageRedactionRegion & {
1483
+ readonly mode: "pixelate";
1484
+ });
1485
+
1486
+ /**
1487
+ * How a redaction replaces what it covers (ADR 0010): `solid` fills the
1488
+ * region with one colour, and `pixelate` with coarse blocks of the average
1489
+ * colour beneath each. Only `solid` destroys what was there.
1490
+ *
1491
+ * @public
1492
+ */
1493
+ export declare type ImageRedactionMode = "solid" | "pixelate";
1494
+
1495
+ /**
1496
+ * The fields of a redaction that `image.updateRedactions` may set: any but
1497
+ * its key. Setting `mode` to `pixelate` drops the colour, and setting it to
1498
+ * `solid` needs one in the same update.
1499
+ *
1500
+ * @public
1501
+ */
1502
+ export declare interface ImageRedactionProps {
1503
+ readonly mode?: ImageRedaction["mode"];
1504
+ readonly x?: number;
1505
+ readonly y?: number;
1506
+ readonly width?: number;
1507
+ readonly height?: number;
1508
+ readonly colour?: string;
1509
+ }
1510
+
1511
+ /**
1512
+ * What every redaction has, whatever its mode: its identity and its region.
1513
+ *
1514
+ * @public
1515
+ */
1516
+ export declare interface ImageRedactionRegion {
1517
+ /**
1518
+ * Its identity: 1 to {@link MAX_KEY_LENGTH} code points, unique among the
1519
+ * plan's layers and redactions.
1520
+ */
1521
+ readonly key: string;
1522
+ /** The region's left edge, in whole pixels of the scene. May be negative. */
1523
+ readonly x: number;
1524
+ /** The region's top edge, in whole pixels of the scene. May be negative. */
1525
+ readonly y: number;
1526
+ /** At least 1. */
1527
+ readonly width: number;
1528
+ /** At least 1. */
1529
+ readonly height: number;
1530
+ }
1531
+
1226
1532
  /**
1227
1533
  * Options for registering a source.
1228
1534
  *
@@ -1298,6 +1604,16 @@ export declare type ImageRenderOutcome = "drawn" | "superseded";
1298
1604
  */
1299
1605
  export declare type ImageRotation = 0 | 90 | 180 | 270;
1300
1606
 
1607
+ /**
1608
+ * A point of the scene, in whole pixels.
1609
+ *
1610
+ * @public
1611
+ */
1612
+ export declare interface ImageScenePoint {
1613
+ readonly x: number;
1614
+ readonly y: number;
1615
+ }
1616
+
1301
1617
  /**
1302
1618
  * An image editing session (ADR 0003, ADR 0008): one document, its plan
1303
1619
  * over the source it opened, edited by commands with undo and redo, and
@@ -1321,6 +1637,29 @@ export declare interface ImageSession {
1321
1637
  open(file: Blob, options?: {
1322
1638
  readonly signal?: AbortSignal;
1323
1639
  }): Promise<ImageSessionSource>;
1640
+ /**
1641
+ * Probes, checks and decodes another file, and adds it to the document as
1642
+ * an image layer, as one undoable step (ADR 0003, ADR 0004).
1643
+ *
1644
+ * - **Limits:** the file's own, as for `open`; `maxFiles`, counting every
1645
+ * source the session holds; and `maxSessionSize`, counting their decoded
1646
+ * bytes. When the image doesn't fit, the session first drops the oldest
1647
+ * undo steps that alone keep another image, and marks the history as
1648
+ * trimmed. If that isn't enough, nothing is dropped and it fails with
1649
+ * `SESSION_TOO_LARGE`.
1650
+ * - **Placement:** by default the image is centred on what's shown, at
1651
+ * its own size or half the composition's, whichever is smaller, over
1652
+ * every layer, and turned and mirrored back against the plan's
1653
+ * rotation and flips, so it's seen as the file is. `place` returns other commands; they must refer to the
1654
+ * source, or it's released.
1655
+ * - **Lifetime:** the session holds the source while the plan, an undo
1656
+ * or redo step, or an export in progress refers to it, and releases it
1657
+ * then.
1658
+ *
1659
+ * A failure, a cancellation, or another file opened meanwhile adds
1660
+ * nothing and releases the source.
1661
+ */
1662
+ insertImage(file: Blob, options?: ImageInsertOptions): Promise<ImageSessionSource>;
1324
1663
  /**
1325
1664
  * Applies commands as one undoable step. They're checked by the reducer,
1326
1665
  * then the output against `maxImageDimension` and `maxImagePixels`; a
@@ -1331,7 +1670,9 @@ export declare interface ImageSession {
1331
1670
  * Makes the document's plan equal to `plan`, as one undoable step of the
1332
1671
  * commands that reach it, checked as `execute` checks them (ADR 0003). A
1333
1672
  * plan equal to the current one changes nothing. A plan over another
1334
- * source is `INVALID_COMMAND`. For editors whose host holds the plan.
1673
+ * source is `INVALID_COMMAND`, and so is one without `layers`,
1674
+ * `redactions` and `animation`, such as a plan stored before format
1675
+ * version 2. For editors whose host holds the plan.
1335
1676
  */
1336
1677
  applyPlan(plan: ImagePlan): void;
1337
1678
  /**
@@ -1355,7 +1696,7 @@ export declare interface ImageSession {
1355
1696
  readonly signal?: AbortSignal;
1356
1697
  readonly onProgress?: (fraction: number) => void;
1357
1698
  }): Promise<ImageSessionExport>;
1358
- /** Releases the source the session holds. Later calls throw. */
1699
+ /** Releases every source the session holds. Later calls throw. */
1359
1700
  destroy(): Promise<void>;
1360
1701
  }
1361
1702
 
@@ -1366,7 +1707,7 @@ export declare interface ImageSession {
1366
1707
  * @public
1367
1708
  */
1368
1709
  export declare interface ImageSessionEvent {
1369
- readonly type: "open" | "execute" | "undo" | "redo" | "export";
1710
+ readonly type: "open" | "insert" | "execute" | "undo" | "redo" | "export";
1370
1711
  readonly outcome: "done" | "failed" | "cancelled";
1371
1712
  /** The types of the commands applied or undone. */
1372
1713
  readonly commands: readonly ImageCommand["type"][];
@@ -1420,8 +1761,20 @@ export declare interface ImageSessionSnapshot {
1420
1761
  readonly plan: ImagePlan | null;
1421
1762
  /** The document's source, or `null` before a file is open. */
1422
1763
  readonly source: ImageSessionSource | null;
1764
+ /**
1765
+ * Every source the session holds: the document's, then those of image
1766
+ * layers, including ones only the history still refers to (ADR 0004).
1767
+ */
1768
+ readonly sources: readonly ImageSessionSource[];
1423
1769
  readonly canUndo: boolean;
1424
1770
  readonly canRedo: boolean;
1771
+ /**
1772
+ * Whether undo steps were dropped to make room for an image, since the
1773
+ * document was opened: they can no longer be undone.
1774
+ */
1775
+ readonly historyTrimmed: boolean;
1776
+ /** Whether an image is being added as a layer. */
1777
+ readonly inserting: boolean;
1425
1778
  /** Whether a file is being opened. The current document stays until it's ready. */
1426
1779
  readonly opening: boolean;
1427
1780
  /** Whether an export is in progress. */
@@ -1448,6 +1801,25 @@ export declare interface ImageSessionSource extends ImageSourceInfo {
1448
1801
  readonly keepable: ImageKeepableMetadata;
1449
1802
  }
1450
1803
 
1804
+ /**
1805
+ * A rectangle or an ellipse that fills its box, with a fill, a stroke drawn
1806
+ * inside the box, or both (ADR 0009).
1807
+ *
1808
+ * @public
1809
+ */
1810
+ export declare interface ImageShapeLayer extends ImageLayerCommon, ImageLayerBox {
1811
+ readonly kind: "shape";
1812
+ readonly shape: (typeof LAYER_SHAPES)[number];
1813
+ /** The fill, as `#rrggbb` in lower case, or `null` for none. */
1814
+ readonly fill: string | null;
1815
+ /** The stroke, or `null` for none. A shape has a fill or a stroke. */
1816
+ readonly stroke: {
1817
+ readonly colour: string;
1818
+ /** In whole scene pixels, from 1 to `MAX_STROKE_WIDTH`. */
1819
+ readonly width: number;
1820
+ } | null;
1821
+ }
1822
+
1451
1823
  /**
1452
1824
  * A width and a height, in whole pixels.
1453
1825
  *
@@ -1475,6 +1847,56 @@ export declare interface ImageSourceInfo {
1475
1847
  readonly decodedBytes: number;
1476
1848
  }
1477
1849
 
1850
+ /**
1851
+ * One stroke of a drawing: what one gesture drew, from the press to the
1852
+ * release (docs/adr/0014). It has more than one run only when it's long.
1853
+ *
1854
+ * @public
1855
+ */
1856
+ export declare interface ImageStroke {
1857
+ /** `#rrggbb`. */
1858
+ readonly colour: string;
1859
+ /** In whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
1860
+ readonly width: number;
1861
+ /**
1862
+ * 1 to `MAX_STROKE_RUNS` runs, each a polyline `[x0, y0, x1, y1, …]` of 1
1863
+ * to `MAX_RUN_POINTS` points, in whole pixels from the drawing's origin.
1864
+ * A run of one point is a dot.
1865
+ */
1866
+ readonly runs: readonly (readonly number[])[];
1867
+ }
1868
+
1869
+ /**
1870
+ * Text, drawn as large as fits inside its box, never distorted (ADR 0009).
1871
+ * Lines break only at line feeds. Emoji are text.
1872
+ *
1873
+ * @public
1874
+ */
1875
+ export declare interface ImageTextLayer extends ImageLayerCommon, ImageLayerBox {
1876
+ readonly kind: "text";
1877
+ /**
1878
+ * Up to `MAX_LAYER_TEXT_LENGTH` code points. Control characters other
1879
+ * than a line feed, and the bidirectional embedding, override and isolate
1880
+ * controls, are refused.
1881
+ */
1882
+ readonly text: string;
1883
+ readonly font: (typeof LAYER_FONTS)[number];
1884
+ readonly bold: boolean;
1885
+ /** The text's colour, as `#rrggbb` in lower case. */
1886
+ readonly colour: string;
1887
+ readonly align: (typeof LAYER_ALIGNMENTS)[number];
1888
+ }
1889
+
1890
+ /**
1891
+ * What a line of text measures at the size it's laid out at.
1892
+ *
1893
+ * @public
1894
+ */
1895
+ export declare interface ImageTextLine {
1896
+ /** Its advance: how far the pen moves. */
1897
+ readonly width: number;
1898
+ }
1899
+
1478
1900
  /**
1479
1901
  * A small rendering of a source for lists and frame strips. An `ImageBitmap`
1480
1902
  * is one; tests can supply their own. Close it when it's no longer shown.
@@ -1517,6 +1939,40 @@ export declare interface ImageView {
1517
1939
  readonly inset?: number;
1518
1940
  }
1519
1941
 
1942
+ /**
1943
+ * Inserts layers at an index of the plan's layers, which are drawn bottom
1944
+ * to top (ADR 0009). Each needs a key no layer or redaction of the plan has.
1945
+ *
1946
+ * @public
1947
+ */
1948
+ export declare interface InsertLayersCommand {
1949
+ readonly type: "image.insertLayers";
1950
+ /** From 0, under every layer, to the number of layers, over them all. */
1951
+ readonly at: number;
1952
+ readonly layers: readonly ImageLayer[];
1953
+ }
1954
+
1955
+ /**
1956
+ * Inserts redactions at an index of the plan's redactions (ADR 0010). Each
1957
+ * needs a key no layer or redaction of the plan has.
1958
+ *
1959
+ * @public
1960
+ */
1961
+ export declare interface InsertRedactionsCommand {
1962
+ readonly type: "image.insertRedactions";
1963
+ /** From 0 to the number of redactions. */
1964
+ readonly at: number;
1965
+ readonly redactions: readonly ImageRedaction[];
1966
+ }
1967
+
1968
+ /**
1969
+ * The inverse of a transform that has one: every transform here does, since
1970
+ * a box and an output have at least one pixel.
1971
+ *
1972
+ * @public
1973
+ */
1974
+ export declare function invertMatrix(matrix: ImageMatrix): ImageMatrix;
1975
+
1520
1976
  /**
1521
1977
  * Checks whether a value is an {@link ImageError}, optionally with a given
1522
1978
  * code.
@@ -1533,6 +1989,92 @@ export declare function isImageError<Code extends ImageErrorCode = ImageErrorCod
1533
1989
  readonly code: Code;
1534
1990
  };
1535
1991
 
1992
+ /**
1993
+ * Whether text reads right to left: whether its first strongly directional
1994
+ * character is from a right-to-left script, such as Hebrew or Arabic. Text
1995
+ * with no such character reads left to right.
1996
+ *
1997
+ * @public
1998
+ */
1999
+ export declare function isRightToLeft(text: string): boolean;
2000
+
2001
+ /**
2002
+ * How a text layer's lines sit in its box, by the text's own direction.
2003
+ *
2004
+ * @public
2005
+ */
2006
+ export declare const LAYER_ALIGNMENTS: readonly ["start", "center", "end"];
2007
+
2008
+ /**
2009
+ * The fonts a text layer can use: the generic families, which every device
2010
+ * has, so the SDK ships and fetches none (ADR 0009). Names are part of the
2011
+ * document format.
2012
+ *
2013
+ * @public
2014
+ */
2015
+ export declare const LAYER_FONTS: readonly ["sans-serif", "serif", "monospace"];
2016
+
2017
+ /**
2018
+ * The kinds of layer. Names are part of the document format.
2019
+ *
2020
+ * @public
2021
+ */
2022
+ export declare const LAYER_KINDS: readonly ["text", "shape", "image", "drawing", "arrow"];
2023
+
2024
+ /**
2025
+ * The shapes a shape layer can be.
2026
+ *
2027
+ * @public
2028
+ */
2029
+ export declare const LAYER_SHAPES: readonly ["rectangle", "ellipse"];
2030
+
2031
+ /**
2032
+ * The transform from a layer's own box to an output: {@link layerToScene},
2033
+ * then {@link sceneToOutput}. The renderer sets it on the canvas and draws
2034
+ * the layer in its box's own pixels.
2035
+ *
2036
+ * @public
2037
+ */
2038
+ export declare function layerToOutput(box: ImageLayerBox, crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageMatrix;
2039
+
2040
+ /**
2041
+ * The transform from a layer's own box to the scene: the box's top-left
2042
+ * corner is the origin, one unit is one scene pixel, and the box is mirrored
2043
+ * left to right when it's flipped, then turned about its centre by its
2044
+ * rotation, clockwise, in tenths of a degree (ADR 0009).
2045
+ *
2046
+ * @public
2047
+ */
2048
+ export declare function layerToScene(box: ImageLayerBox): ImageMatrix;
2049
+
2050
+ /**
2051
+ * The most strokes in a drawing (docs/adr/0014).
2052
+ *
2053
+ * @public
2054
+ */
2055
+ export declare const MAX_DRAWING_STROKES = 1024;
2056
+
2057
+ /**
2058
+ * The most Unicode code points in a key.
2059
+ *
2060
+ * @public
2061
+ */
2062
+ export declare const MAX_KEY_LENGTH = 64;
2063
+
2064
+ /**
2065
+ * The most Unicode code points in a layer's name.
2066
+ *
2067
+ * @public
2068
+ */
2069
+ export declare const MAX_LAYER_NAME_LENGTH = 100;
2070
+
2071
+ /**
2072
+ * The most Unicode code points in a text layer's text (ADR 0009).
2073
+ *
2074
+ * @public
2075
+ */
2076
+ export declare const MAX_LAYER_TEXT_LENGTH = 1000;
2077
+
1536
2078
  /**
1537
2079
  * The longest a kept metadata value may be, in Unicode code points, as JSON
1538
2080
  * Schema and every language count them (ADR 0005, sdk-core ADR 0045).
@@ -1550,6 +2092,45 @@ export declare const MAX_METADATA_LENGTH = 2000;
1550
2092
  */
1551
2093
  export declare const MAX_PIXEL_RATIO = 4;
1552
2094
 
2095
+ /**
2096
+ * The most layers and redactions a plan holds, together: the format's
2097
+ * ceiling, which the file policy's `maxLayers` applies below (ADR 0009).
2098
+ *
2099
+ * @public
2100
+ */
2101
+ export declare const MAX_PLAN_ITEMS = 1024;
2102
+
2103
+ /**
2104
+ * The most points in one run of a drawing's stroke (docs/adr/0014).
2105
+ *
2106
+ * @public
2107
+ */
2108
+ export declare const MAX_RUN_POINTS = 2000;
2109
+
2110
+ /**
2111
+ * How far from the scene's origin a position may be, in pixels, either way:
2112
+ * four times the longest side `maxImageDimension` allows by default (ADR
2113
+ * 0009).
2114
+ *
2115
+ * @public
2116
+ */
2117
+ export declare const MAX_SCENE_COORDINATE = 65536;
2118
+
2119
+ /**
2120
+ * The most runs in a stroke (docs/adr/0014).
2121
+ *
2122
+ * @public
2123
+ */
2124
+ export declare const MAX_STROKE_RUNS = 64;
2125
+
2126
+ /**
2127
+ * The widest stroke of a shape or a drawing, and the widest arrow's shaft,
2128
+ * in scene pixels.
2129
+ *
2130
+ * @public
2131
+ */
2132
+ export declare const MAX_STROKE_WIDTH = 1024;
2133
+
1553
2134
  /**
1554
2135
  * A crop moved by whole pixels, kept inside the source.
1555
2136
  *
@@ -1557,6 +2138,30 @@ export declare const MAX_PIXEL_RATIO = 4;
1557
2138
  */
1558
2139
  export declare function moveCrop(crop: ImageCrop, dx: number, dy: number, source: ImageSize): ImageCrop;
1559
2140
 
2141
+ /**
2142
+ * Moves layers to an index of the list without them, keeping the order they
2143
+ * had: up or down the stack.
2144
+ *
2145
+ * @public
2146
+ */
2147
+ export declare interface MoveLayersCommand {
2148
+ readonly type: "image.moveLayers";
2149
+ readonly keys: readonly string[];
2150
+ readonly to: number;
2151
+ }
2152
+
2153
+ /**
2154
+ * Moves redactions to an index of the list without them, keeping the order
2155
+ * they had. The order only decides how overlapping redactions look.
2156
+ *
2157
+ * @public
2158
+ */
2159
+ export declare interface MoveRedactionsCommand {
2160
+ readonly type: "image.moveRedactions";
2161
+ readonly keys: readonly string[];
2162
+ readonly to: number;
2163
+ }
2164
+
1560
2165
  /**
1561
2166
  * Every adjustment at 0: the base as it was decoded.
1562
2167
  *
@@ -1635,8 +2240,12 @@ export declare function placement(composition: {
1635
2240
  /**
1636
2241
  * Reads a plan document, such as one parsed from JSON, checking it as
1637
2242
  * {@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.
2243
+ * be one the document lists, as must an image layer's, their crops must fit
2244
+ * inside them, and no two items share a key. Unknown fields are refused, never dropped.
2245
+ *
2246
+ * A document of an earlier version is migrated, so every version stays
2247
+ * readable: version 1 reads as a plan with no layers or redactions, and
2248
+ * version 2 as it is, with the kinds of layer it had.
1640
2249
  *
1641
2250
  * @param value - The parsed JSON.
1642
2251
  * @returns The plan, and its sources by id.
@@ -1650,6 +2259,172 @@ export declare function readImagePlanDocument(value: unknown): {
1650
2259
  readonly sources: Readonly<Record<string, ImagePlanDocumentSource>>;
1651
2260
  };
1652
2261
 
2262
+ /**
2263
+ * The redaction modes. Names are part of the document format.
2264
+ *
2265
+ * @public
2266
+ */
2267
+ export declare const REDACTION_MODES: readonly ["solid", "pixelate"];
2268
+
2269
+ /**
2270
+ * A pixelated region's blocks in the output: the scene's block boundaries
2271
+ * mapped as {@link redactionRectInOutput} maps the region. The region's own
2272
+ * edges are rounded outward and the boundaries between blocks to the
2273
+ * nearest pixel, so the blocks tile exactly the pixels the region covers. A
2274
+ * block with no output pixel is left out. They're listed row by row.
2275
+ *
2276
+ * @public
2277
+ */
2278
+ export declare function redactionBlocksInOutput(region: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageRect[];
2279
+
2280
+ /**
2281
+ * A pixelated region's blocks in the scene, each clipped to `within`: the
2282
+ * part of the source that's rendered, its crop. Blocks are aligned to the
2283
+ * region's top-left corner, and one that falls wholly outside `within` is
2284
+ * left out. They're listed row by row.
2285
+ *
2286
+ * @public
2287
+ */
2288
+ export declare function redactionBlocksInScene(region: ImageRect, within: ImageRect): ImageRect[];
2289
+
2290
+ /**
2291
+ * The side of a pixelated region's square blocks, in scene pixels: the
2292
+ * larger of 8 and a twelfth of the region's longer side, rounded up (ADR
2293
+ * 0010). So a region has at most 12 blocks along its longer side, and a
2294
+ * strip over a line of text is one row of them. It isn't a setting.
2295
+ *
2296
+ * @public
2297
+ */
2298
+ export declare function redactionBlockSize(region: ImageSize): number;
2299
+
2300
+ /**
2301
+ * The output pixels a region covers: the region mapped through the crop,
2302
+ * the rotation, the flips and the output's scale, rounded outward so that
2303
+ * every pixel it touches is covered whole, and clipped to the output (ADR
2304
+ * 0010). `null` when it covers none.
2305
+ *
2306
+ * @param region - The region, in scene pixels.
2307
+ * @param crop - The crop, or the whole source: `cropRect(plan.base.crop, source)`.
2308
+ * @param orientation - The plan's rotation and flips.
2309
+ * @param output - The size being rendered.
2310
+ * @public
2311
+ */
2312
+ export declare function redactionRectInOutput(region: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageRect | null;
2313
+
2314
+ /**
2315
+ * Removes layers, by key.
2316
+ *
2317
+ * @public
2318
+ */
2319
+ export declare interface RemoveLayersCommand {
2320
+ readonly type: "image.removeLayers";
2321
+ readonly keys: readonly string[];
2322
+ }
2323
+
2324
+ /**
2325
+ * Removes redactions, by key.
2326
+ *
2327
+ * @public
2328
+ */
2329
+ export declare interface RemoveRedactionsCommand {
2330
+ readonly type: "image.removeRedactions";
2331
+ readonly keys: readonly string[];
2332
+ }
2333
+
2334
+ /**
2335
+ * Removes strokes from a drawing layer, by index. A drawing keeps at least
2336
+ * one stroke: to remove the last, remove the layer.
2337
+ *
2338
+ * @public
2339
+ */
2340
+ export declare interface RemoveStrokesCommand {
2341
+ readonly type: "image.removeStrokes";
2342
+ readonly key: string;
2343
+ readonly indexes: readonly number[];
2344
+ }
2345
+
2346
+ /**
2347
+ * Puts removed layers back, each at its index, by rising index. It's what
2348
+ * undoes {@link RemoveLayersCommand}: the reducer applies it, but it isn't
2349
+ * part of the portable command format (ADR 0009).
2350
+ *
2351
+ * @public
2352
+ */
2353
+ export declare interface RestoreLayersCommand {
2354
+ readonly type: "image.restoreLayers";
2355
+ readonly entries: readonly {
2356
+ readonly at: number;
2357
+ readonly layer: ImageLayer;
2358
+ }[];
2359
+ }
2360
+
2361
+ /**
2362
+ * Puts removed redactions back, each at its index, by rising index. It's
2363
+ * what undoes {@link RemoveRedactionsCommand}: the reducer applies it, but
2364
+ * it isn't part of the portable command format (ADR 0009).
2365
+ *
2366
+ * @public
2367
+ */
2368
+ export declare interface RestoreRedactionsCommand {
2369
+ readonly type: "image.restoreRedactions";
2370
+ readonly entries: readonly {
2371
+ readonly at: number;
2372
+ readonly redaction: ImageRedaction;
2373
+ }[];
2374
+ }
2375
+
2376
+ /**
2377
+ * Puts removed strokes back, each at its index, by rising index. It's what
2378
+ * undoes {@link RemoveStrokesCommand}: the reducer applies it, but it isn't
2379
+ * part of the portable command format (ADR 0009).
2380
+ *
2381
+ * @public
2382
+ */
2383
+ export declare interface RestoreStrokesCommand {
2384
+ readonly type: "image.restoreStrokes";
2385
+ readonly key: string;
2386
+ readonly entries: readonly {
2387
+ readonly at: number;
2388
+ readonly stroke: ImageStroke;
2389
+ }[];
2390
+ }
2391
+
2392
+ /**
2393
+ * A rectangle of the scene as the composition shows it: through the crop,
2394
+ * the rotation and the flips, in composition pixels, without clipping. The
2395
+ * plan turns by quarters, so it's still a rectangle in whole pixels. The
2396
+ * editor places a region's frame with it.
2397
+ *
2398
+ * @public
2399
+ */
2400
+ export declare function sceneRectToComposition(rect: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2): ImageRect;
2401
+
2402
+ /**
2403
+ * The transform from the scene to an image layer's source pixels: where a
2404
+ * point of the scene falls in the bitmap the layer draws. The renderer uses
2405
+ * it to replace, in a copy of that bitmap, the pixels a redaction covers
2406
+ * (ADR 0010).
2407
+ *
2408
+ * @param crop - The part of the source the layer draws: its crop, or all of it.
2409
+ * @public
2410
+ */
2411
+ export declare function sceneToLayerSource(box: ImageLayerBox, crop: ImageCrop): ImageMatrix;
2412
+
2413
+ /**
2414
+ * The transform from the scene to an output of the given size: through the
2415
+ * crop, the rotation and the flips, then the output's scale (ADR 0009). The
2416
+ * renderer draws layers through it, and the base through the same mapping,
2417
+ * so a layer stays on the pixels it was placed on.
2418
+ *
2419
+ * It's built from three points mapped by `sourceToComposition`, so it can't
2420
+ * disagree with the geometry the editor places frames with. Its entries are
2421
+ * exact for an output at the composition's own size.
2422
+ *
2423
+ * @param crop - The crop, or the whole source: `cropRect(plan.base.crop, source)`.
2424
+ * @public
2425
+ */
2426
+ export declare function sceneToOutput(crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageMatrix;
2427
+
1653
2428
  /**
1654
2429
  * Sets or removes the base's crop, in whole pixels of the oriented source.
1655
2430
  *
@@ -1681,6 +2456,18 @@ export declare interface SetFilterCommand {
1681
2456
  readonly filter: ImageFilter | null;
1682
2457
  }
1683
2458
 
2459
+ /**
2460
+ * Sets the whole order of the layers: every key, once. It's what undoes
2461
+ * {@link MoveLayersCommand}: the reducer applies it, but it isn't part of
2462
+ * the portable command format (ADR 0009).
2463
+ *
2464
+ * @public
2465
+ */
2466
+ export declare interface SetLayerOrderCommand {
2467
+ readonly type: "image.setLayerOrder";
2468
+ readonly keys: readonly string[];
2469
+ }
2470
+
1684
2471
  /**
1685
2472
  * Sets one metadata field to keep on export. An empty value keeps nothing.
1686
2473
  *
@@ -1712,6 +2499,39 @@ export declare interface SetOutputCommand {
1712
2499
  readonly output: ImageOutput;
1713
2500
  }
1714
2501
 
2502
+ /**
2503
+ * Sets the whole order of the redactions: every key, once. It's what undoes
2504
+ * {@link MoveRedactionsCommand}: the reducer applies it, but it isn't part
2505
+ * of the portable command format (ADR 0009).
2506
+ *
2507
+ * @public
2508
+ */
2509
+ export declare interface SetRedactionOrderCommand {
2510
+ readonly type: "image.setRedactionOrder";
2511
+ readonly keys: readonly string[];
2512
+ }
2513
+
2514
+ /**
2515
+ * A pointer's samples as one stroke's `runs` (docs/adr/0014): repeats
2516
+ * dropped, long input cut into runs of at most 2,000 points that share
2517
+ * their end points, and each run simplified by Ramer–Douglas–Peucker with
2518
+ * distance to the segment. The same samples give the same runs in every
2519
+ * engine: every comparison is between whole numbers.
2520
+ *
2521
+ * A tolerance of 0 drops only repeats and points exactly on a segment.
2522
+ *
2523
+ * @param points - `[x0, y0, x1, y1, …]`, in whole pixels from the drawing's
2524
+ * origin: at least one point.
2525
+ * @param tolerance - In whole scene pixels, from 0. The draw tool passes one
2526
+ * screen pixel's worth.
2527
+ * @returns 1 to 64 runs, each `[x0, y0, …]` of 1 to 2,000 points.
2528
+ * @throws `RangeError` for no points, an odd number of coordinates, a
2529
+ * coordinate or a tolerance that isn't a whole number, or more points
2530
+ * than 64 runs hold: a caller's mistake, since samples aren't a file's.
2531
+ * @public
2532
+ */
2533
+ export declare function simplifyStroke(points: readonly number[], tolerance: number): number[][];
2534
+
1715
2535
  /**
1716
2536
  * Maps a point in the cropped source to the composition, through the plan's
1717
2537
  * rotation and then its flips. Points are continuous coordinates, so the
@@ -1732,6 +2552,34 @@ export declare function sourceToComposition(point: ImagePoint, crop: ImageCrop,
1732
2552
  */
1733
2553
  export declare function toImagePlanDocument(plan: ImagePlan, sources: Readonly<Record<string, ImagePlanDocumentSource>>): ImagePlanDocument;
1734
2554
 
2555
+ /**
2556
+ * Sets some fields of some layers: their boxes after a move, their opacity,
2557
+ * a text layer's text. `props` may hold any field of the layer's kind except
2558
+ * `key` and `kind`.
2559
+ *
2560
+ * @public
2561
+ */
2562
+ export declare interface UpdateLayersCommand {
2563
+ readonly type: "image.updateLayers";
2564
+ readonly updates: readonly {
2565
+ readonly key: string;
2566
+ readonly props: Readonly<Record<string, unknown>>;
2567
+ }[];
2568
+ }
2569
+
2570
+ /**
2571
+ * Sets some fields of some redactions, such as their regions after a move.
2572
+ *
2573
+ * @public
2574
+ */
2575
+ export declare interface UpdateRedactionsCommand {
2576
+ readonly type: "image.updateRedactions";
2577
+ readonly updates: readonly {
2578
+ readonly key: string;
2579
+ readonly props: ImageRedactionProps;
2580
+ }[];
2581
+ }
2582
+
1735
2583
  /**
1736
2584
  * No rotation and no flips.
1737
2585
  *