@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/react.d.ts CHANGED
@@ -25,6 +25,19 @@ import type { Store } from '@hussmartinez/sdk-core';
25
25
  import type { Tool } from '@hussmartinez/sdk-core';
26
26
  import type { ToolRegistry } from '@hussmartinez/sdk-core';
27
27
 
28
+ /**
29
+ * Appends strokes to a drawing layer (ADR 0009, docs/adr/0014): one stroke
30
+ * for each gesture, however many runs it has.
31
+ *
32
+ * @public
33
+ */
34
+ declare interface AddStrokesCommand {
35
+ readonly type: "image.addStrokes";
36
+ /** The drawing's key. */
37
+ readonly key: string;
38
+ readonly strokes: readonly ImageStroke[];
39
+ }
40
+
28
41
  /**
29
42
  * An EXIF orientation, 1 to 8: how the stored pixels must be turned to be
30
43
  * upright. 1 means they already are (ADR 0005).
@@ -61,6 +74,25 @@ export declare interface ImageAdjustPanelProps {
61
74
  readonly className?: string;
62
75
  }
63
76
 
77
+ /**
78
+ * An arrow from one point of the scene to another (ADR 0009,
79
+ * docs/adr/0014). Its head's size follows its width, and its tip is exactly
80
+ * on `to`.
81
+ *
82
+ * @public
83
+ */
84
+ declare interface ImageArrowLayer extends ImageLayerCommon {
85
+ readonly kind: "arrow";
86
+ /** The tail. */
87
+ readonly from: ImageScenePoint;
88
+ /** The tip. It differs from `from`. */
89
+ readonly to: ImageScenePoint;
90
+ /** `#rrggbb`. */
91
+ readonly colour: string;
92
+ /** The shaft's width, in whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
93
+ readonly width: number;
94
+ }
95
+
64
96
  /**
65
97
  * The crop frame's geometry (docs/adr/0007): pure functions over crops in
66
98
  * whole pixels of the oriented source, which the editor's frame, keys and
@@ -91,6 +123,13 @@ declare interface ImageBase {
91
123
  readonly filter: ImageFilter | null;
92
124
  }
93
125
 
126
+ /**
127
+ * A layer that has a box: text, a shape or an image.
128
+ *
129
+ * @public
130
+ */
131
+ declare type ImageBoxedLayer = ImageTextLayer | ImageShapeLayer | ImageImageLayer;
132
+
94
133
  /**
95
134
  * Options every port call accepts.
96
135
  *
@@ -107,11 +146,11 @@ declare interface ImageCallOptions {
107
146
 
108
147
  /**
109
148
  * Every edit to an {@link ImagePlan}: plain, structured-cloneable data
110
- * (ADR 0003). Feature pull requests add their own commands to this union.
149
+ * (ADR 0003, ADR 0009).
111
150
  *
112
151
  * @public
113
152
  */
114
- declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand;
153
+ declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand | InsertLayersCommand | RemoveLayersCommand | MoveLayersCommand | UpdateLayersCommand | AddStrokesCommand | RemoveStrokesCommand | InsertRedactionsCommand | RemoveRedactionsCommand | MoveRedactionsCommand | UpdateRedactionsCommand | ImageInverseCommand;
115
154
 
116
155
  /**
117
156
  * A rectangle in whole pixels of the oriented source: `x` and `y` from its
@@ -166,6 +205,45 @@ declare interface ImageDevelop {
166
205
  readonly vibrance: number;
167
206
  }
168
207
 
208
+ /**
209
+ * Freehand strokes (ADR 0009, docs/adr/0014). A drawing has an origin and
210
+ * no box: moving it changes its origin, never its points. Its strokes are
211
+ * drawn opaque and the drawing composited as one, so strokes that cross
212
+ * don't darken each other.
213
+ *
214
+ * @public
215
+ */
216
+ declare interface ImageDrawingLayer extends ImageLayerCommon {
217
+ readonly kind: "drawing";
218
+ /** Its origin, in whole scene pixels. May be negative. */
219
+ readonly x: number;
220
+ readonly y: number;
221
+ /** 1 to `MAX_DRAWING_STROKES` strokes, in the order they're drawn. */
222
+ readonly strokes: readonly ImageStroke[];
223
+ }
224
+
225
+ /**
226
+ * The draw panel (docs/adr/0015), shown while drawing: the pen or the
227
+ * highlighter, the colour and the width the next stroke takes, and a button
228
+ * that removes the last stroke. It says that drawing needs a pointer, and
229
+ * where the keyboard's way to point at something is.
230
+ *
231
+ * The panel keeps its size, whatever is chosen or drawn, so the stage
232
+ * doesn't move under a stroke.
233
+ *
234
+ * @public
235
+ */
236
+ export declare function ImageDrawPanel(props: ImageDrawPanelProps): ReactNode;
237
+
238
+ /**
239
+ * Props of {@link ImageDrawPanel}.
240
+ *
241
+ * @public
242
+ */
243
+ export declare interface ImageDrawPanelProps {
244
+ readonly className?: string;
245
+ }
246
+
169
247
  /**
170
248
  * The image editor (docs/adr/0007): a toolbar and a stage over an image
171
249
  * session, with the family's shortcuts while focus is inside it. It creates
@@ -214,6 +292,12 @@ export declare interface ImageEditorHandle {
214
292
  readonly session: ImageSession;
215
293
  /** Opens an image, replacing the current one once it has opened. */
216
294
  open(file: Blob): Promise<void>;
295
+ /**
296
+ * Adds an image as a layer in the middle of the image as it's shown, as
297
+ * one undoable step, and shows the layers with it selected. A file that
298
+ * can't be added is reported on the stage, as a failed open is.
299
+ */
300
+ insertImage(file: Blob): Promise<void>;
217
301
  /** Applies commands as one undoable step. */
218
302
  execute(commands: ImageCommand | readonly ImageCommand[]): void;
219
303
  /** Renders and encodes the image as it is now. */
@@ -225,240 +309,699 @@ export declare interface ImageEditorHandle {
225
309
  }
226
310
 
227
311
  /**
228
- * The parts of `ImageEditor` that take extra classes through `classNames`.
229
- *
230
- * @public
231
- */
232
- export declare type ImageEditorPart = "root" | "toolbar" | "stage" | "inspector";
233
-
234
- /**
235
- * Props of {@link ImageEditor}. The session props are the provider's: pass
236
- * a `session` of your own over your `engine`, or let the editor create one.
237
- *
238
- * @public
239
- */
240
- export declare interface ImageEditorProps extends Omit<ImageEditorProviderProps, "children"> {
241
- /** An image to open on mount. Images the user opens in the editor replace it. */
242
- readonly initialFile?: Blob;
243
- /**
244
- * The plan, for a host that holds it: the controlled form. When it changes,
245
- * the editor applies it as one undoable step (`session.applyPlan`). Use it
246
- * with `onChange`, which gets the plans the editor makes.
247
- */
248
- readonly plan?: ImagePlan;
249
- /** Called with the plan after each committed edit, open, undo or redo, never during a gesture. */
250
- readonly onChange?: (plan: ImagePlan) => void;
251
- /** Which tools are present, by id, in order. All of them by default. */
252
- readonly tools?: readonly string[];
253
- /** The toolbar's groups, as tool ids. */
254
- readonly toolbar?: readonly (readonly string[])[];
255
- /** Icon components by name, over ui's. */
256
- readonly icons?: Readonly<Record<string, IconComponent>>;
257
- /** Extra classes on the root. */
258
- readonly className?: string;
259
- /** Extra classes on each part. */
260
- readonly classNames?: Readonly<Partial<Record<ImageEditorPart, string>>>;
261
- /** Drop the visual styles, keeping layout and accessibility. */
262
- readonly unstyled?: boolean;
263
- /** Which capabilities are on: the inspector's panels and export. All of them by default. */
264
- readonly features?: ImageEditorFeatures;
265
- /** The colour mode, set as `data-hm-theme` on the editor's root. Unset, it inherits the page's. */
266
- readonly theme?: ImageEditorTheme;
267
- /**
268
- * Takes the exported file instead of the export dialog's download button;
269
- * the dialog closes once it's called.
270
- */
271
- readonly onExport?: (blob: Blob, details: ImageSessionExport) => void;
272
- }
273
-
274
- /**
275
- * Provides an image session, its engine, the stage's view and the SDK's
276
- * text to the components below it: `ImageStage`, `ImageToolbar` and the
277
- * hooks (docs/adr/0007). `ImageEditor` renders one itself.
278
- *
279
- * @example
280
- * ```tsx
281
- * <ImageEditorProvider locale="de" messages={{ "editor.empty": "Öffnen Sie ein Bild." }}>
282
- * <ImageToolbar />
283
- * <ImageStage />
284
- * </ImageEditorProvider>
285
- * ```
286
- *
287
- * @public
288
- */
289
- export declare function ImageEditorProvider(props: ImageEditorProviderProps): ReactNode;
290
-
291
- /**
292
- * Props of {@link ImageEditorProvider}.
293
- *
294
- * @public
295
- */
296
- export declare interface ImageEditorProviderProps {
297
- /**
298
- * The engine that probes, decodes and holds images, and draws the stage.
299
- * Defaults to the SDK's own, created with `assetsUrl`. A session of your own
300
- * must use this engine.
301
- */
302
- readonly engine?: ImageEngine;
303
- /** The processor for exports. Defaults to the SDK's own, on the engine. */
304
- readonly processor?: ImageProcessor;
305
- /** A session of your own, over `engine`, instead of one the provider creates. */
306
- readonly session?: ImageSession;
307
- /**
308
- * Where the application serves the package's `dist/assets/` directory, for
309
- * the engine the provider creates (docs/adr/0002).
310
- */
311
- readonly assetsUrl?: string | URL;
312
- /** File limits for a session the provider creates (docs/adr/0004). */
313
- readonly filePolicy?: ImageFilePolicyOverrides;
314
- /** Anonymous usage events from a session the provider creates. */
315
- readonly onEvent?: (event: ImageSessionEvent) => void;
316
- /** Text overrides, typed against the English catalogue (ADR 0019). */
317
- readonly messages?: MessageOverrides<ImageMessageCatalogue>;
318
- /** The locale for numbers and plurals. Defaults to `"en"`. */
319
- readonly locale?: string;
320
- /** The components that use the session, such as `ImageStage`. */
321
- readonly children?: ReactNode;
322
- }
323
-
324
- /**
325
- * The editor's own state, outside the session and its history
326
- * (docs/adr/0007): the active tool, a crop in progress, and a gesture's
327
- * transient plan, which the stage renders instead of the session's.
328
- *
329
- * @public
330
- */
331
- export declare interface ImageEditorState {
332
- /** The tool that takes over the stage, such as `crop`, or `null`. */
333
- readonly tool: "crop" | null;
334
- /** The crop being made, in whole pixels of the oriented source, and its aspect. */
335
- readonly crop: {
336
- readonly pending: ImageCrop;
337
- readonly aspect: ImageAspect;
338
- } | null;
339
- /**
340
- * A gesture's plan while it runs: the session's plan with the gesture's
341
- * change, which isn't an edit until the gesture ends.
342
- */
343
- readonly preview: ImagePlan | null;
344
- /** The dialog the editor shows over the stage, such as `export`, or `null`. */
345
- readonly dialog: "export" | null;
346
- }
347
-
348
- /**
349
- * The editor's colour mode: ui's light or dark theme, or the system's. Unset,
350
- * it inherits the page's.
312
+ * The type of {@link imageEditorMessages}, for typing the editor's
313
+ * `messages` overrides with `MessageOverrides<ImageEditorMessageCatalogue>`.
351
314
  *
352
315
  * @public
353
316
  */
354
- export declare type ImageEditorTheme = "light" | "dark" | "system";
317
+ export declare type ImageEditorMessageCatalogue = typeof imageEditorMessages;
355
318
 
356
319
  /**
357
- * The port for reading images: probe a file's headers, decode it into a
358
- * source the engine holds, make thumbnails and release sources (ADR 0001,
359
- * ADR 0002, ADR 0003, ADR 0008). The SDK's own adapter probes with its own
360
- * readers and decodes with `createImageBitmap`, both in its render worker;
361
- * hosts can pass their own to the editor's `engine` prop, and every
362
- * implementation must pass the engine's contract tests.
363
- *
364
- * `register` checks a file's own limits, from `filePolicy`, against the
365
- * engine's own probe before decoding it, so a host can't decode past them by
366
- * passing a probe of another file. Session-wide limits, such as
367
- * `maxSessionSize`, are the session's (ADR 0004).
368
- *
369
- * Failures reject with `ImageError`: `INVALID_IMAGE` for a malformed file,
370
- * one whose headers claim more than its data holds, or one whose decoded
371
- * size differs from the probe's; `UNSUPPORTED_FORMAT` for one the probe
372
- * can't bound; `DECODE_FAILED` when the browser can't decode it; and
373
- * sdk-core's codes for cancellation and worker failures.
320
+ * The English message catalogue of the SDK's components: `imageMessages`,
321
+ * with sdk-core's text, errors and warnings; `@hussmartinez/ui`'s, for the
322
+ * ui components the editor renders (sdk-core ADR 0046); and the text of the
323
+ * editor, its stage, toolbar and tools, its panels and the export dialog.
374
324
  *
375
- * @public
376
- */
377
- declare interface ImageEngine {
378
- /** Reads a file's headers and metadata, without decoding it. */
379
- probe(file: Blob, options?: ImageCallOptions): Promise<ImageProbe>;
380
- /**
381
- * Decodes a probed file into a source with the given id, upright. The
382
- * decoded size must equal the probe's oriented size, or the call rejects
383
- * with `INVALID_IMAGE` and keeps nothing. A file over one of
384
- * `filePolicy`'s per-file limits rejects with that limit's code, before
385
- * anything decodes it. An id already in use is a
386
- * `TypeError`.
387
- */
388
- register(id: string, file: Blob, probe: ImageProbe, options?: ImageRegisterOptions): Promise<ImageSourceInfo>;
389
- /**
390
- * A rendering of a source that fits inside `maxSize` × `maxSize`, keeping
391
- * its aspect ratio and never enlarging it. An unknown id is a `TypeError`.
392
- */
393
- thumbnail(id: string, maxSize: number, options?: ImageCallOptions): Promise<ImageThumbnail>;
394
- /** Frees a source's pixels. Releasing an unknown id does nothing. */
395
- release(id: string): Promise<void>;
396
- /** Releases the engine, its sources and its worker. Pending calls reject, and later calls throw. */
397
- destroy(): Promise<void>;
398
- }
399
-
400
- /**
401
- * The error `@hussmartinez/image-sdk` throws and rejects with, with a stable
402
- * `code`, structured `details` and the underlying error as `cause`. Show
403
- * users the text for its code from {@link imageMessages}, never its
404
- * `message`, which is for developers and may contain text from the file.
325
+ * `ImageEditor`, `ImageEditorProvider` and `<hm-image-editor>` each build
326
+ * one `Messages` object from it, with the host's locale and overrides, and
327
+ * the editor gives the same object to its own components and to ui's.
328
+ * Override any of its keys through their `messages`, typed with
329
+ * `ImageEditorMessageCatalogue`.
405
330
  *
406
- * @example
407
- * ```ts
408
- * try {
409
- * await session.open(file);
410
- * } catch (error) {
411
- * if (isImageError(error, "DECODE_FAILED")) {
412
- * suggestConvertingToPng();
413
- * } else {
414
- * show(messages.error(error));
415
- * }
416
- * }
417
- * ```
331
+ * It's defined in the React entry, so the server-safe `.` entry and its
332
+ * `imageMessages` carry no interface text (docs/adr/0012).
418
333
  *
419
334
  * @public
420
335
  */
421
- declare class ImageError extends SdkError<ImageErrorCode> {
422
- /** Always `"ImageError"`, which survives minification and worker boundaries. */
423
- readonly name = "ImageError";
424
- }
425
-
426
- /**
427
- * Error codes of `@hussmartinez/image-sdk`: sdk-core's own codes, such as
428
- * `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the image SDK's
429
- * (ADR 0001, ADR 0004). They never change meaning once released.
430
- *
431
- * - `INVALID_IMAGE`: the file is malformed, its headers claim more than its
432
- * data can carry or less than its decoder would produce, or its decoded
433
- * size differs from what its headers declare.
434
- * - `UNSUPPORTED_FORMAT`: the format isn't recognised, its bound can't be
435
- * read, or the browser can't encode the requested export format.
436
- * `details.format` names it.
437
- * - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
438
- * usually because it lacks the format. `details.format` names it.
439
- * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as a
440
- * crop outside its source. `details.reason` says why, as a stable token
441
- * (`ImageCommandRejection`).
442
- * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
443
- * valid in its format. `details.reason` says why (`ImageDocumentRejection`).
444
- * A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
445
- * instead, with `details.reason` `unknown-format` or `unknown-format-version`.
446
- * - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
447
- * the `maxImagePixels` limit.
448
- * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
449
- * `maxImageDimension` limit.
450
- * - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
451
- * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
452
- * `maxSessionSize` limit.
453
- * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
454
- *
455
- * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
456
- * value and the `unit`. Other codes' `details` name the format involved,
336
+ export declare const imageEditorMessages: {
337
+ 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
+ readonly "editor.label": "Image editor";
339
+ readonly "editor.preview": "Edited image preview, {width, number} × {height, number}";
340
+ readonly "editor.empty": "Open an image to start editing. It stays on this device.";
341
+ readonly "editor.choose": "Choose an image";
342
+ readonly "editor.dropHint": "or drop it here";
343
+ readonly "editor.opening": "Opening the image…";
344
+ readonly "editor.cancel": "Cancel";
345
+ readonly "editor.opened": "Image opened, {width, number} × {height, number}.";
346
+ readonly "editor.undid": "Undid {action}.";
347
+ readonly "editor.redid": "Redid {action}.";
348
+ readonly "actions.image.setCrop": "crop";
349
+ readonly "actions.image.setOrientation": "rotate or flip";
350
+ readonly "actions.image.setOutput": "size";
351
+ readonly "actions.image.setMetadata": "metadata";
352
+ readonly "actions.image.setDevelop": "adjustment";
353
+ readonly "actions.image.setFilter": "filter";
354
+ readonly "actions.image.insertLayers": "layer";
355
+ readonly "actions.image.removeLayers": "layer";
356
+ readonly "actions.image.restoreLayers": "layer";
357
+ readonly "actions.image.moveLayers": "layer order";
358
+ readonly "actions.image.setLayerOrder": "layer order";
359
+ readonly "actions.image.updateLayers": "layer change";
360
+ readonly "actions.image.addStrokes": "stroke";
361
+ readonly "actions.image.removeStrokes": "stroke";
362
+ readonly "actions.image.restoreStrokes": "stroke";
363
+ readonly "actions.image.insertRedactions": "redaction";
364
+ readonly "actions.image.removeRedactions": "redaction";
365
+ readonly "actions.image.restoreRedactions": "redaction";
366
+ readonly "actions.image.moveRedactions": "redaction order";
367
+ readonly "actions.image.setRedactionOrder": "redaction order";
368
+ readonly "actions.image.updateRedactions": "redaction change";
369
+ readonly "toolbar.label": "Image tools";
370
+ readonly "toolbar.groups.file": "File";
371
+ readonly "toolbar.groups.history": "History";
372
+ readonly "toolbar.groups.orientation": "Rotate";
373
+ readonly "toolbar.groups.zoom": "Zoom";
374
+ readonly "toolbar.groups.other": "More tools";
375
+ readonly "tools.open": "Open image";
376
+ readonly "tools.undo": "Undo";
377
+ readonly "tools.redo": "Redo";
378
+ readonly "tools.rotate-left": "Rotate left";
379
+ readonly "tools.rotate-right": "Rotate right";
380
+ readonly "tools.zoom-in": "Zoom in";
381
+ readonly "tools.zoom-out": "Zoom out";
382
+ readonly "tools.zoom-fit": "Fit to the stage";
383
+ readonly "tools.crop": "Crop";
384
+ readonly "tools.flip-horizontal": "Flip horizontally";
385
+ readonly "tools.flip-vertical": "Flip vertically";
386
+ readonly "toolbar.groups.crop": "Crop";
387
+ readonly "crop.frame": "Crop area";
388
+ 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.";
389
+ readonly "crop.size": "{width, number} × {height, number}, from {x, number}, {y, number}";
390
+ readonly "crop.panel": "Crop";
391
+ readonly "crop.x": "Left";
392
+ readonly "crop.y": "Top";
393
+ readonly "crop.width": "Width";
394
+ readonly "crop.height": "Height";
395
+ readonly "crop.aspect": "Aspect ratio";
396
+ readonly "crop.aspects.free": "Free";
397
+ readonly "crop.aspects.original": "Original";
398
+ readonly "crop.aspects.ratio": "{width}:{height}";
399
+ readonly "crop.apply": "Apply crop";
400
+ readonly "crop.cancel": "Cancel";
401
+ readonly "crop.reset": "Whole image";
402
+ readonly "crop.applied": "Cropped to {width, number} × {height, number}.";
403
+ readonly "tools.redact": "Redact";
404
+ readonly "toolbar.groups.redact": "Redact";
405
+ readonly "redact.panel": "Redact";
406
+ readonly "redact.intro": "Cover parts of the image. Only the exported image is redacted: the original stays in the editor.";
407
+ readonly "redact.add": "Add area";
408
+ readonly "redact.done": "Done";
409
+ readonly "redact.mode": "Cover with";
410
+ readonly "redact.modes.solid": "Solid colour";
411
+ readonly "redact.modes.pixelate": "Pixelation";
412
+ readonly "redact.pixelateHint": "Pixelation may not hide text. For text and numbers, use a solid colour.";
413
+ readonly "redact.colour": "Colour";
414
+ readonly "redact.colours.black": "Black";
415
+ readonly "redact.colours.white": "White";
416
+ readonly "redact.x": "Left";
417
+ readonly "redact.y": "Top";
418
+ readonly "redact.width": "Width";
419
+ readonly "redact.height": "Height";
420
+ readonly "redact.areas": "Redacted areas";
421
+ readonly "redact.none": "No areas yet. Drag across the image, or add one.";
422
+ readonly "redact.area": "Area {index, number}: {mode}, {width, number} × {height, number}";
423
+ readonly "redact.modeNames.solid": "solid colour";
424
+ readonly "redact.modeNames.pixelate": "pixelated";
425
+ readonly "redact.remove": "Remove area {index, number}";
426
+ readonly "redact.frame": "Redacted area {index, number} of {count, number}";
427
+ 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.";
428
+ readonly "redact.added": {
429
+ readonly $plural: "count";
430
+ } & {
431
+ readonly one: "Area added. {count} area is redacted.";
432
+ readonly other: "Area added. {count, number} areas are redacted.";
433
+ };
434
+ readonly "redact.removedLast": "Area removed. Nothing is redacted.";
435
+ readonly "redact.removed": {
436
+ readonly $plural: "count";
437
+ } & {
438
+ readonly one: "Area removed. {count} area is redacted.";
439
+ readonly other: "Area removed. {count, number} areas are redacted.";
440
+ };
441
+ readonly "tools.add-text": "Add text";
442
+ readonly "tools.add-rectangle": "Add a rectangle";
443
+ readonly "tools.add-ellipse": "Add an ellipse";
444
+ readonly "tools.add-arrow": "Add an arrow";
445
+ readonly "tools.add-image": "Add an image";
446
+ readonly "tools.draw": "Draw";
447
+ readonly "toolbar.groups.draw": "Draw";
448
+ readonly "toolbar.groups.add": "Add";
449
+ readonly "editor.inserting": "Adding the image…";
450
+ readonly "layers.text": "Text";
451
+ readonly "layers.font": "Font";
452
+ readonly "layers.fonts.sans-serif": "Sans";
453
+ readonly "layers.fonts.serif": "Serif";
454
+ readonly "layers.fonts.monospace": "Mono";
455
+ readonly "layers.align": "Alignment";
456
+ readonly "layers.alignments.start": "Start";
457
+ readonly "layers.alignments.center": "Centre";
458
+ readonly "layers.alignments.end": "End";
459
+ readonly "layers.bold": "Bold";
460
+ readonly "layers.colour": "Colour";
461
+ readonly "layers.arrow.from.x": "Tail, left";
462
+ readonly "layers.arrow.from.y": "Tail, top";
463
+ readonly "layers.arrow.to.x": "Tip, left";
464
+ readonly "layers.arrow.to.y": "Tip, top";
465
+ readonly "layers.arrow.width": "Width";
466
+ readonly "layers.fill": "Fill";
467
+ readonly "layers.outline": "Outline";
468
+ readonly "layers.fillColour": "Fill colour";
469
+ readonly "layers.outlineColour": "Outline colour";
470
+ readonly "layers.outlineWidth": "Outline width";
471
+ readonly "layers.colours.black": "Black";
472
+ readonly "layers.colours.white": "White";
473
+ readonly "layers.colours.red": "Red";
474
+ readonly "layers.colours.yellow": "Yellow";
475
+ readonly "layers.colours.green": "Green";
476
+ readonly "layers.colours.blue": "Blue";
477
+ readonly "draw.panel": "Draw";
478
+ 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.";
479
+ readonly "draw.mode": "Draw with";
480
+ readonly "draw.modes.pen": "Pen";
481
+ readonly "draw.modes.highlighter": "Highlighter";
482
+ readonly "draw.colour": "Colour";
483
+ readonly "draw.width": "Width";
484
+ readonly "draw.removeLast": "Remove last stroke";
485
+ readonly "draw.removed": "Removed the last stroke.";
486
+ readonly "draw.done": "Done";
487
+ readonly "tools.layers": "Layers";
488
+ readonly "toolbar.groups.layers": "Layers";
489
+ readonly "layers.panel": "Layers";
490
+ readonly "layers.list": "Layers, the top one first";
491
+ readonly "layers.none": "No layers yet. Add text, a shape or an image from the toolbar.";
492
+ readonly "layers.kinds.text": "Text";
493
+ readonly "layers.kinds.rectangle": "Rectangle";
494
+ readonly "layers.kinds.ellipse": "Ellipse";
495
+ readonly "layers.kinds.image": "Image";
496
+ readonly "layers.kinds.drawing": "Drawing";
497
+ readonly "layers.kinds.arrow": "Arrow";
498
+ readonly "layers.visible": "Show {name}";
499
+ readonly "layers.selected": "Selected layer";
500
+ readonly "layers.moveUp": "Move up";
501
+ readonly "layers.moveDown": "Move down";
502
+ readonly "layers.mirror": "Mirror";
503
+ readonly "layers.duplicate": "Duplicate";
504
+ readonly "layers.remove": "Delete";
505
+ readonly "layers.name": "Name";
506
+ readonly "layers.x": "Left";
507
+ readonly "layers.y": "Top";
508
+ readonly "layers.width": "Width";
509
+ readonly "layers.height": "Height";
510
+ readonly "layers.rotation": "Turn, in degrees";
511
+ readonly "layers.opacity": "Opacity, in percent";
512
+ readonly "layers.done": "Done";
513
+ readonly "layers.frame": "Layer {index, number} of {count, number}: {name}";
514
+ 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.";
515
+ readonly "layers.drawingDescription": {
516
+ readonly $plural: "count";
517
+ } & {
518
+ 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.";
519
+ 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.";
520
+ };
521
+ 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.";
522
+ readonly "layers.movedUp": "Moved {name} up. It's layer {index, number} of {count, number}.";
523
+ readonly "layers.movedDown": "Moved {name} down. It's layer {index, number} of {count, number}.";
524
+ readonly "layers.duplicated": "Duplicated {name}.";
525
+ readonly "layers.removed": "Deleted {name}.";
526
+ readonly "inspector.label": "Panels";
527
+ readonly "inspector.adjust": "Adjust";
528
+ readonly "inspector.filters": "Filters";
529
+ readonly "inspector.info": "Info";
530
+ readonly "notices.label": "Notices";
531
+ readonly "notices.dismiss": "Dismiss";
532
+ readonly "notices.colourProfile": "This image has a colour profile. Colours outside sRGB will be clipped in the exported file.";
533
+ readonly "info.panel": "Image info";
534
+ readonly "info.size": "Size";
535
+ readonly "info.sizeValue": "{width, number} × {height, number} pixels";
536
+ readonly "info.format": "Format";
537
+ readonly "info.formats.png": "PNG";
538
+ readonly "info.formats.jpeg": "JPEG";
539
+ readonly "info.formats.webp": "WebP";
540
+ readonly "info.formats.gif": "GIF";
541
+ readonly "info.formats.avif": "AVIF";
542
+ readonly "info.formats.heif": "HEIF";
543
+ readonly "info.formats.bmp": "BMP";
544
+ readonly "info.frames": "Frames";
545
+ readonly "info.fileSize": "File size";
546
+ readonly "info.fileSizeValue": "{size, fileSize}";
547
+ readonly "info.metadata": "Metadata in the file";
548
+ readonly "info.metadataNone": "None";
549
+ readonly "info.kept": "Kept on export";
550
+ readonly "info.keptNone": "Nothing";
551
+ readonly "develop.panel": "Adjust";
552
+ readonly "develop.temperature": "Temperature";
553
+ readonly "develop.tint": "Tint";
554
+ readonly "develop.exposure": "Exposure";
555
+ readonly "develop.highlights": "Highlights";
556
+ readonly "develop.shadows": "Shadows";
557
+ readonly "develop.contrast": "Contrast";
558
+ readonly "develop.saturation": "Saturation";
559
+ readonly "develop.vibrance": "Vibrance";
560
+ readonly "develop.reset": "Reset {name}";
561
+ readonly "develop.resetAll": "Reset all";
562
+ readonly "develop.wasReset": "All adjustments reset.";
563
+ readonly "filters.panel": "Filters";
564
+ readonly "filters.label": "Filter";
565
+ readonly "filters.none": "None";
566
+ readonly "filters.vivid": "Vivid";
567
+ readonly "filters.warm": "Warm";
568
+ readonly "filters.cool": "Cool";
569
+ readonly "filters.fade": "Fade";
570
+ readonly "filters.mono": "Mono";
571
+ readonly "filters.noir": "Noir";
572
+ readonly "filters.sepia": "Sepia";
573
+ readonly "filters.strength": "Strength";
574
+ readonly "toolbar.groups.export": "Export";
575
+ readonly "tools.export": "Export";
576
+ readonly "tools.exportWhileCropping": "Apply or cancel the crop before exporting.";
577
+ readonly "export.title": "Export image";
578
+ readonly "export.description": "The file is made on this device, and nothing is uploaded.";
579
+ readonly "export.format": "Format";
580
+ readonly "export.formats.png": "PNG";
581
+ readonly "export.formats.jpeg": "JPEG";
582
+ readonly "export.formats.webp": "WebP";
583
+ readonly "export.quality": "Quality";
584
+ readonly "export.qualityValue": "{quality, number}%";
585
+ readonly "export.size": "Size";
586
+ readonly "export.sizes.scale": "Scale";
587
+ readonly "export.sizes.fit": "Fit in a box";
588
+ readonly "export.scale": "Scale, in percent";
589
+ readonly "export.fitWidth": "Largest width";
590
+ readonly "export.fitHeight": "Largest height";
591
+ readonly "export.fields": "Details to include";
592
+ readonly "export.fieldsHint": "Only what you fill in is written to the file.";
593
+ readonly "export.field.title": "Title";
594
+ readonly "export.field.description": "Description";
595
+ readonly "export.field.artist": "Artist";
596
+ readonly "export.field.copyright": "Copyright";
597
+ readonly "export.summary": "Summary";
598
+ readonly "export.output": "{width, number} × {height, number} pixels, {format}";
599
+ readonly "export.removed": "Removed from the file";
600
+ readonly "export.removedNone": "The image had no other details to remove.";
601
+ readonly "export.redacted": {
602
+ readonly $plural: "count";
603
+ } & {
604
+ readonly one: "{count} area is redacted.";
605
+ readonly other: "{count, number} areas are redacted.";
606
+ };
607
+ readonly "export.redactedPixelated": "Pixelated areas may not hide text.";
608
+ readonly "export.kind.location": "Location";
609
+ readonly "export.kind.camera": "Camera details";
610
+ readonly "export.kind.timestamps": "Dates and times";
611
+ readonly "export.kind.thumbnail": "Embedded thumbnail";
612
+ readonly "export.kind.colourProfile": "Colour profile: colours outside sRGB are clipped";
613
+ readonly "export.kind.other": "Other metadata";
614
+ readonly "export.kept": "Kept in the file";
615
+ readonly "export.confirm": "Export";
616
+ readonly "export.cancel": "Cancel";
617
+ readonly "export.progress": "Exporting the image";
618
+ readonly "export.stop": "Stop exporting";
619
+ readonly "export.cancelled": "Export stopped.";
620
+ readonly "export.done": "Exported a {format} of {size, fileSize}.";
621
+ readonly "export.ready": "{width, number} × {height, number} pixels, {format}, {size, fileSize}";
622
+ readonly "export.download": "Download";
623
+ readonly "export.close": "Done";
624
+ readonly "colorField.swatches": "swatches";
625
+ readonly "dialog.close": "Close";
626
+ readonly "fileDropZone.choose": "Choose a file";
627
+ readonly "fileDropZone.chooseMultiple": "Choose files";
628
+ readonly "fileDropZone.hint": "or drop it here";
629
+ readonly "fileDropZone.hintMultiple": "or drop them here";
630
+ readonly "progress.label": "Progress";
631
+ readonly "reorderableList.moved": "{label} moved to position {position} of {count}";
632
+ readonly "spinner.label": "Loading";
633
+ readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
634
+ readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
635
+ readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
636
+ readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
637
+ readonly "errors.DECODE_FAILED": "This browser can't open this kind of image. Try another browser, or convert the file to PNG or JPEG.";
638
+ readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
639
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
640
+ readonly "errors.UNSUPPORTED_PLAN": "This image has edits this version can't show. Update the application and try again.";
641
+ readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
642
+ readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
643
+ readonly "errors.TOO_MANY_FRAMES": {
644
+ readonly $plural: "maximum";
645
+ } & {
646
+ readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
647
+ readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
648
+ };
649
+ 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
+ readonly "errors.TOO_MANY_LAYERS": {
651
+ readonly $plural: "maximum";
652
+ } & {
653
+ readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
654
+ readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
655
+ };
656
+ 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.";
657
+ readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
658
+ readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
659
+ readonly "warnings.maxFrames": {
660
+ readonly $plural: "actual";
661
+ } & {
662
+ readonly one: "This animation has {actual} frame.";
663
+ readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
664
+ };
665
+ readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
666
+ readonly "warnings.maxLayers": {
667
+ readonly $plural: "actual";
668
+ } & {
669
+ readonly one: "This image has {actual} layer.";
670
+ readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
671
+ };
672
+ readonly "warnings.maxDrawingPoints": "This image has a lot of drawing, and may be slow to edit and export.";
673
+ readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
674
+ readonly "errors.ABORTED": "The operation was cancelled.";
675
+ readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
676
+ readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
677
+ readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
678
+ readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
679
+ readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
680
+ readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
681
+ readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
682
+ readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
683
+ readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
684
+ readonly "errors.TOO_MANY_FILES": {
685
+ readonly $plural: "maximum";
686
+ } & {
687
+ readonly one: "You can add {maximum} file at a time.";
688
+ readonly other: "You can add up to {maximum} files at a time.";
689
+ };
690
+ readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
691
+ readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
692
+ readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
693
+ readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
694
+ readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
695
+ readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
696
+ readonly "keys.control": "Ctrl";
697
+ readonly "keys.alt": "Alt";
698
+ readonly "keys.shift": "Shift";
699
+ readonly "keys.meta": "Meta";
700
+ readonly "keys.apple.control": "\u2303";
701
+ readonly "keys.apple.alt": "\u2325";
702
+ readonly "keys.apple.shift": "\u21E7";
703
+ readonly "keys.apple.meta": "\u2318";
704
+ readonly "keys.space": "Space";
705
+ readonly "keys.enter": "Enter";
706
+ readonly "keys.escape": "Esc";
707
+ readonly "keys.tab": "Tab";
708
+ readonly "keys.delete": "Delete";
709
+ readonly "keys.backspace": "Backspace";
710
+ readonly "keys.arrowUp": "\u2191";
711
+ readonly "keys.arrowDown": "\u2193";
712
+ readonly "keys.arrowLeft": "\u2190";
713
+ readonly "keys.arrowRight": "\u2192";
714
+ readonly "keys.home": "Home";
715
+ readonly "keys.end": "End";
716
+ readonly "keys.pageUp": "Page Up";
717
+ readonly "keys.pageDown": "Page Down";
718
+ };
719
+
720
+ /**
721
+ * The parts of `ImageEditor` that take extra classes through `classNames`.
722
+ *
723
+ * @public
724
+ */
725
+ export declare type ImageEditorPart = "root" | "toolbar" | "stage" | "inspector";
726
+
727
+ /**
728
+ * Props of {@link ImageEditor}. The session props are the provider's: pass
729
+ * a `session` of your own over your `engine`, or let the editor create one.
730
+ *
731
+ * @public
732
+ */
733
+ export declare interface ImageEditorProps extends Omit<ImageEditorProviderProps, "children"> {
734
+ /** An image to open on mount. Images the user opens in the editor replace it. */
735
+ readonly initialFile?: Blob;
736
+ /**
737
+ * The plan, for a host that holds it: the controlled form. When it changes,
738
+ * the editor applies it as one undoable step (`session.applyPlan`). Use it
739
+ * with `onChange`, which gets the plans the editor makes.
740
+ */
741
+ readonly plan?: ImagePlan;
742
+ /** Called with the plan after each committed edit, open, undo or redo, never during a gesture. */
743
+ readonly onChange?: (plan: ImagePlan) => void;
744
+ /** Which tools are present, by id, in order. All of them by default. */
745
+ readonly tools?: readonly string[];
746
+ /** The toolbar's groups, as tool ids. */
747
+ readonly toolbar?: readonly (readonly string[])[];
748
+ /** Icon components by name, over ui's. */
749
+ readonly icons?: Readonly<Record<string, IconComponent>>;
750
+ /** Extra classes on the root. */
751
+ readonly className?: string;
752
+ /** Extra classes on each part. */
753
+ readonly classNames?: Readonly<Partial<Record<ImageEditorPart, string>>>;
754
+ /** Drop the visual styles, keeping layout and accessibility. */
755
+ readonly unstyled?: boolean;
756
+ /** Which capabilities are on: the inspector's panels and export. All of them by default. */
757
+ readonly features?: ImageEditorFeatures;
758
+ /** The colour mode, set as `data-hm-theme` on the editor's root. Unset, it inherits the page's. */
759
+ readonly theme?: ImageEditorTheme;
760
+ /**
761
+ * Takes the exported file instead of the export dialog's download button;
762
+ * the dialog closes once it's called.
763
+ */
764
+ readonly onExport?: (blob: Blob, details: ImageSessionExport) => void;
765
+ }
766
+
767
+ /**
768
+ * Provides an image session, its engine, the stage's view and the SDK's
769
+ * text to the components below it: `ImageStage`, `ImageToolbar` and the
770
+ * hooks (docs/adr/0007). `ImageEditor` renders one itself.
771
+ *
772
+ * @example
773
+ * ```tsx
774
+ * <ImageEditorProvider locale="de" messages={{ "editor.empty": "Öffnen Sie ein Bild." }}>
775
+ * <ImageToolbar />
776
+ * <ImageStage />
777
+ * </ImageEditorProvider>
778
+ * ```
779
+ *
780
+ * @public
781
+ */
782
+ export declare function ImageEditorProvider(props: ImageEditorProviderProps): ReactNode;
783
+
784
+ /**
785
+ * Props of {@link ImageEditorProvider}.
786
+ *
787
+ * @public
788
+ */
789
+ export declare interface ImageEditorProviderProps {
790
+ /**
791
+ * The engine that probes, decodes and holds images, and draws the stage.
792
+ * Defaults to the SDK's own, created with `assetsUrl`. A session of your own
793
+ * must use this engine.
794
+ */
795
+ readonly engine?: ImageEngine;
796
+ /** The processor for exports. Defaults to the SDK's own, on the engine. */
797
+ readonly processor?: ImageProcessor;
798
+ /** A session of your own, over `engine`, instead of one the provider creates. */
799
+ readonly session?: ImageSession;
800
+ /**
801
+ * Where the application serves the package's `dist/assets/` directory, for
802
+ * the engine the provider creates (docs/adr/0002).
803
+ */
804
+ readonly assetsUrl?: string | URL;
805
+ /** File limits for a session the provider creates (docs/adr/0004). */
806
+ readonly filePolicy?: ImageFilePolicyOverrides;
807
+ /** Anonymous usage events from a session the provider creates. */
808
+ readonly onEvent?: (event: ImageSessionEvent) => void;
809
+ /** Text overrides, typed against the English catalogue (ADR 0019). */
810
+ readonly messages?: MessageOverrides<ImageEditorMessageCatalogue>;
811
+ /** The locale for numbers and plurals. Defaults to `"en"`. */
812
+ readonly locale?: string;
813
+ /** The components that use the session, such as `ImageStage`. */
814
+ readonly children?: ReactNode;
815
+ }
816
+
817
+ /**
818
+ * The editor's own state, outside the session and its history
819
+ * (docs/adr/0007): the active tool, a crop in progress, the redaction or
820
+ * the layer that's selected, what's drawn with, and a gesture's transient plan, which the
821
+ * stage renders instead of the session's.
822
+ *
823
+ * @public
824
+ */
825
+ 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;
828
+ /** The crop being made, in whole pixels of the oriented source, and its aspect. */
829
+ readonly crop: {
830
+ readonly pending: ImageCrop;
831
+ readonly aspect: ImageAspect;
832
+ } | null;
833
+ /**
834
+ * While redacting: the key of the selected redaction, if any, and the mode
835
+ * and colour a new one takes (docs/adr/0010).
836
+ */
837
+ readonly redact: {
838
+ readonly selected: string | null;
839
+ readonly mode: ImageRedactionMode;
840
+ readonly colour: string;
841
+ } | null;
842
+ /**
843
+ * While the layers are shown: the key of the selected layer, if any
844
+ * (docs/adr/0013). Selection is view state, outside the plan and its
845
+ * history.
846
+ */
847
+ readonly layers: {
848
+ readonly selected: string | null;
849
+ /**
850
+ * Where the panel moves focus, once, before it clears this: to the
851
+ * selected layer in the `list`, when the layers tool starts; or to the
852
+ * `text` field of a text layer just added. Unset, focus stays where it
853
+ * is, as when a shape or an image is added.
854
+ */
855
+ readonly focus?: "list" | "text";
856
+ } | null;
857
+ /**
858
+ * While drawing (docs/adr/0015): what the next stroke is drawn with, and
859
+ * the key of the drawing layer it joins, if there is one.
860
+ */
861
+ readonly draw: {
862
+ /** A pen draws opaque strokes; a highlighter wide ones in a see-through drawing. */
863
+ readonly mode: "pen" | "highlighter";
864
+ readonly colour: string;
865
+ /** In scene pixels. */
866
+ readonly width: number;
867
+ /** The drawing the next stroke joins, or `null` to start a new one. */
868
+ readonly target: string | null;
869
+ } | null;
870
+ /**
871
+ * What an editor's own action failed with, such as adding a layer over
872
+ * the limit or an image that can't be read. The stage shows its text
873
+ * until the next such action succeeds, or another image opens.
874
+ */
875
+ readonly error: ImageError | null;
876
+ /**
877
+ * A gesture's plan while it runs: the session's plan with the gesture's
878
+ * change, which isn't an edit until the gesture ends.
879
+ */
880
+ readonly preview: ImagePlan | null;
881
+ /** The dialog the editor shows over the stage, such as `export`, or `null`. */
882
+ readonly dialog: "export" | null;
883
+ }
884
+
885
+ /**
886
+ * The editor's colour mode: ui's light or dark theme, or the system's. Unset,
887
+ * it inherits the page's.
888
+ *
889
+ * @public
890
+ */
891
+ export declare type ImageEditorTheme = "light" | "dark" | "system";
892
+
893
+ /**
894
+ * The port for reading images: probe a file's headers, decode it into a
895
+ * source the engine holds, make thumbnails and release sources (ADR 0001,
896
+ * ADR 0002, ADR 0003, ADR 0008). The SDK's own adapter probes with its own
897
+ * readers and decodes with `createImageBitmap`, both in its render worker;
898
+ * hosts can pass their own to the editor's `engine` prop, and every
899
+ * implementation must pass the engine's contract tests.
900
+ *
901
+ * `register` checks a file's own limits, from `filePolicy`, against the
902
+ * engine's own probe before decoding it, so a host can't decode past them by
903
+ * passing a probe of another file. Session-wide limits, such as
904
+ * `maxSessionSize`, are the session's (ADR 0004).
905
+ *
906
+ * Failures reject with `ImageError`: `INVALID_IMAGE` for a malformed file,
907
+ * one whose headers claim more than its data holds, or one whose decoded
908
+ * size differs from the probe's; `UNSUPPORTED_FORMAT` for one the probe
909
+ * can't bound; `DECODE_FAILED` when the browser can't decode it; and
910
+ * sdk-core's codes for cancellation and worker failures.
911
+ *
912
+ * @public
913
+ */
914
+ declare interface ImageEngine {
915
+ /** Reads a file's headers and metadata, without decoding it. */
916
+ probe(file: Blob, options?: ImageCallOptions): Promise<ImageProbe>;
917
+ /**
918
+ * Decodes a probed file into a source with the given id, upright. The
919
+ * decoded size must equal the probe's oriented size, or the call rejects
920
+ * with `INVALID_IMAGE` and keeps nothing. A file over one of
921
+ * `filePolicy`'s per-file limits rejects with that limit's code, before
922
+ * anything decodes it. An id already in use is a
923
+ * `TypeError`.
924
+ */
925
+ register(id: string, file: Blob, probe: ImageProbe, options?: ImageRegisterOptions): Promise<ImageSourceInfo>;
926
+ /**
927
+ * A rendering of a source that fits inside `maxSize` × `maxSize`, keeping
928
+ * its aspect ratio and never enlarging it. An unknown id is a `TypeError`.
929
+ */
930
+ thumbnail(id: string, maxSize: number, options?: ImageCallOptions): Promise<ImageThumbnail>;
931
+ /** Frees a source's pixels. Releasing an unknown id does nothing. */
932
+ release(id: string): Promise<void>;
933
+ /** Releases the engine, its sources and its worker. Pending calls reject, and later calls throw. */
934
+ destroy(): Promise<void>;
935
+ }
936
+
937
+ /**
938
+ * The error `@hussmartinez/image-sdk` throws and rejects with, with a stable
939
+ * `code`, structured `details` and the underlying error as `cause`. Show
940
+ * users the text for its code from {@link imageMessages}, never its
941
+ * `message`, which is for developers and may contain text from the file.
942
+ *
943
+ * @example
944
+ * ```ts
945
+ * try {
946
+ * await session.open(file);
947
+ * } catch (error) {
948
+ * if (isImageError(error, "DECODE_FAILED")) {
949
+ * suggestConvertingToPng();
950
+ * } else {
951
+ * show(messages.error(error));
952
+ * }
953
+ * }
954
+ * ```
955
+ *
956
+ * @public
957
+ */
958
+ declare class ImageError extends SdkError<ImageErrorCode> {
959
+ /** Always `"ImageError"`, which survives minification and worker boundaries. */
960
+ readonly name = "ImageError";
961
+ }
962
+
963
+ /**
964
+ * Error codes of `@hussmartinez/image-sdk`: sdk-core's own codes, such as
965
+ * `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the image SDK's
966
+ * (ADR 0001, ADR 0004). They never change meaning once released.
967
+ *
968
+ * - `INVALID_IMAGE`: the file is malformed, its headers claim more than its
969
+ * data can carry or less than its decoder would produce, or its decoded
970
+ * size differs from what its headers declare.
971
+ * - `UNSUPPORTED_FORMAT`: the format isn't recognised, its bound can't be
972
+ * read, or the browser can't encode the requested export format.
973
+ * `details.format` names it.
974
+ * - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
975
+ * usually because it lacks the format. `details.format` names it.
976
+ * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as a
977
+ * crop outside its source. `details.reason` says why, as a stable token
978
+ * (`ImageCommandRejection`).
979
+ * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
980
+ * valid in its format. `details.reason` says why (`ImageDocumentRejection`).
981
+ * A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
982
+ * instead, with `details.reason` `unknown-format` or `unknown-format-version`.
983
+ * - `UNSUPPORTED_PLAN`: a plan holds something the renderer or processor
984
+ * can't draw, such as a layer kind from a later release. Nothing is drawn
985
+ * or exported without it (ADR 0009). `details.reason` names the part:
986
+ * `layers`, `redactions` or `animation`.
987
+ * - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
988
+ * the `maxImagePixels` limit.
989
+ * - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
990
+ * `maxImageDimension` limit.
991
+ * - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
992
+ * - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
993
+ * `maxSessionSize` limit.
994
+ * - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
995
+ * - `TOO_MANY_POINTS`: the plan's drawings hold more points than the
996
+ * `maxDrawingPoints` limit.
997
+ *
998
+ * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
999
+ * value and the `unit`. Other codes' `details` name the format involved,
457
1000
  * and a `reason`, never data from the file.
458
1001
  *
459
1002
  * @public
460
1003
  */
