@hussmartinez/image-sdk 0.6.0 → 0.7.1

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
@@ -29,6 +29,28 @@ export declare interface AddStrokesCommand {
29
29
  readonly strokes: readonly ImageStroke[];
30
30
  }
31
31
 
32
+ /**
33
+ * The limits on holding a file as an animation (docs/adr/0011): its frames,
34
+ * what they could decode to, and its screen. A file over one of them isn't
35
+ * refused: it's held as its first frame, a still.
36
+ *
37
+ * @public
38
+ */
39
+ export declare const ANIMATION_LIMITS: readonly ["maxFrames", "maxDecodedSize", "maxAnimationPixels"];
40
+
41
+ /**
42
+ * Which of {@link ANIMATION_LIMITS} a probed file is over, and which it's
43
+ * near, as an animation. It never throws: a file over one opens as a still.
44
+ *
45
+ * @param ceiling - The most frames the engine holds whatever the policy
46
+ * says, such as `MAX_ANIMATION_FRAMES`: over it counts as over `maxFrames`.
47
+ * @public
48
+ */
49
+ export declare function animationLimits(policy: ImageFilePolicy, probe: ImageProbe, ceiling?: number): {
50
+ readonly over: ImageLimitName[];
51
+ readonly near: ImageLimitName[];
52
+ };
53
+
32
54
  /**
33
55
  * Where a point goes under a transform.
34
56
  *
@@ -99,9 +121,13 @@ export declare function backingSize(view: ImageView): {
99
121
  * `ImageError` with the limit's code (ADR 0004). Returns the limits whose
100
122
  * warning threshold the file reaches.
101
123
  *
124
+ * @param frames - What of an animated file is to be held: `"all"` its
125
+ * frames, the default, which counts every frame against `maxFrames` and
126
+ * `maxDecodedSize`; `"first"` its first frame, a still, which counts one
127
+ * (docs/adr/0011).
102
128
  * @public
103
129
  */
104
- export declare function checkFileLimits(policy: ImageFilePolicy, fileSize: number, probe: ImageProbe): ImageLimitName[];
130
+ export declare function checkFileLimits(policy: ImageFilePolicy, fileSize: number, probe: ImageProbe, frames?: "first" | "all"): ImageLimitName[];
105
131
 
106
132
  /**
107
133
  * Checks an export's output size against a policy before its canvas is
@@ -247,7 +273,7 @@ export declare function createImageProcessor(engine: ImageEngine): ImageProcesso
247
273
  *
248
274
  * @public
249
275
  */
250
- export declare function createImageReducer(sourceSize: (id: string) => ImageSize | undefined): Reducer<ImagePlan, ImageCommand>;
276
+ export declare function createImageReducer(sourceSize: (id: string) => ImageReducerSource | undefined): Reducer<ImagePlan, ImageCommand>;
251
277
 
252
278
  /**
253
279
  * Creates the SDK's preview renderer over an engine from
@@ -460,7 +486,20 @@ export declare const IMAGE_PLAN_FORMAT = "hm-image-plan";
460
486
  *
461
487
  * @public
462
488
  */
463
- export declare const IMAGE_PLAN_VERSION = 3;
489
+ export declare const IMAGE_PLAN_VERSION = 4;
490
+
491
+ /**
492
+ * An animation (docs/adr/0011): the frames of the base's source, in the
493
+ * order they play. Everything else in the plan applies to every frame.
494
+ *
495
+ * @public
496
+ */
497
+ export declare interface ImageAnimation {
498
+ /** `null`: play once. 0: for ever. Otherwise that many repeats, to {@link MAX_FRAME_DELAY}. */
499
+ readonly loop: number | null;
500
+ /** 1 to {@link MAX_ANIMATION_FRAMES} frames. */
501
+ readonly frames: readonly ImageFrame[];
502
+ }
464
503
 
465
504
  /**
466
505
  * An arrow from one point of the scene to another (ADR 0009,
@@ -553,7 +592,7 @@ export declare interface ImageCallOptions {
553
592
  *
554
593
  * @public
555
594
  */
