js-draw 1.20.3 → 1.21.2

package/dist/cjs/util/ClipboardHandler.js

@@ -25,8 +25,9 @@ mime.endsWith('+xml') || mime.startsWith('text/');
  * js-draw clipboard events.
  */
 class ClipboardHandler {
-    constructor(editor) {
+    constructor(editor, callbacks) {
         this.editor = editor;
+        this.callbacks = callbacks;
         _ClipboardHandler_preferClipboardEvents.set(this, false);
     }
     /**
@@ -37,7 +38,27 @@ class ClipboardHandler {
      * 				`navigator.clipboard` will be used instead.
      * @returns true if the paste event was handled by the editor.
      */
-    async paste(event) {
+    paste(event) {
+        const onError = (error) => {
+            if (this.callbacks?.onPasteError) {
+                this.callbacks.onPasteError(error);
+                return Promise.resolve(false);
+            }
+            else {
+                throw error;
+            }
+        };
+        try {
+            // Use .catch rather than `async` to prevent future modifications from
+            // moving clipboard handling logic out of user event handlers.
+            // In the past, `await`s have caused permissions issues in some browsers.
+            return this.pasteInternal(event).catch(onError);
+        }
+        catch (error) {
+            return onError(error);
+        }
+    }
+    async pasteInternal(event) {
         const editor = this.editor;
         const clipboardData = event?.dataTransfer ?? event?.clipboardData ?? null;
         const hasEvent = !!clipboardData;
@@ -136,45 +157,82 @@ class ClipboardHandler {
      * images.
      */
     copy(event) {
-        const mimeToData = Object.create(null);
+        const onError = (error) => {
+            if (this.callbacks?.onCopyError) {
+                this.callbacks.onCopyError(error);
+                return Promise.resolve();
+            }
+            else {
+                throw error;
+            }
+        };
+        try {
+            // As above, use `.catch` to be certain that certain copyInternal
+            // is run now, before returning.
+            return this.copyInternal(event).catch(onError);
+        }
+        catch (error) {
+            return onError(error);
+        }
+    }
+    copyInternal(event) {
+        const mimeToData = new Map();
         if (this.editor.toolController.dispatchInputEvent({
             kind: inputEvents_1.InputEvtType.CopyEvent,
             setData: (mime, data) => {
-                mimeToData[mime] = data;
+                mimeToData.set(mime, data);
             },
         })) {
             event?.preventDefault();
         }
-        const mimeTypes = Object.keys(mimeToData);
+        const mimeTypes = [...mimeToData.keys()];
         const hasNonTextMimeTypes = mimeTypes.some(mime => !isTextMimeType(mime));
-        const copyToEvent = () => {
+        const copyToEvent = (reason) => {
             if (!event) {
-                throw new Error('Unable to paste -- no event provided.');
+                throw new Error(`Unable to copy -- no event provided${reason ? `. Original error: ${reason}` : ''}`);
             }
-            for (const key in mimeToData) {
-                const value = mimeToData[key];
+            for (const [key, value] of mimeToData.entries()) {
                 if (typeof value === 'string') {
                     event.clipboardData?.setData(key, value);
                 }
             }
         };
         const copyToClipboardApi = () => {
-            const mappedMimeToData = Object.create(null);
-            const mimeMapping = {
-                // image/svg+xml is unsupported in Chrome.
-                'image/svg+xml': 'text/html',
-            };
-            for (const key in mimeToData) {
-                const data = mimeToData[key];
-                const mappedKey = mimeMapping[key] || key;
-                if (typeof data === 'string') {
-                    mappedMimeToData[mappedKey] = new Blob([new TextEncoder().encode(data)], { type: mappedKey });
+            const mapInternalDataToBrowserData = (originalMimeToData) => {
+                const mappedMimeToData = Object.create(null);
+                for (const [key, data] of originalMimeToData.entries()) {
+                    if (typeof data === 'string') {
+                        const loadedData = new Blob([new TextEncoder().encode(data)], { type: key });
+                        mappedMimeToData[key] = loadedData;
+                    }
+                    else {
+                        mappedMimeToData[key] = data;
+                    }
+                    // Different platforms have varying support for different clipboard MIME types:
+                    // - As of September 2024, image/svg+xml is unsupported on iOS
+                    // - text/html is unsupported on Chrome/Android (and perhaps Chrome on other platforms).
+                    //    - See https://issues.chromium.org/issues/40851502
+                    if (key === 'image/svg+xml') {
+                        mappedMimeToData['text/html'] ??= mappedMimeToData[key];
+                    }
                 }
-                else {
-                    mappedMimeToData[mappedKey] = data;
+                return mappedMimeToData;
+            };
+            const removeUnsupportedMime = (originalMimeToData) => {
+                const filteredMimeToData = Object.create(null);
+                for (const [key, data] of Object.entries(originalMimeToData)) {
+                    // Browser support for ClipboardItem.supports is limited as of mid 2024. However, some browsers
+                    // that do support `.supports` throw an exception when attempting to copy an unsupported MIME type
+                    // (e.g. Firefox).
+                    const unsupported = 'supports' in ClipboardItem && typeof ClipboardItem.supports === 'function' && !ClipboardItem.supports(key);
+                    if (!unsupported) {
+                        filteredMimeToData[key] = data;
+                    }
                 }
-            }
-            return navigator.clipboard.write([new ClipboardItem(mappedMimeToData)]);
+                return filteredMimeToData;
+            };
+            const browserMimeToData = removeUnsupportedMime(mapInternalDataToBrowserData(mimeToData));
+            return navigator.clipboard.write([new ClipboardItem(browserMimeToData)]);
         };
         const supportsClipboardApi = (typeof ClipboardItem !== 'undefined'
             && typeof navigator?.clipboard?.write !== 'undefined');
@@ -183,7 +241,7 @@ class ClipboardHandler {
             const fallBackToCopyEvent = (reason) => {
                 console.warn('Unable to copy to the clipboard API. Future calls to .copy will use ClipboardEvents if possible.', reason);
                 __classPrivateFieldSet(this, _ClipboardHandler_preferClipboardEvents, true, "f");
-                copyToEvent();
+                copyToEvent(reason);
             };
             try {
                 clipboardApiPromise = copyToClipboardApi();

package/dist/cjs/version.js

@@ -6,5 +6,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @internal
  */
 exports.default = {
-    number: '1.20.3',
+    number: '1.21.2',
 };

package/dist/mjs/Editor.d.ts

@@ -1,7 +1,7 @@
 import EditorImage from './image/EditorImage';
 import ToolController from './tools/ToolController';
 import { EditorNotifier, ImageLoader } from './types';
-import { HTMLPointerEventFilter, InputEvtType } from './inputEvents';
+import { HTMLPointerEventFilter, InputEvtType, PointerEvtType } from './inputEvents';
 import Command from './commands/Command';
 import UndoRedoHistory from './UndoRedoHistory';
 import Viewport from './Viewport';
@@ -68,8 +68,8 @@ export interface EditorSettings {
      */
     notices: AboutDialogEntry[];
     /**
-     * Information about the app/website js-draw is running within
-     * to show at the beginning of the about dialog.
+     * Information about the app/website js-draw is running within. This is shown
+     * at the beginning of the about dialog.
      */
     appInfo: {
         name: string;
@@ -291,8 +291,18 @@ export declare class Editor {
      * ```
      */
     getRootElement(): HTMLElement;
-    /** @param fractionLoaded - should be a number from 0 to 1, where 1 represents completely loaded. */
+    /**
+     * @returns the bounding box of the main rendering region of the editor in the HTML viewport.
+     *
+     * @internal
+     */
+    getOutputBBoxInDOM(): Rect2;
+    /**
+     * Shows a "Loading..." message.
+     * @param fractionLoaded - should be a number from 0 to 1, where 1 represents completely loaded.
+     */
     showLoadingWarning(fractionLoaded: number): void;
+    /** @see {@link showLoadingWarning} */
     hideLoadingWarning(): void;
     private previousAccessibilityAnnouncement;
     /**
@@ -389,7 +399,12 @@ export declare class Editor {
     setReadOnly(readOnly: boolean): void;
     isReadOnlyReactiveValue(): ReactiveValue<boolean>;
     isReadOnly(): MutableReactiveValue<boolean>;
-    /** `apply` a command. `command` will be announced for accessibility. */
+    /**
+     * `apply` a command. `command` will be announced for accessibility.
+     *
+     * **Example**:
+     * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
+     */
     dispatch(command: Command, addToHistory?: boolean): void | Promise<void>;
     /**
      * Dispatches a command without announcing it. By default, does not add to history.
@@ -414,7 +429,13 @@ export declare class Editor {
      * has been applied.
      */
     asyncApplyOrUnapplyCommands(commands: Command[], apply: boolean, updateChunkSize: number): Promise<void>;
+    /** @see {@link asyncApplyOrUnapplyCommands } */
     asyncApplyCommands(commands: Command[], chunkSize: number): Promise<void>;
+    /**
+     * @see {@link asyncApplyOrUnapplyCommands}
+     *
+     * If `unapplyInReverseOrder`, commands are reversed before unapplying.
+     */
     asyncUnapplyCommands(commands: Command[], chunkSize: number, unapplyInReverseOrder?: boolean): Promise<void>;
     private announceUndoCallback;
     private announceRedoCallback;
@@ -492,7 +513,7 @@ export declare class Editor {
      * @deprecated
      * @see {@link sendPenEvent} {@link sendTouchEvent}
      */
-    sendPenEvent(eventType: InputEvtType.PointerDownEvt | InputEvtType.PointerMoveEvt | InputEvtType.PointerUpEvt, point: Point2, allPointers?: Pointer[]): void;
+    sendPenEvent(eventType: PointerEvtType, point: Point2, allPointers?: Pointer[]): void;
     /**
      * Adds all components in `components` such that they are in the center of the screen.
      * This is a convenience method that creates **and applies** a single command.

package/dist/mjs/Editor.mjs

@@ -5,7 +5,7 @@ import  { InputEvtType, keyUpEventFromHTMLEvent, keyPressEventFromHTMLEvent }  f
 import  UndoRedoHistory  from './UndoRedoHistory.mjs';
 import  Viewport  from './Viewport.mjs';
 import  EventDispatcher  from './EventDispatcher.mjs';
-import { Vec2, Vec3, Color4, Mat33 } from '@js-draw/math';
+import { Vec2, Vec3, Color4, Mat33, Rect2 } from '@js-draw/math';
 import  Display, { RenderingMode }  from './rendering/Display.mjs';
 import  SVGLoader  from './SVGLoader/SVGLoader.mjs';
 import  Pointer  from './Pointer.mjs';
@@ -29,6 +29,7 @@ import  { MutableReactiveValue }  from './util/ReactiveValue.mjs';
 import  listenForKeyboardEventsFrom  from './util/listenForKeyboardEventsFrom.mjs';
 import  mitLicenseAttribution  from './util/mitLicenseAttribution.mjs';
 import  ClipboardHandler  from './util/ClipboardHandler.mjs';
+import  ContextMenuRecognizer  from './tools/InputFilter/ContextMenuRecognizer.mjs';
 /**
  * The main entrypoint for the full editor.
  *
@@ -164,6 +165,7 @@ export class Editor {
         this.toolController = new ToolController(this, this.localization);
         // TODO: Make this pipeline configurable (e.g. allow users to add global input stabilization)
         this.toolController.addInputMapper(StrokeKeyboardControl.fromEditor(this));
+        this.toolController.addInputMapper(new ContextMenuRecognizer());
         parent.appendChild(this.container);
         this.viewport.updateScreenSize(Vec2.of(this.display.width, this.display.height));
         this.registerListeners();
@@ -221,12 +223,24 @@ export class Editor {
     getRootElement() {
         return this.container;
     }
-    /** @param fractionLoaded - should be a number from 0 to 1, where 1 represents completely loaded. */
+    /**
+     * @returns the bounding box of the main rendering region of the editor in the HTML viewport.
+     *
+     * @internal
+     */
+    getOutputBBoxInDOM() {
+        return Rect2.of(this.renderingRegion.getBoundingClientRect());
+    }
+    /**
+     * Shows a "Loading..." message.
+     * @param fractionLoaded - should be a number from 0 to 1, where 1 represents completely loaded.
+     */
     showLoadingWarning(fractionLoaded) {
         const loadingPercent = Math.round(fractionLoaded * 100);
         this.loadingWarning.innerText = this.localization.loading(loadingPercent);
         this.loadingWarning.style.display = 'block';
     }
+    /** @see {@link showLoadingWarning} */
     hideLoadingWarning() {
         this.loadingWarning.style.display = 'none';
         this.announceForAccessibility(this.localization.doneLoading);
@@ -340,8 +354,8 @@ export class Editor {
             delta = Vec3.of(0, 0, event.deltaY);
         }
         // Ensure that `pos` is relative to `this.renderingRegion`
-        const bbox = this.renderingRegion.getBoundingClientRect();
-        const pos = Vec2.of(event.clientX, event.clientY).minus(Vec2.of(bbox.left, bbox.top));
+        const bbox = this.getOutputBBoxInDOM();
+        const pos = Vec2.of(event.clientX, event.clientY).minus(bbox.topLeft);
         if (this.toolController.dispatchInputEvent({
             kind: InputEvtType.WheelEvt,
             delta,
@@ -689,7 +703,12 @@ export class Editor {
     isReadOnly() {
         return this.readOnly;
     }
-    /** `apply` a command. `command` will be announced for accessibility. */
+    /**
+     * `apply` a command. `command` will be announced for accessibility.
+     *
+     * **Example**:
+     * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
+     */
     dispatch(command, addToHistory = true) {
         const dispatchResult = this.dispatchNoAnnounce(command, addToHistory);
         const commandDescription = command.description(this, this.localization);
@@ -750,12 +769,15 @@ export class Editor {
         this.display.setDraftMode(false);
         this.hideLoadingWarning();
     }
-    // @see {@link asyncApplyOrUnapplyCommands }
+    /** @see {@link asyncApplyOrUnapplyCommands } */
     asyncApplyCommands(commands, chunkSize) {
         return this.asyncApplyOrUnapplyCommands(commands, true, chunkSize);
     }
-    // If `unapplyInReverseOrder`, commands are reversed before unapplying.
-    // @see {@link asyncApplyOrUnapplyCommands }
+    /**
+     * @see {@link asyncApplyOrUnapplyCommands}
+     *
+     * If `unapplyInReverseOrder`, commands are reversed before unapplying.
+     */
     asyncUnapplyCommands(commands, chunkSize, unapplyInReverseOrder = false) {
         if (unapplyInReverseOrder) {
             commands = [...commands]; // copy
@@ -1233,7 +1255,7 @@ export class Editor {
                 '',
                 '',
                 '== js-draw ==',
-                mitLicenseAttribution('2023 Henry Heino'),
+                mitLicenseAttribution('2023-2024 Henry Heino'),
                 '',
             ].join('\n'),
             minimized: true,

package/dist/mjs/SVGLoader/SVGLoader.mjs

@@ -54,7 +54,7 @@ export default class SVGLoader {
             try {
                 fill = Color4.fromString(fillAttribute);
             }
-            catch (e) {
+            catch {
                 console.error('Unknown fill color,', fillAttribute);
             }
         }
@@ -241,7 +241,7 @@ export default class SVGLoader {
                 supportedAttrs?.push(highpTransformAttribute);
             }
             catch (e) {
-                console.warn(`Unable to parse raw transform data, ${rawTransformData}. Falling back to CSS data.`);
+                console.warn(`Unable to parse raw transform data, ${rawTransformData}. Falling back to CSS data. Error:`, e);
             }
         }
         if (!transform) {

package/dist/mjs/Viewport.d.ts

@@ -78,14 +78,14 @@ export declare class Viewport {
         minus(v: Vec3): Vec3;
         dot(other: Vec3): number;
         cross(other: Vec3): Vec3;
-        scale(other: number | Vec3): Vec3;
+        scale(other: Vec3 | number): Vec3;
         orthog(): Vec3;
         extend(distance: number, direction: Vec3): Vec3;
         lerp(target: Vec3, fractionTo: number): Vec3;
         zip(other: Vec3, zip: (componentInThis: number, componentInOther: number) => number): Vec3;
         map(fn: (component: number, index: number) => number): Vec3;
         asArray(): [number, number, number];
-        eq(other: Vec3, fuzz?: number | undefined): boolean;
+        eq(other: Vec3, fuzz?: number): boolean;
         toString(): string;
     };
     /** Returns the size of one screen pixel in canvas units. */

package/dist/mjs/commands/Command.d.ts

@@ -1,5 +1,10 @@
 import Editor from '../Editor';
 import { EditorLocalization } from '../localization';
+/**
+ * A `Command` is an action that can be done, redone, and undone. It's used to enable undo/redo.
+ *
+ * See {@link Editor.dispatch}.
+ */
 export declare abstract class Command {
     abstract apply(editor: Editor): Promise<void> | void;
     abstract unapply(editor: Editor): Promise<void> | void;

package/dist/mjs/commands/Command.mjs

@@ -1,3 +1,8 @@
+/**
+ * A `Command` is an action that can be done, redone, and undone. It's used to enable undo/redo.
+ *
+ * See {@link Editor.dispatch}.
+ */
 export class Command {
     // Called when the command is being deleted
     onDrop(_editor) { }

package/dist/mjs/commands/SerializableCommand.d.ts

@@ -1,8 +1,15 @@
 import Editor from '../Editor';
 import Command from './Command';
 export type DeserializationCallback = (data: Record<string, any> | any[], editor: Editor) => SerializableCommand;
+/**
+ * A command that can be serialized to or deserialized from JSON. To allow a command to be deserialized, {@link SerializableCommand.register}
+ * must be called for each {@link SerializableCommand}.
+ *
+ * This is used to [allow collaborative editing](https://github.com/personalizedrefrigerator/js-draw/tree/main/docs/examples/example-collaborative).
+ */
 export default abstract class SerializableCommand extends Command {
     #private;
+    /** @param commandTypeId - A unique identifier for this command. */
     constructor(commandTypeId: string);
     protected abstract serializeToJSON(): string | Record<string, any> | any[];
     private static deserializationCallbacks;

package/dist/mjs/commands/SerializableCommand.mjs

@@ -11,7 +11,14 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _SerializableCommand_commandTypeId;
 import  Command  from './Command.mjs';
+/**
+ * A command that can be serialized to or deserialized from JSON. To allow a command to be deserialized, {@link SerializableCommand.register}
+ * must be called for each {@link SerializableCommand}.
+ *
+ * This is used to [allow collaborative editing](https://github.com/personalizedrefrigerator/js-draw/tree/main/docs/examples/example-collaborative).
+ */
 class SerializableCommand extends Command {
+    /** @param commandTypeId - A unique identifier for this command. */
     constructor(commandTypeId) {
         super();
         _SerializableCommand_commandTypeId.set(this, void 0);
@@ -32,6 +39,8 @@ class SerializableCommand extends Command {
     }
     // Convert a `string` containing JSON data (or the output of `JSON.parse`) into a
     // `Command`.
+    //
+    // Implementations should assume that `data` is untrusted.
     static deserialize(data, editor) {
         const json = typeof data === 'string' ? JSON.parse(data) : data;
         const commandType = json.commandType;

package/dist/mjs/dialogs/makeAboutDialog.d.ts

@@ -10,6 +10,6 @@ export interface AboutDialogEntry {
     minimized?: boolean;
 }
 declare const makeAboutDialog: (editor: Editor, entries: AboutDialogEntry[]) => {
-    close: () => void;
+    close: () => Promise<void>;
 };
 export default makeAboutDialog;

package/dist/mjs/dialogs/makeAboutDialog.mjs

@@ -1,24 +1,9 @@
+import  makeMessageDialog  from './makeMessageDialog.mjs';
 const makeAboutDialog = (editor, entries) => {
-    const overlay = document.createElement('div');
-    const { remove: removeOverlay } = editor.createHTMLOverlay(overlay);
-    overlay.classList.add('dialog-container', 'about-dialog-container');
-    const dialog = document.createElement('dialog');
-    const heading = document.createElement('h1');
-    heading.innerText = editor.localization.about;
-    heading.setAttribute('autofocus', 'true');
-    const closeButton = document.createElement('button');
-    closeButton.innerText = editor.localization.closeDialog;
-    closeButton.classList.add('close-button');
-    closeButton.onclick = () => removeOverlay();
-    overlay.onclick = event => {
-        if (event.target === overlay) {
-            removeOverlay();
-        }
-    };
-    const licenseContainer = document.createElement('div');
-    licenseContainer.classList.add('about-entry-container');
-    // Allow scrolling in the license container -- don't forward wheel events.
-    licenseContainer.onwheel = evt => evt.stopPropagation();
+    const dialog = makeMessageDialog(editor, {
+        title: editor.localization.about,
+        contentClassNames: ['about-dialog-content'],
+    });
     for (const entry of entries) {
         const container = document.createElement(entry.minimized ? 'details' : 'div');
         container.classList.add('about-entry');
@@ -38,14 +23,11 @@ const makeAboutDialog = (editor, entries) => {
             bodyText.innerText = entry.text;
             container.appendChild(bodyText);
         }
-        licenseContainer.appendChild(container);
+        dialog.appendChild(container);
     }
-    dialog.replaceChildren(heading, licenseContainer, closeButton);
-    overlay.replaceChildren(dialog);
-    dialog.show();
     return {
         close: () => {
-            removeOverlay();
+            return dialog.close();
         },
     };
 };

package/dist/mjs/dialogs/makeMessageDialog.d.ts

@@ -0,0 +1,11 @@
+import type Editor from '../Editor';
+export interface MessageDialogOptions {
+    title: string;
+    classNames?: string[];
+    contentClassNames?: string[];
+}
+declare const makeAboutDialog: (editor: Editor, options: MessageDialogOptions) => {
+    close: () => Promise<void>;
+    appendChild: (child: Node) => void;
+};
+export default makeAboutDialog;

package/dist/mjs/dialogs/makeMessageDialog.mjs

@@ -0,0 +1,51 @@
+import  waitForTimeout  from '../util/waitForTimeout.mjs';
+const makeAboutDialog = (editor, options) => {
+    const overlay = document.createElement('div');
+    const { remove: removeOverlay } = editor.createHTMLOverlay(overlay);
+    overlay.classList.add('dialog-container', 'message-dialog-container', ...(options.classNames ?? []));
+    const dialog = document.createElement('dialog');
+    const contentWrapper = document.createElement('div');
+    contentWrapper.classList.add('message-dialog-content', ...(options.contentClassNames ?? []));
+    const heading = document.createElement('h1');
+    heading.textContent = options.title;
+    heading.setAttribute('autofocus', 'true');
+    const closeButton = document.createElement('button');
+    closeButton.innerText = editor.localization.closeDialog;
+    closeButton.classList.add('close');
+    const scrollRegion = document.createElement('div');
+    scrollRegion.classList.add('scroll');
+    // Allow scrolling in the scrollable container -- don't forward wheel events.
+    scrollRegion.onwheel = evt => evt.stopPropagation();
+    contentWrapper.replaceChildren(heading, scrollRegion, closeButton);
+    dialog.replaceChildren(contentWrapper);
+    overlay.replaceChildren(dialog);
+    const closeTimeout = 300;
+    dialog.style.setProperty('--close-delay', `${closeTimeout}ms`);
+    const closeDialog = async () => {
+        dialog.classList.add('-closing');
+        await waitForTimeout(closeTimeout);
+        dialog.close();
+    };
+    const addCloseListeners = () => {
+        dialog.addEventListener('pointerdown', event => {
+            if (event.target === dialog) {
+                void closeDialog();
+            }
+        });
+        dialog.onclose = () => {
+            removeOverlay();
+        };
+        closeButton.onclick = () => closeDialog();
+    };
+    addCloseListeners();
+    dialog.showModal();
+    return {
+        close: () => {
+            return closeDialog();
+        },
+        appendChild: (child) => {
+            scrollRegion.appendChild(child);
+        },
+    };
+};
+export default makeAboutDialog;

package/dist/mjs/image/EditorImage.d.ts

@@ -21,6 +21,9 @@ export type EditorImageNotifier = EventDispatcher<EditorImageEventType, {
  * 3. stop the render process early by returning `false`.
  */
 export type PreRenderComponentCallback = (component: AbstractComponent, componentsProcessed: number, totalComponents: number) => Promise<boolean>;
+/**
+ * Handles lookup/storage of elements in the image.
+ */
 export default class EditorImage {
     private root;
     private background;
@@ -88,7 +91,8 @@ export default class EditorImage {
      *
      * @see {@link Display.flatten}
      *
-     * @example
+     * **Example**:
+     *
      * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
      */
     static addElement(elem: AbstractComponent, applyByFlattening?: boolean): SerializableCommand;
@@ -199,6 +203,16 @@ export declare class ImageNode {
     getParent(): ImageNode | null;
     protected getChildrenIntersectingRegion(region: Rect2, isTooSmallFilter?: TooSmallToRenderCheck): ImageNode[];
     getChildrenOrSelfIntersectingRegion(region: Rect2): ImageNode[];
+    /**
+     * Returns a list of `ImageNode`s with content (and thus no children).
+     * Override getChildrenIntersectingRegion to customize how this method
+     * determines whether/which children are in `region`.
+     *
+     * @paran region - All resultant `ImageNode`s must intersect `region`.
+     * @param isTooSmall - If `isTooSmall` returns true for an image node, that node
+     *                     is excluded from the output.
+     *
+     */
     getLeavesIntersectingRegion(region: Rect2, isTooSmall?: TooSmallToRenderCheck): ImageNode[];
     getChildWithContent(target: AbstractComponent): ImageNode | null;
     getLeaves(): ImageNode[];

package/dist/mjs/image/EditorImage.mjs

@@ -20,7 +20,9 @@ export var EditorImageEventType;
     EditorImageEventType[EditorImageEventType["AutoresizeModeChanged"] = 1] = "AutoresizeModeChanged";
 })(EditorImageEventType || (EditorImageEventType = {}));
 let debugMode = false;
-// Handles lookup/storage of elements in the image
+/**
+ * Handles lookup/storage of elements in the image.
+ */
 class EditorImage {
     // @internal
     constructor() {
@@ -181,7 +183,8 @@ class EditorImage {
      *
      * @see {@link Display.flatten}
      *
-     * @example
+     * **Example**:
+     *
      * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
      */
     static addElement(elem, applyByFlattening = false) {
@@ -518,9 +521,16 @@ export class ImageNode {
         }
         return this.getChildrenIntersectingRegion(region);
     }
-    // Returns a list of `ImageNode`s with content (and thus no children).
-    // Override getChildrenIntersectingRegion to customize how this method
-    // determines whether/which children are in `region`.
+    /**
+     * Returns a list of `ImageNode`s with content (and thus no children).
+     * Override getChildrenIntersectingRegion to customize how this method
+     * determines whether/which children are in `region`.
+     *
+     * @paran region - All resultant `ImageNode`s must intersect `region`.
+     * @param isTooSmall - If `isTooSmall` returns true for an image node, that node
+     *                     is excluded from the output.
+     *
+     */
     getLeavesIntersectingRegion(region, isTooSmall) {
         const result = [];
         const workList = [];