461
- 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";
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";
462
1005
 
463
1006
  /**
464
1007
  * The export dialog (docs/adr/0007). Export is irreversible, so it shows a
@@ -613,6 +1156,19 @@ declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "
613
1156
  */
614
1157
  export declare const imageIcons: Readonly<Record<string, IconComponent>>;
615
1158
 
1159
+ /**
1160
+ * Another image, drawn to fill its box (ADR 0009).
1161
+ *
1162
+ * @public
1163
+ */
1164
+ declare interface ImageImageLayer extends ImageLayerCommon, ImageLayerBox {
1165
+ readonly kind: "image";
1166
+ /** The id of a registered source. */
1167
+ readonly source: string;
1168
+ /** The part of that source to draw, in its own pixels, or `null` for all of it. */
1169
+ readonly crop: ImageCrop | null;
1170
+ }
1171
+
616
1172
  /**
617
1173
  * The Info panel (docs/adr/0007): what the editor knows of the open image,
618
1174
  * as a list of terms: its upright size, format, frames and file size, the
@@ -633,6 +1189,30 @@ export declare interface ImageInfoPanelProps {
633
1189
  readonly className?: string;
634
1190
  }
635
1191
 
1192
+ /**
1193
+ * Options for {@link ImageSession.insertImage}.
1194
+ *
1195
+ * @public
1196
+ */
1197
+ declare interface ImageInsertOptions {
1198
+ readonly signal?: AbortSignal;
1199
+ /**
1200
+ * The commands that add the image to the plan, instead of the default
1201
+ * layer: given the new source and the plan as it is.
1202
+ */
1203
+ readonly place?: (source: ImageSessionSource, plan: ImagePlan) => ImageCommand | readonly ImageCommand[];
1204
+ }
1205
+
1206
+ /**
1207
+ * The commands that exist only to undo others. The reducer applies them, and
1208
+ * they're plain data like every command, but the `hm-image-command` format
1209
+ * doesn't include them: an inverse's shape may change between releases
1210
+ * (sdk-core ADR 0045).
1211
+ *
1212
+ * @public
1213
+ */
1214
+ declare type ImageInverseCommand = RestoreStrokesCommand | RestoreLayersCommand | SetLayerOrderCommand | RestoreRedactionsCommand | SetRedactionOrderCommand;
1215
+
636
1216
  /**
637
1217
  * The metadata fields a user may keep on export (ADR 0005). Empty strings
638
1218
  * mean the field isn't written.
@@ -647,354 +1227,190 @@ declare interface ImageKeepableMetadata {
647
1227
  }
648
1228
 
649
1229
  /**
650
- * The type of {@link imageLimitDefinitions}.
1230
+ * A layer over the base: text, a shape, another image, a drawing or an
1231
+ * arrow (ADR 0009). Layers are drawn bottom to top, in the plan's order, and
1232
+ * redactions over all of them.
651
1233
  *
652
1234
  * @public
653
1235
  */