556
- export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | AddStrokesCommand | RemoveStrokesCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
595
+ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | AddStrokesCommand | RemoveStrokesCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | InsertFramesCommand | RemoveFramesCommand | MoveFramesCommand | ReverseFramesCommand | UpdateFramesCommand | SetLoopCommand | ImageInverseCommand;
557
596
 
558
597
  /**
559
598
  * Why a command was refused, as a stable token: `details.reason` on the
@@ -604,10 +643,21 @@ export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetO
604
643
  * - `too-many-layers`: more layers and redactions than `MAX_PLAN_ITEMS`,
605
644
  * the format's ceiling. The file policy's `maxLayers` is checked by the
606
645
  * session, with its own error code.
646
+ * - `not-animated`: a frame command for a plan whose `animation` is `null`.
647
+ * - `unknown-frame`: a key no frame has.
648
+ * - `invalid-frame`: a frame of the source that the source doesn't have.
649
+ * - `invalid-delay`: a delay that isn't a whole number from 0 to
650
+ * `MAX_FRAME_DELAY`.
651
+ * - `invalid-loop`: a loop count that isn't `null` or a whole number from 0
652
+ * to `MAX_FRAME_DELAY`.
653
+ * - `no-frames`: removing every frame. An animation keeps at least one.
654
+ * - `too-many-frames`: more frames than `MAX_ANIMATION_FRAMES`, the
655
+ * format's ceiling. The file policy's `maxFrames` is checked by the
656
+ * session, with its own error code.
607
657
  *
608
658
  * @public
609
659
  */
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";
660
+ 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" | "not-animated" | "unknown-frame" | "invalid-frame" | "invalid-delay" | "invalid-loop" | "no-frames" | "too-many-frames";
611
661
 
612
662
  /**
613
663
  * A rectangle in whole pixels of the oriented source: `x` and `y` from its
@@ -659,14 +709,16 @@ export declare interface ImageDevelop {
659
709
  * `unknown-redaction-mode`, `invalid-region`, `invalid-colour`,
660
710
  * `unknown-layer-kind`, `invalid-box`, `invalid-opacity`, `invalid-text`,
661
711
  * `text-too-long`, `empty-shape`, `empty-drawing`, `empty-arrow`,
662
- * `invalid-points` and `too-many-layers`. `unknown-source` and
712
+ * `invalid-points`, `too-many-layers`, `invalid-frame`, `invalid-delay`
713
+ * and `invalid-loop`. `unknown-source` and
663
714
  * `crop-outside-source` apply to an image layer too. A drawing or an
664
715
  * arrow in a document of version 2, which has neither, is
665
- * `unknown-layer-kind`.
716
+ * `unknown-layer-kind`. An animation over a source with one frame is
717
+ * `not-animated`.
666
718
  *
667
719
  * @public
668
720
  */
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";
721
+ 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" | "not-animated" | "invalid-frame" | "invalid-delay" | "invalid-loop";
670
722
 
671
723
  /**
672
724
  * Freehand strokes (ADR 0009, docs/adr/0014). A drawing has an origin and
@@ -804,6 +856,9 @@ export declare class ImageError extends SdkError<ImageErrorCode> {
804
856
  * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
805
857
  * `maxImageDimension` limit.
806
858
  * - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
859
+ * - `ANIMATION_TOO_LARGE`: a file asked for with all its frames has a screen
860
+ * over the `maxAnimationPixels` limit. The session doesn't raise it: it
861
+ * opens such a file as its first frame instead (docs/adr/0011).
807
862
  * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
808
863
  * `maxSessionSize` limit.
809
864
  * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
@@ -816,12 +871,14 @@ export declare class ImageError extends SdkError<ImageErrorCode> {
816
871
  *
817
872
  * @public
818
873
  */
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";
874
+ 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" | "ANIMATION_TOO_LARGE" | "SESSION_TOO_LARGE" | "TOO_MANY_LAYERS" | "TOO_MANY_POINTS";
820
875
 
821
876
  /**
822
877
  * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
823
878
  * the lossy formats; it defaults to 0.92. WebP is encoded only where the
824
- * browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`.
879
+ * browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`. A GIF is
880
+ * written by the SDK's own encoder, every frame of an animated plan and one
881
+ * frame of a still, and carries no metadata (docs/adr/0011).
825
882
  *
826
883
  * @public
827
884
  */
