bpmn-js 11.4.1 → 12.0.0

package/dist/bpmn-viewer.development.js

@@ -1,5 +1,5 @@
 /*!
- * bpmn-js - bpmn-viewer v11.4.1
+ * bpmn-js - bpmn-viewer v12.0.0
  *
  * Copyright (c) 2014-present, camunda Services GmbH
  *
@@ -8,7 +8,7 @@
  *
  * Source Code: https://github.com/bpmn-io/bpmn-js
  *
- * Date: 2023-02-16
+ * Date: 2023-03-29
  */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
@@ -447,6 +447,14 @@
 
   var DEFAULT_RENDER_PRIORITY$1 = 1000;
 
+  /**
+   * @typedef {import('../model').Base} Base
+   * @typedef {import('../model').Connection} Connection
+   * @typedef {import('../model').Shape} Shape
+   *
+   * @typedef {import('../core/EventBus').default} EventBus
+   */
+
   /**
    * The base implementation of shape and connection renderers.
    *
@@ -485,52 +493,51 @@
   }
 
   /**
-   * Should check whether *this* renderer can render
-   * the element/connection.
+   * Checks whether an element can be rendered.
    *
-   * @param {element} element
+   * @param {Base} element The element to be rendered.
    *
-   * @returns {boolean}
+   * @returns {boolean} Whether the element can be rendered.
    */
-  BaseRenderer.prototype.canRender = function() {};
+  BaseRenderer.prototype.canRender = function(element) {};
 
   /**
-   * Provides the shape's snap svg element to be drawn on the `canvas`.
+   * Draws a shape.
    *
-   * @param {djs.Graphics} visuals
-   * @param {Shape} shape
+   * @param {SVGElement} visuals The SVG element to draw the shape into.
+   * @param {Shape} shape The shape to be drawn.
    *
-   * @returns {Snap.svg} [returns a Snap.svg paper element ]
+   * @returns {SVGElement} The SVG element of the shape drawn.
    */
-  BaseRenderer.prototype.drawShape = function() {};
+  BaseRenderer.prototype.drawShape = function(visuals, shape) {};
 
   /**
-   * Provides the shape's snap svg element to be drawn on the `canvas`.
+   * Draws a connection.
    *
-   * @param {djs.Graphics} visuals
-   * @param {Connection} connection
+   * @param {SVGElement} visuals The SVG element to draw the connection into.
+   * @param {Connection} connection The connection to be drawn.
    *
-   * @returns {Snap.svg} [returns a Snap.svg paper element ]
+   * @returns {SVGElement} The SVG element of the connection drawn.
    */
-  BaseRenderer.prototype.drawConnection = function() {};
+  BaseRenderer.prototype.drawConnection = function(visuals, connection) {};
 
   /**
-   * Gets the SVG path of a shape that represents it's visual bounds.
+   * Gets the SVG path of the graphical representation of a shape.
    *
-   * @param {Shape} shape
+   * @param {Shape} shape The shape.
    *
-   * @return {string} svg path
+   * @return {string} The SVG path of the shape.
    */
-  BaseRenderer.prototype.getShapePath = function() {};
+  BaseRenderer.prototype.getShapePath = function(shape) {};
 
   /**
-   * Gets the SVG path of a connection that represents it's visual bounds.
+   * Gets the SVG path of the graphical representation of a connection.
    *
-   * @param {Connection} connection
+   * @param {Connection} connection The connection.
    *
-   * @return {string} svg path
+   * @return {string} The SVG path of the connection.
    */
-  BaseRenderer.prototype.getConnectionPath = function() {};
+  BaseRenderer.prototype.getConnectionPath = function(connection) {};
 
   /**
    * Is an element of the given BPMN type?
@@ -1337,9 +1344,15 @@
   }
 
   /**
-   * @param { [ string, ...any[] ][] } elements
+   * @typedef {(string|number)[]} Component
    *
-   * @return { string }
+   * @typedef {import('../util/Types').Point} Point
+   */
+
+  /**
+   * @param {Component[]} elements
+   *
+   * @return {string}
    */
   function componentsToPath(elements) {
     return elements.flat().join(',').replace(/,?([A-z]),?/g, '$1');
@@ -1419,9 +1432,9 @@
   }
 
   /**
-   * @param { { x: number, y: number }[] } points
-   * @param { any } [attrs]
-   * @param { number } [radius]
+   * @param {Point[]} points
+   * @param {*} [attrs]
+   * @param {number} [radius]
    *
    * @return {SVGElement}
    */
@@ -1446,8 +1459,8 @@
   }
 
   /**
-   * @param { SVGElement } gfx
-   * @param { { x: number, y: number }[]} points
+   * @param {SVGElement} gfx
+   * @param {Point[]} points
    *
    * @return {SVGElement}
    */
@@ -2162,7 +2175,7 @@
   }
 
   /**
-   * @param {<SVGElement>} element
+   * @param {SVGElement} element
    * @param {number} x
    * @param {number} y
    * @param {number} angle
@@ -4242,6 +4255,10 @@
     return getRectPath(element);
   };
 
+  /**
+   * @typedef {import('../util/Types').Dimensions} Dimensions
+   */
+
   var DEFAULT_BOX_PADDING = 0;
 
   var DEFAULT_LABEL_SIZE$1 = {
@@ -4315,7 +4332,8 @@
    *
    * Alters the lines passed.
    *
-   * @param  {Array<string>} lines
+   * @param {string[]} lines
+   *
    * @return {Object} the line descriptor, an object { width, height, text }
    */
   function layoutNext(lines, maxWidth, fakeText) {
@@ -4360,8 +4378,9 @@
    * Shortens a line based on spacing and hyphens.
    * Returns the shortened result on success.
    *
-   * @param  {string} line
-   * @param  {number} maxLength the maximum characters of the string
+   * @param {string} line
+   * @param {number} maxLength the maximum characters of the string
+   *
    * @return {string} the shortened string
    */
   function semanticShorten(line, maxLength) {
@@ -5201,6 +5220,10 @@
     pathMap: [ 'type', PathMap ]
   };
 
+  /**
+   * @typedef {import('./').Replacements} Replacements
+   */
+
   /**
    * A simple translation stub to be used for multi-language support
    * in diagrams. Can be easily replaced with a more sophisticated
@@ -5215,7 +5238,7 @@
    * }
    *
    * @param {string} template to interpolate
-   * @param {Object} [replacements] a map with substitutes
+   * @param {Replacements} [replacements] a map with substitutes
    *
    * @return {string} the translated string
    */
@@ -5368,8 +5391,6 @@
     }, size);
   }
 
-  var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
-
   function getDefaultExportFromCjs (x) {
   	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
   }