654
- declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1236
+ declare type ImageLayer = ImageBoxedLayer | ImageDrawingLayer | ImageArrowLayer;
655
1237
 
656
1238
  /**
657
- * The image SDK's limit definitions: sdk-core's core limits with image
658
- * defaults, plus five for images (ADR 0004).
659
- *
660
- * | Limit | Code | Default maximum | Default warning |
661
- * |---|---|---|---|
662
- * | `maxFileSize` | `FILE_TOO_LARGE` | 100 MB | 50 MB |
663
- * | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
664
- * | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
665
- * | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
666
- * | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
667
- * | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
668
- * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
669
- * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
670
- * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
671
- *
672
- * Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
673
- * per pixel. `maxImagePixels` is the same limit, with the same name, code
674
- * and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
1239
+ * Where a positioned layer is: a box in whole pixels of the scene, the
1240
+ * base's oriented source, mirrored or not, then turned about its centre
1241
+ * (ADR 0009). The box stays
1242
+ * on the pixels it covers when the image is cropped or turned.
675
1243
  *
676
1244
  * @public
677
1245
  */
678
- declare const imageLimitDefinitions: {
679
- readonly maxDecodedSize: {
680
- readonly default: 1000000000;
681
- readonly warning: 400000000;
682
- readonly code: "DECODED_SIZE_TOO_LARGE";
683
- readonly unit: "bytes";
684
- };
685
- readonly maxImagePixels: {
686
- readonly code: "IMAGE_TOO_LARGE";
687
- readonly unit: "pixels";
688
- readonly default: 50000000;
689
- readonly warning: 24000000;
690
- };
691
- readonly maxImageDimension: {
692
- readonly code: "IMAGE_DIMENSION_TOO_LARGE";
693
- readonly unit: "pixels";
694
- readonly default: 16384;
695
- };
696
- readonly maxFrames: {
697
- readonly code: "TOO_MANY_FRAMES";
698
- readonly unit: "count";
699
- readonly default: 300;
700
- readonly warning: 100;
701
- };
702
- readonly maxSessionSize: {
703
- readonly code: "SESSION_TOO_LARGE";
704
- readonly unit: "bytes";
705
- readonly default: 1000000000;
706
- readonly warning: 500000000;
707
- };
708
- readonly maxLayers: {
709
- readonly code: "TOO_MANY_LAYERS";
710
- readonly unit: "count";
711
- readonly default: 256;
712
- };
713
- readonly maxFileSize: {
714
- readonly code: "FILE_TOO_LARGE";
715
- readonly unit: "bytes";
716
- readonly default: 100000000;
717
- readonly warning: 50000000;
718
- };
719
- readonly maxFiles: {
720
- readonly code: "TOO_MANY_FILES";
721
- readonly unit: "count";
722
- readonly default: 20;
723
- };
724
- readonly maxProcessingTime: {
725
- readonly code: "PROCESSING_TIME_EXCEEDED";
726
- readonly unit: "milliseconds";
727
- readonly default: 120000;
728
- };
729
- };
1246
+ declare interface ImageLayerBox {
1247
+ /** The box's left edge, before its rotation. May be negative. */
1248
+ readonly x: number;
1249
+ /** The box's top edge, before its rotation. May be negative. */
1250
+ readonly y: number;
1251
+ /** At least 1. */
1252
+ readonly width: number;
1253
+ /** At least 1. */
1254
+ readonly height: number;
1255
+ /** Tenths of a degree, clockwise about the box's centre: 0 to 3599. */
1256
+ readonly rotation: number;
1257
+ /**
1258
+ * Whether the layer is mirrored left to right, about the box's own
1259
+ * vertical axis, before it's turned. With a half turn, that's a mirror top
1260
+ * to bottom, so one flip is all a box needs.
1261
+ */
1262
+ readonly flipX: boolean;
1263
+ }
730
1264
 