@@ -833,6 +890,8 @@ export declare type ImageExportFormat = {
833
890
  } | {
834
891
  readonly type: "webp";
835
892
  readonly quality?: number;
893
+ } | {
894
+ readonly type: "gif";
836
895
  };
837
896
 
838
897
  /**
@@ -845,6 +904,11 @@ export declare type ImageExportFormat = {
845
904
  export declare interface ImageExportJob {
846
905
  readonly plan: ImagePlan;
847
906
  readonly format: ImageExportFormat;
907
+ /**
908
+ * Which frame of an animated plan to export, as an index into the plan's
909
+ * `animation.frames`: 0 when omitted. A still has only frame 0.
910
+ */
911
+ readonly frame?: number;
848
912
  }
849
913
 
850
914
  /**
@@ -912,6 +976,30 @@ export declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
912
976
  */
913
977
  export declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
914
978
 
979
+ /**
980
+ * One frame of an animation (docs/adr/0011): which of the source's frames
981
+ * it shows, and for how long. It holds no pixels, so two frames may show
982
+ * the same one.
983
+ *
984
+ * @public
985
+ */
986
+ export declare interface ImageFrame {
987
+ /**
988
+ * Its identity: 1 to {@link MAX_KEY_LENGTH} code points, unique among the
989
+ * plan's layers, redactions and frames.
990
+ */
991
+ readonly key: string;
992
+ /** A frame of the base's source, from 0. */
993
+ readonly frame: number;
994
+ /** How long it's shown, in hundredths of a second: 0 to {@link MAX_FRAME_DELAY}. */
995
+ readonly delay: number;
996
+ }
997
+
998
+ /** The fields of a frame an update may set. @public */
999
+ export declare interface ImageFrameProps {
1000
+ readonly delay?: number;
1001
+ }
1002
+
915
1003
  /**
916
1004
  * Another image, drawn to fill its box (ADR 0009).
917
1005
  *
@@ -947,7 +1035,7 @@ declare interface ImageInsertOptions {
947
1035
  *
948
1036
  * @public
949
1037
  */
950
- export declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
1038
+ export declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand | RestoreFramesCommand | SetFrameOrderCommand;
951
1039
 
952
1040
  /**
953
1041
  * The metadata fields a user may keep on export (ADR 0005). Empty strings
@@ -1036,7 +1124,7 @@ export declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1036
1124
 
1037
1125
  /**
1038
1126
  * The image SDK's limit definitions: sdk-core's core limits with image
1039
- * defaults, plus five for images (ADR 0004).
1127
+ * defaults, plus six for images (ADR 0004, docs/adr/0011).
1040
1128
  *
1041
1129
  * | Limit | Code | Default maximum | Default warning |
1042
1130
  * |---|---|---|---|
@@ -1047,6 +1135,7 @@ export declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1047
1135
  * | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
1048
1136
  * | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
1049
1137
  * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
1138
+ * | `maxAnimationPixels` | `ANIMATION_TOO_LARGE` | 8 megapixels | 2 megapixels |
1050
1139
  * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
1051
1140
  * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
1052
1141
  * | `maxDrawingPoints` | `TOO_MANY_POINTS` | 200,000 | 100,000 |
@@ -1055,6 +1144,13 @@ export declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1055
1144
  * per pixel. `maxImagePixels` is the same limit, with the same name, code
1056
1145
  * and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
1057
1146
  *
1147
+ * `maxAnimationPixels` is the size of an animation's screen: an
1148
+ * animation's working set is several screens, so it needs a lower ceiling
1149
+ * than a still's. With `maxFrames` and, across its frames,
1150
+ * `maxDecodedSize`, it's a limit on holding a file as an animation, not on
1151
+ * what opens: an animated file over any of them opens as its first frame,
1152
+ * a still (docs/adr/0011). As a still it's held to the others.
1153
+ *
1058
1154
  * @public
1059
1155
  */
