@hussmartinez/image-sdk 0.6.0 → 0.7.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/react.d.ts CHANGED
@@ -74,6 +74,19 @@ export declare interface ImageAdjustPanelProps {
74
74
  readonly className?: string;
75
75
  }
76
76
 
77
+ /**
78
+ * An animation (docs/adr/0011): the frames of the base's source, in the
79
+ * order they play. Everything else in the plan applies to every frame.
80
+ *
81
+ * @public
82
+ */
83
+ declare interface ImageAnimation {
84
+ /** `null`: play once. 0: for ever. Otherwise that many repeats, to {@link MAX_FRAME_DELAY}. */
85
+ readonly loop: number | null;
86
+ /** 1 to {@link MAX_ANIMATION_FRAMES} frames. */
87
+ readonly frames: readonly ImageFrame[];
88
+ }
89
+
77
90
  /**
78
91
  * An arrow from one point of the scene to another (ADR 0009,
79
92
  * docs/adr/0014). Its head's size follows its width, and its tip is exactly
@@ -150,7 +163,7 @@ declare interface ImageCallOptions {
150
163
  *
151
164
  * @public
152
165
  */
153
- declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | AddStrokesCommand | RemoveStrokesCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
166
+ 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;
154
167
 
155
168
  /**
156
169
  * A rectangle in whole pixels of the oriented source: `x` and `y` from its
@@ -337,10 +350,12 @@ export declare const imageEditorMessages: {
337
350
  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.";
338
351
  readonly "editor.label": "Image editor";
339
352
  readonly "editor.preview": "Edited image preview, {width, number} × {height, number}";
353
+ readonly "editor.openingPreview": "First frame of the image being opened, {width, number} × {height, number}";
340
354
  readonly "editor.empty": "Open an image to start editing. It stays on this device.";
341
355
  readonly "editor.choose": "Choose an image";
342
356
  readonly "editor.dropHint": "or drop it here";
343
357
  readonly "editor.opening": "Opening the image…";
358
+ readonly "editor.checkingFrames": "Checking frames: {done, number} of {total, number}";
344
359
  readonly "editor.cancel": "Cancel";
345
360
  readonly "editor.opened": "Image opened, {width, number} × {height, number}.";
346
361
  readonly "editor.undid": "Undid {action}.";
@@ -366,6 +381,14 @@ export declare const imageEditorMessages: {
366
381
  readonly "actions.image.moveRedactions": "redaction order";
367
382
  readonly "actions.image.setRedactionOrder": "redaction order";
368
383
  readonly "actions.image.updateRedactions": "redaction change";
384
+ readonly "actions.image.insertFrames": "frame";
385
+ readonly "actions.image.removeFrames": "frame";
386
+ readonly "actions.image.restoreFrames": "frame";
387
+ readonly "actions.image.moveFrames": "frame order";
388
+ readonly "actions.image.setFrameOrder": "frame order";
389
+ readonly "actions.image.reverseFrames": "frame order";
390
+ readonly "actions.image.updateFrames": "frame timing";
391
+ readonly "actions.image.setLoop": "repeat count";
369
392
  readonly "toolbar.label": "Image tools";
370
393
  readonly "toolbar.groups.file": "File";
371
394
  readonly "toolbar.groups.history": "History";
@@ -374,6 +397,7 @@ export declare const imageEditorMessages: {
374
397
  readonly "toolbar.groups.other": "More tools";
375
398
  readonly "tools.open": "Open image";
376
399
  readonly "tools.undo": "Undo";
400
+ readonly "tools.play": "Play";
377
401
  readonly "tools.redo": "Redo";
378
402
  readonly "tools.rotate-left": "Rotate left";
379
403
  readonly "tools.rotate-right": "Rotate right";
@@ -527,8 +551,52 @@ export declare const imageEditorMessages: {
527
551
  readonly "inspector.adjust": "Adjust";
528
552
  readonly "inspector.filters": "Filters";
529
553
  readonly "inspector.info": "Info";
554
+ readonly "timeline.label": "Animation";
555
+ readonly "timeline.play": "Play";
556
+ readonly "timeline.frame": "Frame";
557
+ readonly "timeline.position": "Frame {frame, number} of {count, number}";
558
+ readonly "timeline.where": "Frame {frame, number} of {count, number}, {seconds, number} s";
559
+ readonly "tools.frames": "Frames";
560
+ readonly "toolbar.groups.frames": "Frames";
561
+ readonly "frames.panel": "Frames";
562
+ readonly "frames.list": "Frames, in the order they play";
563
+ readonly "frames.row": "Frame {index, number}, {seconds} seconds";
564
+ readonly "frames.selected": "Selected frame";
565
+ readonly "frames.moveEarlier": "Move earlier";
566
+ readonly "frames.moveLater": "Move later";
567
+ readonly "frames.duplicate": "Duplicate";
568
+ readonly "frames.remove": "Delete";
569
+ readonly "frames.reverse": "Reverse order";
570
+ readonly "frames.delay": "Delay, in seconds";
571
+ readonly "frames.delayAll": "Use for every frame";
572
+ readonly "frames.loop": "Plays";
573
+ readonly "frames.loops.once": "Once";
574
+ readonly "frames.loops.repeat": "Repeats";
575
+ readonly "frames.loops.forever": "For ever";
576
+ readonly "frames.repeats": "Times it repeats after the first";
577
+ readonly "frames.done": "Done";
578
+ readonly "frames.movedEarlier": "Moved frame {from, number} earlier. It's frame {index, number} of {count, number}.";
579
+ readonly "frames.movedLater": "Moved frame {from, number} later. It's frame {index, number} of {count, number}.";
580
+ readonly "frames.duplicated": "Duplicated frame {index, number}. The copy is frame {copy, number}.";
581
+ readonly "frames.removed": {
582
+ readonly $plural: "count";
583
+ } & {
584
+ readonly one: "Deleted frame {index, number}. One frame is left.";
585
+ readonly other: "Deleted frame {index, number}. {count, number} frames are left.";
586
+ };
587
+ readonly "frames.reversed": "Reversed the order of the frames.";
588
+ readonly "frames.delayedAll": "Every frame now shows for {seconds} seconds.";
530
589
  readonly "notices.label": "Notices";
531
590
  readonly "notices.dismiss": "Dismiss";
591
+ readonly "notices.incomplete": {
592
+ readonly $plural: "frames";
593
+ } & {
594
+ readonly one: "This animation's file is damaged. Only its first frame could be opened, of {listed, number}.";
595
+ readonly other: "This animation's file is damaged. {frames, number} of its {listed, number} frames could be opened.";
596
+ };
597
+ readonly "notices.incompleteEnd": "This animation's file is damaged at its end. All {frames, number} of its frames were opened.";
598
+ readonly "notices.animationTooLarge": "This animation is too large to edit as an animation. Its first frame is open as a still image.";
599
+ readonly "notices.firstFrame": "This file is an animation. Its first frame is open as a still image.";
532
600
  readonly "notices.colourProfile": "This image has a colour profile. Colours outside sRGB will be clipped in the exported file.";
533
601
  readonly "info.panel": "Image info";
534
602
  readonly "info.size": "Size";
@@ -580,6 +648,7 @@ export declare const imageEditorMessages: {
580
648
  readonly "export.formats.png": "PNG";
581
649
  readonly "export.formats.jpeg": "JPEG";
582
650
  readonly "export.formats.webp": "WebP";
651
+ readonly "export.formats.gif": "GIF";
583
652
  readonly "export.quality": "Quality";
584
653
  readonly "export.qualityValue": "{quality, number}%";
585
654
  readonly "export.size": "Size";
@@ -590,6 +659,7 @@ export declare const imageEditorMessages: {
590
659
  readonly "export.fitHeight": "Largest height";
591
660
  readonly "export.fields": "Details to include";
592
661
  readonly "export.fieldsHint": "Only what you fill in is written to the file.";
662
+ readonly "export.fieldsNone": "A {format} file carries no details: these aren't written to it.";
593
663
  readonly "export.field.title": "Title";
594
664
  readonly "export.field.description": "Description";
595
665
  readonly "export.field.artist": "Artist";
@@ -646,6 +716,7 @@ export declare const imageEditorMessages: {
646
716
  readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
647
717
  readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
648
718
  };
719
+ readonly "errors.ANIMATION_TOO_LARGE": "This animation is too large to open with all its frames. Its first frame can still be opened.";
649
720
  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.";
650
721
  readonly "errors.TOO_MANY_LAYERS": {
651
722
  readonly $plural: "maximum";
@@ -662,6 +733,7 @@ export declare const imageEditorMessages: {
662
733
  readonly one: "This animation has {actual} frame.";
663
734
  readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
664
735
  };
736
+ readonly "warnings.maxAnimationPixels": "This animation is large, and may be slow to play, edit and export.";
665
737
  readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
666
738
  readonly "warnings.maxLayers": {
667
739
  readonly $plural: "actual";
@@ -804,6 +876,12 @@ export declare interface ImageEditorProviderProps {
804
876
  readonly assetsUrl?: string | URL;
805
877
  /** File limits for a session the provider creates (docs/adr/0004). */