731
1265
  /**
732
- * The names of the image SDK's limits.
1266
+ * What every layer has (ADR 0009).
733
1267
  *
734
1268
  * @public
735
1269
  */
736
- declare type ImageLimitName = keyof ImageLimitDefinitions;
1270
+ declare interface ImageLayerCommon {
1271
+ /**
1272
+ * Its identity: 1 to `MAX_KEY_LENGTH` code points, unique among the plan's
1273
+ * layers and redactions.
1274
+ */
1275
+ readonly key: string;
1276
+ /**
1277
+ * What the layers list calls it: up to `MAX_LAYER_NAME_LENGTH` code
1278
+ * points. Empty means the editor's own label for the kind.
1279
+ */
1280
+ readonly name: string;
1281
+ /** Whether it's drawn. */
1282
+ readonly visible: boolean;
1283
+ /** A whole number from 0, transparent, to 100, opaque. */
1284
+ readonly opacity: number;
1285
+ }
1286
+
1287
+ /**
1288
+ * The layers panel (docs/adr/0013), shown while the layers tool is on: the
1289
+ * list of layers, the top one first, each with a button that shows or hides
1290
+ * it; buttons that move the selected layer up and down the stack, mirror
1291
+ * it, copy it and delete it; and its name, place, size, turn and opacity as
1292
+ * fields, with its own kind's under them. Everything a frame on the stage
1293
+ * does with a drag, the panel does with a button or a field (WCAG 2.5.7).
1294
+ *
1295
+ * The list is ui's `ReorderableList`: one tab stop, the Up and Down arrows
1296
+ * between layers, `Alt` (`Option` on macOS) with them to move the focused
1297
+ * layer up and down the stack, and `Delete` to remove it: pdf-sdk's keys
1298
+ * for its pages.
1299
+ *
1300
+ * The panel keeps its size, whatever is selected: with no layer selected its
1301
+ * fields are disabled, and keep their place. Where the inspector sits under
1302
+ * the stage, a panel that grew would shrink the stage, and move the image
1303
+ * under the pointer.
1304
+ *
1305
+ * @public
1306
+ */
1307
+ export declare function ImageLayersPanel(props: ImageLayersPanelProps): ReactNode;
737
1308
 