1060
1156
  export declare const imageLimitDefinitions: {
@@ -1081,6 +1177,12 @@ export declare const imageLimitDefinitions: {
1081
1177
  readonly default: 300;
1082
1178
  readonly warning: 100;
1083
1179
  };
1180
+ readonly maxAnimationPixels: {
1181
+ readonly code: "ANIMATION_TOO_LARGE";
1182
+ readonly unit: "pixels";
1183
+ readonly default: 8000000;
1184
+ readonly warning: 2000000;
1185
+ };
1084
1186
  readonly maxSessionSize: {
1085
1187
  readonly code: "SESSION_TOO_LARGE";
1086
1188
  readonly unit: "bytes";
@@ -1199,6 +1301,7 @@ export declare const imageMessages: {
1199
1301
  readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
1200
1302
  readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
1201
1303
  };
1304
+ readonly "errors.ANIMATION_TOO_LARGE": "This animation is too large to open with all its frames. Its first frame can still be opened.";
1202
1305
  readonly "errors.SESSION_TOO_LARGE": "The open images would use {actual, fileSize} of memory, which is over the {maximum, fileSize} limit. Close an image, or clear the undo history, and try again.";
1203
1306
  readonly "errors.TOO_MANY_LAYERS": {
1204
1307
  readonly $plural: "maximum";
@@ -1215,6 +1318,7 @@ export declare const imageMessages: {
1215
1318
  readonly one: "This animation has {actual} frame.";
1216
1319
  readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
1217
1320
  };
1321
+ readonly "warnings.maxAnimationPixels": "This animation is large, and may be slow to play, edit and export.";
1218
1322
  readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
1219
1323
  readonly "warnings.maxLayers": {
1220
1324
  readonly $plural: "actual";
@@ -1330,16 +1434,16 @@ export declare interface ImagePlan {
1330
1434
  readonly layers: readonly ImageLayer[];
1331
1435
  /** The redactions, applied over every layer (ADR 0010). */
1332
1436
  readonly redactions: readonly ImageRedaction[];
1333
- /** The animation (ADR 0011). Always `null` until format version 4. */
1334
- readonly animation: null;
1437
+ /** The animation, or `null` for a still (docs/adr/0011). */
1438
+ readonly animation: ImageAnimation | null;
1335
1439
  readonly output: ImageOutput;
1336
1440
  /** The fields the user chose to keep on export. Never a location (ADR 0005). */
1337
1441
  readonly metadata: ImageKeepableMetadata;
1338
1442
  }
1339
1443
 
1340
1444
  /**
1341
- * The plan as portable JSON: `hm-image-plan` version 3, which
1342
- * `formats/hm-image-plan/v3.schema.json` describes
1445
+ * The plan as portable JSON: `hm-image-plan` version 4, which
1446
+ * `formats/hm-image-plan/v4.schema.json` describes
1343
1447
  * (docs/formats/hm-image-plan.md). Positions are whole pixels of the
1344
1448
  * oriented source, and the base names its source by an id the document
1345
1449
  * lists.
@@ -1354,12 +1458,15 @@ export declare interface ImagePlanDocument extends ImagePlan {
1354
1458
 
1355
1459
  /**
1356
1460
  * A source, as a plan document records it: its oriented size in pixels,
1357
- * which a crop must fit inside, and, once documents travel with their files,
1358
- * its content.
1461
+ * which a crop must fit inside; how many frames it has, which an
1462
+ * animation's frames must be among; and, once documents travel with their
1463
+ * files, its content.
1359
1464
  *
1360
1465
  * @public
1361
1466
  */
1362
1467
  export declare interface ImagePlanDocumentSource extends ImageSize {
1468
+ /** 1 for a still. A document from before version 4 reads as 1. */
1469
+ readonly frames: number;
1363
1470
  readonly asset?: ImageAssetReference;
1364
1471
  }
1365
1472
 
@@ -1529,6 +1636,17 @@ export declare interface ImageRedactionRegion {
1529
1636
  readonly height: number;
1530
1637
  }
1531
1638
 
1639
+ /**
1640
+ * What the reducer needs to know of a source: its oriented size, to check
1641
+ * crops, and how many frames it has, to check an animation's. A source
1642
+ * that gives no count has one frame.
1643
+ *
1644
+ * @public
1645
+ */
1646
+ export declare interface ImageReducerSource extends ImageSize {
1647
+ readonly frames?: number;
1648
+ }
1649
+
1532
1650
  /**
1533
1651
  * Options for registering a source.
1534
1652
  *
@@ -1544,6 +1662,27 @@ export declare interface ImageRegisterOptions extends ImageProgressOptions {
1544
1662
  * directly.
1545
1663
  */
1546
1664
  readonly filePolicy?: ImageFilePolicy;
1665
+ /**
1666
+ * Which frames of an animated file the source holds (docs/adr/0011).
1667
+ *
1668
+ * - `"first"`, the default: its first frame, as a still.
1669
+ * - `"all"`: every frame. The engine decodes each once to check it, so
1670
+ * the call takes as long as that; `onProgress` follows it, and the
1671
+ * source's `frames` are those that decoded. A file with one frame is a
1672
+ * still either way. A file whose screen is over `filePolicy`'s
1673
+ * `maxAnimationPixels` rejects with `ANIMATION_TOO_LARGE`: register it
1674
+ * as `"first"` instead, as the session does.
1675
+ */
1676
+ readonly frames?: "first" | "all";
1677
+ /**
1678
+ * For a source registered with all its frames: called once its first
1679
+ * frame can be drawn, before the rest are checked and before `register`
1680
+ * resolves (docs/adr/0011). From then until `register` settles, a renderer
1681
+ * of the same engine may draw a still plan of the source, its first frame;
1682
+ * nothing else may use it yet. Not called for a still, or by an engine
1683
+ * that can't show a source early.
1684
+ */
1685
+ readonly onFirstFrame?: () => void;
1547
1686
  }
1548
1687
 
1549
1688
  /**
@@ -1691,10 +1830,14 @@ export declare interface ImageSession {
1691
1830
  * `maxProcessingTime` aborts the processor's signal with
1692
1831
  * `PROCESSING_TIME_EXCEEDED`. Custom adapters must observe that signal;
1693
1832
  * a session cannot preempt an arbitrary adapter that ignores it.
1833
+ *
1834
+ * An animation exports as one frame to these formats: `frame`, an index
1835
+ * into the plan's `animation.frames`, 0 when omitted (docs/adr/0011).
1694
1836
  */
1695
1837
  export(format: ImageExportFormat, options?: {
1696
1838
  readonly signal?: AbortSignal;
1697
1839
  readonly onProgress?: (fraction: number) => void;
1840
+ readonly frame?: number;
1698
1841
  }): Promise<ImageSessionExport>;
1699
1842
  /** Releases every source the session holds. Later calls throw. */
1700
1843
  destroy(): Promise<void>;
@@ -1745,6 +1888,12 @@ export declare interface ImageSessionOptions {
1745
1888
  readonly processor: ImageProcessor;
1746
1889
  /** The host's limits, over `imageLimits`' defaults (ADR 0004). */
1747
1890
  readonly filePolicy?: ImageFilePolicyOverrides;
1891
+ /**
1892
+ * Whether an animated file opens as an animation (docs/adr/0011). `true`
1893
+ * when omitted. With `false`, every file opens as a still: an animated
1894
+ * one as its first frame, as before 0.7.0.
1895
+ */
1896
+ readonly animations?: boolean;
1748
1897
  readonly onEvent?: (event: ImageSessionEvent) => void;
1749
1898
  }
1750
1899
 
@@ -1777,6 +1926,26 @@ export declare interface ImageSessionSnapshot {
1777
1926
  readonly inserting: boolean;
1778
1927
  /** Whether a file is being opened. The current document stays until it's ready. */
1779
1928
  readonly opening: boolean;
1929
+ /**
1930
+ * How far the open of an animation has got: the frames checked, of those
1931
+ * the file lists (docs/adr/0011). `null` when nothing is being opened,
1932
+ * and for a still.
1933
+ */
1934
+ readonly progress: {
1935
+ readonly done: number;
1936
+ readonly total: number;
1937
+ } | null;
1938
+ /**
1939
+ * The first frame of the animation being opened, once it can be drawn and
1940
+ * while the rest are checked (docs/adr/0011): a source id a renderer of
1941
+ * the session's engine may draw as a still, and its size. `null` when
1942
+ * nothing is opening, for a still, and before the first frame is ready.
1943
+ */
1944
+ readonly openingFrame: {
1945
+ readonly source: string;
1946
+ readonly width: number;
1947
+ readonly height: number;
1948
+ } | null;
1780
1949
  /** Whether an export is in progress. */
1781
1950
  readonly exporting: boolean;
1782
1951
  /** The limits the last open, edit or export came near: at or above their warnings. */
@@ -1799,6 +1968,12 @@ export declare interface ImageSessionSource extends ImageSourceInfo {
1799
1968
  readonly metadata: ImageMetadataPresence;
1800
1969
  /** The fields the user may choose to keep, as the file had them. */
1801
1970
  readonly keepable: ImageKeepableMetadata;
1971
+ /**
1972
+ * How many frames the file lists. More than `frames` when an animated
1973
+ * file is open as its first frame, or when its frames ended early
1974
+ * (docs/adr/0011).
1975
+ */
1976
+ readonly fileFrames: number;
1802
1977
  }
1803
1978
 
1804
1979
  /**
@@ -1841,10 +2016,42 @@ export declare interface ImageSourceInfo {
1841
2016
  readonly format: ImageFormat;
1842
2017
  readonly width: number;
1843
2018
  readonly height: number;
2019
+ /**
2020
+ * How many frames the source holds: 1 for a still, and for an animated
2021
+ * file registered as its first frame. For a source registered with all
2022
+ * its frames, the frames that decoded (docs/adr/0011).
2023
+ */
1844
2024
  readonly frames: number;
1845
2025
  readonly hasAlpha: boolean;
1846
- /** The bytes the decoded source takes in the worker: frames × width × height × 4. */
2026
+ /**
2027
+ * The bytes the source takes in the worker: width × height × 4 for a
2028
+ * still. An animated source counts what's held, not every frame: its
2029
+ * screens in memory and its frame cache's ceiling (docs/adr/0011).
2030
+ */
1847
2031
  readonly decodedBytes: number;
2032
+ /**
2033
+ * The timing the file gives its frames, for a source registered with all
2034
+ * its frames; `null` for a still.
2035
+ */
2036
+ readonly timing: ImageSourceTiming | null;
2037
+ /**
2038
+ * Whether the file's frames ended early: before its end, or at a frame
2039
+ * that couldn't be decoded (docs/adr/0011). The frames before that are
2040
+ * the source's. Always `false` for a still.
2041
+ */
2042
+ readonly incomplete: boolean;
2043
+ }
2044
+
2045
+ /**
2046
+ * How an animated file plays (docs/adr/0011), as the file has it.
2047
+ *
2048
+ * @public
2049
+ */
2050
+ declare interface ImageSourceTiming {
2051
+ /** `null`: play once. 0: for ever. Otherwise that many repeats. */
2052
+ readonly loop: number | null;
2053
+ /** Each frame's delay in hundredths of a second, 0 to 65,535: one for each of the source's frames. */
2054
+ readonly delays: readonly number[];
1848
2055
  }
1849
2056
 
1850
2057
  /**
@@ -1937,6 +2144,25 @@ export declare interface ImageView {
1937
2144
  * be cut off where the image meets the stage's edge. 0 when omitted.
1938
2145
  */
1939
2146
  readonly inset?: number;
2147
+ /**
2148
+ * Which frame of an animated plan is shown, as an index into the plan's
2149
+ * `animation.frames`: 0 when omitted. It's view state, like the zoom
2150
+ * (docs/adr/0011).
2151
+ */
2152
+ readonly frame?: number;
2153
+ }
2154
+
2155
+ /**
2156
+ * Inserts frames into the animation, such as duplicates (docs/adr/0011).
2157
+ * Each shows a frame the base's source has.
2158
+ *
2159
+ * @public
2160
+ */
2161
+ export declare interface InsertFramesCommand {
2162
+ readonly type: "image.insertFrames";
2163
+ /** The index, from 0 to the number of frames. */
2164
+ readonly at: number;
2165
+ readonly frames: readonly ImageFrame[];
1940
2166
  }
1941
2167
 
1942
2168
  /**
@@ -2047,6 +2273,15 @@ export declare function layerToOutput(box: ImageLayerBox, crop: ImageCrop, orien
2047
2273
  */
2048
2274
  export declare function layerToScene(box: ImageLayerBox): ImageMatrix;
2049
2275
 
2276
+ /**
2277
+ * The most frames an animation lists: the format's ceiling, which the file
2278
+ * policy's `maxFrames` applies below (docs/adr/0011). It's the most frames
2279
+ * the SDK's GIF decoder keeps a table of.
2280
+ *
2281
+ * @public
2282
+ */
2283
+ export declare const MAX_ANIMATION_FRAMES = 4096;
2284
+
2050
2285
  /**
2051
2286
  * The most strokes in a drawing (docs/adr/0014).
2052
2287
  *
@@ -2054,6 +2289,14 @@ export declare function layerToScene(box: ImageLayerBox): ImageMatrix;
2054
2289
  */
2055
2290
  export declare const MAX_DRAWING_STROKES = 1024;
2056
2291
 
2292
+ /**
2293
+ * The longest a frame is shown, and the most times an animation repeats:
2294
+ * what a GIF's sixteen bits hold.
2295
+ *
2296
+ * @public
2297
+ */
2298
+ export declare const MAX_FRAME_DELAY = 65535;
2299
+
2057
2300
  /**
2058
2301
  * The most Unicode code points in a key.
2059
2302
  *
@@ -2138,6 +2381,17 @@ export declare const MAX_STROKE_WIDTH = 1024;
2138
2381
  */
2139
2382
  export declare function moveCrop(crop: ImageCrop, dx: number, dy: number, source: ImageSize): ImageCrop;
2140
2383
 
2384
+ /**
2385
+ * Moves frames to an index of the list without them, keeping their order.
2386
+ *
2387
+ * @public
2388
+ */
2389
+ export declare interface MoveFramesCommand {
2390
+ readonly type: "image.moveFrames";
2391
+ readonly keys: readonly string[];
2392
+ readonly to: number;
2393
+ }
2394
+
2141
2395
  /**
2142
2396
  * Moves layers to an index of the list without them, keeping the order they
2143
2397
  * had: up or down the stack.
@@ -2244,8 +2498,9 @@ export declare function placement(composition: {
2244
2498
  * inside them, and no two items share a key. Unknown fields are refused, never dropped.
2245
2499
  *
2246
2500
  * 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.
2501
+ * readable: version 1 reads as a plan with no layers or redactions, version
2502
+ * 2 as it is, with the kinds of layer it had, and version 3 as a still,
2503
+ * each of its sources with one frame.
2249
2504
  *
2250
2505
  * @param value - The parsed JSON.
2251
2506
  * @returns The plan, and its sources by id.
@@ -2311,6 +2566,16 @@ export declare function redactionBlockSize(region: ImageSize): number;
2311
2566
  */
2312
2567
  export declare function redactionRectInOutput(region: ImageRect, crop: ImageCrop, orientation: ImageOrientation_2, output: ImageSize): ImageRect | null;
2313
2568
 
2569
+ /**
2570
+ * Removes frames from the animation, which keeps at least one.
2571
+ *
2572
+ * @public
2573
+ */
2574
+ export declare interface RemoveFramesCommand {
2575
+ readonly type: "image.removeFrames";
2576
+ readonly keys: readonly string[];
2577
+ }
2578
+
2314
2579
  /**
2315
2580
  * Removes layers, by key.
2316
2581
  *
@@ -2343,6 +2608,21 @@ export declare interface RemoveStrokesCommand {
2343
2608
  readonly indexes: readonly number[];
2344
2609
  }
2345
2610
 
2611
+ /**
2612
+ * Puts removed frames back, each at its index, by rising index. It's what
2613
+ * undoes {@link RemoveFramesCommand}: the reducer applies it, but it isn't
2614
+ * part of the portable command format (ADR 0009).
2615
+ *
2616
+ * @public
2617
+ */
2618
+ export declare interface RestoreFramesCommand {
2619
+ readonly type: "image.restoreFrames";
2620
+ readonly entries: readonly {
2621
+ readonly at: number;
2622
+ readonly frame: ImageFrame;
2623
+ }[];
2624
+ }
2625
+
2346
2626
  /**
2347
2627
  * Puts removed layers back, each at its index, by rising index. It's what
2348
2628
  * undoes {@link RemoveLayersCommand}: the reducer applies it, but it isn't
@@ -2389,6 +2669,15 @@ export declare interface RestoreStrokesCommand {
2389
2669
  }[];
2390
2670
  }
2391
2671
 
2672
+ /**
2673
+ * Reverses the order the frames play in. It undoes itself.
2674
+ *
2675
+ * @public
2676
+ */
2677
+ export declare interface ReverseFramesCommand {
2678
+ readonly type: "image.reverseFrames";
2679
+ }
2680
+
2392
2681
  /**
2393
2682
  * A rectangle of the scene as the composition shows it: through the crop,
2394
2683
  * the rotation and the flips, in composition pixels, without clipping. The
@@ -2456,6 +2745,18 @@ export declare interface SetFilterCommand {
2456
2745
  readonly filter: ImageFilter | null;
2457
2746
  }
2458
2747
 
2748
+ /**
2749
+ * Sets the whole order of the frames: every key, once. It's what undoes
2750
+ * {@link MoveFramesCommand}: the reducer applies it, but it isn't part of
2751
+ * the portable command format (ADR 0009).
2752
+ *
2753
+ * @public
2754
+ */
2755
+ export declare interface SetFrameOrderCommand {
2756
+ readonly type: "image.setFrameOrder";
2757
+ readonly keys: readonly string[];
2758
+ }
2759
+
2459
2760
  /**
2460
2761
  * Sets the whole order of the layers: every key, once. It's what undoes
2461
2762
  * {@link MoveLayersCommand}: the reducer applies it, but it isn't part of
@@ -2468,6 +2769,16 @@ export declare interface SetLayerOrderCommand {
2468
2769
  readonly keys: readonly string[];
2469
2770
  }
2470
2771
 
2772
+ /**
2773
+ * Sets how many times the animation repeats: `null` for once, 0 for ever.
2774
+ *
2775
+ * @public
2776
+ */
2777
+ export declare interface SetLoopCommand {
2778
+ readonly type: "image.setLoop";
2779
+ readonly loop: number | null;
2780
+ }
2781
+
2471
2782
  /**
2472
2783
  * Sets one metadata field to keep on export. An empty value keeps nothing.
2473
2784
  *
@@ -2546,12 +2857,26 @@ export declare function sourceToComposition(point: ImagePoint, crop: ImageCrop,
2546
2857
  *
2547
2858
  * @param plan - The plan.
2548
2859
  * @param sources - The sources by id, with at least the base's. They're
2549
- * written as given.
2860
+ * written as given: each with its size and its frame count, 1 for a
2861
+ * still.
2550
2862
  * @throws `TypeError` if the base's source is missing from `sources`.
2551
2863
  * @public
2552
2864
  */
2553
2865
  export declare function toImagePlanDocument(plan: ImagePlan, sources: Readonly<Record<string, ImagePlanDocumentSource>>): ImagePlanDocument;
2554
2866
 
2867
+ /**
2868
+ * Sets some frames' delays: one command for one frame or for all of them.
2869
+ *
2870
+ * @public
2871
+ */
2872
+ export declare interface UpdateFramesCommand {
2873
+ readonly type: "image.updateFrames";
2874
+ readonly updates: readonly {
2875
+ readonly key: string;
2876
+ readonly props: ImageFrameProps;
2877
+ }[];
2878
+ }
2879
+
2555
2880
  /**
2556
2881
  * Sets some fields of some layers: their boxes after a move, their opacity,
2557
2882
  * a text layer's text. `props` may hold any field of the layer's kind except