@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/element.d.ts CHANGED
@@ -19,11 +19,24 @@ import type { MessageOverrides } from '@hussmartinez/sdk-core';
19
19
  import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
20
20
  import { SdkError } from '@hussmartinez/sdk-core';
21
21
 
22
+ /**
23
+ * Appends strokes to a drawing layer (ADR 0009, docs/adr/0014): one stroke
24
+ * for each gesture, however many runs it has.
25
+ *
26
+ * @public
27
+ */
28
+ declare interface AddStrokesCommand {
29
+ readonly type: "image.addStrokes";
30
+ /** The drawing's key. */
31
+ readonly key: string;
32
+ readonly strokes: readonly ImageStroke[];
33
+ }
34
+
22
35
  /**
23
36
  * Registers `<hm-image-editor>`, or the tag you name, and returns its class
24
37
  * (docs/adr/0007, sdk-core ADR 0040): the attributes `theme`, `locale` and
25
38
  * `tools`; the properties `file`, `plan`, `filePolicy`, `assetsUrl`,
26
- * `messages`, `engine` and `processor`; the methods `open`, `execute`,
39
+ * `messages`, `engine` and `processor`; the methods `open`, `insertImage`, `execute`,
27
40
  * `export`, `undo` and `redo`; and the events `hm-image-editor-change`,
28
41
  * `-event`, `-export` and `-error`. Calling it again returns the same class.
29
42
  *
@@ -57,6 +70,25 @@ declare type ExifOrientation = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
57
70
  */
58
71
  declare const FILTER_PRESETS: readonly ["vivid", "warm", "cool", "fade", "mono", "noir", "sepia"];
59
72
 
73
+ /**
74
+ * An arrow from one point of the scene to another (ADR 0009,
75
+ * docs/adr/0014). Its head's size follows its width, and its tip is exactly
76
+ * on `to`.
77
+ *
78
+ * @public
79
+ */
80
+ declare interface ImageArrowLayer extends ImageLayerCommon {
81
+ readonly kind: "arrow";
82
+ /** The tail. */
83
+ readonly from: ImageScenePoint;
84
+ /** The tip. It differs from `from`. */
85
+ readonly to: ImageScenePoint;
86
+ /** `#rrggbb`. */
87
+ readonly colour: string;
88
+ /** The shaft's width, in whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
89
+ readonly width: number;
90
+ }
91
+
60
92
  /**
61
93
  * The image being edited: a source, its crop and orientation, and its
62
94
  * develop adjustments and filter.
@@ -74,6 +106,13 @@ declare interface ImageBase {
74
106
  readonly filter: ImageFilter | null;
75
107
  }
76
108
 
109
+ /**
110
+ * A layer that has a box: text, a shape or an image.
111
+ *
112
+ * @public
113
+ */
114
+ declare type ImageBoxedLayer = ImageTextLayer | ImageShapeLayer | ImageImageLayer;
115
+
77
116
  /**
78
117
  * Options every port call accepts.
79
118
  *
@@ -90,11 +129,11 @@ declare interface ImageCallOptions {
90
129
 
91
130
  /**
92
131
  * Every edit to an {@link ImagePlan}: plain, structured-cloneable data
93
- * (ADR 0003). Feature pull requests add their own commands to this union.
132
+ * (ADR 0003, ADR 0009).
94
133
  *
95
134
  * @public
96
135
  */
97
- declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand;
136
+ declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | AddStrokesCommand | RemoveStrokesCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
98
137
 
99
138
  /**
100
139
  * A rectangle in whole pixels of the oriented source: `x` and `y` from its
@@ -130,6 +169,23 @@ declare interface ImageDevelop {
130
169
  readonly vibrance: number;
131
170
  }
132
171
 
172
+ /**
173
+ * Freehand strokes (ADR 0009, docs/adr/0014). A drawing has an origin and
174
+ * no box: moving it changes its origin, never its points. Its strokes are
175
+ * drawn opaque and the drawing composited as one, so strokes that cross
176
+ * don't darken each other.
177
+ *
178
+ * @public
179
+ */
180
+ declare interface ImageDrawingLayer extends ImageLayerCommon {
181
+ readonly kind: "drawing";
182
+ /** Its origin, in whole scene pixels. May be negative. */
183
+ readonly x: number;
184
+ readonly y: number;
185
+ /** 1 to `MAX_DRAWING_STROKES` strokes, in the order they're drawn. */
186
+ readonly strokes: readonly ImageStroke[];
187
+ }
188
+
133
189
  /**
134
190
  * The element's events, fired as `hm-image-editor-<name>`. None carries a
135
191
  * file name or contents (sdk-core ADR 0012):
@@ -149,7 +205,7 @@ export declare type ImageEditorElementEvent = "change" | "event" | "export" | "e
149
205
  *
150
206
  * @public
151
207
  */
152
- export declare type ImageEditorElementMethods = Pick<ImageEditorHandle, "open" | "execute" | "export" | "undo" | "redo">;
208
+ export declare type ImageEditorElementMethods = Pick<ImageEditorHandle, "open" | "insertImage" | "execute" | "export" | "undo" | "redo">;
153
209
 
154
210
  /**
155
211
  * The `<hm-image-editor>` element's props: its attributes, `theme`, `locale`
@@ -173,7 +229,7 @@ export declare interface ImageEditorElementProps {
173
229
  /** Where the application serves the package's `dist/assets/` directory. */
174
230
  assetsUrl?: string | URL;
175
231
  /** Text overrides, typed against the English catalogue. */
176
- messages?: MessageOverrides<ImageMessageCatalogue>;
232
+ messages?: MessageOverrides<ImageEditorMessageCatalogue>;
177
233
  engine?: ImageEngine;
178
234
  processor?: ImageProcessor;
179
235
  }