738
1309
  /**
739
- * The type of {@link imageMessages}, for typing a host's overrides with
740
- * `MessageOverrides<ImageMessageCatalogue>`.
1310
+ * Props of {@link ImageLayersPanel}.
741
1311
  *
742
1312
  * @public
743
1313
  */
744
- declare type ImageMessageCatalogue = typeof imageMessages;
1314
+ export declare interface ImageLayersPanelProps {
1315
+ readonly className?: string;
1316
+ }
745
1317
 
746
1318
  /**
747
- * The image SDK's English message catalogue: sdk-core's and ui's messages, and text
748
- * for every {@link ImageErrorCode} and every limit's warning. Pass it to
749
- * `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
750
- * overrides. It also has the editor's text: its labels, states,
751
- * announcements and tool names.
1319
+ * The type of {@link imageLimitDefinitions}.
752
1320
  *
753
- * Error text is looked up by code, with the error's `details` as
754
- * parameters, and never taken from `error.message` (ADR 0019).
1321
+ * @public
1322
+ */
1323
+ declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
1324
+
1325
+ /**
1326
+ * The image SDK's limit definitions: sdk-core's core limits with image
1327
+ * defaults, plus five for images (ADR 0004).
755
1328
  *
756
- * @example
757
- * ```ts
758
- * const messages = createMessages(imageMessages, { locale: "en", overrides: props.messages });
759
- * messages.error(error); // "This animation has 400 frames, which is over the 300-frame limit."
760
- * messages.t("warnings.maxSessionSize", { actual: 600e6 });
761
- * ```
1329
+ * | Limit | Code | Default maximum | Default warning |
1330
+ * |---|---|---|---|
1331
+ * | `maxFileSize` | `FILE_TOO_LARGE` | 100 MB | 50 MB |
1332
+ * | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
1333
+ * | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
1334
+ * | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
1335
+ * | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
1336
+ * | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
1337
+ * | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
1338
+ * | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
1339
+ * | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
1340
+ * | `maxDrawingPoints` | `TOO_MANY_POINTS` | 200,000 | 100,000 |
1341
+ *
1342
+ * Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
1343
+ * per pixel. `maxImagePixels` is the same limit, with the same name, code
1344
+ * and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
762
1345
  *
763
1346
  * @public
764
1347
  */