806
878
  readonly filePolicy?: ImageFilePolicyOverrides;
879
+ /**
880
+ * Whether an animated file opens as an animation, for a session the
881
+ * provider creates (docs/adr/0011). `true` when omitted; with `false`,
882
+ * every file opens as a still, an animated one as its first frame.
883
+ */
884
+ readonly animations?: boolean;
807
885
  /** Anonymous usage events from a session the provider creates. */
808
886
  readonly onEvent?: (event: ImageSessionEvent) => void;
809
887
  /** Text overrides, typed against the English catalogue (ADR 0019). */
@@ -823,8 +901,12 @@ export declare interface ImageEditorProviderProps {
823
901
  * @public
824
902
  */
825
903
  export declare interface ImageEditorState {
826
- /** The tool that takes over the stage, such as `crop`, or `null`. */
827
- readonly tool: "crop" | "redact" | "layers" | "draw" | null;
904
+ /**
905
+ * The tool that takes over the stage, such as `crop`, or `null`. With
906
+ * `frames`, the inspector lists an animation's frames (docs/adr/0011);
907
+ * the one selected is the one shown, `playback.frame`.
908
+ */
909
+ readonly tool: "crop" | "redact" | "layers" | "draw" | "frames" | null;
828
910
  /** The crop being made, in whole pixels of the oriented source, and its aspect. */
829
911
  readonly crop: {
830
912
  readonly pending: ImageCrop;
@@ -880,6 +962,16 @@ export declare interface ImageEditorState {
880
962
  readonly preview: ImagePlan | null;
881
963
  /** The dialog the editor shows over the stage, such as `export`, or `null`. */
882
964
  readonly dialog: "export" | null;
965
+ /**
966
+ * An animation's frame being shown, as an index into the plan's
967
+ * `animation.frames`, and whether it's playing (docs/adr/0011). View
968
+ * state, like the zoom: outside the plan and its history. No tool resets
969
+ * it; another image opening does.
970
+ */
971
+ readonly playback: {
972
+ readonly frame: number;
973
+ readonly playing: boolean;
974
+ };
883
975
  }
884
976
 
885
977
  /**
@@ -989,6 +1081,9 @@ declare class ImageError extends SdkError<ImageErrorCode> {
989
1081
  * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
990
1082
  * `maxImageDimension` limit.
991
1083
  * - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
1084
+ * - `ANIMATION_TOO_LARGE`: a file asked for with all its frames has a screen
1085
+ * over the `maxAnimationPixels` limit. The session doesn't raise it: it
1086
+ * opens such a file as its first frame instead (docs/adr/0011).
992
1087
  * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
993
1088
  * `maxSessionSize` limit.
994
1089
  * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
@@ -1001,7 +1096,7 @@ declare class ImageError extends SdkError<ImageErrorCode> {
1001
1096
  *
1002
1097
  * @public
1003
1098
  */
1004
- 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";
1099
+ 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";
1005
1100
 
1006
1101
  /**
1007
1102
  * The export dialog (docs/adr/0007). Export is irreversible, so it shows a
@@ -1039,7 +1134,9 @@ export declare interface ImageExportDialogProps {
1039
1134
  /**
1040
1135
  * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
1041
1136
  * the lossy formats; it defaults to 0.92. WebP is encoded only where the
1042
- * browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`.
1137
+ * browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`. A GIF is
1138
+ * written by the SDK's own encoder, every frame of an animated plan and one
1139
+ * frame of a still, and carries no metadata (docs/adr/0011).
1043
1140
  *
1044
1141
  * @public
1045
1142
  */
@@ -1051,6 +1148,8 @@ declare type ImageExportFormat = {
1051
1148
  } | {
1052
1149
  readonly type: "webp";
1053
1150
  readonly quality?: number;
1151
+ } | {
1152
+ readonly type: "gif";
1054
1153
  };
1055
1154
 
1056
1155
  /**
@@ -1063,6 +1162,11 @@ declare type ImageExportFormat = {
1063
1162
  declare interface ImageExportJob {
1064
1163
  readonly plan: ImagePlan;
1065
1164
  readonly format: ImageExportFormat;
1165
+ /**
1166
+ * Which frame of an animated plan to export, as an index into the plan's
1167
+ * `animation.frames`: 0 when omitted. A still has only frame 0.
1168
+ */
1169
+ readonly frame?: number;
1066
1170
  }
1067
1171
 
1068
1172
  /**
@@ -1148,6 +1252,60 @@ declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
1148
1252
  */
1149
1253
  declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
1150
1254
 
1255
+ /**
1256
+ * One frame of an animation (docs/adr/0011): which of the source's frames
1257
+ * it shows, and for how long. It holds no pixels, so two frames may show
1258
+ * the same one.
1259
+ *
1260
+ * @public
1261
+ */
1262
+ declare interface ImageFrame {
1263
+ /**
1264
+ * Its identity: 1 to {@link MAX_KEY_LENGTH} code points, unique among the
1265
+ * plan's layers, redactions and frames.
1266
+ */
1267
+ readonly key: string;
1268
+ /** A frame of the base's source, from 0. */
1269
+ readonly frame: number;
1270
+ /** How long it's shown, in hundredths of a second: 0 to {@link MAX_FRAME_DELAY}. */
1271
+ readonly delay: number;
1272
+ }
1273
+
1274
+ /** The fields of a frame an update may set. @public */
1275
+ declare interface ImageFrameProps {
1276
+ readonly delay?: number;
1277
+ }
1278
+
1279
+ /**
1280
+ * The frames panel (docs/adr/0011), shown while the frames tool is on: an
1281
+ * animation's frames in the order they play, each with its thumbnail and
1282
+ * named by its place and delay, such as "Frame 3, 0.10 seconds"; buttons
1283
+ * that move the selected frame earlier and later, copy it and delete it,
1284
+ * and reverse the order; the selected frame's delay; and how many times
1285
+ * the animation plays. The frame selected is the frame the stage shows.
1286
+ *
1287
+ * The list is ui's `ReorderableList`, as the layers' is: one tab stop, the
1288
+ * Up and Down arrows between frames, `Alt` (`Option` on macOS) with them to
1289
+ * move the focused frame, and `Delete` to remove it. Every edit is one undo
1290
+ * step, and the panel says what it did.
1291
+ *
1292
+ * Thumbnails are drawn only for the rows in view, at most
1293
+ * `MAX_FRAME_THUMBNAILS` at a time, and released when their rows scroll out
1294
+ * of view.
1295
+ *
1296
+ * @public
1297
+ */
1298
+ export declare function ImageFramesPanel(props: ImageFramesPanelProps): ReactNode;
1299
+
1300
+ /**
1301
+ * Props of {@link ImageFramesPanel}.
1302
+ *
1303
+ * @public
1304
+ */
1305
+ export declare interface ImageFramesPanelProps {
1306
+ readonly className?: string;
1307
+ }
1308
+
1151
1309
  /**
1152
1310
  * The components of the icons the editor's tools name, from ui's set
1153
1311
  * (sdk-core ADR 0030). A host's `icons` prop overrides any of them.
@@ -1211,7 +1369,7 @@ declare interface ImageInsertOptions {
1211
1369
  *
1212
1370
  * @public
1213
1371
  */
1214
- declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
1372
+ declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand | RestoreFramesCommand | SetFrameOrderCommand;
1215
1373
 
1216
1374
  /**
1217
1375
  * The metadata fields a user may keep on export (ADR 0005). Empty strings
@@ -1324,7 +1482,7 @@ declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1324
1482
 
1325
1483
  /**
1326
1484
  * The image SDK's limit definitions: sdk-core's core limits with image
1327
- * defaults, plus five for images (ADR 0004).
1485
+ * defaults, plus six for images (ADR 0004, docs/adr/0011).
1328
1486
  *
1329
1487
  * | Limit | Code | Default maximum | Default warning |
1330
1488
  * |---|---|---|---|
@@ -1335,6 +1493,7 @@ declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1335
1493
  * | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
1336
1494
  * | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
1337
1495
  * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
1496
+ * | `maxAnimationPixels` | `ANIMATION_TOO_LARGE` | 8 megapixels | 2 megapixels |
1338
1497
  * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
1339
1498
  * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
1340
1499
  * | `maxDrawingPoints` | `TOO_MANY_POINTS` | 200,000 | 100,000 |
@@ -1343,6 +1502,13 @@ declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1343
1502
  * per pixel. `maxImagePixels` is the same limit, with the same name, code
1344
1503
  * and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
1345
1504
  *
1505
+ * `maxAnimationPixels` is the size of an animation's screen: an
1506
+ * animation's working set is several screens, so it needs a lower ceiling
1507
+ * than a still's. With `maxFrames` and, across its frames,
1508
+ * `maxDecodedSize`, it's a limit on holding a file as an animation, not on
1509
+ * what opens: an animated file over any of them opens as its first frame,
1510
+ * a still (docs/adr/0011). As a still it's held to the others.
1511
+ *
1346
1512
  * @public
1347
1513
  */
1348
1514
  declare const imageLimitDefinitions: {
@@ -1369,6 +1535,12 @@ declare const imageLimitDefinitions: {
1369
1535
  readonly default: 300;
1370
1536
  readonly warning: 100;
1371
1537
  };
1538
+ readonly maxAnimationPixels: {
1539
+ readonly code: "ANIMATION_TOO_LARGE";
1540
+ readonly unit: "pixels";
1541
+ readonly default: 8000000;
1542
+ readonly warning: 2000000;
1543
+ };
1372
1544
  readonly maxSessionSize: {
1373
1545
  readonly code: "SESSION_TOO_LARGE";
1374
1546
  readonly unit: "bytes";
@@ -1470,8 +1642,8 @@ declare interface ImagePlan {
1470
1642
  readonly layers: readonly ImageLayer[];
1471
1643
  /** The redactions, applied over every layer (ADR 0010). */
1472
1644
  readonly redactions: readonly ImageRedaction[];
1473
- /** The animation (ADR 0011). Always `null` until format version 4. */
1474
- readonly animation: null;
1645
+ /** The animation, or `null` for a still (docs/adr/0011). */
1646
+ readonly animation: ImageAnimation | null;
1475
1647
  readonly output: ImageOutput;
1476
1648
  /** The fields the user chose to keep on export. Never a location (ADR 0005). */
1477
1649
  readonly metadata: ImageKeepableMetadata;
@@ -1651,6 +1823,27 @@ declare interface ImageRegisterOptions extends ImageProgressOptions {
1651
1823
  * directly.
1652
1824
  */
1653
1825
  readonly filePolicy?: ImageFilePolicy;
1826
+ /**
1827
+ * Which frames of an animated file the source holds (docs/adr/0011).
1828
+ *
1829
+ * - `"first"`, the default: its first frame, as a still.
1830
+ * - `"all"`: every frame. The engine decodes each once to check it, so
1831
+ * the call takes as long as that; `onProgress` follows it, and the
1832
+ * source's `frames` are those that decoded. A file with one frame is a
1833
+ * still either way. A file whose screen is over `filePolicy`'s
1834
+ * `maxAnimationPixels` rejects with `ANIMATION_TOO_LARGE`: register it
1835
+ * as `"first"` instead, as the session does.
1836
+ */
1837
+ readonly frames?: "first" | "all";
1838
+ /**
1839
+ * For a source registered with all its frames: called once its first
1840
+ * frame can be drawn, before the rest are checked and before `register`
1841
+ * resolves (docs/adr/0011). From then until `register` settles, a renderer
1842
+ * of the same engine may draw a still plan of the source, its first frame;
1843
+ * nothing else may use it yet. Not called for a still, or by an engine
1844
+ * that can't show a source early.
1845
+ */
1846
+ readonly onFirstFrame?: () => void;
1654
1847
  }
1655
1848
 
1656
1849
  /**
@@ -1747,10 +1940,14 @@ declare interface ImageSession {
1747
1940
  * `maxProcessingTime` aborts the processor's signal with
1748
1941
  * `PROCESSING_TIME_EXCEEDED`. Custom adapters must observe that signal;
1749
1942
  * a session cannot preempt an arbitrary adapter that ignores it.
1943
+ *
1944
+ * An animation exports as one frame to these formats: `frame`, an index
1945
+ * into the plan's `animation.frames`, 0 when omitted (docs/adr/0011).
1750
1946
  */
1751
1947
  export(format: ImageExportFormat, options?: {
1752
1948
  readonly signal?: AbortSignal;
1753
1949
  readonly onProgress?: (fraction: number) => void;
1950
+ readonly frame?: number;
1754
1951
  }): Promise<ImageSessionExport>;
1755
1952
  /** Releases every source the session holds. Later calls throw. */
1756
1953
  destroy(): Promise<void>;
@@ -1818,6 +2015,26 @@ declare interface ImageSessionSnapshot {
1818
2015
  readonly inserting: boolean;
1819
2016
  /** Whether a file is being opened. The current document stays until it's ready. */
1820
2017
  readonly opening: boolean;
2018
+ /**
2019
+ * How far the open of an animation has got: the frames checked, of those
2020
+ * the file lists (docs/adr/0011). `null` when nothing is being opened,
2021
+ * and for a still.
2022
+ */
2023
+ readonly progress: {
2024
+ readonly done: number;
2025
+ readonly total: number;
2026
+ } | null;
2027
+ /**
2028
+ * The first frame of the animation being opened, once it can be drawn and
2029
+ * while the rest are checked (docs/adr/0011): a source id a renderer of
2030
+ * the session's engine may draw as a still, and its size. `null` when
2031
+ * nothing is opening, for a still, and before the first frame is ready.
2032
+ */
2033
+ readonly openingFrame: {
2034
+ readonly source: string;
2035
+ readonly width: number;
2036
+ readonly height: number;
2037
+ } | null;
1821
2038
  /** Whether an export is in progress. */
1822
2039
  readonly exporting: boolean;
1823
2040
  /** The limits the last open, edit or export came near: at or above their warnings. */
@@ -1840,6 +2057,12 @@ declare interface ImageSessionSource extends ImageSourceInfo {
1840
2057
  readonly metadata: ImageMetadataPresence;
1841
2058
  /** The fields the user may choose to keep, as the file had them. */
1842
2059
  readonly keepable: ImageKeepableMetadata;
2060
+ /**
2061
+ * How many frames the file lists. More than `frames` when an animated
2062
+ * file is open as its first frame, or when its frames ended early
2063
+ * (docs/adr/0011).
2064
+ */
2065
+ readonly fileFrames: number;
1843
2066
  }
1844
2067
 
1845
2068
  /**
@@ -1882,10 +2105,42 @@ declare interface ImageSourceInfo {
1882
2105
  readonly format: ImageFormat;
1883
2106
  readonly width: number;
1884
2107
  readonly height: number;
2108
+ /**
2109
+ * How many frames the source holds: 1 for a still, and for an animated
2110
+ * file registered as its first frame. For a source registered with all
2111
+ * its frames, the frames that decoded (docs/adr/0011).
2112
+ */
1885
2113
  readonly frames: number;
1886
2114
  readonly hasAlpha: boolean;
1887
- /** The bytes the decoded source takes in the worker: frames × width × height × 4. */
2115
+ /**
2116
+ * The bytes the source takes in the worker: width × height × 4 for a
2117
+ * still. An animated source counts what's held, not every frame: its
2118
+ * screens in memory and its frame cache's ceiling (docs/adr/0011).
2119
+ */
1888
2120
  readonly decodedBytes: number;
2121
+ /**
2122
+ * The timing the file gives its frames, for a source registered with all
2123
+ * its frames; `null` for a still.
2124
+ */
2125
+ readonly timing: ImageSourceTiming | null;
2126
+ /**
2127
+ * Whether the file's frames ended early: before its end, or at a frame
2128
+ * that couldn't be decoded (docs/adr/0011). The frames before that are
2129
+ * the source's. Always `false` for a still.
2130
+ */
2131
+ readonly incomplete: boolean;
2132
+ }
2133
+
2134
+ /**
2135
+ * How an animated file plays (docs/adr/0011), as the file has it.
2136
+ *
2137
+ * @public
2138
+ */
2139
+ declare interface ImageSourceTiming {
2140
+ /** `null`: play once. 0: for ever. Otherwise that many repeats. */
2141
+ readonly loop: number | null;
2142
+ /** Each frame's delay in hundredths of a second, 0 to 65,535: one for each of the source's frames. */
2143
+ readonly delays: readonly number[];
1889
2144
  }
1890
2145
 
1891
2146
  /**
@@ -2060,6 +2315,19 @@ export declare interface ImageViewState {
2060
2315
  };
2061
2316
  }
2062
2317
 
2318
+ /**
2319
+ * Inserts frames into the animation, such as duplicates (docs/adr/0011).
2320
+ * Each shows a frame the base's source has.
2321
+ *
2322
+ * @public
2323
+ */
2324
+ declare interface InsertFramesCommand {
2325
+ readonly type: "image.insertFrames";
2326
+ /** The index, from 0 to the number of frames. */
2327
+ readonly at: number;
2328
+ readonly frames: readonly ImageFrame[];
2329
+ }
2330
+
2063
2331
  /**
2064
2332
  * Inserts layers at an index of the plan's layers, which are drawn bottom
2065
2333
  * to top (ADR 0009). Each needs a key no layer or redaction of the plan has.
@@ -2109,6 +2377,17 @@ declare const LAYER_FONTS: readonly ["sans-serif", "serif", "monospace"];
2109
2377
  */
2110
2378
  declare const LAYER_SHAPES: readonly ["rectangle", "ellipse"];
2111
2379
 
2380
+ /**
2381
+ * Moves frames to an index of the list without them, keeping their order.
2382
+ *
2383
+ * @public
2384
+ */
2385
+ declare interface MoveFramesCommand {
2386
+ readonly type: "image.moveFrames";
2387
+ readonly keys: readonly string[];
2388
+ readonly to: number;
2389
+ }
2390
+
2112
2391
  /**
2113
2392
  * Moves layers to an index of the list without them, keeping the order they
2114
2393
  * had: up or down the stack.
@@ -2133,6 +2412,16 @@ declare interface MoveRedactionsCommand {
2133
2412
  readonly to: number;
2134
2413
  }
2135
2414
 
2415
+ /**
2416
+ * Removes frames from the animation, which keeps at least one.
2417
+ *
2418
+ * @public
2419
+ */
2420
+ declare interface RemoveFramesCommand {
2421
+ readonly type: "image.removeFrames";
2422
+ readonly keys: readonly string[];
2423
+ }
2424
+
2136
2425
  /**
2137
2426
  * Removes layers, by key.
2138
2427
  *
@@ -2165,6 +2454,21 @@ declare interface RemoveStrokesCommand {
2165
2454
  readonly indexes: readonly number[];
2166
2455
  }
2167
2456
 
2457
+ /**
2458
+ * Puts removed frames back, each at its index, by rising index. It's what
2459
+ * undoes {@link RemoveFramesCommand}: the reducer applies it, but it isn't
2460
+ * part of the portable command format (ADR 0009).
2461
+ *
2462
+ * @public
2463
+ */
2464
+ declare interface RestoreFramesCommand {
2465
+ readonly type: "image.restoreFrames";
2466
+ readonly entries: readonly {
2467
+ readonly at: number;
2468
+ readonly frame: ImageFrame;
2469
+ }[];
2470
+ }
2471
+
2168
2472
  /**
2169
2473
  * Puts removed layers back, each at its index, by rising index. It's what
2170
2474
  * undoes {@link RemoveLayersCommand}: the reducer applies it, but it isn't
@@ -2211,6 +2515,15 @@ declare interface RestoreStrokesCommand {
2211
2515
  }[];
2212
2516
  }
2213
2517
 
2518
+ /**
2519
+ * Reverses the order the frames play in. It undoes itself.
2520
+ *
2521
+ * @public
2522
+ */
2523
+ declare interface ReverseFramesCommand {
2524
+ readonly type: "image.reverseFrames";
2525
+ }
2526
+
2214
2527
  /**
2215
2528
  * Sets or removes the base's crop, in whole pixels of the oriented source.
2216
2529
  *
@@ -2242,6 +2555,18 @@ declare interface SetFilterCommand {
2242
2555
  readonly filter: ImageFilter | null;
2243
2556
  }
2244
2557
 
2558
+ /**
2559
+ * Sets the whole order of the frames: every key, once. It's what undoes
2560
+ * {@link MoveFramesCommand}: the reducer applies it, but it isn't part of
2561
+ * the portable command format (ADR 0009).
2562
+ *
2563
+ * @public
2564
+ */
2565
+ declare interface SetFrameOrderCommand {
2566
+ readonly type: "image.setFrameOrder";
2567
+ readonly keys: readonly string[];
2568
+ }
2569
+
2245
2570
  /**
2246
2571
  * Sets the whole order of the layers: every key, once. It's what undoes
2247
2572
  * {@link MoveLayersCommand}: the reducer applies it, but it isn't part of
@@ -2254,6 +2579,16 @@ declare interface SetLayerOrderCommand {
2254
2579
  readonly keys: readonly string[];
2255
2580
  }
2256
2581
 
2582
+ /**
2583
+ * Sets how many times the animation repeats: `null` for once, 0 for ever.
2584
+ *
2585
+ * @public
2586
+ */
2587
+ declare interface SetLoopCommand {
2588
+ readonly type: "image.setLoop";
2589
+ readonly loop: number | null;
2590
+ }
2591
+
2257
2592
  /**
2258
2593
  * Sets one metadata field to keep on export. An empty value keeps nothing.
2259
2594
  *
@@ -2297,6 +2632,19 @@ declare interface SetRedactionOrderCommand {
2297
2632
  readonly keys: readonly string[];
2298
2633
  }
2299
2634
 
2635
+ /**
2636
+ * Sets some frames' delays: one command for one frame or for all of them.
2637
+ *
2638
+ * @public
2639
+ */
2640
+ declare interface UpdateFramesCommand {
2641
+ readonly type: "image.updateFrames";
2642
+ readonly updates: readonly {
2643
+ readonly key: string;
2644
+ readonly props: ImageFrameProps;
2645
+ }[];
2646
+ }
2647
+
2300
2648
  /**
2301
2649
  * Sets some fields of some layers: their boxes after a move, their opacity,
2302
2650
  * a text layer's text. `props` may hold any field of the layer's kind except
package/dist/react.js CHANGED
@@ -1,2 +1,2 @@
1
1
  "use client";
2
- export { s as ImageAdjustPanel, h as ImageCropPanel, m as ImageDrawPanel, t as ImageEditor, u as ImageEditorProvider, f as ImageExportDialog, o as ImageFilterPanel, a as ImageInfoPanel, l as ImageLayersPanel, c as ImageRedactPanel, i as ImageStage, r as ImageToolbar, d as imageEditorMessages, n as imageIcons, x as imageTools, g as useImageDocument, _ as useImageEditorState, v as useImageMessages, y as useImageSession, b as useImageView } from "./shared/editor-Bj9Xo5nf.js";
2
+ export { o as ImageAdjustPanel, g as ImageCropPanel, h as ImageDrawPanel, t as ImageEditor, u as ImageEditorProvider, f as ImageExportDialog, a as ImageFilterPanel, l as ImageFramesPanel, i as ImageInfoPanel, c as ImageLayersPanel, s as ImageRedactPanel, m as ImageStage, r as ImageToolbar, d as imageEditorMessages, n as imageIcons, S as imageTools, _ as useImageDocument, v as useImageEditorState, y as useImageMessages, b as useImageSession, x as useImageView } from "./shared/editor-CV39S-zb.js";