@@ -188,6 +244,12 @@ declare interface ImageEditorHandle {
188
244
  readonly session: ImageSession;
189
245
  /** Opens an image, replacing the current one once it has opened. */
190
246
  open(file: Blob): Promise<void>;
247
+ /**
248
+ * Adds an image as a layer in the middle of the image as it's shown, as
249
+ * one undoable step, and shows the layers with it selected. A file that
250
+ * can't be added is reported on the stage, as a failed open is.
251
+ */
252
+ insertImage(file: Blob): Promise<void>;
191
253
  /** Applies commands as one undoable step. */
192
254
  execute(commands: ImageCommand | readonly ImageCommand[]): void;
193
255
  /** Renders and encodes the image as it is now. */
@@ -199,389 +261,32 @@ declare interface ImageEditorHandle {
199
261
  }
200
262
 
201
263
  /**
202
- * The port for reading images: probe a file's headers, decode it into a
203
- * source the engine holds, make thumbnails and release sources (ADR 0001,
204
- * ADR 0002, ADR 0003, ADR 0008). The SDK's own adapter probes with its own
205
- * readers and decodes with `createImageBitmap`, both in its render worker;
206
- * hosts can pass their own to the editor's `engine` prop, and every
207
- * implementation must pass the engine's contract tests.
208
- *
209
- * `register` checks a file's own limits, from `filePolicy`, against the
210
- * engine's own probe before decoding it, so a host can't decode past them by
211
- * passing a probe of another file. Session-wide limits, such as
212
- * `maxSessionSize`, are the session's (ADR 0004).
213
- *
214
- * Failures reject with `ImageError`: `INVALID_IMAGE` for a malformed file,
215
- * one whose headers claim more than its data holds, or one whose decoded
216
- * size differs from the probe's; `UNSUPPORTED_FORMAT` for one the probe
217
- * can't bound; `DECODE_FAILED` when the browser can't decode it; and
218
- * sdk-core's codes for cancellation and worker failures.
219
- *
220
- * @public
221
- */
222
- declare interface ImageEngine {
223
- /** Reads a file's headers and metadata, without decoding it. */
224
- probe(file: Blob, options?: ImageCallOptions): Promise<ImageProbe>;
225
- /**
226
- * Decodes a probed file into a source with the given id, upright. The
227
- * decoded size must equal the probe's oriented size, or the call rejects
228
- * with `INVALID_IMAGE` and keeps nothing. A file over one of
229
- * `filePolicy`'s per-file limits rejects with that limit's code, before
230
- * anything decodes it. An id already in use is a
231
- * `TypeError`.
232
- */
233
- register(id: string, file: Blob, probe: ImageProbe, options?: ImageRegisterOptions): Promise<ImageSourceInfo>;
234
- /**
235
- * A rendering of a source that fits inside `maxSize` × `maxSize`, keeping
236
- * its aspect ratio and never enlarging it. An unknown id is a `TypeError`.
237
- */
238
- thumbnail(id: string, maxSize: number, options?: ImageCallOptions): Promise<ImageThumbnail>;
239
- /** Frees a source's pixels. Releasing an unknown id does nothing. */
240
- release(id: string): Promise<void>;
241
- /** Releases the engine, its sources and its worker. Pending calls reject, and later calls throw. */
242
- destroy(): Promise<void>;
243
- }
244
-
245
- /**
246
- * The error `@hussmartinez/image-sdk` throws and rejects with, with a stable
247
- * `code`, structured `details` and the underlying error as `cause`. Show
248
- * users the text for its code from {@link imageMessages}, never its
249
- * `message`, which is for developers and may contain text from the file.
250
- *
251
- * @example
252
- * ```ts
253
- * try {
254
- * await session.open(file);
255
- * } catch (error) {
256
- * if (isImageError(error, "DECODE_FAILED")) {
257
- * suggestConvertingToPng();
258
- * } else {
259
- * show(messages.error(error));
260
- * }
261
- * }
262
- * ```
263
- *
264
- * @public
265
- */
266
- declare class ImageError extends SdkError<ImageErrorCode> {
267
- /** Always `"ImageError"`, which survives minification and worker boundaries. */
268
- readonly name = "ImageError";
269
- }
270
-
271
- /**
272
- * Error codes of `@hussmartinez/image-sdk`: sdk-core's own codes, such as
273
- * `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the image SDK's
274
- * (ADR 0001, ADR 0004). They never change meaning once released.
275
- *
276
- * - `INVALID_IMAGE`: the file is malformed, its headers claim more than its
277
- * data can carry or less than its decoder would produce, or its decoded
278
- * size differs from what its headers declare.
279
- * - `UNSUPPORTED_FORMAT`: the format isn't recognised, its bound can't be
280
- * read, or the browser can't encode the requested export format.
281
- * `details.format` names it.
282
- * - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
283
- * usually because it lacks the format. `details.format` names it.
284
- * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as a
285
- * crop outside its source. `details.reason` says why, as a stable token
286
- * (`ImageCommandRejection`).
287
- * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
288
- * valid in its format. `details.reason` says why (`ImageDocumentRejection`).
289
- * A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
290
- * instead, with `details.reason` `unknown-format` or `unknown-format-version`.
291
- * - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
292
- * the `maxImagePixels` limit.
293
- * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
294
- * `maxImageDimension` limit.
295
- * - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
296
- * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
297
- * `maxSessionSize` limit.
298
- * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
299
- *
300
- * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
301
- * value and the `unit`. Other codes' `details` name the format involved,
302
- * and a `reason`, never data from the file.
303
- *
304
- * @public
305
- */
306
- 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";
307
-
308
- /**
309
- * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
310
- * the lossy formats; it defaults to 0.92. WebP is encoded only where the
311
- * browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`.
312
- *
313
- * @public
314
- */
315
- declare type ImageExportFormat = {
316
- readonly type: "png";
317
- } | {
318
- readonly type: "jpeg";
319
- readonly quality?: number;
320
- } | {
321
- readonly type: "webp";
322
- readonly quality?: number;
323
- };
324
-
325
- /**
326
- * One export: a plan over sources registered with the same engine, and the
327
- * output format. The plan's kept metadata goes into the file, and nothing
328
- * else does (ADR 0005).
329
- *
330
- * @public
331
- */
332
- declare interface ImageExportJob {
333
- readonly plan: ImagePlan;
334
- readonly format: ImageExportFormat;
335
- }
336
-
337
- /**
338
- * Options for exporting.
339
- *
340
- * @public
341
- */
342
- declare interface ImageExportOptions extends ImageProgressOptions {
343
- /**
344
- * The limits the output canvas is checked against before it's allocated:
345
- * `maxImageDimension` and `maxImagePixels` (ADR 0004). The defaults of
346
- * `imageLimits` when omitted.
347
- */
348
- readonly filePolicy?: ImageFilePolicy;
349
- }
350
-
351
- /**
352
- * What the export dialog reports about a finished export, for the element's
353
- * `export` event: no pixels and no file, which an event must never carry
354
- * (sdk-core ADR 0012). The element's `export()` method returns the file.
355
- *
356
- * @public
357
- */
358
- export declare interface ImageExportReport {
359
- readonly format: ImageExportFormat["type"];
360
- readonly width: number;
361
- readonly height: number;
362
- /** The file's size in bytes. */
363
- readonly size: number;
364
- readonly removed: readonly (keyof ImageMetadataPresence)[];
365
- readonly kept: readonly (keyof ImageKeepableMetadata)[];
366
- }
367
-
368
- /**
369
- * A resolved file policy for the image SDK. Violations throw
370
- * {@link ImageError}.
371
- *
372
- * @public
373
- */
374
- declare type ImageFilePolicy = FilePolicy<ImageLimitDefinitions>;
375
-
376
- /**
377
- * A host's `filePolicy`: a new maximum, or `{ maximum, warning }`, for any of
378
- * the image SDK's limits. `Infinity` disables a maximum, which removes a
379
- * protection against hostile files, or disables a warning. Unknown limit
380
- * names throw `TypeError` when the policy is resolved.
381
- *
382
- * @example
383
- * ```ts
384
- * // Large scans: raise the pixel and decoded sizes together.
385
- * const filePolicy: ImageFilePolicyOverrides = {
386
- * maxImagePixels: 100_000_000,
387
- * maxDecodedSize: { maximum: 2e9, warning: 800e6 },
388
- * };
389
- * ```
390
- *
391
- * @public
392
- */
393
- declare type ImageFilePolicyOverrides = FilePolicyOverrides<ImageLimitDefinitions>;
394
-
395
- /**
396
- * A filter preset and its strength, an integer from 0 (no effect) to 100.
397
- *
398
- * @public
399
- */
400
- declare interface ImageFilter {
401
- readonly preset: ImageFilterPreset;
402
- readonly strength: number;
403
- }
404
-
405
- /**
406
- * A filter preset's name.
264
+ * The type of {@link imageEditorMessages}, for typing the editor's
265
+ * `messages` overrides with `MessageOverrides<ImageEditorMessageCatalogue>`.
407
266
  *
408
267
  * @public
409
268
  */
410
- declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
269
+ export declare type ImageEditorMessageCatalogue = typeof imageEditorMessages;
411
270
 
412
271
  /**
413
- * The formats the probe recognises, by their signature bytes (ADR 0001).
272
+ * The English message catalogue of the SDK's components: `imageMessages`,
273
+ * with sdk-core's text, errors and warnings; `@hussmartinez/ui`'s, for the
274
+ * ui components the editor renders (sdk-core ADR 0046); and the text of the
275
+ * editor, its stage, toolbar and tools, its panels and the export dialog.
414
276
  *
415
- * @public
416
- */
417
- declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
418
-
419
- /**
420
- * The metadata fields a user may keep on export (ADR 0005). Empty strings
421
- * mean the field isn't written.
277
+ * `ImageEditor`, `ImageEditorProvider` and `<hm-image-editor>` each build
278
+ * one `Messages` object from it, with the host's locale and overrides, and
279
+ * the editor gives the same object to its own components and to ui's.
280
+ * Override any of its keys through their `messages`, typed with
281
+ * `ImageEditorMessageCatalogue`.
422
282
  *
423
- * @public
424
- */
425
- declare interface ImageKeepableMetadata {
426
- readonly title: string;
427
- readonly description: string;
428
- readonly artist: string;
429
- readonly copyright: string;
430
- }
431
-
432
- /**
433
- * The type of {@link imageLimitDefinitions}.
283
+ * It's defined in the React entry, so the server-safe `.` entry and its
284
+ * `imageMessages` carry no interface text (docs/adr/0012).
434
285
  *
435
286
  * @public
436
287
  */
437
- declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
438
-
439
- /**
440
- * The image SDK's limit definitions: sdk-core's core limits with image
441
- * defaults, plus five for images (ADR 0004).
442
- *
443
- * | Limit | Code | Default maximum | Default warning |
444
- * |---|---|---|---|
445
- * | `maxFileSize` | `FILE_TOO_LARGE` | 100 MB | 50 MB |
446
- * | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
447
- * | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
448
- * | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
449
- * | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
450
- * | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
451
- * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
452
- * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
453
- * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
454
- *
455
- * Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
456
- * per pixel. `maxImagePixels` is the same limit, with the same name, code
457
- * and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
458
- *
459
- * @public
460
- */
461
- declare const imageLimitDefinitions: {
462
- readonly maxDecodedSize: {
463
- readonly default: 1000000000;
464
- readonly warning: 400000000;
465
- readonly code: "DECODED_SIZE_TOO_LARGE";
466
- readonly unit: "bytes";
467
- };
468
- readonly maxImagePixels: {
469
- readonly code: "IMAGE_TOO_LARGE";
470
- readonly unit: "pixels";
471
- readonly default: 50000000;
472
- readonly warning: 24000000;
473
- };
474
- readonly maxImageDimension: {
475
- readonly code: "IMAGE_DIMENSION_TOO_LARGE";
476
- readonly unit: "pixels";
477
- readonly default: 16384;
478
- };
479
- readonly maxFrames: {
480
- readonly code: "TOO_MANY_FRAMES";
481
- readonly unit: "count";
482
- readonly default: 300;
483
- readonly warning: 100;
484
- };
485
- readonly maxSessionSize: {
486
- readonly code: "SESSION_TOO_LARGE";
487
- readonly unit: "bytes";
488
- readonly default: 1000000000;
489
- readonly warning: 500000000;
490
- };
491
- readonly maxLayers: {
492
- readonly code: "TOO_MANY_LAYERS";
493
- readonly unit: "count";
494
- readonly default: 256;
495
- };
496
- readonly maxFileSize: {
497
- readonly code: "FILE_TOO_LARGE";
498
- readonly unit: "bytes";
499
- readonly default: 100000000;
500
- readonly warning: 50000000;
501
- };
502
- readonly maxFiles: {
503
- readonly code: "TOO_MANY_FILES";
504
- readonly unit: "count";
505
- readonly default: 20;
506
- };
507
- readonly maxProcessingTime: {
508
- readonly code: "PROCESSING_TIME_EXCEEDED";
509
- readonly unit: "milliseconds";
510
- readonly default: 120000;
511
- };
512
- };
513
-
514
- /**
515
- * The names of the image SDK's limits.
516
- *
517
- * @public
518
- */
519
- declare type ImageLimitName = keyof ImageLimitDefinitions;
520
-
521
- /**
522
- * The type of {@link imageMessages}, for typing a host's overrides with
523
- * `MessageOverrides<ImageMessageCatalogue>`.
524
- *
525
- * @public
526
- */
527
- declare type ImageMessageCatalogue = typeof imageMessages;
528
-
529
- /**
530
- * The image SDK's English message catalogue: sdk-core's and ui's messages, and text
531
- * for every {@link ImageErrorCode} and every limit's warning. Pass it to
532
- * `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
533
- * overrides. It also has the editor's text: its labels, states,
534
- * announcements and tool names.
535
- *
536
- * Error text is looked up by code, with the error's `details` as
537
- * parameters, and never taken from `error.message` (ADR 0019).
538
- *
539
- * @example
540
- * ```ts
541
- * const messages = createMessages(imageMessages, { locale: "en", overrides: props.messages });
542
- * messages.error(error); // "This animation has 400 frames, which is over the 300-frame limit."
543
- * messages.t("warnings.maxSessionSize", { actual: 600e6 });
544
- * ```
545
- *
546
- * @public
547
- */
548
- declare const imageMessages: {
288
+ export declare const imageEditorMessages: {
549
289
  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.";
550
- readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
551
- readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
552
- readonly "errors.DECODE_FAILED": "This browser can't open this kind of image. Try another browser, or convert the file to PNG or JPEG.";
553
- readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
554
- readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
555
- readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
556
- readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
557
- readonly "errors.TOO_MANY_FRAMES": {
558
- readonly $plural: "maximum";
559
- } & {
560
- readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
561
- readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
562
- };
563
- 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.";
564
- readonly "errors.TOO_MANY_LAYERS": {
565
- readonly $plural: "maximum";
566
- } & {
567
- readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
568
- readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
569
- };
570
- readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
571
- readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
572
- readonly "warnings.maxFrames": {
573
- readonly $plural: "actual";
574
- } & {
575
- readonly one: "This animation has {actual} frame.";
576
- readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
577
- };
578
- readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
579
- readonly "warnings.maxLayers": {
580
- readonly $plural: "actual";
581
- } & {
582
- readonly one: "This image has {actual} layer.";
583
- readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
584
- };
585
290
  readonly "editor.label": "Image editor";
586
291
  readonly "editor.preview": "Edited image preview, {width, number} × {height, number}";
587
292
  readonly "editor.empty": "Open an image to start editing. It stays on this device.";
@@ -598,6 +303,21 @@ declare const imageMessages: {
598
303
  readonly "actions.image.setMetadata": "metadata";
599
304
  readonly "actions.image.setDevelop": "adjustment";
600
305
  readonly "actions.image.setFilter": "filter";
306
+ readonly "actions.image.insertLayers": "layer";
307
+ readonly "actions.image.removeLayers": "layer";
308
+ readonly "actions.image.restoreLayers": "layer";
309
+ readonly "actions.image.moveLayers": "layer order";
310
+ readonly "actions.image.setLayerOrder": "layer order";
311
+ readonly "actions.image.updateLayers": "layer change";
312
+ readonly "actions.image.addStrokes": "stroke";
313
+ readonly "actions.image.removeStrokes": "stroke";
314
+ readonly "actions.image.restoreStrokes": "stroke";
315
+ readonly "actions.image.insertRedactions": "redaction";
316
+ readonly "actions.image.removeRedactions": "redaction";
317
+ readonly "actions.image.restoreRedactions": "redaction";
318
+ readonly "actions.image.moveRedactions": "redaction order";
319
+ readonly "actions.image.setRedactionOrder": "redaction order";
320
+ readonly "actions.image.updateRedactions": "redaction change";
601
321
  readonly "toolbar.label": "Image tools";
602
322
  readonly "toolbar.groups.file": "File";
603
323
  readonly "toolbar.groups.history": "History";
@@ -617,7 +337,7 @@ declare const imageMessages: {
617
337
  readonly "tools.flip-vertical": "Flip vertically";
618
338
  readonly "toolbar.groups.crop": "Crop";
619
339
  readonly "crop.frame": "Crop area";
620
- 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.";
340
+ readonly "crop.frameDescription": "{width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; with Shift, they resize it; Enter applies and Escape cancels.";
621
341
  readonly "crop.size": "{width, number} × {height, number}, from {x, number}, {y, number}";
622
342
  readonly "crop.panel": "Crop";
623
343
  readonly "crop.x": "Left";
@@ -632,6 +352,129 @@ declare const imageMessages: {
632
352
  readonly "crop.cancel": "Cancel";
633
353
  readonly "crop.reset": "Whole image";
634
354
  readonly "crop.applied": "Cropped to {width, number} × {height, number}.";
355
+ readonly "tools.redact": "Redact";
356
+ readonly "toolbar.groups.redact": "Redact";
357
+ readonly "redact.panel": "Redact";
358
+ readonly "redact.intro": "Cover parts of the image. Only the exported image is redacted: the original stays in the editor.";
359
+ readonly "redact.add": "Add area";
360
+ readonly "redact.done": "Done";
361
+ readonly "redact.mode": "Cover with";
362
+ readonly "redact.modes.solid": "Solid colour";
363
+ readonly "redact.modes.pixelate": "Pixelation";
364
+ readonly "redact.pixelateHint": "Pixelation may not hide text. For text and numbers, use a solid colour.";
365
+ readonly "redact.colour": "Colour";
366
+ readonly "redact.colours.black": "Black";
367
+ readonly "redact.colours.white": "White";
368
+ readonly "redact.x": "Left";
369
+ readonly "redact.y": "Top";
370
+ readonly "redact.width": "Width";
371
+ readonly "redact.height": "Height";
372
+ readonly "redact.areas": "Redacted areas";
373
+ readonly "redact.none": "No areas yet. Drag across the image, or add one.";
374
+ readonly "redact.area": "Area {index, number}: {mode}, {width, number} × {height, number}";
375
+ readonly "redact.modeNames.solid": "solid colour";
376
+ readonly "redact.modeNames.pixelate": "pixelated";
377
+ readonly "redact.remove": "Remove area {index, number}";
378
+ readonly "redact.frame": "Redacted area {index, number} of {count, number}";
379
+ readonly "redact.frameDescription": "{mode}, {width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; with Shift, they resize it; Delete removes it and Escape ends redacting.";
380
+ readonly "redact.added": {
381
+ readonly $plural: "count";
382
+ } & {
383
+ readonly one: "Area added. {count} area is redacted.";
384
+ readonly other: "Area added. {count, number} areas are redacted.";
385
+ };
386
+ readonly "redact.removedLast": "Area removed. Nothing is redacted.";
387
+ readonly "redact.removed": {
388
+ readonly $plural: "count";
389
+ } & {
390
+ readonly one: "Area removed. {count} area is redacted.";
391
+ readonly other: "Area removed. {count, number} areas are redacted.";
392
+ };
393
+ readonly "tools.add-text": "Add text";
394
+ readonly "tools.add-rectangle": "Add a rectangle";
395
+ readonly "tools.add-ellipse": "Add an ellipse";
396
+ readonly "tools.add-arrow": "Add an arrow";
397
+ readonly "tools.add-image": "Add an image";
398
+ readonly "tools.draw": "Draw";
399
+ readonly "toolbar.groups.draw": "Draw";
400
+ readonly "toolbar.groups.add": "Add";
401
+ readonly "editor.inserting": "Adding the image…";
402
+ readonly "layers.text": "Text";
403
+ readonly "layers.font": "Font";
404
+ readonly "layers.fonts.sans-serif": "Sans";
405
+ readonly "layers.fonts.serif": "Serif";
406
+ readonly "layers.fonts.monospace": "Mono";
407
+ readonly "layers.align": "Alignment";
408
+ readonly "layers.alignments.start": "Start";
409
+ readonly "layers.alignments.center": "Centre";
410
+ readonly "layers.alignments.end": "End";
411
+ readonly "layers.bold": "Bold";
412
+ readonly "layers.colour": "Colour";
413
+ readonly "layers.arrow.from.x": "Tail, left";
414
+ readonly "layers.arrow.from.y": "Tail, top";
415
+ readonly "layers.arrow.to.x": "Tip, left";
416
+ readonly "layers.arrow.to.y": "Tip, top";
417
+ readonly "layers.arrow.width": "Width";
418
+ readonly "layers.fill": "Fill";
419
+ readonly "layers.outline": "Outline";
420
+ readonly "layers.fillColour": "Fill colour";
421
+ readonly "layers.outlineColour": "Outline colour";
422
+ readonly "layers.outlineWidth": "Outline width";
423
+ readonly "layers.colours.black": "Black";
424
+ readonly "layers.colours.white": "White";
425
+ readonly "layers.colours.red": "Red";
426
+ readonly "layers.colours.yellow": "Yellow";
427
+ readonly "layers.colours.green": "Green";
428
+ readonly "layers.colours.blue": "Blue";
429
+ readonly "draw.panel": "Draw";
430
+ readonly "draw.intro": "Drag across the image to draw. Drawing needs a mouse, a pen or a finger; to point at something with the keyboard, add an arrow.";
431
+ readonly "draw.mode": "Draw with";
432
+ readonly "draw.modes.pen": "Pen";
433
+ readonly "draw.modes.highlighter": "Highlighter";
434
+ readonly "draw.colour": "Colour";
435
+ readonly "draw.width": "Width";
436
+ readonly "draw.removeLast": "Remove last stroke";
437
+ readonly "draw.removed": "Removed the last stroke.";
438
+ readonly "draw.done": "Done";
439
+ readonly "tools.layers": "Layers";
440
+ readonly "toolbar.groups.layers": "Layers";
441
+ readonly "layers.panel": "Layers";
442
+ readonly "layers.list": "Layers, the top one first";
443
+ readonly "layers.none": "No layers yet. Add text, a shape or an image from the toolbar.";
444
+ readonly "layers.kinds.text": "Text";
445
+ readonly "layers.kinds.rectangle": "Rectangle";
446
+ readonly "layers.kinds.ellipse": "Ellipse";
447
+ readonly "layers.kinds.image": "Image";
448
+ readonly "layers.kinds.drawing": "Drawing";
449
+ readonly "layers.kinds.arrow": "Arrow";
450
+ readonly "layers.visible": "Show {name}";
451
+ readonly "layers.selected": "Selected layer";
452
+ readonly "layers.moveUp": "Move up";
453
+ readonly "layers.moveDown": "Move down";
454
+ readonly "layers.mirror": "Mirror";
455
+ readonly "layers.duplicate": "Duplicate";
456
+ readonly "layers.remove": "Delete";
457
+ readonly "layers.name": "Name";
458
+ readonly "layers.x": "Left";
459
+ readonly "layers.y": "Top";
460
+ readonly "layers.width": "Width";
461
+ readonly "layers.height": "Height";
462
+ readonly "layers.rotation": "Turn, in degrees";
463
+ readonly "layers.opacity": "Opacity, in percent";
464
+ readonly "layers.done": "Done";
465
+ readonly "layers.frame": "Layer {index, number} of {count, number}: {name}";
466
+ readonly "layers.frameDescription": "{width, number} × {height, number} pixels, from {x, number}, {y, number}, turned {degrees, number}°. Arrow keys move it; with Shift, they resize it; Delete removes it and Escape closes the layers.";
467
+ readonly "layers.drawingDescription": {
468
+ readonly $plural: "count";
469
+ } & {
470
+ readonly one: "{count} stroke, {width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; Delete removes it and Escape closes the layers.";
471
+ readonly other: "{count, number} strokes, {width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; Delete removes it and Escape closes the layers.";
472
+ };
473
+ readonly "layers.arrowDescription": "From {fromX, number}, {fromY, number} to {toX, number}, {toY, number}. Arrow keys move it; with Shift, they move its tip; Delete removes it and Escape closes the layers.";
474
+ readonly "layers.movedUp": "Moved {name} up. It's layer {index, number} of {count, number}.";
475
+ readonly "layers.movedDown": "Moved {name} down. It's layer {index, number} of {count, number}.";
476
+ readonly "layers.duplicated": "Duplicated {name}.";
477
+ readonly "layers.removed": "Deleted {name}.";
635
478
  readonly "inspector.label": "Panels";
636
479
  readonly "inspector.adjust": "Adjust";
637
480
  readonly "inspector.filters": "Filters";
@@ -682,6 +525,7 @@ declare const imageMessages: {
682
525
  readonly "filters.strength": "Strength";
683
526
  readonly "toolbar.groups.export": "Export";
684
527
  readonly "tools.export": "Export";
528
+ readonly "tools.exportWhileCropping": "Apply or cancel the crop before exporting.";
685
529
  readonly "export.title": "Export image";
686
530
  readonly "export.description": "The file is made on this device, and nothing is uploaded.";
687
531
  readonly "export.format": "Format";
@@ -706,6 +550,13 @@ declare const imageMessages: {
706
550
  readonly "export.output": "{width, number} × {height, number} pixels, {format}";
707
551
  readonly "export.removed": "Removed from the file";
708
552
  readonly "export.removedNone": "The image had no other details to remove.";
553
+ readonly "export.redacted": {
554
+ readonly $plural: "count";
555
+ } & {
556
+ readonly one: "{count} area is redacted.";
557
+ readonly other: "{count, number} areas are redacted.";
558
+ };
559
+ readonly "export.redactedPixelated": "Pixelated areas may not hide text.";
709
560
  readonly "export.kind.location": "Location";
710
561
  readonly "export.kind.camera": "Camera details";
711
562
  readonly "export.kind.timestamps": "Dates and times";
@@ -722,15 +573,55 @@ declare const imageMessages: {
722
573
  readonly "export.ready": "{width, number} × {height, number} pixels, {format}, {size, fileSize}";
723
574
  readonly "export.download": "Download";
724
575
  readonly "export.close": "Done";
576
+ readonly "colorField.swatches": "swatches";
725
577
  readonly "dialog.close": "Close";
726
578
  readonly "fileDropZone.choose": "Choose a file";
727
579
  readonly "fileDropZone.chooseMultiple": "Choose files";
728
580
  readonly "fileDropZone.hint": "or drop it here";
729
581
  readonly "fileDropZone.hintMultiple": "or drop them here";
730
582
  readonly "progress.label": "Progress";
583
+ readonly "reorderableList.moved": "{label} moved to position {position} of {count}";
731
584
  readonly "spinner.label": "Loading";
732
585
  readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
733
586
  readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
587
+ readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
588
+ readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
589
+ readonly "errors.DECODE_FAILED": "This browser can't open this kind of image. Try another browser, or convert the file to PNG or JPEG.";
590
+ readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
591
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
592
+ readonly "errors.UNSUPPORTED_PLAN": "This image has edits this version can't show. Update the application and try again.";
593
+ readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
594
+ readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
595
+ readonly "errors.TOO_MANY_FRAMES": {
596
+ readonly $plural: "maximum";
597
+ } & {
598
+ readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
599
+ readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
600
+ };
601
+ 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.";
602
+ readonly "errors.TOO_MANY_LAYERS": {
603
+ readonly $plural: "maximum";
604
+ } & {
605
+ readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
606
+ readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
607
+ };
608
+ 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.";
609
+ readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
610
+ readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
611
+ readonly "warnings.maxFrames": {
612
+ readonly $plural: "actual";
613
+ } & {
614
+ readonly one: "This animation has {actual} frame.";
615
+ readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
616
+ };
617
+ readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
618
+ readonly "warnings.maxLayers": {
619
+ readonly $plural: "actual";
620
+ } & {
621
+ readonly one: "This image has {actual} layer.";
622
+ readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
623
+ };
624
+ readonly "warnings.maxDrawingPoints": "This image has a lot of drawing, and may be slow to edit and export.";
734
625
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
735
626
  readonly "errors.ABORTED": "The operation was cancelled.";
736
627
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -748,36 +639,464 @@ declare const imageMessages: {
748
639
  readonly one: "You can add {maximum} file at a time.";
749
640
  readonly other: "You can add up to {maximum} files at a time.";
750
641
  };
751
- readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
752
- readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
753
- readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
754
- readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
755
- readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
756
- readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
757
- readonly "keys.control": "Ctrl";
758
- readonly "keys.alt": "Alt";
759
- readonly "keys.shift": "Shift";
760
- readonly "keys.meta": "Meta";
761
- readonly "keys.apple.control": "\u2303";
762
- readonly "keys.apple.alt": "\u2325";
763
- readonly "keys.apple.shift": "\u21E7";
764
- readonly "keys.apple.meta": "\u2318";
765
- readonly "keys.space": "Space";
766
- readonly "keys.enter": "Enter";
767
- readonly "keys.escape": "Esc";
768
- readonly "keys.tab": "Tab";
769
- readonly "keys.delete": "Delete";
770
- readonly "keys.backspace": "Backspace";
771
- readonly "keys.arrowUp": "\u2191";
772
- readonly "keys.arrowDown": "\u2193";
773
- readonly "keys.arrowLeft": "\u2190";
774
- readonly "keys.arrowRight": "\u2192";
775
- readonly "keys.home": "Home";
776
- readonly "keys.end": "End";
777
- readonly "keys.pageUp": "Page Up";
778
- readonly "keys.pageDown": "Page Down";
642
+ readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
643
+ readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
644
+ readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
645
+ readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
646
+ readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
647
+ readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
648
+ readonly "keys.control": "Ctrl";
649
+ readonly "keys.alt": "Alt";
650
+ readonly "keys.shift": "Shift";
651
+ readonly "keys.meta": "Meta";
652
+ readonly "keys.apple.control": "\u2303";
653
+ readonly "keys.apple.alt": "\u2325";
654
+ readonly "keys.apple.shift": "\u21E7";
655
+ readonly "keys.apple.meta": "\u2318";
656
+ readonly "keys.space": "Space";
657
+ readonly "keys.enter": "Enter";
658
+ readonly "keys.escape": "Esc";
659
+ readonly "keys.tab": "Tab";
660
+ readonly "keys.delete": "Delete";
661
+ readonly "keys.backspace": "Backspace";
662
+ readonly "keys.arrowUp": "\u2191";
663
+ readonly "keys.arrowDown": "\u2193";
664
+ readonly "keys.arrowLeft": "\u2190";
665
+ readonly "keys.arrowRight": "\u2192";
666
+ readonly "keys.home": "Home";
667
+ readonly "keys.end": "End";
668
+ readonly "keys.pageUp": "Page Up";
669
+ readonly "keys.pageDown": "Page Down";
670
+ };
671
+
672
+ /**
673
+ * The port for reading images: probe a file's headers, decode it into a
674
+ * source the engine holds, make thumbnails and release sources (ADR 0001,
675
+ * ADR 0002, ADR 0003, ADR 0008). The SDK's own adapter probes with its own
676
+ * readers and decodes with `createImageBitmap`, both in its render worker;
677
+ * hosts can pass their own to the editor's `engine` prop, and every
678
+ * implementation must pass the engine's contract tests.
679
+ *
680
+ * `register` checks a file's own limits, from `filePolicy`, against the
681
+ * engine's own probe before decoding it, so a host can't decode past them by
682
+ * passing a probe of another file. Session-wide limits, such as
683
+ * `maxSessionSize`, are the session's (ADR 0004).
684
+ *
685
+ * Failures reject with `ImageError`: `INVALID_IMAGE` for a malformed file,
686
+ * one whose headers claim more than its data holds, or one whose decoded
687
+ * size differs from the probe's; `UNSUPPORTED_FORMAT` for one the probe
688
+ * can't bound; `DECODE_FAILED` when the browser can't decode it; and
689
+ * sdk-core's codes for cancellation and worker failures.
690
+ *
691
+ * @public
692
+ */
693
+ declare interface ImageEngine {
694
+ /** Reads a file's headers and metadata, without decoding it. */
695
+ probe(file: Blob, options?: ImageCallOptions): Promise<ImageProbe>;
696
+ /**
697
+ * Decodes a probed file into a source with the given id, upright. The
698
+ * decoded size must equal the probe's oriented size, or the call rejects
699
+ * with `INVALID_IMAGE` and keeps nothing. A file over one of
700
+ * `filePolicy`'s per-file limits rejects with that limit's code, before
701
+ * anything decodes it. An id already in use is a
702
+ * `TypeError`.
703
+ */
704
+ register(id: string, file: Blob, probe: ImageProbe, options?: ImageRegisterOptions): Promise<ImageSourceInfo>;
705
+ /**
706
+ * A rendering of a source that fits inside `maxSize` × `maxSize`, keeping
707
+ * its aspect ratio and never enlarging it. An unknown id is a `TypeError`.
708
+ */
709
+ thumbnail(id: string, maxSize: number, options?: ImageCallOptions): Promise<ImageThumbnail>;
710
+ /** Frees a source's pixels. Releasing an unknown id does nothing. */
711
+ release(id: string): Promise<void>;
712
+ /** Releases the engine, its sources and its worker. Pending calls reject, and later calls throw. */
713
+ destroy(): Promise<void>;
714
+ }
715
+
716
+ /**
717
+ * The error `@hussmartinez/image-sdk` throws and rejects with, with a stable
718
+ * `code`, structured `details` and the underlying error as `cause`. Show
719
+ * users the text for its code from {@link imageMessages}, never its
720
+ * `message`, which is for developers and may contain text from the file.
721
+ *
722
+ * @example
723
+ * ```ts
724
+ * try {
725
+ * await session.open(file);
726
+ * } catch (error) {
727
+ * if (isImageError(error, "DECODE_FAILED")) {
728
+ * suggestConvertingToPng();
729
+ * } else {
730
+ * show(messages.error(error));
731
+ * }
732
+ * }
733
+ * ```
734
+ *
735
+ * @public
736
+ */
737
+ declare class ImageError extends SdkError<ImageErrorCode> {
738
+ /** Always `"ImageError"`, which survives minification and worker boundaries. */
739
+ readonly name = "ImageError";
740
+ }
741
+
742
+ /**
743
+ * Error codes of `@hussmartinez/image-sdk`: sdk-core's own codes, such as
744
+ * `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the image SDK's
745
+ * (ADR 0001, ADR 0004). They never change meaning once released.
746
+ *
747
+ * - `INVALID_IMAGE`: the file is malformed, its headers claim more than its
748
+ * data can carry or less than its decoder would produce, or its decoded
749
+ * size differs from what its headers declare.
750
+ * - `UNSUPPORTED_FORMAT`: the format isn't recognised, its bound can't be
751
+ * read, or the browser can't encode the requested export format.
752
+ * `details.format` names it.
753
+ * - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
754
+ * usually because it lacks the format. `details.format` names it.
755
+ * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as a
756
+ * crop outside its source. `details.reason` says why, as a stable token
757
+ * (`ImageCommandRejection`).
758
+ * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
759
+ * valid in its format. `details.reason` says why (`ImageDocumentRejection`).
760
+ * A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
761
+ * instead, with `details.reason` `unknown-format` or `unknown-format-version`.
762
+ * - `UNSUPPORTED_PLAN`: a plan holds something the renderer or processor
763
+ * can't draw, such as a layer kind from a later release. Nothing is drawn
764
+ * or exported without it (ADR 0009). `details.reason` names the part:
765
+ * `layers`, `redactions` or `animation`.
766
+ * - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
767
+ * the `maxImagePixels` limit.
768
+ * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
769
+ * `maxImageDimension` limit.
770
+ * - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
771
+ * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
772
+ * `maxSessionSize` limit.
773
+ * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
774
+ * - `TOO_MANY_POINTS`: the plan's drawings hold more points than the
775
+ * `maxDrawingPoints` limit.
776
+ *
777
+ * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
778
+ * value and the `unit`. Other codes' `details` name the format involved,
779
+ * and a `reason`, never data from the file.
780
+ *
781
+ * @public
782
+ */
783
+ 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";
784
+
785
+ /**
786
+ * The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
787
+ * the lossy formats; it defaults to 0.92. WebP is encoded only where the
788
+ * browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`.
789
+ *
790
+ * @public
791
+ */
792
+ declare type ImageExportFormat = {
793
+ readonly type: "png";
794
+ } | {
795
+ readonly type: "jpeg";
796
+ readonly quality?: number;
797
+ } | {
798
+ readonly type: "webp";
799
+ readonly quality?: number;
800
+ };
801
+
802
+ /**
803
+ * One export: a plan over sources registered with the same engine, and the
804
+ * output format. The plan's kept metadata goes into the file, and nothing
805
+ * else does (ADR 0005).
806
+ *
807
+ * @public
808
+ */
809
+ declare interface ImageExportJob {
810
+ readonly plan: ImagePlan;
811
+ readonly format: ImageExportFormat;
812
+ }
813
+
814
+ /**
815
+ * Options for exporting.
816
+ *
817
+ * @public
818
+ */
819
+ declare interface ImageExportOptions extends ImageProgressOptions {
820
+ /**
821
+ * The limits the output canvas is checked against before it's allocated:
822
+ * `maxImageDimension` and `maxImagePixels` (ADR 0004). The defaults of
823
+ * `imageLimits` when omitted.
824
+ */
825
+ readonly filePolicy?: ImageFilePolicy;
826
+ }
827
+
828
+ /**
829
+ * What the export dialog reports about a finished export, for the element's
830
+ * `export` event: no pixels and no file, which an event must never carry
831
+ * (sdk-core ADR 0012). The element's `export()` method returns the file.
832
+ *
833
+ * @public
834
+ */
835
+ export declare interface ImageExportReport {
836
+ readonly format: ImageExportFormat["type"];
837
+ readonly width: number;
838
+ readonly height: number;
839
+ /** The file's size in bytes. */
840
+ readonly size: number;
841
+ readonly removed: readonly (keyof ImageMetadataPresence)[];
842
+ readonly kept: readonly (keyof ImageKeepableMetadata)[];
843
+ }
844
+
845
+ /**
846
+ * A resolved file policy for the image SDK. Violations throw
847
+ * {@link ImageError}.
848
+ *
849
+ * @public
850
+ */
851
+ declare type ImageFilePolicy = FilePolicy<ImageLimitDefinitions>;
852
+
853
+ /**
854
+ * A host's `filePolicy`: a new maximum, or `{ maximum, warning }`, for any of
855
+ * the image SDK's limits. `Infinity` disables a maximum, which removes a
856
+ * protection against hostile files, or disables a warning. Unknown limit
857
+ * names throw `TypeError` when the policy is resolved.
858
+ *
859
+ * @example
860
+ * ```ts
861
+ * // Large scans: raise the pixel and decoded sizes together.
862
+ * const filePolicy: ImageFilePolicyOverrides = {
863
+ * maxImagePixels: 100_000_000,
864
+ * maxDecodedSize: { maximum: 2e9, warning: 800e6 },
865
+ * };
866
+ * ```
867
+ *
868
+ * @public
869
+ */
870
+ declare type ImageFilePolicyOverrides = FilePolicyOverrides<ImageLimitDefinitions>;
871
+
872
+ /**
873
+ * A filter preset and its strength, an integer from 0 (no effect) to 100.
874
+ *
875
+ * @public
876
+ */
877
+ declare interface ImageFilter {
878
+ readonly preset: ImageFilterPreset;
879
+ readonly strength: number;
880
+ }
881
+
882
+ /**
883
+ * A filter preset's name.
884
+ *
885
+ * @public
886
+ */
887
+ declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
888
+
889
+ /**
890
+ * The formats the probe recognises, by their signature bytes (ADR 0001).
891
+ *
892
+ * @public
893
+ */
894
+ declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
895
+
896
+ /**
897
+ * Another image, drawn to fill its box (ADR 0009).
898
+ *
899
+ * @public
900
+ */
901
+ declare interface ImageImageLayer extends ImageLayerCommon, ImageLayerBox {
902
+ readonly kind: "image";
903
+ /** The id of a registered source. */
904
+ readonly source: string;
905
+ /** The part of that source to draw, in its own pixels, or `null` for all of it. */
906
+ readonly crop: ImageCrop | null;
907
+ }
908
+
909
+ /**
910
+ * Options for {@link ImageSession.insertImage}.
911
+ *
912
+ * @public
913
+ */
914
+ declare interface ImageInsertOptions {
915
+ readonly signal?: AbortSignal;
916
+ /**
917
+ * The commands that add the image to the plan, instead of the default
918
+ * layer: given the new source and the plan as it is.
919
+ */
920
+ readonly place?: (source: ImageSessionSource, plan: ImagePlan) => ImageCommand | readonly ImageCommand[];
921
+ }
922
+
923
+ /**
924
+ * The commands that exist only to undo others. The reducer applies them, and
925
+ * they're plain data like every command, but the `hm-image-command` format
926
+ * doesn't include them: an inverse's shape may change between releases
927
+ * (sdk-core ADR 0045).
928
+ *
929
+ * @public
930
+ */
931
+ declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
932
+
933
+ /**
934
+ * The metadata fields a user may keep on export (ADR 0005). Empty strings
935
+ * mean the field isn't written.
936
+ *
937
+ * @public
938
+ */
939
+ declare interface ImageKeepableMetadata {
940
+ readonly title: string;
941
+ readonly description: string;
942
+ readonly artist: string;
943
+ readonly copyright: string;
944
+ }
945
+
946
+ /**
947
+ * A layer over the base: text, a shape, another image, a drawing or an
948
+ * arrow (ADR 0009). Layers are drawn bottom to top, in the plan's order, and
949
+ * redactions over all of them.
950
+ *
951
+ * @public
952
+ */
953
+ declare type ImageLayer = ImageBoxedLayer | ImageDrawingLayer | ImageArrowLayer;
954
+
955
+ /**
956
+ * Where a positioned layer is: a box in whole pixels of the scene, the
957
+ * base's oriented source, mirrored or not, then turned about its centre
958
+ * (ADR 0009). The box stays
959
+ * on the pixels it covers when the image is cropped or turned.
960
+ *
961
+ * @public
962
+ */
963
+ declare interface ImageLayerBox {
964
+ /** The box's left edge, before its rotation. May be negative. */
965
+ readonly x: number;
966
+ /** The box's top edge, before its rotation. May be negative. */
967
+ readonly y: number;
968
+ /** At least 1. */
969
+ readonly width: number;
970
+ /** At least 1. */
971
+ readonly height: number;
972
+ /** Tenths of a degree, clockwise about the box's centre: 0 to 3599. */
973
+ readonly rotation: number;
974
+ /**
975
+ * Whether the layer is mirrored left to right, about the box's own
976
+ * vertical axis, before it's turned. With a half turn, that's a mirror top
977
+ * to bottom, so one flip is all a box needs.
978
+ */
979
+ readonly flipX: boolean;
980
+ }
981
+
982
+ /**
983
+ * What every layer has (ADR 0009).
984
+ *
985
+ * @public
986
+ */
987
+ declare interface ImageLayerCommon {
988
+ /**
989
+ * Its identity: 1 to `MAX_KEY_LENGTH` code points, unique among the plan's
990
+ * layers and redactions.
991
+ */
992
+ readonly key: string;
993
+ /**
994
+ * What the layers list calls it: up to `MAX_LAYER_NAME_LENGTH` code
995
+ * points. Empty means the editor's own label for the kind.
996
+ */
997
+ readonly name: string;
998
+ /** Whether it's drawn. */
999
+ readonly visible: boolean;
1000
+ /** A whole number from 0, transparent, to 100, opaque. */
1001
+ readonly opacity: number;
1002
+ }
1003
+
1004
+ /**
1005
+ * The type of {@link imageLimitDefinitions}.
1006
+ *
1007
+ * @public
1008
+ */
1009
+ declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1010
+
1011
+ /**
1012
+ * The image SDK's limit definitions: sdk-core's core limits with image
1013
+ * defaults, plus five for images (ADR 0004).
1014
+ *
1015
+ * | Limit | Code | Default maximum | Default warning |
1016
+ * |---|---|---|---|
1017
+ * | `maxFileSize` | `FILE_TOO_LARGE` | 100 MB | 50 MB |
1018
+ * | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
1019
+ * | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
1020
+ * | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
1021
+ * | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
1022
+ * | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
1023
+ * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
1024
+ * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
1025
+ * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
1026
+ * | `maxDrawingPoints` | `TOO_MANY_POINTS` | 200,000 | 100,000 |
1027
+ *
1028
+ * Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
1029
+ * per pixel. `maxImagePixels` is the same limit, with the same name, code
1030
+ * and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
1031
+ *
1032
+ * @public
1033
+ */
1034
+ declare const imageLimitDefinitions: {
1035
+ readonly maxDecodedSize: {
1036
+ readonly default: 1000000000;
1037
+ readonly warning: 400000000;
1038
+ readonly code: "DECODED_SIZE_TOO_LARGE";
1039
+ readonly unit: "bytes";
1040
+ };
1041
+ readonly maxImagePixels: {
1042
+ readonly code: "IMAGE_TOO_LARGE";
1043
+ readonly unit: "pixels";
1044
+ readonly default: 50000000;
1045
+ readonly warning: 24000000;
1046
+ };
1047
+ readonly maxImageDimension: {
1048
+ readonly code: "IMAGE_DIMENSION_TOO_LARGE";
1049
+ readonly unit: "pixels";
1050
+ readonly default: 16384;
1051
+ };
1052
+ readonly maxFrames: {
1053
+ readonly code: "TOO_MANY_FRAMES";
1054
+ readonly unit: "count";
1055
+ readonly default: 300;
1056
+ readonly warning: 100;
1057
+ };
1058
+ readonly maxSessionSize: {
1059
+ readonly code: "SESSION_TOO_LARGE";
1060
+ readonly unit: "bytes";
1061
+ readonly default: 1000000000;
1062
+ readonly warning: 500000000;
1063
+ };
1064
+ readonly maxLayers: {
1065
+ readonly code: "TOO_MANY_LAYERS";
1066
+ readonly unit: "count";
1067
+ readonly default: 256;
1068
+ };
1069
+ readonly maxDrawingPoints: {
1070
+ readonly code: "TOO_MANY_POINTS";
1071
+ readonly unit: "count";
1072
+ readonly default: 200000;
1073
+ readonly warning: 100000;
1074
+ };
1075
+ readonly maxFileSize: {
1076
+ readonly code: "FILE_TOO_LARGE";
1077
+ readonly unit: "bytes";
1078
+ readonly default: 100000000;
1079
+ readonly warning: 50000000;
1080
+ };
1081
+ readonly maxFiles: {
1082
+ readonly code: "TOO_MANY_FILES";
1083
+ readonly unit: "count";
1084
+ readonly default: 20;
1085
+ };
1086
+ readonly maxProcessingTime: {
1087
+ readonly code: "PROCESSING_TIME_EXCEEDED";
1088
+ readonly unit: "milliseconds";
1089
+ readonly default: 120000;
1090
+ };
779
1091
  };
780
1092
 
1093
+ /**
1094
+ * The names of the image SDK's limits.
1095
+ *
1096
+ * @public
1097
+ */
1098
+ declare type ImageLimitName = keyof ImageLimitDefinitions;
1099
+
781
1100
  /**
782
1101
  * Which kinds of metadata a file carries, as presence flags, never values,
783
1102
  * so the editor can say what an export removes (ADR 0005).
@@ -826,12 +1145,19 @@ declare type ImageOutput = {
826
1145
 
827
1146
  /**
828
1147
  * The session's document: a description of the edits over an immutable
829
- * source, rendered to pixels only for display and export (ADR 0003).
1148
+ * source, rendered to pixels only for display and export (ADR 0003, ADR
1149
+ * 0009).
830
1150
  *
831
1151
  * @public
832
1152
  */
833
1153
  declare interface ImagePlan {
834
1154
  readonly base: ImageBase;
1155
+ /** The layers over the base, bottom to top, placed in the scene (ADR 0009). */
1156
+ readonly layers: readonly ImageLayer[];
1157
+ /** The redactions, applied over every layer (ADR 0010). */
1158
+ readonly redactions: readonly ImageRedaction[];
1159
+ /** The animation (ADR 0011). Always `null` until format version 4. */
1160
+ readonly animation: null;
835
1161
  readonly output: ImageOutput;
836
1162
  /** The fields the user chose to keep on export. Never a location (ADR 0005). */
837
1163
  readonly metadata: ImageKeepableMetadata;
@@ -907,6 +1233,62 @@ declare interface ImageProgressOptions extends ImageCallOptions {
907
1233
  readonly onProgress?: (fraction: number) => void;
908
1234
  }
909
1235
 
1236
+ /**
1237
+ * A region of the image that an export doesn't show (ADR 0010): a rectangle
1238
+ * in whole pixels of the scene, the base's oriented source, so it stays on
1239
+ * the pixels it covers when the image is cropped or turned (ADR 0009).
1240
+ *
1241
+ * A redaction has no opacity, visibility or rotation, and is drawn over
1242
+ * every layer. Only exports are redacted: the plan describes the redaction,
1243
+ * and the source is unchanged.
1244
+ *
1245
+ * @public
1246
+ */
1247
+ declare type ImageRedaction = (ImageRedactionRegion & {
1248
+ readonly mode: "solid";
1249
+ /** The fill, as `#rrggbb` in lower case. */
1250
+ readonly colour: string;
1251
+ }) | (ImageRedactionRegion & {
1252
+ readonly mode: "pixelate";
1253
+ });
1254
+
1255
+ /**
1256
+ * The fields of a redaction that `image.updateRedactions` may set: any but
1257
+ * its key. Setting `mode` to `pixelate` drops the colour, and setting it to
1258
+ * `solid` needs one in the same update.
1259
+ *
1260
+ * @public
1261
+ */
1262
+ declare interface ImageRedactionProps {
1263
+ readonly mode?: ImageRedaction["mode"];
1264
+ readonly x?: number;
1265
+ readonly y?: number;
1266
+ readonly width?: number;
1267
+ readonly height?: number;
1268
+ readonly colour?: string;
1269
+ }
1270
+
1271
+ /**
1272
+ * What every redaction has, whatever its mode: its identity and its region.
1273
+ *
1274
+ * @public
1275
+ */
1276
+ declare interface ImageRedactionRegion {
1277
+ /**
1278
+ * Its identity: 1 to {@link MAX_KEY_LENGTH} code points, unique among the
1279
+ * plan's layers and redactions.
1280
+ */
1281
+ readonly key: string;
1282
+ /** The region's left edge, in whole pixels of the scene. May be negative. */
1283
+ readonly x: number;
1284
+ /** The region's top edge, in whole pixels of the scene. May be negative. */
1285
+ readonly y: number;
1286
+ /** At least 1. */
1287
+ readonly width: number;
1288
+ /** At least 1. */
1289
+ readonly height: number;
1290
+ }
1291
+
910
1292
  /**
911
1293
  * Options for registering a source.
912
1294
  *
@@ -931,6 +1313,16 @@ declare interface ImageRegisterOptions extends ImageProgressOptions {
931
1313
  */
932
1314
  declare type ImageRotation = 0 | 90 | 180 | 270;
933
1315
 
1316
+ /**
1317
+ * A point of the scene, in whole pixels.
1318
+ *
1319
+ * @public
1320
+ */
1321
+ declare interface ImageScenePoint {
1322
+ readonly x: number;
1323
+ readonly y: number;
1324
+ }
1325
+
934
1326
  /**
935
1327
  * An image editing session (ADR 0003, ADR 0008): one document, its plan
936
1328
  * over the source it opened, edited by commands with undo and redo, and
@@ -954,6 +1346,29 @@ declare interface ImageSession {
954
1346
  open(file: Blob, options?: {
955
1347
  readonly signal?: AbortSignal;
956
1348
  }): Promise<ImageSessionSource>;
1349
+ /**
1350
+ * Probes, checks and decodes another file, and adds it to the document as
1351
+ * an image layer, as one undoable step (ADR 0003, ADR 0004).
1352
+ *
1353
+ * - **Limits:** the file's own, as for `open`; `maxFiles`, counting every
1354
+ * source the session holds; and `maxSessionSize`, counting their decoded
1355
+ * bytes. When the image doesn't fit, the session first drops the oldest
1356
+ * undo steps that alone keep another image, and marks the history as
1357
+ * trimmed. If that isn't enough, nothing is dropped and it fails with
1358
+ * `SESSION_TOO_LARGE`.
1359
+ * - **Placement:** by default the image is centred on what's shown, at
1360
+ * its own size or half the composition's, whichever is smaller, over
1361
+ * every layer, and turned and mirrored back against the plan's
1362
+ * rotation and flips, so it's seen as the file is. `place` returns other commands; they must refer to the
1363
+ * source, or it's released.
1364
+ * - **Lifetime:** the session holds the source while the plan, an undo
1365
+ * or redo step, or an export in progress refers to it, and releases it
1366
+ * then.
1367
+ *
1368
+ * A failure, a cancellation, or another file opened meanwhile adds
1369
+ * nothing and releases the source.
1370
+ */
1371
+ insertImage(file: Blob, options?: ImageInsertOptions): Promise<ImageSessionSource>;
957
1372
  /**
958
1373
  * Applies commands as one undoable step. They're checked by the reducer,
959
1374
  * then the output against `maxImageDimension` and `maxImagePixels`; a
@@ -964,7 +1379,9 @@ declare interface ImageSession {
964
1379
  * Makes the document's plan equal to `plan`, as one undoable step of the
965
1380
  * commands that reach it, checked as `execute` checks them (ADR 0003). A
966
1381
  * plan equal to the current one changes nothing. A plan over another
967
- * source is `INVALID_COMMAND`. For editors whose host holds the plan.
1382
+ * source is `INVALID_COMMAND`, and so is one without `layers`,
1383
+ * `redactions` and `animation`, such as a plan stored before format
1384
+ * version 2. For editors whose host holds the plan.
968
1385
  */
969
1386
  applyPlan(plan: ImagePlan): void;
970
1387
  /**
@@ -988,7 +1405,7 @@ declare interface ImageSession {
988
1405
  readonly signal?: AbortSignal;
989
1406
  readonly onProgress?: (fraction: number) => void;
990
1407
  }): Promise<ImageSessionExport>;
991
- /** Releases the source the session holds. Later calls throw. */
1408
+ /** Releases every source the session holds. Later calls throw. */
992
1409
  destroy(): Promise<void>;
993
1410
  }
994
1411
 
@@ -1025,8 +1442,20 @@ declare interface ImageSessionSnapshot {
1025
1442
  readonly plan: ImagePlan | null;
1026
1443
  /** The document's source, or `null` before a file is open. */
1027
1444
  readonly source: ImageSessionSource | null;
1445
+ /**
1446
+ * Every source the session holds: the document's, then those of image
1447
+ * layers, including ones only the history still refers to (ADR 0004).
1448
+ */
1449
+ readonly sources: readonly ImageSessionSource[];
1028
1450
  readonly canUndo: boolean;
1029
1451
  readonly canRedo: boolean;
1452
+ /**
1453
+ * Whether undo steps were dropped to make room for an image, since the
1454
+ * document was opened: they can no longer be undone.
1455
+ */
1456
+ readonly historyTrimmed: boolean;
1457
+ /** Whether an image is being added as a layer. */
1458
+ readonly inserting: boolean;
1030
1459
  /** Whether a file is being opened. The current document stays until it's ready. */
1031
1460
  readonly opening: boolean;
1032
1461
  /** Whether an export is in progress. */
@@ -1053,6 +1482,25 @@ declare interface ImageSessionSource extends ImageSourceInfo {
1053
1482
  readonly keepable: ImageKeepableMetadata;
1054
1483
  }
1055
1484
 
1485
+ /**
1486
+ * A rectangle or an ellipse that fills its box, with a fill, a stroke drawn
1487
+ * inside the box, or both (ADR 0009).
1488
+ *
1489
+ * @public
1490
+ */
1491
+ declare interface ImageShapeLayer extends ImageLayerCommon, ImageLayerBox {
1492
+ readonly kind: "shape";
1493
+ readonly shape: (typeof LAYER_SHAPES)[number];
1494
+ /** The fill, as `#rrggbb` in lower case, or `null` for none. */
1495
+ readonly fill: string | null;
1496
+ /** The stroke, or `null` for none. A shape has a fill or a stroke. */
1497
+ readonly stroke: {
1498
+ readonly colour: string;
1499
+ /** In whole scene pixels, from 1 to `MAX_STROKE_WIDTH`. */
1500
+ readonly width: number;
1501
+ } | null;
1502
+ }
1503
+
1056
1504
  /**
1057
1505
  * A width and a height, in whole pixels.
1058
1506
  *
@@ -1080,6 +1528,46 @@ declare interface ImageSourceInfo {
1080
1528
  readonly decodedBytes: number;
1081
1529
  }
1082
1530
 
1531
+ /**
1532
+ * One stroke of a drawing: what one gesture drew, from the press to the
1533
+ * release (docs/adr/0014). It has more than one run only when it's long.
1534
+ *
1535
+ * @public
1536
+ */
1537
+ declare interface ImageStroke {
1538
+ /** `#rrggbb`. */
1539
+ readonly colour: string;
1540
+ /** In whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
1541
+ readonly width: number;
1542
+ /**
1543
+ * 1 to `MAX_STROKE_RUNS` runs, each a polyline `[x0, y0, x1, y1, …]` of 1
1544
+ * to `MAX_RUN_POINTS` points, in whole pixels from the drawing's origin.
1545
+ * A run of one point is a dot.
1546
+ */
1547
+ readonly runs: readonly (readonly number[])[];
1548
+ }
1549
+
1550
+ /**
1551
+ * Text, drawn as large as fits inside its box, never distorted (ADR 0009).
1552
+ * Lines break only at line feeds. Emoji are text.
1553
+ *
1554
+ * @public
1555
+ */
1556
+ declare interface ImageTextLayer extends ImageLayerCommon, ImageLayerBox {
1557
+ readonly kind: "text";
1558
+ /**
1559
+ * Up to `MAX_LAYER_TEXT_LENGTH` code points. Control characters other
1560
+ * than a line feed, and the bidirectional embedding, override and isolate
1561
+ * controls, are refused.
1562
+ */
1563
+ readonly text: string;
1564
+ readonly font: (typeof LAYER_FONTS)[number];
1565
+ readonly bold: boolean;
1566
+ /** The text's colour, as `#rrggbb` in lower case. */
1567
+ readonly colour: string;
1568
+ readonly align: (typeof LAYER_ALIGNMENTS)[number];
1569
+ }
1570
+
1083
1571
  /**
1084
1572
  * A small rendering of a source for lists and frame strips. An `ImageBitmap`
1085
1573
  * is one; tests can supply their own. Close it when it's no longer shown.
@@ -1092,6 +1580,157 @@ declare interface ImageThumbnail {
1092
1580
  close(): void;
1093
1581
  }
1094
1582
 
1583
+ /**
1584
+ * Inserts layers at an index of the plan's layers, which are drawn bottom
1585
+ * to top (ADR 0009). Each needs a key no layer or redaction of the plan has.
1586
+ *
1587
+ * @public
1588
+ */
1589
+ declare interface InsertLayersCommand {
1590
+ readonly type: "image.insertLayers";
1591
+ /** From 0, under every layer, to the number of layers, over them all. */
1592
+ readonly at: number;
1593
+ readonly layers: readonly ImageLayer[];
1594
+ }
1595
+
1596
+ /**
1597
+ * Inserts redactions at an index of the plan's redactions (ADR 0010). Each
1598
+ * needs a key no layer or redaction of the plan has.
1599
+ *
1600
+ * @public
1601
+ */
1602
+ declare interface InsertRedactionsCommand {
1603
+ readonly type: "image.insertRedactions";
1604
+ /** From 0 to the number of redactions. */
1605
+ readonly at: number;
1606
+ readonly redactions: readonly ImageRedaction[];
1607
+ }
1608
+
1609
+ /**
1610
+ * How a text layer's lines sit in its box, by the text's own direction.
1611
+ *
1612
+ * @public
1613
+ */
1614
+ declare const LAYER_ALIGNMENTS: readonly ["start", "center", "end"];
1615
+
1616
+ /**
1617
+ * The fonts a text layer can use: the generic families, which every device
1618
+ * has, so the SDK ships and fetches none (ADR 0009). Names are part of the
1619
+ * document format.
1620
+ *
1621
+ * @public
1622
+ */
1623
+ declare const LAYER_FONTS: readonly ["sans-serif", "serif", "monospace"];
1624
+
1625
+ /**
1626
+ * The shapes a shape layer can be.
1627
+ *
1628
+ * @public
1629
+ */
1630
+ declare const LAYER_SHAPES: readonly ["rectangle", "ellipse"];
1631
+
1632
+ /**
1633
+ * Moves layers to an index of the list without them, keeping the order they
1634
+ * had: up or down the stack.
1635
+ *
1636
+ * @public
1637
+ */
1638
+ declare interface MoveLayersCommand {
1639
+ readonly type: "image.moveLayers";
1640
+ readonly keys: readonly string[];
1641
+ readonly to: number;
1642
+ }
1643
+
1644
+ /**
1645
+ * Moves redactions to an index of the list without them, keeping the order
1646
+ * they had. The order only decides how overlapping redactions look.
1647
+ *
1648
+ * @public
1649
+ */
1650
+ declare interface MoveRedactionsCommand {
1651
+ readonly type: "image.moveRedactions";
1652
+ readonly keys: readonly string[];
1653
+ readonly to: number;
1654
+ }
1655
+
1656
+ /**
1657
+ * Removes layers, by key.
1658
+ *
1659
+ * @public
1660
+ */
1661
+ declare interface RemoveLayersCommand {
1662
+ readonly type: "image.removeLayers";
1663
+ readonly keys: readonly string[];
1664
+ }
1665
+
1666
+ /**
1667
+ * Removes redactions, by key.
1668
+ *
1669
+ * @public
1670
+ */
1671
+ declare interface RemoveRedactionsCommand {
1672
+ readonly type: "image.removeRedactions";
1673
+ readonly keys: readonly string[];
1674
+ }
1675
+
1676
+ /**
1677
+ * Removes strokes from a drawing layer, by index. A drawing keeps at least
1678
+ * one stroke: to remove the last, remove the layer.
1679
+ *
1680
+ * @public
1681
+ */
1682
+ declare interface RemoveStrokesCommand {
1683
+ readonly type: "image.removeStrokes";
1684
+ readonly key: string;
1685
+ readonly indexes: readonly number[];
1686
+ }
1687
+
1688
+ /**
1689
+ * Puts removed layers back, each at its index, by rising index. It's what
1690
+ * undoes {@link RemoveLayersCommand}: the reducer applies it, but it isn't
1691
+ * part of the portable command format (ADR 0009).
1692
+ *
1693
+ * @public
1694
+ */
1695
+ declare interface RestoreLayersCommand {
1696
+ readonly type: "image.restoreLayers";
1697
+ readonly entries: readonly {
1698
+ readonly at: number;
1699
+ readonly layer: ImageLayer;
1700
+ }[];
1701
+ }
1702
+
1703
+ /**
1704
+ * Puts removed redactions back, each at its index, by rising index. It's
1705
+ * what undoes {@link RemoveRedactionsCommand}: the reducer applies it, but
1706
+ * it isn't part of the portable command format (ADR 0009).
1707
+ *
1708
+ * @public
1709
+ */
1710
+ declare interface RestoreRedactionsCommand {
1711
+ readonly type: "image.restoreRedactions";
1712
+ readonly entries: readonly {
1713
+ readonly at: number;
1714
+ readonly redaction: ImageRedaction;
1715
+ }[];
1716
+ }
1717
+
1718
+ /**
1719
+ * Puts removed strokes back, each at its index, by rising index. It's what
1720
+ * undoes {@link RemoveStrokesCommand}: the reducer applies it, but it isn't
1721
+ * part of the portable command format (ADR 0009).
1722
+ *
1723
+ * @public
1724
+ */
1725
+ declare interface RestoreStrokesCommand {
1726
+ readonly type: "image.restoreStrokes";
1727
+ readonly key: string;
1728
+ readonly entries: readonly {
1729
+ readonly at: number;
1730
+ readonly stroke: ImageStroke;
1731
+ }[];
1732
+ }
1733
+
1095
1734
  /**
1096
1735
  * Sets or removes the base's crop, in whole pixels of the oriented source.
1097
1736
  *
@@ -1123,6 +1762,18 @@ declare interface SetFilterCommand {
1123
1762
  readonly filter: ImageFilter | null;
1124
1763
  }
1125
1764
 
1765
+ /**
1766
+ * Sets the whole order of the layers: every key, once. It's what undoes
1767
+ * {@link MoveLayersCommand}: the reducer applies it, but it isn't part of
1768
+ * the portable command format (ADR 0009).
1769
+ *
1770
+ * @public
1771
+ */
1772
+ declare interface SetLayerOrderCommand {
1773
+ readonly type: "image.setLayerOrder";
1774
+ readonly keys: readonly string[];
1775
+ }
1776
+
1126
1777
  /**
1127
1778
  * Sets one metadata field to keep on export. An empty value keeps nothing.
1128
1779
  *
@@ -1154,4 +1805,44 @@ declare interface SetOutputCommand {
1154
1805
  readonly output: ImageOutput;
1155
1806
  }
1156
1807
 
1808
+ /**
1809
+ * Sets the whole order of the redactions: every key, once. It's what undoes
1810
+ * {@link MoveRedactionsCommand}: the reducer applies it, but it isn't part
1811
+ * of the portable command format (ADR 0009).
1812
+ *
1813
+ * @public
1814
+ */
1815
+ declare interface SetRedactionOrderCommand {
1816
+ readonly type: "image.setRedactionOrder";
1817
+ readonly keys: readonly string[];
1818
+ }
1819
+
1820
+ /**
1821
+ * Sets some fields of some layers: their boxes after a move, their opacity,
1822
+ * a text layer's text. `props` may hold any field of the layer's kind except
1823
+ * `key` and `kind`.
1824
+ *
1825
+ * @public
1826
+ */
1827
+ declare interface UpdateLayersCommand {
1828
+ readonly type: "image.updateLayers";
1829
+ readonly updates: readonly {
1830
+ readonly key: string;
1831
+ readonly props: Readonly<Record<string, unknown>>;
1832
+ }[];
1833
+ }
1834
+
1835
+ /**
1836
+ * Sets some fields of some redactions, such as their regions after a move.
1837
+ *
1838
+ * @public
1839
+ */
1840
+ declare interface UpdateRedactionsCommand {
1841
+ readonly type: "image.updateRedactions";
1842
+ readonly updates: readonly {
1843
+ readonly key: string;
1844
+ readonly props: ImageRedactionProps;
1845
+ }[];
1846
+ }
1847
+
1157
1848
  export { }