@@ -5386,9 +5407,9 @@
   /**
    * Convert the given bounds to a { top, left, bottom, right } descriptor.
    *
-   * @param {Bounds|Point} bounds
+   * @param {Point|Rect} bounds
    *
-   * @return {Object}
+   * @return {RectTRBL}
    */
   function asTRBL(bounds) {
     return {
@@ -5403,9 +5424,9 @@
   /**
    * Convert a { top, left, bottom, right } to an objects bounds.
    *
-   * @param {Object} trbl
+   * @param {RectTRBL} trbl
    *
-   * @return {Bounds}
+   * @return {Rect}
    */
   function asBounds(trbl) {
     return {
@@ -5420,7 +5441,7 @@
   /**
    * Get the mid of the given bounds or point.
    *
-   * @param {Bounds|Point} bounds
+   * @param {Point|Rect} bounds
    *
    * @return {Point}
    */
@@ -5435,7 +5456,7 @@
   /**
    * Get the mid of the given Connection.
    *
-   * @param {djs.Base.Connection} connection
+   * @param {Connection} connection
    *
    * @return {Point}
    */
@@ -5494,7 +5515,7 @@
   /**
    * Get the mid of the given Element.
    *
-   * @param {djs.Base.Connection} connection
+   * @param {Connection} connection
    *
    * @return {Point}
    */
@@ -5904,6 +5925,14 @@
     return isPrimaryButton(event) && originalEvent.shiftKey;
   }
 
+  /**
+   * @typedef {import('../../model').Base} Base
+   *
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('../../draw/Styles').default} Styles
+   */
+
   function allowAll(event) { return true; }
 
   function allowPrimaryAndAuxiliary(event) {
@@ -5933,6 +5962,8 @@
    * prevents the original DOM operation.
    *
    * @param {EventBus} eventBus
+   * @param {ElementRegistry} elementRegistry
+   * @param {Styles} styles
    */
   function InteractionEvents(eventBus, elementRegistry, styles) {
 
@@ -5942,8 +5973,8 @@
      * Fire an interaction event.
      *
      * @param {string} type local event name, e.g. element.click.
-     * @param {DOMEvent} event native event
-     * @param {djs.model.Base} [element] the diagram element to emit the event on;
+     * @param {MouseEvent|TouchEvent} event native event
+     * @param {Base} [element] the diagram element to emit the event on;
      *                                   defaults to the event target
      */
     function fire(type, event, element) {
@@ -6025,8 +6056,8 @@
      * on the target shape or connection.
      *
      * @param {string} eventName the name of the triggered DOM event
-     * @param {MouseEvent} event
-     * @param {djs.model.Base} targetElement
+     * @param {MouseEvent|TouchEvent} event
+     * @param {Base} targetElement
      */
     function triggerMouseEvent(eventName, event, targetElement) {
 
@@ -6192,7 +6223,7 @@
     /**
      * Create default hit for the given element.
      *
-     * @param {djs.model.Base} element
+     * @param {Base} element
      * @param {SVGElement} gfx
      *
      * @return {SVGElement} created hit
@@ -6264,8 +6295,8 @@
     /**
      * Update default hit of the element.
      *
-     * @param  {djs.model.Base} element
-     * @param  {SVGElement} gfx
+     * @param {Base} element
+     * @param {SVGElement} gfx
      *
      * @return {SVGElement} updated hit
      */
@@ -6313,7 +6344,7 @@
    * @event element.hover
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6324,7 +6355,7 @@
    * @event element.out
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6335,7 +6366,7 @@
    * @event element.click
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6346,7 +6377,7 @@
    * @event element.dblclick
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6357,7 +6388,7 @@
    * @event element.mousedown
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6368,7 +6399,7 @@
    * @event element.mouseup
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6380,7 +6411,7 @@
    * @event element.contextmenu
    *
    * @type {Object}
-   * @property {djs.model.Base} element
+   * @property {Base} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6394,10 +6425,10 @@
    * Returns the surrounding bbox for all elements in
    * the array or the element primitive.
    *
-   * @param {Array<djs.model.Shape>|djs.model.Shape} elements
+   * @param {Base|Base[]} elements
    * @param {boolean} [stopRecursion=false]
    *
-   * @return {Bounds}
+   * @return {Rect}
    */
   function getBBox(elements, stopRecursion) {
 
@@ -6468,6 +6499,12 @@
 
   var LOW_PRIORITY$2 = 500;
 
+  /**
+   * @typedef {import('../../model').Base} Base
+   *
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('../../draw/Styles').default} Styles
+   */
 
   /**
    * @class
@@ -6477,9 +6514,8 @@
    *
    * @param {EventBus} eventBus
    * @param {Styles} styles
-   * @param {ElementRegistry} elementRegistry
    */
-  function Outline(eventBus, styles, elementRegistry) {
+  function Outline(eventBus, styles) {
 
     this.offset = 6;
 
@@ -6537,8 +6573,8 @@
    * Updates the outline of a shape respecting the dimension of the
    * element and an outline offset.
    *
-   * @param  {SVGElement} outline
-   * @param  {djs.model.Base} element
+   * @param {SVGElement} outline
+   * @param {Base} element
    */
   Outline.prototype.updateShapeOutline = function(outline, element) {
 
@@ -6556,8 +6592,8 @@
    * Updates the outline of a connection respecting the bounding box of
    * the connection and an outline offset.
    *
-   * @param  {SVGElement} outline
-   * @param  {djs.model.Base} element
+   * @param {SVGElement} outline
+   * @param {Base} element
    */
   Outline.prototype.updateConnectionOutline = function(outline, connection) {
 
@@ -6580,13 +6616,17 @@
     outline: [ 'type', Outline ]
   };
 
+  /**
+   * @typedef {import('../../core/EventBus').default} EventBus
+   */
+
   /**
    * A service that offers the current selection in a diagram.
    * Offers the api to control the selection, too.
    *
    * @class
    *
-   * @param {EventBus} eventBus the event bus
+   * @param {EventBus} eventBus
    */
   function Selection(eventBus, canvas) {
 
@@ -6642,8 +6682,8 @@
    *
    * @method Selection#select
    *
-   * @param  {Object|Object[]} elements element or array of elements to be selected
-   * @param  {boolean} [add] whether the element(s) should be appended to the current selection, defaults to false
+   * @param {Object|Object[]} elements element or array of elements to be selected
+   * @param {boolean} [add] whether the element(s) should be appended to the current selection, defaults to false
    */
   Selection.prototype.select = function(elements, add) {
     var selectedElements = this._selectedElements,
@@ -6682,6 +6722,12 @@
     this._eventBus.fire('selection.changed', { oldSelection: oldSelection, newSelection: selectedElements });
   };
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('./Selection').default} Selection
+   */
+
   var MARKER_HOVER = 'hover',
       MARKER_SELECTED = 'selected';
 
@@ -6698,6 +6744,7 @@
    *
    * @param {Canvas} canvas
    * @param {EventBus} eventBus
+   * @param {Selection} selection
    */
   function SelectionVisuals(canvas, eventBus, selection) {
     this._canvas = canvas;
@@ -6803,6 +6850,19 @@
     };
   }
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('./Selection').default} Selection
+   */
+
+  /**
+   * @param {EventBus} eventBus
+   * @param {Selection} selection
+   * @param {Canvas} canvas
+   * @param {ElementRegistry} elementRegistry
+   */
   function SelectionBehavior(eventBus, selection, canvas, elementRegistry) {
 
     // Select elements on create
@@ -6923,9 +6983,8 @@
   /**
    * Util that provides unique IDs.
    *
-   * @class djs.util.IdGenerator
+   * @class
    * @constructor
-   * @memberOf djs.util
    *
    * The ids can be customized via a given prefix and contain a random value to avoid collisions.
    *
@@ -6940,8 +6999,6 @@
   /**
    * Returns a next unique ID.
    *
-   * @method djs.util.IdGenerator#next
-   *
    * @returns {string} the id
    */
   IdGenerator.prototype.next = function() {
@@ -6953,6 +7010,18 @@
 
   var LOW_PRIORITY$1 = 500;
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   *
+   * @typedef {import('./Overlays').Overlay} Overlay
+   * @typedef {import('./Overlays').OverlayAttrs} OverlayAttrs
+   * @typedef {import('./Overlays').OverlayContainer} OverlayContainer
+   * @typedef {import('./Overlays').OverlaysConfig} OverlaysConfig
+   * @typedef {import('./Overlays').OverlaysConfigDefault} OverlaysConfigDefault
+   * @typedef {import('./Overlays').OverlaysFilter} OverlaysFilter
+   */
 
   /**
    * A service that allows users to attach overlays to diagram elements.
@@ -6962,6 +7031,7 @@
    * @example
    *
    * // add a pink badge on the top left of the shape
+   *
    * overlays.add(someShape, {
    *   position: {
    *     top: -5,
@@ -7013,19 +7083,21 @@
    *     }
    * }
    *
-   * @param {Object} config
+   * @param {OverlaysConfig} config
    * @param {EventBus} eventBus
    * @param {Canvas} canvas
    * @param {ElementRegistry} elementRegistry
    */
   function Overlays(config, eventBus, canvas, elementRegistry) {
-
     this._eventBus = eventBus;
     this._canvas = canvas;
     this._elementRegistry = elementRegistry;
 
     this._ids = ids;
 
+    /**
+     * @type {OverlaysConfigDefault}
+     */
     this._overlayDefaults = assign$1({
 
       // no show constraints
@@ -7036,16 +7108,18 @@
     }, config && config.defaults);
 
     /**
-     * Mapping overlayId -> overlay
+     * @type {Map<string, Overlay>}
      */
     this._overlays = {};
 
     /**
-     * Mapping elementId -> overlay container
+     * @type {OverlayContainer[]}
      */
     this._overlayContainers = [];
 
-    // root html element for all overlays
+    /**
+     * @type {HTMLElement}
+     */
     this._overlayRoot = createRoot(canvas.getContainer());
 
     this._init();
@@ -7061,12 +7135,12 @@
 
 
   /**
-   * Returns the overlay with the specified id or a list of overlays
+   * Returns the overlay with the specified ID or a list of overlays
    * for an element with a given type.
    *
    * @example
    *
-   * // return the single overlay with the given id
+   * // return the single overlay with the given ID
    * overlays.get('some-id');
    *
    * // return all overlays for the shape
@@ -7075,16 +7149,12 @@
    * // return all overlays on shape with type 'badge'
    * overlays.get({ element: someShape, type: 'badge' });
    *
-   * // shape can also be specified as id
+   * // shape can also be specified as ID
    * overlays.get({ element: 'element-id', type: 'badge' });
    *
+   * @param {OverlaysFilter} search The filter to be used to find the overlay(s).
    *
-   * @param {Object} search
-   * @param {string} [search.id]
-   * @param {string|djs.model.Base} [search.element]
-   * @param {string} [search.type]
-   *
-   * @return {Object|Array<Object>} the overlay(s)
+   * @return {Overlay|Overlay[]} The overlay(s).
    */
   Overlays.prototype.get = function(search) {
 
@@ -7116,27 +7186,13 @@
   };
 
   /**
-   * Adds a HTML overlay to an element.
-   *
-   * @param {string|djs.model.Base}   element   attach overlay to this shape
-   * @param {string}                  [type]    optional type to assign to the overlay
-   * @param {Object}                  overlay   the overlay configuration
+   * Adds an HTML overlay to an element.
    *
-   * @param {string|DOMElement}       overlay.html                 html element to use as an overlay
-   * @param {Object}                  [overlay.show]               show configuration
-   * @param {number}                  [overlay.show.minZoom]       minimal zoom level to show the overlay
-   * @param {number}                  [overlay.show.maxZoom]       maximum zoom level to show the overlay
-   * @param {Object}                  overlay.position             where to attach the overlay
-   * @param {number}                  [overlay.position.left]      relative to element bbox left attachment
-   * @param {number}                  [overlay.position.top]       relative to element bbox top attachment
-   * @param {number}                  [overlay.position.bottom]    relative to element bbox bottom attachment
-   * @param {number}                  [overlay.position.right]     relative to element bbox right attachment
-   * @param {boolean|Object}          [overlay.scale=true]         false to preserve the same size regardless of
-   *                                                               diagram zoom
-   * @param {number}                  [overlay.scale.min]
-   * @param {number}                  [overlay.scale.max]
+   * @param {Base|string} element The element to add the overlay to.
+   * @param {string} [type] An optional type that can be used to filter.
+   * @param {OverlayAttrs} overlay The overlay.
    *
-   * @return {string}                 id that may be used to reference the overlay for update or removal
+   * @return {string} The overlay's ID that can be used to get or remove it.
    */
   Overlays.prototype.add = function(element, type, overlay) {
 
@@ -7177,11 +7233,11 @@
 
 
   /**
-   * Remove an overlay with the given id or all overlays matching the given filter.
+   * Remove an overlay with the given ID or all overlays matching the given filter.
    *
    * @see Overlays#get for filter options.
    *
-   * @param {string|object} [filter]
+   * @param {OverlaysFilter} filter The filter to be used to find the overlay.
    */
   Overlays.prototype.remove = function(filter) {
 
@@ -7217,19 +7273,32 @@
 
   };
 
+  /**
+   * Checks whether overlays are shown.
+   *
+   * @returns {boolean} Whether overlays are shown.
+   */
   Overlays.prototype.isShown = function() {
     return this._overlayRoot.style.display !== 'none';
   };
 
+  /**
+   * Show all overlays.
+   */
   Overlays.prototype.show = function() {
     setVisible(this._overlayRoot);
   };
 
-
+  /**
+   * Hide all overlays.
+   */
   Overlays.prototype.hide = function() {
     setVisible(this._overlayRoot, false);
   };
 
+  /**
+   * Remove all overlays and their container.
+   */
   Overlays.prototype.clear = function() {
     this._overlays = {};
 
@@ -7605,6 +7674,13 @@
     overlays: [ 'type', Overlays ]
   };
 
+  /**
+   * @typedef {import('../../core/Canvas').default} Canvas
+   * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('../../core/EventBus').default} EventBus
+   * @typedef {import('../../core/GraphicsFactory').default} GraphicsFactory
+   */
+
   /**
    * Adds change support to the diagram, including
    *
@@ -7674,32 +7750,41 @@
     changeSupport: [ 'type', ChangeSupport ]
   };
 
+  /**
+   * @typedef {import('../core/EventBus').default} EventBus
+   * @typedef {import(./CommandInterceptor).HandlerFunction} HandlerFunction
+   * @typedef {import(./CommandInterceptor).ComposeHandlerFunction} ComposeHandlerFunction
+   */
+
   var DEFAULT_PRIORITY$1 = 1000;
 
   /**
-   * A utility that can be used to plug-in into the command execution for
+   * A utility that can be used to plug into the command execution for
    * extension and/or validation.
    *
+   * @class
+   * @constructor
+   *
    * @param {EventBus} eventBus
    *
    * @example
    *
-   * import inherits from 'inherits-browser';
-   *
    * import CommandInterceptor from 'diagram-js/lib/command/CommandInterceptor';
    *
-   * function CommandLogger(eventBus) {
-   *   CommandInterceptor.call(this, eventBus);
+   * class CommandLogger extends CommandInterceptor {
+   *   constructor(eventBus) {
+   *     super(eventBus);
    *
-   *   this.preExecute(function(event) {
-   *     console.log('command pre-execute', event);
+   *   this.preExecute('shape.create', (event) => {
+   *     console.log('commandStack.shape-create.preExecute', event);
    *   });
    * }
-   *
-   * inherits(CommandLogger, CommandInterceptor);
-   *
    */
   function CommandInterceptor(eventBus) {
+
+    /**
+     * @type {EventBus}
+     */
     this._eventBus = eventBus;
   }
 
@@ -7712,16 +7797,15 @@
   }
 
   /**
-   * Register an interceptor for a command execution
-   *
-   * @param {string|Array<string>} [events] list of commands to register on
-   * @param {string} [hook] command hook, i.e. preExecute, executed to listen on
-   * @param {number} [priority] the priority on which to hook into the execution
-   * @param {Function} handlerFn interceptor to be invoked with (event)
-   * @param {boolean} unwrap if true, unwrap the event and pass (context, command, event) to the
-   *                          listener instead
-   * @param {Object} [that] Pass context (`this`) to the handler function
-   */
+     * Intercept a command during one of the phases.
+     *
+     * @param {string|string[]} [events] One or more commands to intercept.
+     * @param {string} [hook] Phase during which to intercept command.
+     * @param {number} [priority] Priority with which command will be intercepted.
+     * @param {ComposeHandlerFunction|HandlerFunction} handlerFn Callback.
+     * @param {boolean} [unwrap] Whether the event should be unwrapped.
+     * @param {*} [that] `this` value the callback will be called with.
+     */
   CommandInterceptor.prototype.on = function(events, hook, priority, handlerFn, unwrap, that) {
 
     if (isFunction(hook) || isNumber(hook)) {
@@ -7777,24 +7861,19 @@
   ];
 
   /*
-   * Install hook shortcuts
-   *
-   * This will generate the CommandInterceptor#(preExecute|...|reverted) methods
-   * which will in term forward to CommandInterceptor#on.
+   * Add prototype methods for each phase of command execution (e.g. execute,
+   * revert).
    */
   forEach$1(hooks, function(hook) {
 
     /**
-     * {canExecute|preExecute|preExecuted|execute|executed|postExecute|postExecuted|revert|reverted}
+     * Add prototype method for a specific phase of command execution.
      *
-     * A named hook for plugging into the command execution
-     *
-     * @param {string|Array<string>} [events] list of commands to register on
-     * @param {number} [priority] the priority on which to hook into the execution
-     * @param {Function} handlerFn interceptor to be invoked with (event)
-     * @param {boolean} [unwrap=false] if true, unwrap the event and pass (context, command, event) to the
-     *                          listener instead
-     * @param {Object} [that] Pass context (`this`) to the handler function
+     * @param {string|string[]} [events] One or more commands to intercept.
+     * @param {number} [priority] Priority with which command will be intercepted.
+     * @param {ComposeHandlerFunction|HandlerFunction} handlerFn Callback.
+     * @param {boolean} [unwrap] Whether the event should be unwrapped.
+     * @param {*} [that] `this` value the callback will be called with.
      */
     CommandInterceptor.prototype[hook] = function(events, priority, handlerFn, unwrap, that) {
 
@@ -7810,12 +7889,18 @@
     };
   });
 
+  /**
+   * @typedef {import('didi').Injector} Injector
+   *
+   * @typedef {import('../../core/Canvas').default} Canvas
+   */
+
   /**
    * A modeling behavior that ensures we set the correct root element
    * as we undo and redo commands.
    *
    * @param {Canvas} canvas
-   * @param {didi.Injector} injector
+   * @param {Injector} injector
    */
   function RootElementsBehavior(canvas, injector) {
 
@@ -7849,111 +7934,10 @@
     rootElementsBehavior: [ 'type', RootElementsBehavior ]
   };
 
-  var css_escape = {exports: {}};
-
-  /*! https://mths.be/cssescape v1.5.1 by @mathias | MIT license */
-
-  (function (module, exports) {
-  (function(root, factory) {
-  		// https://github.com/umdjs/umd/blob/master/returnExports.js
-  		{
-  			// For Node.js.
-  			module.exports = factory(root);
-  		}
-  	}(typeof commonjsGlobal != 'undefined' ? commonjsGlobal : commonjsGlobal, function(root) {
-
-  		if (root.CSS && root.CSS.escape) {
-  			return root.CSS.escape;
-  		}
-
-  		// https://drafts.csswg.org/cssom/#serialize-an-identifier
-  		var cssEscape = function(value) {
-  			if (arguments.length == 0) {
-  				throw new TypeError('`CSS.escape` requires an argument.');
-  			}
-  			var string = String(value);
-  			var length = string.length;
-  			var index = -1;
-  			var codeUnit;
-  			var result = '';
-  			var firstCodeUnit = string.charCodeAt(0);
-  			while (++index < length) {
-  				codeUnit = string.charCodeAt(index);
-  				// Note: there’s no need to special-case astral symbols, surrogate
-  				// pairs, or lone surrogates.
-
-  				// If the character is NULL (U+0000), then the REPLACEMENT CHARACTER
-  				// (U+FFFD).
-  				if (codeUnit == 0x0000) {
-  					result += '\uFFFD';
-  					continue;
-  				}
-
-  				if (
-  					// If the character is in the range [\1-\1F] (U+0001 to U+001F) or is
-  					// U+007F, […]
-  					(codeUnit >= 0x0001 && codeUnit <= 0x001F) || codeUnit == 0x007F ||
-  					// If the character is the first character and is in the range [0-9]
-  					// (U+0030 to U+0039), […]
-  					(index == 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
-  					// If the character is the second character and is in the range [0-9]
-  					// (U+0030 to U+0039) and the first character is a `-` (U+002D), […]
-  					(
-  						index == 1 &&
-  						codeUnit >= 0x0030 && codeUnit <= 0x0039 &&
-  						firstCodeUnit == 0x002D
-  					)
-  				) {
-  					// https://drafts.csswg.org/cssom/#escape-a-character-as-code-point
-  					result += '\\' + codeUnit.toString(16) + ' ';
-  					continue;
-  				}
-
-  				if (
-  					// If the character is the first character and is a `-` (U+002D), and
-  					// there is no second character, […]
-  					index == 0 &&
-  					length == 1 &&
-  					codeUnit == 0x002D
-  				) {
-  					result += '\\' + string.charAt(index);
-  					continue;
-  				}
-
-  				// If the character is not handled by one of the above rules and is
-  				// greater than or equal to U+0080, is `-` (U+002D) or `_` (U+005F), or
-  				// is in one of the ranges [0-9] (U+0030 to U+0039), [A-Z] (U+0041 to
-  				// U+005A), or [a-z] (U+0061 to U+007A), […]
-  				if (
-  					codeUnit >= 0x0080 ||
-  					codeUnit == 0x002D ||
-  					codeUnit == 0x005F ||
-  					codeUnit >= 0x0030 && codeUnit <= 0x0039 ||
-  					codeUnit >= 0x0041 && codeUnit <= 0x005A ||
-  					codeUnit >= 0x0061 && codeUnit <= 0x007A
-  				) {
-  					// the character itself
-  					result += string.charAt(index);
-  					continue;
-  				}
-
-  				// Otherwise, the escaped character.
-  				// https://drafts.csswg.org/cssom/#escape-a-character
-  				result += '\\' + string.charAt(index);
-
-  			}
-  			return result;
-  		};
-
-  		if (!root.CSS) {
-  			root.CSS = {};
-  		}
-
-  		root.CSS.escape = cssEscape;
-  		return cssEscape;
-
-  	}));
-  } (css_escape));
+  /**
+   * @param {string} str
+   * @returns {string}
+   */
 
   var HTML_ESCAPE_MAP = {
     '&': '&amp;',
@@ -9088,6 +9072,11 @@
     return value;
   }
 
+  /**
+   * @typedef {import('../core/EventBus').default} EventBus
+   * @typedef {import('./Styles').default} Styles
+   */
+
   // apply default renderer with lowest possible priority
   // so that it only kicks in if noone else could render
   var DEFAULT_RENDER_PRIORITY = 1;
@@ -9205,9 +9194,9 @@
     /**
      * Builds a style definition from a className, a list of traits and an object of additional attributes.
      *
-     * @param  {string} className
-     * @param  {Array<string>} traits
-     * @param  {Object} additionalAttrs
+     * @param {string} className
+     * @param {Array<string>} traits
+     * @param {Object} additionalAttrs
      *
      * @return {Object} the style defintion
      */
@@ -9220,8 +9209,8 @@
     /**
      * Builds a style definition from a list of traits and an object of additional attributes.
      *
-     * @param  {Array<string>} traits
-     * @param  {Object} additionalAttrs
+     * @param {Array<string>} traits
+     * @param {Object} additionalAttrs
      *
      * @return {Object} the style defintion
      */
@@ -9258,8 +9247,8 @@
   /**
    * Failsafe remove an element from a collection
    *
-   * @param  {Array<Object>} [collection]
-   * @param  {Object} [element]
+   * @param {Array<Object>} [collection]
+   * @param {Object} [element]
    *
    * @return {number} the previous index of the element
    */
@@ -9329,6 +9318,27 @@
     }
   }
 
+  /**
+   * @typedef {import('.').ConnectionLike} ConnectionLike
+   * @typedef {import('.').RootLike} RootLike
+   * @typedef {import('.').ShapeLike} ShapeLike
+   *
+   * @typedef {import('./Canvas').CanvasConfig} CanvasConfig
+   * @typedef {import('./Canvas').CanvasLayer} CanvasLayer
+   * @typedef {import('./Canvas').CanvasLayers} CanvasLayers
+   * @typedef {import('./Canvas').CanvasPlane} CanvasPlane
+   * @typedef {import('./Canvas').CanvasViewbox} CanvasViewbox
+   *
+   * @typedef {import('./ElementRegistry').default} ElementRegistry
+   * @typedef {import('./EventBus').default} EventBus
+   * @typedef {import('./GraphicsFactory').default} GraphicsFactory
+   *
+   * @typedef {import('../util/Types').Dimensions} Dimensions
+   * @typedef {import('../util/Types').Point} Point
+   * @typedef {import('../util/Types').Rect} Rect
+   * @typedef {import('../util/Types').RectTRBL} RectTRBL
+   */
+
   function round(number, resolution) {
     return Math.round(number * resolution) / resolution;
   }
@@ -9349,7 +9359,8 @@
    * Creates a HTML container element for a SVG element with
    * the given configuration
    *
-   * @param  {Object} options
+   * @param {CanvasConfig} options
+   *
    * @return {HTMLElement} the container element
    */
   function createContainer(options) {
@@ -9409,21 +9420,34 @@
    *
    * @emits Canvas#canvas.init
    *
-   * @param {Object} config
+   * @param {CanvasConfig|null} config
    * @param {EventBus} eventBus
    * @param {GraphicsFactory} graphicsFactory
    * @param {ElementRegistry} elementRegistry
    */
   function Canvas(config, eventBus, graphicsFactory, elementRegistry) {
-
     this._eventBus = eventBus;
     this._elementRegistry = elementRegistry;
     this._graphicsFactory = graphicsFactory;
 
+    /**
+     * @type {number}
+     */
     this._rootsIdx = 0;
 
+    /**
+     * @type {CanvasLayers}
+     */
     this._layers = {};
+
+    /**
+     * @type {CanvasPlane[]}
+     */
     this._planes = [];
+
+    /**
+     * @type {RootLike|null}
+     */
     this._rootElement = null;
 
     this._init(config || {});
@@ -9448,6 +9472,8 @@
    *    ...
    *   </svg>
    * </div>
+   *
+   * @param {CanvasConfig} config
    */
   Canvas.prototype._init = function(config) {
 
@@ -9469,7 +9495,7 @@
       this._viewboxChanged = debounce(bind$2(this._viewboxChanged, this), 300);
     }
 
-    eventBus.on('diagram.init', function() {
+    eventBus.on('diagram.init', () => {
 
       /**
        * An event indicating that the canvas is ready to be drawn on.
@@ -9487,7 +9513,7 @@
         viewport: viewport
       });
 
-    }, this);
+    });
 
     // reset viewbox on shape changes to
     // recompute the viewbox
@@ -9498,15 +9524,15 @@
       'connection.removed',
       'elements.changed',
       'root.set'
-    ], function() {
+    ], () => {
       delete this._cachedViewbox;
-    }, this);
+    });
 
     eventBus.on('diagram.destroy', 500, this._destroy, this);
     eventBus.on('diagram.clear', 500, this._clear, this);
   };
 
-  Canvas.prototype._destroy = function(emit) {
+  Canvas.prototype._destroy = function() {
     this._eventBus.fire('canvas.destroy', {
       svg: this._svg,
       viewport: this._viewport
@@ -9553,7 +9579,7 @@
    * Returns the default layer on which
    * all elements are drawn.
    *
-   * @returns {SVGElement}
+   * @return {SVGElement}  The SVG element of the layer.
    */
   Canvas.prototype.getDefaultLayer = function() {
     return this.getLayer(BASE_LAYER, PLANE_LAYER_INDEX);
@@ -9569,10 +9595,10 @@
    * A layer with a certain index is always created above all
    * existing layers with the same index.
    *
-   * @param {string} name
-   * @param {number} index
+   * @param {string} name The name of the layer.
+   * @param {number} [index] The index of the layer.
    *
-   * @returns {SVGElement}
+   * @return {SVGElement} The SVG element of the layer.
    */
   Canvas.prototype.getLayer = function(name, index) {
 
@@ -9601,8 +9627,9 @@
    *
    * This is used to determine the node a layer should be inserted at.
    *
-   * @param {Number} index
-   * @returns {Number}
+   * @param {number} index
+   *
+   * @return {number}
    */
   Canvas.prototype._getChildIndex = function(index) {
     return reduce(this._layers, function(childIndex, layer) {
@@ -9620,7 +9647,7 @@
    * @param {string} name
    * @param {number} [index=0]
    *
-   * @return {Object} layer descriptor with { index, group: SVGGroup }
+   * @return {CanvasLayer}
    */
   Canvas.prototype._createLayer = function(name, index) {
 
@@ -9641,8 +9668,9 @@
   /**
    * Shows a given layer.
    *
-   * @param {String} layer
-   * @returns {SVGElement}
+   * @param {string} layer The name of the layer.
+   *
+   * @return {SVGElement} The SVG element of the layer.
    */
   Canvas.prototype.showLayer = function(name) {
 
@@ -9676,8 +9704,9 @@
   /**
    * Hides a given layer.
    *
-   * @param {String} layer
-   * @returns {SVGElement}
+   * @param {string} layer The name of the layer.
+   *
+   * @return {SVGElement} The SVG element of the layer.
    */
   Canvas.prototype.hideLayer = function(name) {
 
@@ -9719,7 +9748,7 @@
   /**
    * Returns the currently active layer. Can be null.
    *
-   * @returns {SVGElement|null}
+   * @return {CanvasLayer|null} The active layer of `null`.
    */
   Canvas.prototype.getActiveLayer = function() {
     const plane = this._findPlaneForRoot(this.getRootElement());
@@ -9735,9 +9764,9 @@
   /**
    * Returns the plane which contains the given element.
    *
-   * @param {string|djs.model.Base} element
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
    *
-   * @return {djs.model.Base} root for element
+   * @return {RootLike|undefined} The root of the element.
    */
   Canvas.prototype.findRoot = function(element) {
     if (typeof element === 'string') {
@@ -9758,7 +9787,7 @@
   /**
    * Return a list of all root elements on the diagram.
    *
-   * @return {djs.model.Root[]}
+   * @return {(RootLike)[]} The list of root elements.
    */
   Canvas.prototype.getRootElements = function() {
     return this._planes.map(function(plane) {
@@ -9777,7 +9806,7 @@
    * Returns the html element that encloses the
    * drawing canvas.
    *
-   * @return {DOMNode}
+   * @return {HTMLElement} The HTML element of the container.
    */
   Canvas.prototype.getContainer = function() {
     return this._container;
@@ -9817,8 +9846,8 @@
      *
      * @event element.marker.update
      * @type {Object}
-     * @property {djs.model.Element} element the shape
-     * @property {Object} gfx the graphical representation of the shape
+     * @property {Base} element the shape
+     * @property {SVGElement} gfx the graphical representation of the shape
      * @property {string} marker
      * @property {boolean} add true if the marker was added, false if it got removed
      */
@@ -9833,14 +9862,15 @@
    * integrate extension into the marker life-cycle, too.
    *
    * @example
+   *
    * canvas.addMarker('foo', 'some-marker');
    *
    * const fooGfx = canvas.getGraphics('foo');
    *
    * fooGfx; // <g class="... some-marker"> ... </g>
    *
-   * @param {string|djs.model.Base} element
-   * @param {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.addMarker = function(element, marker) {
     this._updateMarker(element, marker, true);
@@ -9853,18 +9883,18 @@
    * Fires the element.marker.update event, making it possible to
    * integrate extension into the marker life-cycle, too.
    *
-   * @param  {string|djs.model.Base} element
-   * @param  {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.removeMarker = function(element, marker) {
     this._updateMarker(element, marker, false);
   };
 
   /**
-   * Check the existence of a marker on element.
+   * Check whether an element has a given marker.
    *
-   * @param  {string|djs.model.Base} element
-   * @param  {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.hasMarker = function(element, marker) {
     if (!element.id) {
@@ -9882,8 +9912,8 @@
    * Fires the element.marker.update event, making it possible to
    * integrate extension into the marker life-cycle, too.
    *
-   * @param  {string|djs.model.Base} element
-   * @param  {string} marker
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {string} marker The marker.
    */
   Canvas.prototype.toggleMarker = function(element, marker) {
     if (this.hasMarker(element, marker)) {
@@ -9906,7 +9936,7 @@
    * root elements can be null. This is used for applications that want to manage
    * root elements themselves.
    *
-   * @returns {Object|djs.model.Root|null} rootElement.
+   * @return {RootLike} The current root element.
    */
   Canvas.prototype.getRootElement = function() {
     const rootElement = this._rootElement;
@@ -9922,11 +9952,10 @@
   /**
    * Adds a given root element and returns it.
    *
-   * @param {Object|djs.model.Root} rootElement
+   * @param {ShapeLike} [rootElement] The root element to be added.
    *
-   * @return {Object|djs.model.Root} rootElement
+   * @return {RootLike} The added root element or an implicit root element.
    */
-
   Canvas.prototype.addRootElement = function(rootElement) {
     const idx = this._rootsIdx++;
 
@@ -9957,11 +9986,11 @@
   };
 
   /**
-   * Removes a given rootElement and returns it.
+   * Removes a given root element and returns it.
    *
-   * @param {djs.model.Root|String} rootElement
+   * @param {ShapeLike|string} rootElement The root element or its ID.
    *
-   * @return {Object|djs.model.Root} rootElement
+   * @return {ShapeLike|undefined} The removed root element.
    */
   Canvas.prototype.removeRootElement = function(rootElement) {
 
@@ -9995,15 +10024,13 @@
   };
 
 
-  // root element handling //////////////////////
-
   /**
    * Sets a given element as the new root element for the canvas
    * and returns the new root element.
    *
-   * @param {Object|djs.model.Root} rootElement
+   * @param {RootLike} rootElement The root element to be set.
    *
-   * @return {Object|djs.model.Root} new root element
+   * @return {RootLike} The set root element.
    */
   Canvas.prototype.setRootElement = function(rootElement, override) {
 
@@ -10090,8 +10117,6 @@
     this._eventBus.fire('root.set', { element: rootElement });
   };
 
-  // add functionality //////////////////////
-
   Canvas.prototype._ensureValid = function(type, element) {
     if (!element.id) {
       throw new Error('element must have an id');
@@ -10132,11 +10157,11 @@
    * Extensions may hook into these events to perform their magic.
    *
    * @param {string} type
-   * @param {Object|djs.model.Base} element
-   * @param {Object|djs.model.Base} [parent]
+   * @param {ConnectionLike|ShapeLike} element
+   * @param {ShapeLike} [parent]
    * @param {number} [parentIndex]
    *
-   * @return {Object|djs.model.Base} the added element
+   * @return {ConnectionLike|ShapeLike} The added element.
    */
   Canvas.prototype._addElement = function(type, element, parent, parentIndex) {
 
@@ -10165,26 +10190,26 @@
   };
 
   /**
-   * Adds a shape to the canvas
+   * Adds a shape to the canvas.
    *
-   * @param {Object|djs.model.Shape} shape to add to the diagram
-   * @param {djs.model.Base} [parent]
-   * @param {number} [parentIndex]
+   * @param {ShapeLike} shape The shape to be added
+   * @param {ShapeLike} [parent] The shape's parent.
+   * @param {number} [parentIndex] The index at which to add the shape to the parent's children.
    *
-   * @return {djs.model.Shape} the added shape
+   * @return {ShapeLike} The added shape.
    */
   Canvas.prototype.addShape = function(shape, parent, parentIndex) {
     return this._addElement('shape', shape, parent, parentIndex);
   };
 
   /**
-   * Adds a connection to the canvas
+   * Adds a connection to the canvas.
    *
-   * @param {Object|djs.model.Connection} connection to add to the diagram
-   * @param {djs.model.Base} [parent]
-   * @param {number} [parentIndex]
+   * @param {ConnectionLike} connection The connection to be added.
+   * @param {ShapeLike} [parent] The connection's parent.
+   * @param {number} [parentIndex] The index at which to add the connection to the parent's children.
    *
-   * @return {djs.model.Connection} the added connection
+   * @return {ConnectionLike} The added connection.
    */
   Canvas.prototype.addConnection = function(connection, parent, parentIndex) {
     return this._addElement('connection', connection, parent, parentIndex);
@@ -10225,11 +10250,14 @@
 
 
   /**
-   * Removes a shape from the canvas
+   * Removes a shape from the canvas.
+   *
+   * @fires ShapeRemoveEvent
+   * @fires ShapeRemovedEvent
    *
-   * @param {string|djs.model.Shape} shape or shape id to be removed
+   * @param {ShapeLike|string} shape The shape or its ID.
    *
-   * @return {djs.model.Shape} the removed shape
+   * @return {ShapeLike} The removed shape.
    */
   Canvas.prototype.removeShape = function(shape) {
 
@@ -10238,10 +10266,10 @@
      *
      * @memberOf Canvas
      *
-     * @event shape.remove
+     * @event ShapeRemoveEvent
      * @type {Object}
-     * @property {djs.model.Shape} element the shape descriptor
-     * @property {Object} gfx the graphical representation of the shape
+     * @property {ShapeLike} element The shape.
+     * @property {SVGElement} gfx The graphical element.
      */
 
     /**
@@ -10249,21 +10277,24 @@
      *
      * @memberOf Canvas
      *
-     * @event shape.removed
+     * @event ShapeRemoved
      * @type {Object}
-     * @property {djs.model.Shape} element the shape descriptor
-     * @property {Object} gfx the graphical representation of the shape
+     * @property {ShapeLike} element The shape.
+     * @property {SVGElement} gfx The graphical element.
      */
     return this._removeElement(shape, 'shape');
   };
 
 
   /**
-   * Removes a connection from the canvas
+   * Removes a connection from the canvas.
    *
-   * @param {string|djs.model.Connection} connection or connection id to be removed
+   * @fires ConnectionRemoveEvent
+   * @fires ConnectionRemovedEvent
    *
-   * @return {djs.model.Connection} the removed connection
+   * @param {ConnectionLike|string} connection The connection or its ID.
+   *
+   * @return {ConnectionLike} The removed connection.
    */
   Canvas.prototype.removeConnection = function(connection) {
 
@@ -10272,10 +10303,10 @@
      *
      * @memberOf Canvas
      *
-     * @event connection.remove
+     * @event ConnectionRemoveEvent
      * @type {Object}
-     * @property {djs.model.Connection} element the connection descriptor
-     * @property {Object} gfx the graphical representation of the connection
+     * @property {ConnectionLike} element The connection.
+     * @property {SVGElement} gfx The graphical element.
      */
 
     /**
@@ -10285,20 +10316,20 @@
      *
      * @event connection.removed
      * @type {Object}
-     * @property {djs.model.Connection} element the connection descriptor
-     * @property {Object} gfx the graphical representation of the connection
+     * @property {ConnectionLike} element The connection.
+     * @property {SVGElement} gfx The graphical element.
      */
     return this._removeElement(connection, 'connection');
   };
 
 
   /**
-   * Return the graphical object underlaying a certain diagram element
+   * Returns the graphical element of an element.
    *
-   * @param {string|djs.model.Base} element descriptor of the element
-   * @param {boolean} [secondary=false] whether to return the secondary connected element
+   * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
+   * @param {boolean} [secondary=false] Whether to return the secondary graphical element.
    *
-   * @return {SVGElement}
+   * @return {SVGElement} The graphical element.
    */
   Canvas.prototype.getGraphics = function(element, secondary) {
     return this._elementRegistry.getGraphics(element, secondary);
@@ -10370,13 +10401,9 @@
    *   height: zoomedAndScrolledViewbox.outer.height
    * });
    *
-   * @param  {Object} [box] the new view box to set
-   * @param  {number} box.x the top left X coordinate of the canvas visible in view box
-   * @param  {number} box.y the top left Y coordinate of the canvas visible in view box
-   * @param  {number} box.width the visible width
-   * @param  {number} box.height
+   * @param {Rect} [box] The viewbox to be set.
    *
-   * @return {Object} the current view box
+   * @return {CanvasViewbox} The set viewbox.
    */
   Canvas.prototype.viewbox = function(box) {
 
@@ -10445,10 +10472,9 @@
   /**
    * Gets or sets the scroll of the canvas.
    *
-   * @param {Object} [delta] the new scroll to apply.
+   * @param {Point} [delta] The scroll to be set.
    *
-   * @param {number} [delta.dx]
-   * @param {number} [delta.dy]
+   * @return {Point}
    */
   Canvas.prototype.scroll = function(delta) {
 
@@ -10472,9 +10498,8 @@
    * Scrolls the viewbox to contain the given element.
    * Optionally specify a padding to be applied to the edges.
    *
-   * @param {Object|String} [element] the element to scroll to.
-   * @param {Object|Number} [padding=100] the padding to be applied. Can also specify top, bottom, left and right.
-   *
+   * @param {ShapeLike|ConnectionLike|string} element The element to scroll to or its ID.
+   * @param {RectTRBL|number} [padding=100] The padding to be applied. Can also specify top, bottom, left and right.
    */
   Canvas.prototype.scrollToElement = function(element, padding) {
     let defaultPadding = 100;
@@ -10542,17 +10567,17 @@
   };
 
   /**
-   * Gets or sets the current zoom of the canvas, optionally zooming
-   * to the specified position.
+   * Gets or sets the current zoom of the canvas, optionally zooming to the
+   * specified position.
    *
-   * The getter may return a cached zoom level. Call it with `false` as
-   * the first argument to force recomputation of the current level.
+   * The getter may return a cached zoom level. Call it with `false` as the first
+   * argument to force recomputation of the current level.
    *
-   * @param {string|number} [newScale] the new zoom level, either a number, i.e. 0.9,
-   *                                   or `fit-viewport` to adjust the size to fit the current viewport
-   * @param {string|Point} [center] the reference point { x: .., y: ..} to zoom to, 'auto' to zoom into mid or null
+   * @param {number|string} [newScale] The new zoom level, either a number,
+   * i.e. 0.9, or `fit-viewport` to adjust the size to fit the current viewport.
+   * @param {Point} [center] The reference point { x: ..., y: ...} to zoom to.
    *
-   * @return {number} the current scale
+   * @return {number} The set zoom level.
    */
   Canvas.prototype.zoom = function(newScale, center) {
 
@@ -10675,9 +10700,9 @@
 
 
   /**
-   * Returns the size of the canvas
+   * Returns the size of the canvas.
    *
-   * @return {Dimensions}
+   * @return {Dimensions} The size of the canvas.
    */
   Canvas.prototype.getSize = function() {
     return {
@@ -10688,14 +10713,14 @@
 
 
   /**
-   * Return the absolute bounding box for the given element
+   * Returns the absolute bounding box of an element.
+   *
+   * The absolute bounding box may be used to display overlays in the callers
+   * (browser) coordinate system rather than the zoomed in/out canvas coordinates.
    *
-   * The absolute bounding box may be used to display overlays in the
-   * callers (browser) coordinate system rather than the zoomed in/out
-   * canvas coordinates.
+   * @param {ShapeLike|ConnectionLike} element The element.
    *
-   * @param  {ElementDescriptor} element
-   * @return {Bounds} the absolute bounding box
+   * @return {Rect} The element's absolute bounding box.
    */
   Canvas.prototype.getAbsoluteBBox = function(element) {
     const vbox = this.viewbox();
@@ -10730,8 +10755,7 @@
   };
 
   /**
-   * Fires an event in order other modules can react to the
-   * canvas resizing
+   * Fires an event so other modules can react to the canvas resizing.
    */
   Canvas.prototype.resized = function() {
 
@@ -10743,11 +10767,21 @@
 
   var ELEMENT_ID = 'data-element-id';
 
+  /**
+   * @typedef {import('.').ElementLike} ElementLike
+   *
+   * @typedef {import('./EventBus').default} EventBus
+   *
+   * @typedef {import('./ElementRegistry').ElementRegistryCallback} ElementRegistryCallback
+   */
 
   /**
+   * A registry that keeps track of all shapes in the diagram.
+   *
    * @class
+   * @constructor
    *
-   * A registry that keeps track of all shapes in the diagram.
+   * @param {EventBus} eventBus
    */
   function ElementRegistry(eventBus) {
     this._elements = {};
@@ -10758,11 +10792,11 @@
   ElementRegistry.$inject = [ 'eventBus' ];
 
   /**
-   * Register a pair of (element, gfx, (secondaryGfx)).
+   * Add an element and its graphical representation(s) to the registry.
    *
-   * @param {djs.model.Base} element
-   * @param {SVGElement} gfx
-   * @param {SVGElement} [secondaryGfx] optional other element to register, too
+   * @param {ElementLike} element The element to be added.
+   * @param {SVGElement} gfx The primary graphical representation.
+   * @param {SVGElement} [secondaryGfx] The secondary graphical representation.
    */
   ElementRegistry.prototype.add = function(element, gfx, secondaryGfx) {
 
@@ -10781,9 +10815,9 @@
   };
 
   /**
-   * Removes an element from the registry.
+   * Remove an element from the registry.
    *
-   * @param {string|djs.model.Base} element
+   * @param {ElementLike|string} element
    */
   ElementRegistry.prototype.remove = function(element) {
     var elements = this._elements,
@@ -10804,10 +10838,10 @@
   };
 
   /**
-   * Update the id of an element
+   * Update an elements ID.
    *
-   * @param {string|djs.model.Base} element
-   * @param {string} newId
+   * @param {ElementLike|string} element The element or its ID.
+   * @param {string} newId The new ID.
    */
   ElementRegistry.prototype.updateId = function(element, newId) {
 
@@ -10833,11 +10867,11 @@
   };
 
   /**
-   * Update the graphics of an element
+   * Update the graphical representation of an element.
    *
-   * @param {string|djs.model.Base} element
-   * @param {SVGElement} gfx
-   * @param {boolean} [secondary=false] whether to update the secondary connected element
+   * @param {ElementLike|string} element The element or its ID.
+   * @param {SVGElement} gfx The new graphical representation.
+   * @param {boolean} [secondary=false] Whether to update the secondary graphical representation.
    */
   ElementRegistry.prototype.updateGraphics = function(filter, gfx, secondary) {
     var id = filter.id || filter;
@@ -10858,17 +10892,17 @@
   };
 
   /**
-   * Return the model element for a given id or graphics.
+   * Get the element with the given ID or graphical representation.
    *
    * @example
    *
    * elementRegistry.get('SomeElementId_1');
-   * elementRegistry.get(gfx);
    *
+   * elementRegistry.get(gfx);
    *
-   * @param {string|SVGElement} filter for selecting the element
+   * @param {string|SVGElement} filter The elements ID or graphical representation.
    *
-   * @return {djs.model.Base}
+   * @return {ElementLike|undefined} The element.
    */
   ElementRegistry.prototype.get = function(filter) {
     var id;
@@ -10886,9 +10920,9 @@
   /**
    * Return all elements that match a given filter function.
    *
-   * @param {Function} fn
+   * @param {ElementRegistryCallback} fn The filter function.
    *
-   * @return {Array<djs.model.Base>}
+   * @return {ElementLike[]} The matching elements.
    */
   ElementRegistry.prototype.filter = function(fn) {
 
@@ -10904,11 +10938,11 @@
   };
 
   /**
-   * Return the first element that satisfies the provided testing function.
+   * Return the first element that matches the given filter function.
    *
-   * @param {Function} fn
+   * @param {Function} fn The filter function.
    *
-   * @return {djs.model.Base}
+   * @return {ElementLike|undefined} The matching element.
    */
   ElementRegistry.prototype.find = function(fn) {
     var map = this._elements,
@@ -10927,18 +10961,18 @@
   };
 
   /**
-   * Return all rendered model elements.
+   * Get all elements.
    *
-   * @return {Array<djs.model.Base>}
+   * @return {ElementLike[]} All elements.
    */
   ElementRegistry.prototype.getAll = function() {
     return this.filter(function(e) { return e; });
   };
 
   /**
-   * Iterate over all diagram elements.
+   * Execute a given function for each element.
    *
-   * @param {Function} fn
+   * @param {Function} fn The function to execute.
    */
   ElementRegistry.prototype.forEach = function(fn) {
 
@@ -10954,19 +10988,20 @@
   };
 
   /**
-   * Return the graphical representation of an element or its id.
+   * Return the graphical representation of an element.
    *
    * @example
+   *
    * elementRegistry.getGraphics('SomeElementId_1');
+   *
    * elementRegistry.getGraphics(rootElement); // <g ...>
    *
    * elementRegistry.getGraphics(rootElement, true); // <svg ...>
    *
+   * @param {ElementLike|string} filter The element or its ID.
+   * @param {boolean} [secondary=false] Whether to return the secondary graphical representation.
    *
-   * @param {string|djs.model.Base} filter
-   * @param {boolean} [secondary=false] whether to return the secondary connected element
-   *
-   * @return {SVGElement}
+   * @return {SVGElement} The graphical representation.
    */
   ElementRegistry.prototype.getGraphics = function(filter, secondary) {
     var id = filter.id || filter;
@@ -10976,12 +11011,11 @@
   };
 
   /**
-   * Validate the suitability of the given id and signals a problem
-   * with an exception.
+   * Validate an ID and throw an error if invalid.
    *
    * @param {string} id
    *
-   * @throws {Error} if id is empty or already assigned
+   * @throws {Error} Error indicating that the ID is invalid or already assigned.
    */
   ElementRegistry.prototype._validateId = function(id) {
     if (!id) {
@@ -10993,7 +11027,11 @@
     }
   };
 
-  var objectRefs = {exports: {}};
+  var objectRefsExports = {};
+  var objectRefs = {
+    get exports(){ return objectRefsExports; },
+    set exports(v){ objectRefsExports = v; },
+  };
 
   var collection = {};
 
@@ -11313,7 +11351,7 @@
   	module.exports.Collection = collection;
   } (objectRefs));
 
-  var Refs = /*@__PURE__*/getDefaultExportFromCjs(objectRefs.exports);
+  var Refs = /*@__PURE__*/getDefaultExportFromCjs(objectRefsExports);
 
   var parentRefs = new Refs({ name: 'children', enumerable: true, collection: true }, { name: 'parent' }),
       labelRefs = new Refs({ name: 'labels', enumerable: true, collection: true }, { name: 'labelTarget' }),
@@ -11321,14 +11359,6 @@
       outgoingRefs = new Refs({ name: 'outgoing', collection: true }, { name: 'source' }),
       incomingRefs = new Refs({ name: 'incoming', collection: true }, { name: 'target' });
 
-  /**
-   * @namespace djs.model
-   */
-
-  /**
-   * @memberOf djs.model
-   */
-
   /**
    * The basic graphical representation
    *
@@ -11525,21 +11555,47 @@
   };
 
   /**
-   * Creates a new model element of the specified type
+   * Creates a model element of the given type.
    *
    * @method create
    *
    * @example
    *
-   * var shape1 = Model.create('shape', { x: 10, y: 10, width: 100, height: 100 });
-   * var shape2 = Model.create('shape', { x: 210, y: 210, width: 100, height: 100 });
+   * import * as Model from 'diagram-js/lib/model';
+   *
+   * const connection = Model.create('connection', {
+   *   waypoints: [
+   *     { x: 100, y: 100 },
+   *     { x: 200, y: 100 }
+   *   ]
+   * });
+   *
+   * const label = Model.create('label', {
+   *   x: 100,
+   *   y: 100,
+   *   width: 100,
+   *   height: 100,
+   *   labelTarget: shape
+   * });
+   *
+   * const root = Model.create('root', {
+   *   x: 100,
+   *   y: 100,
+   *   width: 100,
+   *   height: 100
+   * });
    *
-   * var connection = Model.create('connection', { waypoints: [ { x: 110, y: 55 }, {x: 210, y: 55 } ] });
+   * const shape = Model.create('shape', {
+   *   x: 100,
+   *   y: 100,
+   *   width: 100,
+   *   height: 100
+   * });
    *
-   * @param  {string} type lower-cased model name
-   * @param  {Object} attrs attributes to initialize the new model instance with
+   * @param {string} type The type of model element to be created.
+   * @param {Object} attrs Attributes to create the model element with.
    *
-   * @return {Base} the new model instance
+   * @return {Connection|Label|Root|Shape} The created model element.
    */
   function create(type, attrs) {
     var Type = types$6[type];
@@ -11550,36 +11606,78 @@
   }
 
   /**
-   * A factory for diagram-js shapes
+   * @typedef {import('../model/index').Base} Base
+   * @typedef {import('../model/index').Connection} Connection
+   * @typedef {import('../model/index').Label} Label
+   * @typedef {import('../model/index').Root} Root
+   * @typedef {import('../model/index').Shape} Shape
+   * @typedef {import('../model/index').ModelAttrsConnection} ModelAttrsConnection
+   * @typedef {import('../model/index').ModelAttrsLabel} ModelAttrsLabel
+   * @typedef {import('../model/index').ModelAttrsRoot} ModelAttrsRoot
+   * @typedef {import('../model/index').ModelAttrsShape} ModelAttrsShape
+   */
+
+  /**
+   * A factory for model elements.
+   *
+   * @class
+   * @constructor
    */
   function ElementFactory() {
     this._uid = 12;
   }
 
-
+  /**
+   * Create a root element.
+   *
+   * @param {ModelAttrsRoot} attrs The attributes of the root element to be created.
+   *
+   * @return {Root} The created root element.
+   */
   ElementFactory.prototype.createRoot = function(attrs) {
     return this.create('root', attrs);
   };
 
+  /**
+   * Create a label.
+   *
+   * @param {ModelAttrsLabel} attrs The attributes of the label to be created.
+   *
+   * @return {Label} The created label.
+   */
   ElementFactory.prototype.createLabel = function(attrs) {
     return this.create('label', attrs);
   };
 
+  /**
+   * Create a shape.
+   *
+   * @param {ModelAttrsShape} attrs The attributes of the shape to be created.
+   *
+   * @return {Shape} The created shape.
+   */
   ElementFactory.prototype.createShape = function(attrs) {
     return this.create('shape', attrs);
   };
 
+  /**
+   * Create a connection.
+   *
+   * @param {ModelAttrsConnection} attrs The attributes of the connection to be created.
+   *
+   * @return {Connection} The created connection.
+   */
   ElementFactory.prototype.createConnection = function(attrs) {
     return this.create('connection', attrs);
   };
 
   /**
-   * Create a model element with the given type and
-   * a number of pre-set attributes.
+   * Create a model element of the given type with the given attributes.
    *
-   * @param  {string} type
-   * @param  {Object} attrs
-   * @return {djs.model.Base} the newly created model instance
+   * @param {string} type The type of the model element.
+   * @param {Object} attrs The attributes of the model element.
+   *
+   * @return {Connection|Label|Root|Shape} The created model element.
    */
   ElementFactory.prototype.create = function(type, attrs) {
 
@@ -11598,6 +11696,16 @@
 
   var slice = Array.prototype.slice;
 
+  /**
+   * @typedef {import('./EventBus').Event} Event
+   * @typedef {import('./EventBus').EventCallback} EventCallback
+   *
+   * @typedef {Object} EventListener
+   * @property {Function} callback
+   * @property {EventListener|null} next
+   * @property {number} priority
+   */
+
   /**
    * A general purpose event bus.
    *
@@ -11702,10 +11810,10 @@
    *
    * Returning anything but `undefined` from a listener will stop the listener propagation.
    *
-   * @param {string|Array<string>} events
-   * @param {number} [priority=1000] the priority in which this listener is called, larger is higher
-   * @param {Function} callback
-   * @param {Object} [that] Pass context (`this`) to the callback
+   * @param {string|string[]} events The event(s) to listen to.
+   * @param {number} [priority=1000] The priority with which to listen.
+   * @param {EventCallback} callback The callback.
+   * @param {*} [that] Value of `this` the callback will be called with.
    */
   EventBus.prototype.on = function(events, priority, callback, that) {
 
@@ -11745,12 +11853,12 @@
 
 
   /**
-   * Register an event listener that is executed only once.
+   * Register an event listener that is called only once.
    *
-   * @param {string} event the event name to register for
-   * @param {number} [priority=1000] the priority in which this listener is called, larger is higher
-   * @param {Function} callback the callback to execute
-   * @param {Object} [that] Pass context (`this`) to the callback
+   * @param {string} event The event to listen to.
+   * @param {number} [priority=1000] The priority with which to listen.
+   * @param {EventCallback} callback The callback.
+   * @param {*} [that] Value of `this` the callback will be called with.
    */
   EventBus.prototype.once = function(event, priority, callback, that) {
     var self = this;
@@ -11789,8 +11897,8 @@
    *
    * If no callback is given, all listeners for a given event name are being removed.
    *
-   * @param {string|Array<string>} events
-   * @param {Function} [callback]
+   * @param {string|string[]} events The events.
+   * @param {EventCallback} [callback] The callback.
    */
   EventBus.prototype.off = function(events, callback) {
 
@@ -11806,11 +11914,11 @@
 
 
   /**
-   * Create an EventBus event.
+   * Create an event recognized be the event bus.
    *
-   * @param {Object} data
+   * @param {Object} data Event data.
    *
-   * @return {Object} event, recognized by the eventBus
+   * @return {Event} An event that will be recognized by the event bus.
    */
   EventBus.prototype.createEvent = function(data) {
     var event = new InternalEvent();
@@ -11822,7 +11930,7 @@
 
 
   /**
-   * Fires a named event.
+   * Fires an event.
    *
    * @example
    *
@@ -11844,12 +11952,11 @@
    *
    * events.fire({ type: 'foo' }, 'I am bar!');
    *
-   * @param {string} [name] the optional event name
-   * @param {Object} [event] the event object
-   * @param {...Object} additional arguments to be passed to the callback functions
+   * @param {string} [type] The event type.
+   * @param {Object} [data] The event or event data.
+   * @param {...*} additional Additional arguments the callback will be called with.
    *
-   * @return {boolean} the events return value, if specified or false if the
-   *                   default action was prevented by listeners
+   * @return {*} The return value. Will be set to `false` if the default was prevented.
    */
   EventBus.prototype.fire = function(type, data) {
     var event,
@@ -11914,7 +12021,13 @@
     return returnValue;
   };
 
-
+  /**
+   * Handle an error by firing an event.
+   *
+   * @param {Error} error The error to be handled.
+   *
+   * @return {boolean} Whether the error was handled.
+   */
   EventBus.prototype.handleError = function(error) {
     return this.fire('error', { error: error }) === false;
   };
@@ -11977,7 +12090,7 @@
     return returnValue;
   };
 
-  /*
+  /**
    * Add new listener with a certain priority to the list
    * of listeners (for the given event).
    *
@@ -11991,7 +12104,7 @@
    *    * after: [ 1500, 1500, (new=1300), 1000, 1000, (new=1000) ]
    *
    * @param {string} event
-   * @param {Object} listener { priority, callback }
+   * @param {EventListener} listener
    */
   EventBus.prototype._addListener = function(event, newListener) {
 
@@ -12097,9 +12210,9 @@
    * Invoke function. Be fast...
    *
    * @param {Function} fn
-   * @param {Array<Object>} args
+   * @param {*[]} args
    *
-   * @return {Any}
+   * @return {*}
    */
   function invokeFunction(fn, args) {
     return fn.apply(null, args);
@@ -12113,11 +12226,11 @@
    */
 
   /**
-   * Returns the visual part of a diagram element
+   * Returns the visual part of a diagram element.
    *
-   * @param {Snap<SVGElement>} gfx
+   * @param {SVGElement} gfx
    *
-   * @return {Snap<SVGElement>}
+   * @return {SVGElement}
    */
   function getVisual(gfx) {
     return gfx.childNodes[0];
@@ -12126,15 +12239,28 @@
   /**
    * Returns the children for a given diagram element.
    *
-   * @param {Snap<SVGElement>} gfx
-   * @return {Snap<SVGElement>}
+   * @param {SVGElement} gfx
+   * @return {SVGElement}
    */
   function getChildren(gfx) {
     return gfx.parentNode.childNodes[1];
   }
 
   /**
-   * A factory that creates graphical elements
+   * @typedef {import('../model').ModelType} ModelType
+   * @typedef {import('../model').ModelTypeConnection} ModelTypeConnection
+   * @typedef {import('../model').ModelTypeShape} ModelTypeShape
+   *
+   * @typedef {import('.').ConnectionLike} ConnectionLike
+   * @typedef {import('.').ElementLike} ElementLike
+   * @typedef {import('.').ShapeLike} ShapeLike
+   *
+   * @typedef {import('./ElementRegistry').default} ElementRegistry
+   * @typedef {import('./EventBus').default} EventBus
+   */
+
+  /**
+   * A factory that creates graphical elements.
    *
    * @param {EventBus} eventBus
    * @param {ElementRegistry} elementRegistry
@@ -12202,7 +12328,7 @@
    * </g>
    *
    * @param {string} type the type of the element, i.e. shape | connection
-   * @param {SVGElement} [childrenGfx]
+   * @param {SVGElement} childrenGfx
    * @param {number} [parentIndex] position to create container in parent
    * @param {boolean} [isFrame] is frame element
    *
@@ -12240,11 +12366,25 @@
     return gfx;
   };
 
+  /**
+   * Create a graphical element.
+   *
+   * @param {ModelType} type The type of the element.
+   * @param {ElementLike} element The element.
+   * @param {number} [parentIndex] The index at which to add the graphical element to its parent's children.
+   *
+   * @return {SVGElement} The graphical element.
+   */
   GraphicsFactory.prototype.create = function(type, element, parentIndex) {
     var childrenGfx = this._getChildrenContainer(element.parent);
     return this._createContainer(type, childrenGfx, parentIndex, isFrameElement(element));
   };
 
+  /**
+   * Update the containments of the given elements.
+   *
+   * @param {ElementLike[]} elements The elements.
+   */
   GraphicsFactory.prototype.updateContainments = function(elements) {
 
     var self = this,
@@ -12280,30 +12420,63 @@
     });
   };
 
+  /**
+   * Draw a shape.
+   *
+   * @param {SVGElement} visual The graphical element.
+   * @param {ShapeLike} element The shape.
+   */
   GraphicsFactory.prototype.drawShape = function(visual, element) {
     var eventBus = this._eventBus;
 
     return eventBus.fire('render.shape', { gfx: visual, element: element });
   };
 
+  /**
+   * Get the path of a shape.
+   *
+   * @param {ShapeLike} element The shape.
+   *
+   * @return {string} The path of the shape.
+   */
   GraphicsFactory.prototype.getShapePath = function(element) {
     var eventBus = this._eventBus;
 
     return eventBus.fire('render.getShapePath', element);
   };
 
+  /**
+   * Draw a connection.
+   *
+   * @param {SVGElement} visual The graphical element.
+   * @param {ConnectionLike} element The connection.
+   */
   GraphicsFactory.prototype.drawConnection = function(visual, element) {
     var eventBus = this._eventBus;
 
     return eventBus.fire('render.connection', { gfx: visual, element: element });
   };
 
-  GraphicsFactory.prototype.getConnectionPath = function(waypoints) {
+  /**
+   * Get the path of a connection.
+   *
+   * @param {ConnectionLike} element The connection.
+   *
+   * @return {string} The path of the connection.
+   */
+  GraphicsFactory.prototype.getConnectionPath = function(connection) {
     var eventBus = this._eventBus;
 
-    return eventBus.fire('render.getConnectionPath', waypoints);
+    return eventBus.fire('render.getConnectionPath', connection);
   };
 
+  /**
+   * Update an elements graphical representation.
+   *
+   * @param {ModelTypeShape|ModelTypeConnection} type The type of the element.
+   * @param {ElementLike} element The element.
+   * @param {SVGElement} gfx The graphical representation.
+   */
   GraphicsFactory.prototype.update = function(type, element, gfx) {
 
     // do NOT update root element
@@ -12333,6 +12506,11 @@
     }
   };
 
+  /**
+   * Remove a graphical element.
+   *
+   * @param {ElementLike} element The element.
+   */
   GraphicsFactory.prototype.remove = function(element) {
     var gfx = this._elementRegistry.getGraphics(element);
 
@@ -12366,13 +12544,17 @@
   };
 
   /**
-   * @typedef { import('didi').ModuleDeclaration } Module
+   * @typedef {import('didi').InjectionContext} InjectionContext
+   * @typedef {import('didi').LocalsMap} LocalsMap
+   * @typedef {import('didi').ModuleDeclaration} ModuleDeclaration
+   *
+   * @typedef {import('./Diagram').DiagramOptions} DiagramOptions
    */
 
   /**
    * Bootstrap an injector from a list of modules, instantiating a number of default components
    *
-   * @param {Array<Module>} modules
+   * @param {ModuleDeclaration[]} modules
    *
    * @return {Injector} a injector to use to access the components
    */
@@ -12387,7 +12569,8 @@
   /**
    * Creates an injector from passed options.
    *
-   * @param {Object} options
+   * @param {DiagramOptions} [options]
+   *
    * @return {Injector}
    */
   function createInjector(options) {
@@ -12410,8 +12593,7 @@
    *
    * To register extensions with the diagram, pass them as Array<Module> to the constructor.
    *
-   * @class djs.Diagram
-   * @memberOf djs
+   * @class
    * @constructor
    *
    * @example
@@ -12449,9 +12631,9 @@
    *
    * // 'shape ... was added to the diagram' logged to console
    *
-   * @param {Object} options
-   * @param {Array<Module>} [options.modules] external modules to instantiate with the diagram
-   * @param {Injector} [injector] an (optional) injector to bootstrap the diagram with
+   * @param {DiagramOptions} [options]
+   * @param {ModuleDeclaration[]} [options.modules] External modules to instantiate with the diagram.
+   * @param {Injector} [injector] An (optional) injector to bootstrap the diagram with.
    */
   function Diagram(options, injector) {
 
@@ -12461,22 +12643,23 @@
     // API
 
     /**
-     * Resolves a diagram service
+     * Resolves a diagram service.
      *
      * @method Diagram#get
      *
-     * @param {string} name the name of the diagram service to be retrieved
-     * @param {boolean} [strict=true] if false, resolve missing services to null
+     * @param {string} name The name of the service to get.
+     * @param {boolean} [strict=true] If false, resolve missing services to null.
      */
     this.get = injector.get;
 
     /**
-     * Executes a function into which diagram services are injected
+     * Executes a function with its dependencies injected.
      *
      * @method Diagram#invoke
      *
-     * @param {Function|Object[]} fn the function to resolve
-     * @param {Object} locals a number of locals to use to resolve certain dependencies
+     * @param {Function} fn The function to be executed.
+     * @param {InjectionContext} [context] The context.
+     * @param {LocalsMap} [locals] The locals.
      */
     this.invoke = injector.invoke;
 
@@ -20882,7 +21065,20 @@
 
 
   /**
-   * @typedef { import('didi').ModuleDeclaration } Module
+   * @typedef {import('didi').ModuleDeclaration} ModuleDeclaration
+   *
+   * @typedef {import('./BaseViewer').BaseModelerOptions} BaseModelerOptions
+   * @typedef {import('./BaseViewer').ModdleElement} ModdleElement
+   * @typedef {import('./BaseViewer').ImportXMLResult} ImportXMLResult
+   * @typedef {import('./BaseViewer').ImportXMLError} ImportXMLError
+   * @typedef {import('./BaseViewer').ImportDefinitionsResult} ImportDefinitionsResult
+   * @typedef {import('./BaseViewer').ImportDefinitionsError} ImportDefinitionsError
+   * @typedef {import('./BaseViewer').ModdleElement} ModdleElement
+   * @typedef {import('./BaseViewer').ModdleElementsById} ModdleElementsById
+   * @typedef {import('./BaseViewer').OpenResult} OpenResult
+   * @typedef {import('./BaseViewer').OpenError} OpenError
+   * @typedef {import('./BaseViewer').SaveXMLOptions} SaveXMLOptions
+   * @typedef {import('./BaseViewer').SaveXMLResult} SaveXMLResult
    */
 
   /**
@@ -20891,20 +21087,20 @@
    * Have a look at {@link Viewer}, {@link NavigatedViewer} or {@link Modeler} for
    * bundles that include actual features.
    *
-   * @param {Object} [options] configuration options to pass to the viewer
-   * @param {DOMElement} [options.container] the container to render the viewer in, defaults to body.
-   * @param {string|number} [options.width] the width of the viewer
-   * @param {string|number} [options.height] the height of the viewer
-   * @param {Object} [options.moddleExtensions] extension packages to provide
-   * @param {Module[]} [options.modules] a list of modules to override the default modules
-   * @param {Module[]} [options.additionalModules] a list of modules to use with the default modules
+   * @param {BaseModelerOptions} [options] The options to configure the viewer.
    */
   function BaseViewer(options) {
 
+    /**
+     * @type {BaseModelerOptions}
+     */
     options = assign$1({}, DEFAULT_OPTIONS, options);
 
     this._moddle = this._createModdle(options);
 
+    /**
+     * @type {HTMLElement}
+     */
     this._container = this._createContainer(options);
 
     /* <project-logo> */
@@ -20918,22 +21114,6 @@
 
   e(BaseViewer, Diagram);
 
-  /**
-  * The importXML result.
-  *
-  * @typedef {Object} ImportXMLResult
-  *
-  * @property {Array<string>} warnings
-  */
-
-  /**
-  * The importXML error.
-  *
-  * @typedef {Error} ImportXMLError
-  *
-  * @property {Array<string>} warnings
-  */
-
   /**
    * Parse and render a BPMN 2.0 diagram.
    *
@@ -20944,7 +21124,7 @@
    *
    * During import the viewer will fire life-cycle events:
    *
-   *   * import.parse.start (about to read model from xml)
+   *   * import.parse.start (about to read model from XML)
    *   * import.parse.complete (model read; may have worked or not)
    *   * import.render.start (graphical import start)
    *   * import.render.complete (graphical import finished)
@@ -20952,10 +21132,18 @@
    *
    * You can use these events to hook into the life-cycle.
    *
-   * @param {string} xml the BPMN 2.0 xml
-   * @param {ModdleElement<BPMNDiagram>|string} [bpmnDiagram] BPMN diagram or id of diagram to render (if not provided, the first one will be rendered)
+   * @throws {ImportXMLError} An error thrown during the import of the XML.
+   *
+   * @fires BaseViewer#ImportParseStart
+   * @fires BaseViewer#ImportParseComplete
+   * @fires Importer#ImportRenderStart
+   * @fires Importer#ImportRenderComplete
+   * @fires BaseViewer#ImportDone
    *
-   * Returns {Promise<ImportXMLResult, ImportXMLError>}
+   * @param {string} xml The BPMN 2.0 XML to be imported.
+   * @param {ModdleElement|string} [bpmnDiagram] The optional diagram or Id of the BPMN diagram to open.
+   *
+   * @return {Promise<ImportXMLResult>} A promise resolving with warnings that were produced during the import.
    */
   BaseViewer.prototype.importXML = wrapForCompatibility(async function importXML(xml, bpmnDiagram) {
 
@@ -20991,6 +21179,14 @@
 
       // hook in pre-parse listeners +
       // allow xml manipulation
+
+      /**
+       * A `import.parse.start` event.
+       *
+       * @event BaseViewer#ImportParseStart
+       * @type {Object}
+       * @property {string} xml The XML that is to be parsed.
+       */
       xml = this._emit('import.parse.start', { xml: xml }) || xml;
 
       let parseResult;
@@ -21013,6 +21209,18 @@
 
       // hook in post parse listeners +
       // allow definitions manipulation
+
+      /**
+       * A `import.parse.complete` event.
+       *
+       * @event BaseViewer#ImportParseComplete
+       * @type {Object}
+       * @property {Error|null} error An error thrown when parsing the XML.
+       * @property {ModdleElement} definitions The definitions model element.
+       * @property {ModdleElementsById} elementsById The model elements by ID.
+       * @property {ModdleElement[]} references The referenced model elements.
+       * @property {string[]} warnings The warnings produced when parsing the XML.
+       */
       definitions = this._emit('import.parse.complete', ParseCompleteEvent({
         error: null,
         definitions: definitions,
@@ -21025,6 +21233,14 @@
 
       aggregatedWarnings = aggregatedWarnings.concat(importResult.warnings);
 
+      /**
+       * A `import.parse.complete` event.
+       *
+       * @event BaseViewer#ImportDone
+       * @type {Object}
+       * @property {ImportXMLError|null} error An error thrown during import.
+       * @property {string[]} warnings The warnings.
+       */
       this._emit('import.done', { error: null, warnings: aggregatedWarnings });
 
       return { warnings: aggregatedWarnings };
@@ -21041,21 +21257,6 @@
     }
   });
 
-  /**
-  * The importDefinitions result.
-  *
-  * @typedef {Object} ImportDefinitionsResult
-  *
-  * @property {Array<string>} warnings
-  */
-
-  /**
-  * The importDefinitions error.
-  *
-  * @typedef {Error} ImportDefinitionsError
-  *
-  * @property {Array<string>} warnings
-  */
 
   /**
    * Import parsed definitions and render a BPMN 2.0 diagram.
@@ -21072,10 +21273,12 @@
    *
    * You can use these events to hook into the life-cycle.
    *
-   * @param {ModdleElement<Definitions>} definitions parsed BPMN 2.0 definitions
-   * @param {ModdleElement<BPMNDiagram>|string} [bpmnDiagram] BPMN diagram or id of diagram to render (if not provided, the first one will be rendered)
+   * @throws {ImportDefinitionsError} An error thrown during the import of the definitions.
+   *
+   * @param {ModdleElement} definitions The definitions.
+   * @param {ModdleElement|string} [bpmnDiagram] The optional diagram or ID of the BPMN diagram to open.
    *
-   * Returns {Promise<ImportDefinitionsResult, ImportDefinitionsError>}
+   * @return {Promise<ImportDefinitionsResult>} A promise resolving with warnings that were produced during the import.
    */
   BaseViewer.prototype.importDefinitions = wrapForCompatibility(async function importDefinitions(definitions, bpmnDiagram) {
     this._setDefinitions(definitions);
@@ -21084,21 +21287,6 @@
     return { warnings: result.warnings };
   });
 
-  /**
-   * The open result.
-   *
-   * @typedef {Object} OpenResult
-   *
-   * @property {Array<string>} warnings
-   */
-
-  /**
-  * The open error.
-  *
-  * @typedef {Error} OpenError
-  *
-  * @property {Array<string>} warnings
-  */
 
   /**
    * Open diagram of previously imported XML.
@@ -21115,9 +21303,11 @@
    *
    * You can use these events to hook into the life-cycle.
    *
-   * @param {string|ModdleElement<BPMNDiagram>} [bpmnDiagramOrId] id or the diagram to open
+   * @throws {OpenError} An error thrown during opening.
+   *
+   * @param {ModdleElement|string} bpmnDiagramOrId The diagram or Id of the BPMN diagram to open.
    *
-   * Returns {Promise<OpenResult, OpenError>}
+   * @return {Promise<OpenResult>} A promise resolving with warnings that were produced during opening.
    */
   BaseViewer.prototype.open = wrapForCompatibility(async function open(bpmnDiagramOrId) {
 
@@ -21158,14 +21348,6 @@
     return { warnings };
   });
 
-  /**
-   * The saveXML result.
-   *
-   * @typedef {Object} SaveXMLResult
-   *
-   * @property {string} xml
-   */
-
   /**
    * Export the currently displayed BPMN 2.0 diagram as
    * a BPMN 2.0 XML document.
@@ -21180,11 +21362,14 @@
    *
    * You can use these events to hook into the life-cycle.
    *
-   * @param {Object} [options] export options
-   * @param {boolean} [options.format=false] output formatted XML
-   * @param {boolean} [options.preamble=true] output preamble
+   * @throws {Error} An error thrown during export.
+   *
+   * @fires BaseViewer#SaveXMLStart
+   * @fires BaseViewer#SaveXMLDone
    *
-   * Returns {Promise<SaveXMLResult, Error>}
+   * @param {SaveXMLOptions} [options] The options.
+   *
+   * @return {Promise<SaveXMLResult>} A promise resolving with the XML.
    */
   BaseViewer.prototype.saveXML = wrapForCompatibility(async function saveXML(options) {
 
@@ -21199,6 +21384,14 @@
       }
 
       // allow to fiddle around with definitions
+
+      /**
+       * A `saveXML.start` event.
+       *
+       * @event BaseViewer#SaveXMLStart
+       * @type {Object}
+       * @property {ModdleElement} definitions The definitions model element.
+       */
       definitions = this._emit('saveXML.start', {
         definitions
       }) || definitions;
@@ -21215,6 +21408,14 @@
 
     const result = error ? { error } : { xml };
 
+    /**
+     * A `saveXML.done` event.
+     *
+     * @event BaseViewer#SaveXMLDone
+     * @type {Object}
+     * @property {Error} [error] An error thrown when saving the XML.
+     * @property {string} [xml] The saved XML.
+     */
     this._emit('saveXML.done', result);
 
     if (error) {
@@ -21224,13 +21425,6 @@
     return result;
   });
 
-  /**
-   * The saveSVG result.
-   *
-   * @typedef {Object} SaveSVGResult
-   *
-   * @property {string} svg
-   */
 
   /**
    * Export the currently displayed BPMN 2.0 diagram as
@@ -21245,11 +21439,13 @@
    *
    * You can use these events to hook into the life-cycle.
    *
-   * @param {Object} [options]
+   * @throws {Error} An error thrown during export.
+   *
+   * @fires BaseViewer#SaveSVGDone
    *
-   * Returns {Promise<SaveSVGResult, Error>}
+   * @return {Promise<SaveSVGResult>} A promise resolving with the SVG.
    */
-  BaseViewer.prototype.saveSVG = wrapForCompatibility(async function saveSVG(options = {}) {
+  BaseViewer.prototype.saveSVG = wrapForCompatibility(async function saveSVG() {
     this._emit('saveSVG.start');
 
     let svg, err;
@@ -21278,6 +21474,14 @@
       err = e;
     }
 
+    /**
+     * A `saveSVG.done` event.
+     *
+     * @event BaseViewer#SaveSVGDone
+     * @type {Object}
+     * @property {Error} [error] An error thrown when saving the SVG.
+     * @property {string} [svg] The saved SVG.
+     */
     this._emit('saveSVG.done', {
       error: err,
       svg: svg
@@ -21329,21 +21533,17 @@
   /**
    * Return modules to instantiate with.
    *
-   * @param {any} options the instance got created with
-   *
-   * @return {Module[]}
+   * @return {ModuleDeclaration[]} The modules.
    */
-  BaseViewer.prototype.getModules = function(options) {
+  BaseViewer.prototype.getModules = function() {
     return this._modules;
   };
 
   /**
    * Remove all drawn elements from the viewer.
    *
-   * After calling this method the viewer can still
-   * be reused for opening another diagram.
-   *
-   * @method BaseViewer#clear
+   * After calling this method the viewer can still be reused for opening another
+   * diagram.
    */
   BaseViewer.prototype.clear = function() {
     if (!this.getDefinitions()) {
@@ -21357,8 +21557,8 @@
   };
 
   /**
-   * Destroy the viewer instance and remove all its
-   * remainders from the document tree.
+   * Destroy the viewer instance and remove all its remainders from the document
+   * tree.
    */
   BaseViewer.prototype.destroy = function() {
 
@@ -21370,29 +21570,34 @@
   };
 
   /**
-   * Register an event listener
+   * Register an event listener.
    *
-   * Remove a previously added listener via {@link #off(event, callback)}.
+   * Remove an event listener via {@link BaseViewer#off}.
    *
-   * @param {string} event
-   * @param {number} [priority]
-   * @param {Function} callback
-   * @param {Object} [that]
+   * @param {string|string[]} events The event(s) to listen to.
+   * @param {number} [priority] The priority with which to listen.
+   * @param {EventCallback} callback The callback.
+   * @param {*} [that] Value of `this` the callback will be called with.
    */
-  BaseViewer.prototype.on = function(event, priority, callback, target) {
-    return this.get('eventBus').on(event, priority, callback, target);
+  BaseViewer.prototype.on = function(events, priority, callback, that) {
+    return this.get('eventBus').on(events, priority, callback, that);
   };
 
   /**
-   * De-register an event listener
+   * Remove an event listener.
    *
-   * @param {string} event
-   * @param {Function} callback
+   * @param {string|string[]} events The event(s).
+   * @param {Function} [callback] The callback.
    */
-  BaseViewer.prototype.off = function(event, callback) {
-    this.get('eventBus').off(event, callback);
+  BaseViewer.prototype.off = function(events, callback) {
+    this.get('eventBus').off(events, callback);
   };
 
+  /**
+   * Attach the viewer to an HTML element.
+   *
+   * @param {HTMLElement} parentNode The parent node to attach to.
+   */
   BaseViewer.prototype.attachTo = function(parentNode) {
 
     if (!parentNode) {
@@ -21419,10 +21624,20 @@
     this.get('canvas').resized();
   };
 
+  /**
+   * Get the definitions model element.
+   *
+   * @returns {ModdleElement} The definitions model element.
+   */
   BaseViewer.prototype.getDefinitions = function() {
     return this._definitions;
   };
 
+  /**
+   * Detach the viewer.
+   *
+   * @fires BaseViewer#DetachEvent
+   */
   BaseViewer.prototype.detach = function() {
 
     const container = this._container,
@@ -21432,6 +21647,12 @@
       return;
     }
 
+    /**
+     * A `detach` event.
+     *
+     * @event BaseViewer#DetachEvent
+     * @type {Object}
+     */
     this._emit('detach', {});
 
     parentNode.removeChild(container);
@@ -21469,7 +21690,7 @@
    * @param  {string} type
    * @param  {Object} event
    *
-   * @return {Object} event processing result (if any)
+   * @return {Object} The return value after calling all event listeners.
    */
   BaseViewer.prototype._emit = function(type, event) {
     return this.get('eventBus').fire(type, event);
@@ -21595,7 +21816,7 @@
   /* </project-logo> */
 
   /**
-   * @typedef { import('didi').ModuleDeclaration } Module
+   * @typedef { import('./BaseViewer').BaseViewerOptions } BaseViewerOptions
    */
 
   /**
@@ -21637,13 +21858,7 @@
    * bpmnViewer.importXML(...);
    * ```
    *
-   * @param {Object} [options] configuration options to pass to the viewer
-   * @param {DOMElement} [options.container] the container to render the viewer in, defaults to body.
-   * @param {string|number} [options.width] the width of the viewer
-   * @param {string|number} [options.height] the height of the viewer
-   * @param {Object} [options.moddleExtensions] extension packages to provide
-   * @param {Module[]} [options.modules] a list of modules to override the default modules
-   * @param {Module[]} [options.additionalModules] a list of modules to use with the default modules
+   * @param {BaseViewerOptions} [options] The options to configure the viewer.
    */
   function Viewer(options) {
     BaseViewer.call(this, options);