765
- declare const imageMessages: {
766
- 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.";
767
- readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
768
- readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
769
- readonly "errors.DECODE_FAILED": "This browser can't open this kind of image. Try another browser, or convert the file to PNG or JPEG.";
770
- readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
771
- readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
772
- readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
773
- readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
774
- readonly "errors.TOO_MANY_FRAMES": {
775
- readonly $plural: "maximum";
776
- } & {
777
- readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
778
- readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
779
- };
780
- 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.";
781
- readonly "errors.TOO_MANY_LAYERS": {
782
- readonly $plural: "maximum";
783
- } & {
784
- readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
785
- readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
786
- };
787
- readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
788
- readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
789
- readonly "warnings.maxFrames": {
790
- readonly $plural: "actual";
791
- } & {
792
- readonly one: "This animation has {actual} frame.";
793
- readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
1348
+ declare const imageLimitDefinitions: {
1349
+ readonly maxDecodedSize: {
1350
+ readonly default: 1000000000;
1351
+ readonly warning: 400000000;
1352
+ readonly code: "DECODED_SIZE_TOO_LARGE";
1353
+ readonly unit: "bytes";
794
1354
  };
795
- readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
796
- readonly "warnings.maxLayers": {
797
- readonly $plural: "actual";
798
- } & {
799
- readonly one: "This image has {actual} layer.";
800
- readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
1355
+ readonly maxImagePixels: {
1356
+ readonly code: "IMAGE_TOO_LARGE";
1357
+ readonly unit: "pixels";
1358
+ readonly default: 50000000;
1359
+ readonly warning: 24000000;
801
1360
  };
802
- readonly "editor.label": "Image editor";
803
- readonly "editor.preview": "Edited image preview, {width, number} × {height, number}";
804
- readonly "editor.empty": "Open an image to start editing. It stays on this device.";
805
- readonly "editor.choose": "Choose an image";
806
- readonly "editor.dropHint": "or drop it here";
807
- readonly "editor.opening": "Opening the image…";
808
- readonly "editor.cancel": "Cancel";
809
- readonly "editor.opened": "Image opened, {width, number} × {height, number}.";
810
- readonly "editor.undid": "Undid {action}.";
811
- readonly "editor.redid": "Redid {action}.";
812
- readonly "actions.image.setCrop": "crop";
813
- readonly "actions.image.setOrientation": "rotate or flip";
814
- readonly "actions.image.setOutput": "size";
815
- readonly "actions.image.setMetadata": "metadata";
816
- readonly "actions.image.setDevelop": "adjustment";
817
- readonly "actions.image.setFilter": "filter";
818
- readonly "toolbar.label": "Image tools";
819
- readonly "toolbar.groups.file": "File";
820
- readonly "toolbar.groups.history": "History";
821
- readonly "toolbar.groups.orientation": "Rotate";
822
- readonly "toolbar.groups.zoom": "Zoom";
823
- readonly "toolbar.groups.other": "More tools";
824
- readonly "tools.open": "Open image";
825
- readonly "tools.undo": "Undo";
826
- readonly "tools.redo": "Redo";
827
- readonly "tools.rotate-left": "Rotate left";
828
- readonly "tools.rotate-right": "Rotate right";
829
- readonly "tools.zoom-in": "Zoom in";
830
- readonly "tools.zoom-out": "Zoom out";
831
- readonly "tools.zoom-fit": "Fit to the stage";
832
- readonly "tools.crop": "Crop";
833
- readonly "tools.flip-horizontal": "Flip horizontally";
834
- readonly "tools.flip-vertical": "Flip vertically";
835
- readonly "toolbar.groups.crop": "Crop";
836
- readonly "crop.frame": "Crop area";
837
- 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.";
838
- readonly "crop.size": "{width, number} × {height, number}, from {x, number}, {y, number}";
839
- readonly "crop.panel": "Crop";
840
- readonly "crop.x": "Left";
841
- readonly "crop.y": "Top";
842
- readonly "crop.width": "Width";
843
- readonly "crop.height": "Height";
844
- readonly "crop.aspect": "Aspect ratio";
845
- readonly "crop.aspects.free": "Free";
846
- readonly "crop.aspects.original": "Original";
847
- readonly "crop.aspects.ratio": "{width}:{height}";
848
- readonly "crop.apply": "Apply crop";
849
- readonly "crop.cancel": "Cancel";
850
- readonly "crop.reset": "Whole image";
851
- readonly "crop.applied": "Cropped to {width, number} × {height, number}.";
852
- readonly "inspector.label": "Panels";
853
- readonly "inspector.adjust": "Adjust";
854
- readonly "inspector.filters": "Filters";
855
- readonly "inspector.info": "Info";
856
- readonly "notices.label": "Notices";
857
- readonly "notices.dismiss": "Dismiss";
858
- readonly "notices.colourProfile": "This image has a colour profile. Colours outside sRGB will be clipped in the exported file.";
859
- readonly "info.panel": "Image info";
860
- readonly "info.size": "Size";
861
- readonly "info.sizeValue": "{width, number} × {height, number} pixels";
862
- readonly "info.format": "Format";
863
- readonly "info.formats.png": "PNG";
864
- readonly "info.formats.jpeg": "JPEG";
865
- readonly "info.formats.webp": "WebP";
866
- readonly "info.formats.gif": "GIF";
867
- readonly "info.formats.avif": "AVIF";
868
- readonly "info.formats.heif": "HEIF";
869
- readonly "info.formats.bmp": "BMP";
870
- readonly "info.frames": "Frames";
871
- readonly "info.fileSize": "File size";
872
- readonly "info.fileSizeValue": "{size, fileSize}";
873
- readonly "info.metadata": "Metadata in the file";
874
- readonly "info.metadataNone": "None";
875
- readonly "info.kept": "Kept on export";
876
- readonly "info.keptNone": "Nothing";
877
- readonly "develop.panel": "Adjust";
878
- readonly "develop.temperature": "Temperature";
879
- readonly "develop.tint": "Tint";
880
- readonly "develop.exposure": "Exposure";
881
- readonly "develop.highlights": "Highlights";
882
- readonly "develop.shadows": "Shadows";
883
- readonly "develop.contrast": "Contrast";
884
- readonly "develop.saturation": "Saturation";
885
- readonly "develop.vibrance": "Vibrance";
886
- readonly "develop.reset": "Reset {name}";
887
- readonly "develop.resetAll": "Reset all";
888
- readonly "develop.wasReset": "All adjustments reset.";
889
- readonly "filters.panel": "Filters";
890
- readonly "filters.label": "Filter";
891
- readonly "filters.none": "None";
892
- readonly "filters.vivid": "Vivid";
893
- readonly "filters.warm": "Warm";
894
- readonly "filters.cool": "Cool";
895
- readonly "filters.fade": "Fade";
896
- readonly "filters.mono": "Mono";
897
- readonly "filters.noir": "Noir";
898
- readonly "filters.sepia": "Sepia";
899
- readonly "filters.strength": "Strength";
900
- readonly "toolbar.groups.export": "Export";
901
- readonly "tools.export": "Export";
902
- readonly "export.title": "Export image";
903
- readonly "export.description": "The file is made on this device, and nothing is uploaded.";
904
- readonly "export.format": "Format";
905
- readonly "export.formats.png": "PNG";
906
- readonly "export.formats.jpeg": "JPEG";
907
- readonly "export.formats.webp": "WebP";
908
- readonly "export.quality": "Quality";
909
- readonly "export.qualityValue": "{quality, number}%";
910
- readonly "export.size": "Size";
911
- readonly "export.sizes.scale": "Scale";
912
- readonly "export.sizes.fit": "Fit in a box";
913
- readonly "export.scale": "Scale, in percent";
914
- readonly "export.fitWidth": "Largest width";
915
- readonly "export.fitHeight": "Largest height";
916
- readonly "export.fields": "Details to include";
917
- readonly "export.fieldsHint": "Only what you fill in is written to the file.";
918
- readonly "export.field.title": "Title";
919
- readonly "export.field.description": "Description";
920
- readonly "export.field.artist": "Artist";
921
- readonly "export.field.copyright": "Copyright";
922
- readonly "export.summary": "Summary";
923
- readonly "export.output": "{width, number} × {height, number} pixels, {format}";
924
- readonly "export.removed": "Removed from the file";
925
- readonly "export.removedNone": "The image had no other details to remove.";
926
- readonly "export.kind.location": "Location";
927
- readonly "export.kind.camera": "Camera details";
928
- readonly "export.kind.timestamps": "Dates and times";
929
- readonly "export.kind.thumbnail": "Embedded thumbnail";
930
- readonly "export.kind.colourProfile": "Colour profile: colours outside sRGB are clipped";
931
- readonly "export.kind.other": "Other metadata";
932
- readonly "export.kept": "Kept in the file";
933
- readonly "export.confirm": "Export";
934
- readonly "export.cancel": "Cancel";
935
- readonly "export.progress": "Exporting the image";
936
- readonly "export.stop": "Stop exporting";
937
- readonly "export.cancelled": "Export stopped.";
938
- readonly "export.done": "Exported a {format} of {size, fileSize}.";
939
- readonly "export.ready": "{width, number} × {height, number} pixels, {format}, {size, fileSize}";
940
- readonly "export.download": "Download";
941
- readonly "export.close": "Done";
942
- readonly "dialog.close": "Close";
943
- readonly "fileDropZone.choose": "Choose a file";
944
- readonly "fileDropZone.chooseMultiple": "Choose files";
945
- readonly "fileDropZone.hint": "or drop it here";
946
- readonly "fileDropZone.hintMultiple": "or drop them here";
947
- readonly "progress.label": "Progress";
948
- readonly "spinner.label": "Loading";
949
- readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
950
- readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
951
- readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
952
- readonly "errors.ABORTED": "The operation was cancelled.";
953
- readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
954
- readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
955
- readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
956
- readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
957
- readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
958
- readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
959
- readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
960
- readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
961
- readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
962
- readonly "errors.TOO_MANY_FILES": {
963
- readonly $plural: "maximum";
964
- } & {
965
- readonly one: "You can add {maximum} file at a time.";
966
- readonly other: "You can add up to {maximum} files at a time.";
1361
+ readonly maxImageDimension: {
1362
+ readonly code: "IMAGE_DIMENSION_TOO_LARGE";
1363
+ readonly unit: "pixels";
1364
+ readonly default: 16384;
1365
+ };
1366
+ readonly maxFrames: {
1367
+ readonly code: "TOO_MANY_FRAMES";
1368
+ readonly unit: "count";
1369
+ readonly default: 300;
1370
+ readonly warning: 100;
1371
+ };
1372
+ readonly maxSessionSize: {
1373
+ readonly code: "SESSION_TOO_LARGE";
1374
+ readonly unit: "bytes";
1375
+ readonly default: 1000000000;
1376
+ readonly warning: 500000000;
1377
+ };
1378
+ readonly maxLayers: {
1379
+ readonly code: "TOO_MANY_LAYERS";
1380
+ readonly unit: "count";
1381
+ readonly default: 256;
1382
+ };
1383
+ readonly maxDrawingPoints: {
1384
+ readonly code: "TOO_MANY_POINTS";
1385
+ readonly unit: "count";
1386
+ readonly default: 200000;
1387
+ readonly warning: 100000;
1388
+ };
1389
+ readonly maxFileSize: {
1390
+ readonly code: "FILE_TOO_LARGE";
1391
+ readonly unit: "bytes";
1392
+ readonly default: 100000000;
1393
+ readonly warning: 50000000;
1394
+ };
1395
+ readonly maxFiles: {
1396
+ readonly code: "TOO_MANY_FILES";
1397
+ readonly unit: "count";
1398
+ readonly default: 20;
1399
+ };
1400
+ readonly maxProcessingTime: {
1401
+ readonly code: "PROCESSING_TIME_EXCEEDED";
1402
+ readonly unit: "milliseconds";
1403
+ readonly default: 120000;
967
1404
  };
968
- readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
969
- readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
970
- readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
971
- readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
972
- readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
973
- readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
974
- readonly "keys.control": "Ctrl";
975
- readonly "keys.alt": "Alt";
976
- readonly "keys.shift": "Shift";
977
- readonly "keys.meta": "Meta";
978
- readonly "keys.apple.control": "\u2303";
979
- readonly "keys.apple.alt": "\u2325";
980
- readonly "keys.apple.shift": "\u21E7";
981
- readonly "keys.apple.meta": "\u2318";
982
- readonly "keys.space": "Space";
983
- readonly "keys.enter": "Enter";
984
- readonly "keys.escape": "Esc";
985
- readonly "keys.tab": "Tab";
986
- readonly "keys.delete": "Delete";
987
- readonly "keys.backspace": "Backspace";
988
- readonly "keys.arrowUp": "\u2191";
989
- readonly "keys.arrowDown": "\u2193";
990
- readonly "keys.arrowLeft": "\u2190";
991
- readonly "keys.arrowRight": "\u2192";
992
- readonly "keys.home": "Home";
993
- readonly "keys.end": "End";
994
- readonly "keys.pageUp": "Page Up";
995
- readonly "keys.pageDown": "Page Down";
996
1405
  };
997
1406
 
1407
+ /**
1408
+ * The names of the image SDK's limits.
1409
+ *
1410
+ * @public
1411
+ */
1412
+ declare type ImageLimitName = keyof ImageLimitDefinitions;
1413
+
998
1414
  /**
999
1415
  * Which kinds of metadata a file carries, as presence flags, never values,
1000
1416
  * so the editor can say what an export removes (ADR 0005).
@@ -1043,12 +1459,19 @@ declare type ImageOutput = {
1043
1459
 
1044
1460
  /**
1045
1461
  * The session's document: a description of the edits over an immutable
1046
- * source, rendered to pixels only for display and export (ADR 0003).
1462
+ * source, rendered to pixels only for display and export (ADR 0003, ADR
1463
+ * 0009).
1047
1464
  *
1048
1465
  * @public
1049
1466
  */
1050
1467
  declare interface ImagePlan {
1051
1468
  readonly base: ImageBase;
1469
+ /** The layers over the base, bottom to top, placed in the scene (ADR 0009). */
1470
+ readonly layers: readonly ImageLayer[];
1471
+ /** The redactions, applied over every layer (ADR 0010). */
1472
+ readonly redactions: readonly ImageRedaction[];
1473
+ /** The animation (ADR 0011). Always `null` until format version 4. */
1474
+ readonly animation: null;
1052
1475
  readonly output: ImageOutput;
1053
1476
  /** The fields the user chose to keep on export. Never a location (ADR 0005). */
1054
1477
  readonly metadata: ImageKeepableMetadata;
@@ -1124,6 +1547,95 @@ declare interface ImageProgressOptions extends ImageCallOptions {
1124
1547
  readonly onProgress?: (fraction: number) => void;
1125
1548
  }
1126
1549
 
1550
+ /**
1551
+ * A region of the image that an export doesn't show (ADR 0010): a rectangle
1552
+ * in whole pixels of the scene, the base's oriented source, so it stays on
1553
+ * the pixels it covers when the image is cropped or turned (ADR 0009).
1554
+ *
1555
+ * A redaction has no opacity, visibility or rotation, and is drawn over
1556
+ * every layer. Only exports are redacted: the plan describes the redaction,
1557
+ * and the source is unchanged.
1558
+ *
1559
+ * @public
1560
+ */
1561
+ declare type ImageRedaction = (ImageRedactionRegion & {
1562
+ readonly mode: "solid";
1563
+ /** The fill, as `#rrggbb` in lower case. */
1564
+ readonly colour: string;
1565
+ }) | (ImageRedactionRegion & {
1566
+ readonly mode: "pixelate";
1567
+ });
1568
+
1569
+ /**
1570
+ * How a redaction replaces what it covers (ADR 0010): `solid` fills the
1571
+ * region with one colour, and `pixelate` with coarse blocks of the average
1572
+ * colour beneath each. Only `solid` destroys what was there.
1573
+ *
1574
+ * @public
1575
+ */
1576
+ declare type ImageRedactionMode = "solid" | "pixelate";
1577
+
1578
+ /**
1579
+ * The fields of a redaction that `image.updateRedactions` may set: any but
1580
+ * its key. Setting `mode` to `pixelate` drops the colour, and setting it to
1581
+ * `solid` needs one in the same update.
1582
+ *
1583
+ * @public
1584
+ */
1585
+ declare interface ImageRedactionProps {
1586
+ readonly mode?: ImageRedaction["mode"];
1587
+ readonly x?: number;
1588
+ readonly y?: number;
1589
+ readonly width?: number;
1590
+ readonly height?: number;
1591
+ readonly colour?: string;
1592
+ }
1593
+
1594
+ /**
1595
+ * What every redaction has, whatever its mode: its identity and its region.
1596
+ *
1597
+ * @public
1598
+ */
1599
+ declare interface ImageRedactionRegion {
1600
+ /**
1601
+ * Its identity: 1 to {@link MAX_KEY_LENGTH} code points, unique among the
1602
+ * plan's layers and redactions.
1603
+ */
1604
+ readonly key: string;
1605
+ /** The region's left edge, in whole pixels of the scene. May be negative. */
1606
+ readonly x: number;
1607
+ /** The region's top edge, in whole pixels of the scene. May be negative. */
1608
+ readonly y: number;
1609
+ /** At least 1. */
1610
+ readonly width: number;
1611
+ /** At least 1. */
1612
+ readonly height: number;
1613
+ }
1614
+
1615
+ /**
1616
+ * The redact panel (docs/adr/0010), shown while redacting: what a new area
1617
+ * is covered with, a button that adds one without dragging (WCAG 2.5.7),
1618
+ * the selected area's position and size in source pixels, and the list of
1619
+ * every area, each with its mode, its size and a button to remove it, so
1620
+ * what's covered can be read without the preview.
1621
+ *
1622
+ * The panel keeps its size while redacting, whatever is selected or chosen.
1623
+ * Where the inspector sits under the stage, a panel that grew would shrink
1624
+ * the stage, and move the image under the pointer.
1625
+ *
1626
+ * @public
1627
+ */
1628
+ export declare function ImageRedactPanel(props: ImageRedactPanelProps): ReactNode;
1629
+
1630
+ /**
1631
+ * Props of {@link ImageRedactPanel}.
1632
+ *
1633
+ * @public
1634
+ */
1635
+ export declare interface ImageRedactPanelProps {
1636
+ readonly className?: string;
1637
+ }
1638
+
1127
1639
  /**
1128
1640
  * Options for registering a source.
1129
1641
  *
@@ -1148,6 +1660,16 @@ declare interface ImageRegisterOptions extends ImageProgressOptions {
1148
1660
  */
1149
1661
  declare type ImageRotation = 0 | 90 | 180 | 270;
1150
1662
 
1663
+ /**
1664
+ * A point of the scene, in whole pixels.
1665
+ *
1666
+ * @public
1667
+ */
1668
+ declare interface ImageScenePoint {
1669
+ readonly x: number;
1670
+ readonly y: number;
1671
+ }
1672
+
1151
1673
  /**
1152
1674
  * An image editing session (ADR 0003, ADR 0008): one document, its plan
1153
1675
  * over the source it opened, edited by commands with undo and redo, and
@@ -1171,6 +1693,29 @@ declare interface ImageSession {
1171
1693
  open(file: Blob, options?: {
1172
1694
  readonly signal?: AbortSignal;
1173
1695
  }): Promise<ImageSessionSource>;
1696
+ /**
1697
+ * Probes, checks and decodes another file, and adds it to the document as
1698
+ * an image layer, as one undoable step (ADR 0003, ADR 0004).
1699
+ *
1700
+ * - **Limits:** the file's own, as for `open`; `maxFiles`, counting every
1701
+ * source the session holds; and `maxSessionSize`, counting their decoded
1702
+ * bytes. When the image doesn't fit, the session first drops the oldest
1703
+ * undo steps that alone keep another image, and marks the history as
1704
+ * trimmed. If that isn't enough, nothing is dropped and it fails with
1705
+ * `SESSION_TOO_LARGE`.
1706
+ * - **Placement:** by default the image is centred on what's shown, at
1707
+ * its own size or half the composition's, whichever is smaller, over
1708
+ * every layer, and turned and mirrored back against the plan's
1709
+ * rotation and flips, so it's seen as the file is. `place` returns other commands; they must refer to the
1710
+ * source, or it's released.
1711
+ * - **Lifetime:** the session holds the source while the plan, an undo
1712
+ * or redo step, or an export in progress refers to it, and releases it
1713
+ * then.
1714
+ *
1715
+ * A failure, a cancellation, or another file opened meanwhile adds
1716
+ * nothing and releases the source.
1717
+ */
1718
+ insertImage(file: Blob, options?: ImageInsertOptions): Promise<ImageSessionSource>;
1174
1719
  /**
1175
1720
  * Applies commands as one undoable step. They're checked by the reducer,
1176
1721
  * then the output against `maxImageDimension` and `maxImagePixels`; a
@@ -1181,7 +1726,9 @@ declare interface ImageSession {
1181
1726
  * Makes the document's plan equal to `plan`, as one undoable step of the
1182
1727
  * commands that reach it, checked as `execute` checks them (ADR 0003). A
1183
1728
  * plan equal to the current one changes nothing. A plan over another
1184
- * source is `INVALID_COMMAND`. For editors whose host holds the plan.
1729
+ * source is `INVALID_COMMAND`, and so is one without `layers`,
1730
+ * `redactions` and `animation`, such as a plan stored before format
1731
+ * version 2. For editors whose host holds the plan.
1185
1732
  */
1186
1733
  applyPlan(plan: ImagePlan): void;
1187
1734
  /**
@@ -1205,7 +1752,7 @@ declare interface ImageSession {
1205
1752
  readonly signal?: AbortSignal;
1206
1753
  readonly onProgress?: (fraction: number) => void;
1207
1754
  }): Promise<ImageSessionExport>;
1208
- /** Releases the source the session holds. Later calls throw. */
1755
+ /** Releases every source the session holds. Later calls throw. */
1209
1756
  destroy(): Promise<void>;
1210
1757
  }
1211
1758
 
@@ -1216,7 +1763,7 @@ declare interface ImageSession {
1216
1763
  * @public
1217
1764
  */
1218
1765
  declare interface ImageSessionEvent {
1219
- readonly type: "open" | "execute" | "undo" | "redo" | "export";
1766
+ readonly type: "open" | "insert" | "execute" | "undo" | "redo" | "export";
1220
1767
  readonly outcome: "done" | "failed" | "cancelled";
1221
1768
  /** The types of the commands applied or undone. */
1222
1769
  readonly commands: readonly ImageCommand["type"][];
@@ -1255,8 +1802,20 @@ declare interface ImageSessionSnapshot {
1255
1802
  readonly plan: ImagePlan | null;
1256
1803
  /** The document's source, or `null` before a file is open. */
1257
1804
  readonly source: ImageSessionSource | null;
1805
+ /**
1806
+ * Every source the session holds: the document's, then those of image
1807
+ * layers, including ones only the history still refers to (ADR 0004).
1808
+ */
1809
+ readonly sources: readonly ImageSessionSource[];
1258
1810
  readonly canUndo: boolean;
1259
1811
  readonly canRedo: boolean;
1812
+ /**
1813
+ * Whether undo steps were dropped to make room for an image, since the
1814
+ * document was opened: they can no longer be undone.
1815
+ */
1816
+ readonly historyTrimmed: boolean;
1817
+ /** Whether an image is being added as a layer. */
1818
+ readonly inserting: boolean;
1260
1819
  /** Whether a file is being opened. The current document stays until it's ready. */
1261
1820
  readonly opening: boolean;
1262
1821
  /** Whether an export is in progress. */
@@ -1283,6 +1842,25 @@ declare interface ImageSessionSource extends ImageSourceInfo {
1283
1842
  readonly keepable: ImageKeepableMetadata;
1284
1843
  }
1285
1844
 
1845
+ /**
1846
+ * A rectangle or an ellipse that fills its box, with a fill, a stroke drawn
1847
+ * inside the box, or both (ADR 0009).
1848
+ *
1849
+ * @public
1850
+ */
1851
+ declare interface ImageShapeLayer extends ImageLayerCommon, ImageLayerBox {
1852
+ readonly kind: "shape";
1853
+ readonly shape: (typeof LAYER_SHAPES)[number];
1854
+ /** The fill, as `#rrggbb` in lower case, or `null` for none. */
1855
+ readonly fill: string | null;
1856
+ /** The stroke, or `null` for none. A shape has a fill or a stroke. */
1857
+ readonly stroke: {
1858
+ readonly colour: string;
1859
+ /** In whole scene pixels, from 1 to `MAX_STROKE_WIDTH`. */
1860
+ readonly width: number;
1861
+ } | null;
1862
+ }
1863
+
1286
1864
  /**
1287
1865
  * A width and a height, in whole pixels.
1288
1866
  *
@@ -1336,6 +1914,46 @@ export declare interface ImageStageProps {
1336
1914
  readonly className?: string;
1337
1915
  }
1338
1916
 
1917
+ /**
1918
+ * One stroke of a drawing: what one gesture drew, from the press to the
1919
+ * release (docs/adr/0014). It has more than one run only when it's long.
1920
+ *
1921
+ * @public
1922
+ */
1923
+ declare interface ImageStroke {
1924
+ /** `#rrggbb`. */
1925
+ readonly colour: string;
1926
+ /** In whole scene pixels: 1 to `MAX_STROKE_WIDTH`. */
1927
+ readonly width: number;
1928
+ /**
1929
+ * 1 to `MAX_STROKE_RUNS` runs, each a polyline `[x0, y0, x1, y1, …]` of 1
1930
+ * to `MAX_RUN_POINTS` points, in whole pixels from the drawing's origin.
1931
+ * A run of one point is a dot.
1932
+ */
1933
+ readonly runs: readonly (readonly number[])[];
1934
+ }
1935
+
1936
+ /**
1937
+ * Text, drawn as large as fits inside its box, never distorted (ADR 0009).
1938
+ * Lines break only at line feeds. Emoji are text.
1939
+ *
1940
+ * @public
1941
+ */
1942
+ declare interface ImageTextLayer extends ImageLayerCommon, ImageLayerBox {
1943
+ readonly kind: "text";
1944
+ /**
1945
+ * Up to `MAX_LAYER_TEXT_LENGTH` code points. Control characters other
1946
+ * than a line feed, and the bidirectional embedding, override and isolate
1947
+ * controls, are refused.
1948
+ */
1949
+ readonly text: string;
1950
+ readonly font: (typeof LAYER_FONTS)[number];
1951
+ readonly bold: boolean;
1952
+ /** The text's colour, as `#rrggbb` in lower case. */
1953
+ readonly colour: string;
1954
+ readonly align: (typeof LAYER_ALIGNMENTS)[number];
1955
+ }
1956
+
1339
1957
  /**
1340
1958
  * A small rendering of a source for lists and frame strips. An `ImageBitmap`
1341
1959
  * is one; tests can supply their own. Close it when it's no longer shown.
@@ -1353,7 +1971,15 @@ declare interface ImageThumbnail {
1353
1971
  *
1354
1972
  * @public
1355
1973
  */
1356
- export declare type ImageTool = Tool<ImageToolState, ImageToolContext, undefined>;
1974
+ export declare type ImageTool = Tool<ImageToolState, ImageToolContext, undefined> & {
1975
+ /**
1976
+ * Why the tool can't run right now, as a key of the editor's messages,
1977
+ * when there's something the user can do about it. The toolbar keeps a
1978
+ * button with a reason in the keyboard's order and describes it with the
1979
+ * text, so "why is this greyed out" has an answer.
1980
+ */
1981
+ readonly unavailable?: (state: ImageToolState) => string | undefined;
1982
+ };
1357
1983
 
1358
1984
  /**
1359
1985
  * The editor's toolbar (docs/adr/0007): ui's Toolbar, one group per toolbar
@@ -1399,6 +2025,8 @@ export declare interface ImageToolContext {
1399
2025
  readonly editor: Store<ImageEditorState>;
1400
2026
  /** Asks the user for an image, as the open tool does. */
1401
2027
  readonly chooseFile: () => void;
2028
+ /** Asks the user for an image to add as a layer (docs/adr/0013). */
2029
+ readonly chooseLayerImage: () => void;
1402
2030
  }
1403
2031
 
1404
2032
  /**
@@ -1432,6 +2060,157 @@ export declare interface ImageViewState {
1432
2060
  };
1433
2061
  }
1434
2062
 
2063
+ /**
2064
+ * Inserts layers at an index of the plan's layers, which are drawn bottom
2065
+ * to top (ADR 0009). Each needs a key no layer or redaction of the plan has.
2066
+ *
2067
+ * @public
2068
+ */
2069
+ declare interface InsertLayersCommand {
2070
+ readonly type: "image.insertLayers";
2071
+ /** From 0, under every layer, to the number of layers, over them all. */
2072
+ readonly at: number;
2073
+ readonly layers: readonly ImageLayer[];
2074
+ }
2075
+
2076
+ /**
2077
+ * Inserts redactions at an index of the plan's redactions (ADR 0010). Each
2078
+ * needs a key no layer or redaction of the plan has.
2079
+ *
2080
+ * @public
2081
+ */
2082
+ declare interface InsertRedactionsCommand {
2083
+ readonly type: "image.insertRedactions";
2084
+ /** From 0 to the number of redactions. */
2085
+ readonly at: number;
2086
+ readonly redactions: readonly ImageRedaction[];
2087
+ }
2088
+
2089
+ /**
2090
+ * How a text layer's lines sit in its box, by the text's own direction.
2091
+ *
2092
+ * @public
2093
+ */
2094
+ declare const LAYER_ALIGNMENTS: readonly ["start", "center", "end"];
2095
+
2096
+ /**
2097
+ * The fonts a text layer can use: the generic families, which every device
2098
+ * has, so the SDK ships and fetches none (ADR 0009). Names are part of the
2099
+ * document format.
2100
+ *
2101
+ * @public
2102
+ */
2103
+ declare const LAYER_FONTS: readonly ["sans-serif", "serif", "monospace"];
2104
+
2105
+ /**
2106
+ * The shapes a shape layer can be.
2107
+ *
2108
+ * @public
2109
+ */
2110
+ declare const LAYER_SHAPES: readonly ["rectangle", "ellipse"];
2111
+
2112
+ /**
2113
+ * Moves layers to an index of the list without them, keeping the order they
2114
+ * had: up or down the stack.
2115
+ *
2116
+ * @public
2117
+ */
2118
+ declare interface MoveLayersCommand {
2119
+ readonly type: "image.moveLayers";
2120
+ readonly keys: readonly string[];
2121
+ readonly to: number;
2122
+ }
2123
+
2124
+ /**
2125
+ * Moves redactions to an index of the list without them, keeping the order
2126
+ * they had. The order only decides how overlapping redactions look.
2127
+ *
2128
+ * @public
2129
+ */
2130
+ declare interface MoveRedactionsCommand {
2131
+ readonly type: "image.moveRedactions";
2132
+ readonly keys: readonly string[];
2133
+ readonly to: number;
2134
+ }
2135
+
2136
+ /**
2137
+ * Removes layers, by key.
2138
+ *
2139
+ * @public
2140
+ */
2141
+ declare interface RemoveLayersCommand {
2142
+ readonly type: "image.removeLayers";
2143
+ readonly keys: readonly string[];
2144
+ }
2145
+
2146
+ /**
2147
+ * Removes redactions, by key.
2148
+ *
2149
+ * @public
2150
+ */
2151
+ declare interface RemoveRedactionsCommand {
2152
+ readonly type: "image.removeRedactions";
2153
+ readonly keys: readonly string[];
2154
+ }
2155
+
2156
+ /**
2157
+ * Removes strokes from a drawing layer, by index. A drawing keeps at least
2158
+ * one stroke: to remove the last, remove the layer.
2159
+ *
2160
+ * @public
2161
+ */
2162
+ declare interface RemoveStrokesCommand {
2163
+ readonly type: "image.removeStrokes";
2164
+ readonly key: string;
2165
+ readonly indexes: readonly number[];
2166
+ }
2167
+
2168
+ /**
2169
+ * Puts removed layers back, each at its index, by rising index. It's what
2170
+ * undoes {@link RemoveLayersCommand}: the reducer applies it, but it isn't
2171
+ * part of the portable command format (ADR 0009).
2172
+ *
2173
+ * @public
2174
+ */
2175
+ declare interface RestoreLayersCommand {
2176
+ readonly type: "image.restoreLayers";
2177
+ readonly entries: readonly {
2178
+ readonly at: number;
2179
+ readonly layer: ImageLayer;
2180
+ }[];
2181
+ }
2182
+
2183
+ /**
2184
+ * Puts removed redactions back, each at its index, by rising index. It's
2185
+ * what undoes {@link RemoveRedactionsCommand}: the reducer applies it, but
2186
+ * it isn't part of the portable command format (ADR 0009).
2187
+ *
2188
+ * @public
2189
+ */
2190
+ declare interface RestoreRedactionsCommand {
2191
+ readonly type: "image.restoreRedactions";
2192
+ readonly entries: readonly {
2193
+ readonly at: number;
2194
+ readonly redaction: ImageRedaction;
2195
+ }[];
2196
+ }
2197
+
2198
+ /**
2199
+ * Puts removed strokes back, each at its index, by rising index. It's what
2200
+ * undoes {@link RemoveStrokesCommand}: the reducer applies it, but it isn't
2201
+ * part of the portable command format (ADR 0009).
2202
+ *
2203
+ * @public
2204
+ */
2205
+ declare interface RestoreStrokesCommand {
2206
+ readonly type: "image.restoreStrokes";
2207
+ readonly key: string;
2208
+ readonly entries: readonly {
2209
+ readonly at: number;
2210
+ readonly stroke: ImageStroke;
2211
+ }[];
2212
+ }
2213
+
1435
2214
  /**
1436
2215
  * Sets or removes the base's crop, in whole pixels of the oriented source.
1437
2216
  *
@@ -1463,6 +2242,18 @@ declare interface SetFilterCommand {
1463
2242
  readonly filter: ImageFilter | null;
1464
2243
  }
1465
2244
 
2245
+ /**
2246
+ * Sets the whole order of the layers: every key, once. It's what undoes
2247
+ * {@link MoveLayersCommand}: the reducer applies it, but it isn't part of
2248
+ * the portable command format (ADR 0009).
2249
+ *
2250
+ * @public
2251
+ */
2252
+ declare interface SetLayerOrderCommand {
2253
+ readonly type: "image.setLayerOrder";
2254
+ readonly keys: readonly string[];
2255
+ }
2256
+
1466
2257
  /**
1467
2258
  * Sets one metadata field to keep on export. An empty value keeps nothing.
1468
2259
  *
@@ -1494,6 +2285,46 @@ declare interface SetOutputCommand {
1494
2285
  readonly output: ImageOutput;
1495
2286
  }
1496
2287
 
2288
+ /**
2289
+ * Sets the whole order of the redactions: every key, once. It's what undoes
2290
+ * {@link MoveRedactionsCommand}: the reducer applies it, but it isn't part
2291
+ * of the portable command format (ADR 0009).
2292
+ *
2293
+ * @public
2294
+ */
2295
+ declare interface SetRedactionOrderCommand {
2296
+ readonly type: "image.setRedactionOrder";
2297
+ readonly keys: readonly string[];
2298
+ }
2299
+
2300
+ /**
2301
+ * Sets some fields of some layers: their boxes after a move, their opacity,
2302
+ * a text layer's text. `props` may hold any field of the layer's kind except
2303
+ * `key` and `kind`.
2304
+ *
2305
+ * @public
2306
+ */
2307
+ declare interface UpdateLayersCommand {
2308
+ readonly type: "image.updateLayers";
2309
+ readonly updates: readonly {
2310
+ readonly key: string;
2311
+ readonly props: Readonly<Record<string, unknown>>;
2312
+ }[];
2313
+ }
2314
+
2315
+ /**
2316
+ * Sets some fields of some redactions, such as their regions after a move.
2317
+ *
2318
+ * @public
2319
+ */
2320
+ declare interface UpdateRedactionsCommand {
2321
+ readonly type: "image.updateRedactions";
2322
+ readonly updates: readonly {
2323
+ readonly key: string;
2324
+ readonly props: ImageRedactionProps;
2325
+ }[];
2326
+ }
2327
+
1497
2328
  /**
1498
2329
  * The session's snapshot, re-rendering whenever it changes, through
1499
2330
  * `useSyncExternalStore`, so it's safe with concurrent and server rendering.
@@ -1515,7 +2346,7 @@ export declare function useImageEditorState(): readonly [ImageEditorState, Store
1515
2346
  *
1516
2347
  * @public
1517
2348
  */
1518
- export declare function useImageMessages(): Messages<ImageMessageCatalogue>;
2349
+ export declare function useImageMessages(): Messages<ImageEditorMessageCatalogue>;
1519
2350
 
1520
2351
  /**
1521
2352
  * The session of the nearest `ImageEditorProvider`, to open images, run