camunda-bpmn-js 2.1.0 → 2.2.0

package/dist/base-viewer.development.js

@@ -9,9 +9,11 @@
   /**
    * Flatten array, one level deep.
    *
-   * @param {Array<?>} arr
+   * @template T
    *
-   * @return {Array<?>}
+   * @param {T[][]} arr
+   *
+   * @return {T[]}
    */
 
   const nativeToString$1 = Object.prototype.toString;
@@ -37,6 +39,11 @@
     return nativeToString$1.call(obj) === '[object Number]';
   }
 
+  /**
+   * @param {any} obj
+   *
+   * @return {boolean}
+   */
   function isFunction(obj) {
     const tag = nativeToString$1.call(obj);
 
@@ -65,22 +72,74 @@
     return nativeHasOwnProperty$1.call(target, key);
   }
 
+  /**
+   * @template T
+   * @typedef { (
+   *   ((e: T) => boolean) |
+   *   ((e: T, idx: number) => boolean) |
+   *   ((e: T, key: string) => boolean) |
+   *   string |
+   *   number
+   * ) } Matcher
+   */
+
+  /**
+   * @template T
+   * @template U
+   *
+   * @typedef { (
+   *   ((e: T) => U) | string | number
+   * ) } Extractor
+   */
+
+
+  /**
+   * @template T
+   * @typedef { (val: T, key: any) => boolean } MatchFn
+   */
+
+  /**
+   * @template T
+   * @typedef { T[] } ArrayCollection
+   */
+
+  /**
+   * @template T
+   * @typedef { { [key: string]: T } } StringKeyValueCollection
+   */
+
+  /**
+   * @template T
+   * @typedef { { [key: number]: T } } NumberKeyValueCollection
+   */
+
+  /**
+   * @template T
+   * @typedef { StringKeyValueCollection<T> | NumberKeyValueCollection<T> } KeyValueCollection
+   */
+
+  /**
+   * @template T
+   * @typedef { KeyValueCollection<T> | ArrayCollection<T> } Collection
+   */
+
   /**
    * Find element in collection.
    *
-   * @param  {Array|Object} collection
-   * @param  {Function|Object} matcher
+   * @template T
+   * @param {Collection<T>} collection
+   * @param {Matcher<T>} matcher
    *
    * @return {Object}
    */
   function find(collection, matcher) {
 
-    matcher = toMatcher(matcher);
+    const matchFn = toMatcher(matcher);
 
     let match;
 
     forEach$1(collection, function(val, key) {
-      if (matcher(val, key)) {
+      if (matchFn(val, key)) {
         match = val;
 
         return false;
@@ -95,19 +154,20 @@
   /**
    * Find element index in collection.
    *
-   * @param  {Array|Object} collection
-   * @param  {Function} matcher
+   * @template T
+   * @param {Collection<T>} collection
+   * @param {Matcher<T>} matcher
    *
-   * @return {Object}
+   * @return {number}
    */
   function findIndex(collection, matcher) {
 
-    matcher = toMatcher(matcher);
+    const matchFn = toMatcher(matcher);
 
     let idx = isArray$2(collection) ? -1 : undefined;
 
     forEach$1(collection, function(val, key) {
-      if (matcher(val, key)) {
+      if (matchFn(val, key)) {
         idx = key;
 
         return false;
@@ -119,19 +179,22 @@
 
 
   /**
-   * Find element in collection.
+   * Filter elements in collection.
    *
-   * @param  {Array|Object} collection
-   * @param  {Function} matcher
+   * @template T
+   * @param {Collection<T>} collection
+   * @param {Matcher<T>} matcher
    *
-   * @return {Array} result
+   * @return {T[]} result
    */
   function filter(collection, matcher) {
 
+    const matchFn = toMatcher(matcher);
+
     let result = [];
 
     forEach$1(collection, function(val, key) {
-      if (matcher(val, key)) {
+      if (matchFn(val, key)) {
         result.push(val);
       }
     });
@@ -144,10 +207,11 @@
    * Iterate over collection; returning something
    * (non-undefined) will stop iteration.
    *
-   * @param  {Array|Object} collection
-   * @param  {Function} iterator
+   * @template T
+   * @param {Collection<T>} collection
+   * @param { ((item: T, idx: number) => (boolean|void)) | ((item: T, key: string) => (boolean|void)) } iterator
    *
-   * @return {Object} return result that stopped the iteration
+   * @return {T} return result that stopped the iteration
    */
   function forEach$1(collection, iterator) {
 
@@ -178,11 +242,14 @@
   /**
    * Reduce collection, returning a single result.
    *
-   * @param  {Object|Array} collection
-   * @param  {Function} iterator
-   * @param  {Any} result
+   * @template T
+   * @template V
+   *
+   * @param {Collection<T>} collection
+   * @param {(result: V, entry: T, index: any) => V} iterator
+   * @param {V} result
    *
-   * @return {Any} result returned from last iterator
+   * @return {V} result returned from last iterator
    */
   function reduce(collection, iterator, result) {
 
@@ -252,13 +319,17 @@
    *
    * @example
    *
+   * ```javascript
    * const matcher = matchPattern({ id: 1 });
    *
    * let element = find(elements, matcher);
+   * ```
    *
-   * @param  {Object} pattern
+   * @template T
+   *
+   * @param {T} pattern
    *
-   * @return {Function} matcherFn
+   * @return { (el: any) =>  boolean } matcherFn
    */
   function matchPattern(pattern) {
 
@@ -272,6 +343,12 @@
   }
 
 
+  /**
+   * @template T
+   * @param {Matcher<T>} matcher
+   *
+   * @return {MatchFn<T>}
+   */
   function toMatcher(matcher) {
     return isFunction(matcher) ? matcher : (e) => {
       return e === matcher;
@@ -287,6 +364,16 @@
     return Number(arg);
   }
 
+  /* global setTimeout clearTimeout */
+
+  /**
+   * @typedef { {
+   *   (...args: any[]): any;
+   *   flush: () => void;
+   *   cancel: () => void;
+   * } } DebouncedFunction
+   */
+
   /**
    * Debounce fn, calling it only once if the given time
    * elapsed between calls.
@@ -297,7 +384,7 @@
    * @param  {Function} fn
    * @param  {Number} timeout
    *
-   * @return {Function} debounced function
+   * @return {DebouncedFunction} debounced function
    */
   function debounce(fn, timeout) {
 
@@ -343,6 +430,9 @@
       clear();
     }
 
+    /**
+     * @type { DebouncedFunction }
+     */
     function callback(...args) {
       lastNow = Date.now();
 
@@ -386,12 +476,15 @@
   }
 
   /**
-   * Pick given properties from the target object.
+   * Pick properties from the given target.
    *
-   * @param {Object} target
-   * @param {Array} properties
+   * @template T
+   * @template {any[]} V
+   *
+   * @param {T} target
+   * @param {V} properties
    *
-   * @return {Object} target
+   * @return Pick<T, V>
    */
   function pick(target, properties) {
 
@@ -412,10 +505,13 @@
   /**
    * Pick all target properties, excluding the given ones.
    *
-   * @param {Object} target
-   * @param {Array} properties
+   * @template T
+   * @template {any[]} V
    *
-   * @return {Object} target
+   * @param {T} target
+   * @param {V} properties
+   *
+   * @return {Omit<T, V>} target
    */
   function omit(target, properties) {
 
@@ -436,9 +532,9 @@
   var DEFAULT_RENDER_PRIORITY$1 = 1000;
 
   /**
-   * @typedef {import('../model').Base} Base
-   * @typedef {import('../model').Connection} Connection
-   * @typedef {import('../model').Shape} Shape
+   * @typedef {import('../core/Types').ElementLike} Element
+   * @typedef {import('../core/Types').ConnectionLike} Connection
+   * @typedef {import('../core/Types').ShapeLike} Shape
    *
    * @typedef {import('../core/EventBus').default} EventBus
    */
@@ -483,9 +579,9 @@
   /**
    * Checks whether an element can be rendered.
    *
-   * @param {Base} element The element to be rendered.
+   * @param {Element} element The element to be rendered.
    *
-   * @returns {boolean} Whether the element can be rendered.
+   * @return {boolean} Whether the element can be rendered.
    */
   BaseRenderer.prototype.canRender = function(element) {};
 
@@ -495,7 +591,7 @@
    * @param {SVGElement} visuals The SVG element to draw the shape into.
    * @param {Shape} shape The shape to be drawn.
    *
-   * @returns {SVGElement} The SVG element of the shape drawn.
+   * @return {SVGElement} The SVG element of the shape drawn.
    */
   BaseRenderer.prototype.drawShape = function(visuals, shape) {};
 
@@ -505,7 +601,7 @@
    * @param {SVGElement} visuals The SVG element to draw the connection into.
    * @param {Connection} connection The connection to be drawn.
    *
-   * @returns {SVGElement} The SVG element of the connection drawn.
+   * @return {SVGElement} The SVG element of the connection drawn.
    */
   BaseRenderer.prototype.drawConnection = function(visuals, connection) {};
 
@@ -527,10 +623,15 @@
    */
   BaseRenderer.prototype.getConnectionPath = function(connection) {};
 
+  /**
+   * @typedef { import('../model/Types').Element } Element
+   * @typedef { import('../model/Types').ModdleElement } ModdleElement
+   */
+
   /**
    * Is an element of the given BPMN type?
    *
-   * @param  {djs.model.Base|ModdleElement} element
+   * @param  {Element|ModdleElement} element
    * @param  {string} type
    *
    * @return {boolean}
@@ -545,8 +646,8 @@
   /**
    * Return true if element has any of the given types.
    *
-   * @param {djs.model.Base} element
-   * @param {Array<string>} types
+   * @param {Element|ModdleElement} element
+   * @param {string[]} types
    *
    * @return {boolean}
    */
@@ -559,7 +660,7 @@
   /**
    * Return the business object for a given element.
    *
-   * @param  {djs.model.Base|ModdleElement} element
+   * @param {Element|ModdleElement} element
    *
    * @return {ModdleElement}
    */
@@ -570,7 +671,7 @@
   /**
    * Return the di object for a given element.
    *
-   * @param  {djs.model.Base} element
+   * @param {Element} element
    *
    * @return {ModdleElement}
    */
@@ -578,6 +679,17 @@
     return element && element.di;
   }
 
+  /**
+   * @typedef {import('../model/Types').Element} Element
+   * @typedef {import('../model/Types').ModdleElement} ModdleElement
+   */
+
+  /**
+   * @param {Element} element
+   * @param {ModdleElement} [di]
+   *
+   * @return {boolean}
+   */
   function isExpanded(element, di) {
 
     if (is$1(element, 'bpmn:CallActivity')) {
@@ -601,10 +713,175 @@
     return true;
   }
 
+  /**
+   * @param {Element} element
+   *
+   * @return {boolean}
+   */
   function isEventSubProcess(element) {
     return element && !!getBusinessObject(element).triggeredByEvent;
   }
 
+  /**
+   * @typedef {import('diagram-js/lib/util/Types').Point} Point
+   * @typedef {import('diagram-js/lib/util/Types').Rect} Rect
+   *
+   * @typedef {import('../model/Types').Element} Element
+   * @typedef {import('../model/Types').ModdleElement} ModdleElement
+   */
+
+  var DEFAULT_LABEL_SIZE$1 = {
+    width: 90,
+    height: 20
+  };
+
+  var FLOW_LABEL_INDENT = 15;
+
+
+  /**
+   * Return true if the given semantic has an external label.
+   *
+   * @param {Element} semantic
+   *
+   * @return {boolean}
+   */
+  function isLabelExternal(semantic) {
+    return is$1(semantic, 'bpmn:Event') ||
+           is$1(semantic, 'bpmn:Gateway') ||
+           is$1(semantic, 'bpmn:DataStoreReference') ||
+           is$1(semantic, 'bpmn:DataObjectReference') ||
+           is$1(semantic, 'bpmn:DataInput') ||
+           is$1(semantic, 'bpmn:DataOutput') ||
+           is$1(semantic, 'bpmn:SequenceFlow') ||
+           is$1(semantic, 'bpmn:MessageFlow') ||
+           is$1(semantic, 'bpmn:Group');
+  }
+
+  /**
+   * Get the position of a sequence flow label.
+   *
+   * @param  {Point[]} waypoints
+   *
+   * @return {Point}
+   */
+  function getFlowLabelPosition(waypoints) {
+
+    // get the waypoints mid
+    var mid = waypoints.length / 2 - 1;
+
+    var first = waypoints[Math.floor(mid)];
+    var second = waypoints[Math.ceil(mid + 0.01)];
+
+    // get position
+    var position = getWaypointsMid(waypoints);
+
+    // calculate angle
+    var angle = Math.atan((second.y - first.y) / (second.x - first.x));
+
+    var x = position.x,
+        y = position.y;
+
+    if (Math.abs(angle) < Math.PI / 2) {
+      y -= FLOW_LABEL_INDENT;
+    } else {
+      x += FLOW_LABEL_INDENT;
+    }
+
+    return { x: x, y: y };
+  }
+
+
+  /**
+   * Get the middle of a number of waypoints.
+   *
+   * @param  {Point[]} waypoints
+   *
+   * @return {Point}
+   */
+  function getWaypointsMid(waypoints) {
+
+    var mid = waypoints.length / 2 - 1;
+
+    var first = waypoints[Math.floor(mid)];
+    var second = waypoints[Math.ceil(mid + 0.01)];
+
+    return {
+      x: first.x + (second.x - first.x) / 2,
+      y: first.y + (second.y - first.y) / 2
+    };
+  }
+
+  /**
+   * Get the middle of the external label of an element.
+   *
+   * @param {Element} element
+   *
+   * @return {Point}
+   */
+  function getExternalLabelMid(element) {
+
+    if (element.waypoints) {
+      return getFlowLabelPosition(element.waypoints);
+    } else if (is$1(element, 'bpmn:Group')) {
+      return {
+        x: element.x + element.width / 2,
+        y: element.y + DEFAULT_LABEL_SIZE$1.height / 2
+      };
+    } else {
+      return {
+        x: element.x + element.width / 2,
+        y: element.y + element.height + DEFAULT_LABEL_SIZE$1.height / 2
+      };
+    }
+  }
+
+
+  /**
+   * Return the bounds of an elements label, parsed from the elements DI or
+   * generated from its bounds.
+   *
+   * @param {ModdleElement} di
+   * @param {Element} element
+   *
+   * @return {Rect}
+   */
+  function getExternalLabelBounds(di, element) {
+
+    var mid,
+        size,
+        bounds,
+        label = di.label;
+
+    if (label && label.bounds) {
+      bounds = label.bounds;
+
+      size = {
+        width: Math.max(DEFAULT_LABEL_SIZE$1.width, bounds.width),
+        height: bounds.height
+      };
+
+      mid = {
+        x: bounds.x + bounds.width / 2,
+        y: bounds.y + bounds.height / 2
+      };
+    } else {
+
+      mid = getExternalLabelMid(element);
+
+      size = DEFAULT_LABEL_SIZE$1;
+    }
+
+    return assign$1({
+      x: mid.x - size.width / 2,
+      y: mid.y - size.height / 2
+    }, size);
+  }
+
+
+  /**
+   * @typedef { import('../model').DiagramElement } DiagramElement
+   */
+
   function getLabelAttr(semantic) {
     if (
       is$1(semantic, 'bpmn:FlowElement') ||
@@ -638,6 +915,11 @@
     return categoryValueRef.value || '';
   }
 
+  /**
+   * @param {DiagramElement} element
+   *
+   * @return {string} label
+   */
   function getLabel(element) {
     var semantic = element.businessObject,
         attr = getLabelAttr(semantic);
@@ -1338,7 +1620,7 @@
    */
 
   /**
-   * @param {Component[]} elements
+   * @param {Component[] | Component[][]} elements
    *
    * @return {string}
    */
@@ -1346,18 +1628,40 @@
     return elements.flat().join(',').replace(/,?([A-z]),?/g, '$1');
   }
 
+  /**
+   * @param {Point} point
+   *
+   * @return {Component[]}
+   */
   function move(point) {
     return [ 'M', point.x, point.y ];
   }
 
+  /**
+   * @param {Point} point
+   *
+   * @return {Component[]}
+   */
   function lineTo(point) {
     return [ 'L', point.x, point.y ];
   }
 
+  /**
+   * @param {Point} p1
+   * @param {Point} p2
+   * @param {Point} p3
+   *
+   * @return {Component[]}
+   */
   function curveTo(p1, p2, p3) {
     return [ 'C', p1.x, p1.y, p2.x, p2.y, p3.x, p3.y ];
   }
 
+  /**
+   * @param {Point[]} waypoints
+   * @param {number} [cornerRadius]
+   * @return {Component[][]}
+   */
   function drawPath(waypoints, cornerRadius) {
     const pointCount = waypoints.length;
 
@@ -1421,7 +1725,7 @@
 
   /**
    * @param {Point[]} points
-   * @param {*} [attrs]
+   * @param {number|Object} [attrs]
    * @param {number} [radius]
    *
    * @return {SVGElement}
@@ -1470,54 +1774,75 @@
   /**
    * Checks if eventDefinition of the given element matches with semantic type.
    *
-   * @return {boolean} true if element is of the given semantic type
+   * @param {ModdleElement} event
+   * @param {string} eventDefinitionType
+   *
+   * @return {boolean}
    */
-  function isTypedEvent(event, eventDefinitionType, filter) {
-
-    function matches(definition, filter) {
-      return every(filter, function(val, key) {
-
-        // we want a == conversion here, to be able to catch
-        // undefined == false and friends
-        /* jshint -W116 */
-        return definition[key] == val;
-      });
-    }
-
+  function isTypedEvent(event, eventDefinitionType) {
     return some(event.eventDefinitions, function(definition) {
-      return definition.$type === eventDefinitionType && matches(event, filter);
+      return definition.$type === eventDefinitionType;
     });
   }
 
+  /**
+   * Check if element is a throw event.
+   *
+   * @param {ModdleElement} event
+   *
+   * @return {boolean}
+   */
   function isThrowEvent(event) {
     return (event.$type === 'bpmn:IntermediateThrowEvent') || (event.$type === 'bpmn:EndEvent');
   }
 
+  /**
+   * Check if element is a throw event.
+   *
+   * @param {ModdleElement} element
+   *
+   * @return {boolean}
+   */
   function isCollection(element) {
     var dataObject = element.dataObjectRef;
 
     return element.isCollection || (dataObject && dataObject.isCollection);
   }
 
-  function getSemantic(element) {
-    return element.businessObject;
-  }
-
 
   // color access //////////////////////
 
+  /**
+   * @param {Element} element
+   * @param {string} [defaultColor]
+   *
+   * @return {string}
+   */
   function getFillColor(element, defaultColor) {
     var di = getDi(element);
 
     return di.get('color:background-color') || di.get('bioc:fill') || defaultColor || 'white';
   }
 
+  /**
+   * @param {Element} element
+   * @param {string} [defaultColor]
+   *
+   * @return {string}
+   */
   function getStrokeColor(element, defaultColor) {
     var di = getDi(element);
 
     return di.get('color:border-color') || di.get('bioc:stroke') || defaultColor || black;
   }
 
+  /**
+   * @param {Element} element
+   * @param {string} [defaultColor]
+   * @param {string} [defaultStrokeColor]
+   *
+   * @return {string}
+   */
   function getLabelColor(element, defaultColor, defaultStrokeColor) {
     var di = getDi(element),
         label = di.get('label');
@@ -1528,6 +1853,11 @@
 
   // cropping path customizations //////////////////////
 
+  /**
+   * @param {ShapeLike} shape
+   *
+   * @return {string} path
+   */
   function getCirclePath(shape) {
 
     var cx = shape.x + shape.width / 2,
@@ -1545,6 +1875,12 @@
     return componentsToPath(circlePath);
   }
 
+  /**
+   * @param {ShapeLike} shape
+   * @param {number} [borderRadius]
+   *
+   * @return {string} path
+   */
   function getRoundRectPath(shape, borderRadius) {
 
     var x = shape.x,
@@ -1568,6 +1904,11 @@
     return componentsToPath(roundRectPath);
   }
 
+  /**
+   * @param {ShapeLike} shape
+   *
+   * @return {string} path
+   */
   function getDiamondPath(shape) {
 
     var width = shape.width,
@@ -1588,6 +1929,11 @@
     return componentsToPath(diamondPath);
   }
 
+  /**
+   * @param {ShapeLike} shape
+   *
+   * @return {string} path
+   */
   function getRectPath(shape) {
     var x = shape.x,
         y = shape.y,
@@ -2169,11 +2515,11 @@
   }
 
   /**
-   * @param {SVGElement} element
+   * @param {SVGElement} gfx
    * @param {number} x
    * @param {number} y
-   * @param {number} angle
-   * @param {number} amount
+   * @param {number} [angle]
+   * @param {number} [amount]
    */
   function transform(gfx, x, y, angle, amount) {
     var translate = createTransform();
@@ -2190,7 +2536,7 @@
 
 
   /**
-   * @param {SVGElement} element
+   * @param {SVGElement} gfx
    * @param {number} x
    * @param {number} y
    */
@@ -2203,7 +2549,7 @@
 
 
   /**
-   * @param {SVGElement} element
+   * @param {SVGElement} gfx
    * @param {number} angle
    */
   function rotate(gfx, angle) {
@@ -2386,6 +2732,29 @@
 
   var ELEMENT_LABEL_DISTANCE = 10;
 
+  /**
+   * @typedef { Partial<{
+   *   defaultFillColor: string,
+   *   defaultStrokeColor: string,
+   *   defaultLabelColor: string
+   * }> } BpmnRendererConfig
+   */
+
+  /**
+   * @typedef { import('../model').DiagramElement } DiagramElement
+   */
+
+  /**
+   * A renderer for BPMN elements
+   *
+   * @param {BpmnRendererConfig} config
+   * @param {import('diagram-js/lib/core/EventBus').default} eventBus
+   * @param {import('diagram-js/lib/draw/Styles').default} styles
+   * @param {import('./PathMap').default} pathMap
+   * @param {import('diagram-js/lib/core/Canvas').default} canvas
+   * @param {import('./TextRenderer').default} textRenderer
+   * @param {number} [priority]
+   */
   function BpmnRenderer(
       config, eventBus, styles, pathMap,
       canvas, textRenderer, priority) {
@@ -2745,7 +3114,7 @@
 
     function renderEventContent(element, parentGfx) {
 
-      var event = getSemantic(element);
+      var event = getBusinessObject(element);
       var isThrowing = isThrowEvent(event);
 
       if (event.eventDefinitions && event.eventDefinitions.length > 1) {
@@ -2818,7 +3187,7 @@
     }
 
     function renderEmbeddedLabel(parentGfx, element, align) {
-      var semantic = getSemantic(element);
+      var semantic = getBusinessObject(element);
 
       return renderLabel(parentGfx, semantic.name, {
         box: element,
@@ -2884,7 +3253,7 @@
           stroke: getStrokeColor(element, defaultStrokeColor)
         };
 
-        var semantic = getSemantic(element);
+        var semantic = getBusinessObject(element);
 
         if (!semantic.isInterrupting) {
           attrs = {
@@ -3345,7 +3714,7 @@
         return task;
       },
       'bpmn:ReceiveTask' : function(parentGfx, element) {
-        var semantic = getSemantic(element);
+        var semantic = getBusinessObject(element);
 
         var task = renderer('bpmn:Task')(parentGfx, element);
         var pathData;
@@ -3501,12 +3870,12 @@
             stroke: getStrokeColor(element, defaultStrokeColor),
             strokeWidth
           });
-          var text = getSemantic(element).name;
+          var text = getBusinessObject(element).name;
           renderLaneLabel(parentGfx, text, element);
         } else {
 
           // collapsed pool draw text inline
-          var text2 = getSemantic(element).name;
+          var text2 = getBusinessObject(element).name;
           renderLabel(parentGfx, text2, {
             box: element, align: 'center-middle',
             style: {
@@ -3515,7 +3884,7 @@
           });
         }
 
-        var participantMultiplicity = !!(getSemantic(element).participantMultiplicity);
+        var participantMultiplicity = !!(getBusinessObject(element).participantMultiplicity);
 
         if (participantMultiplicity) {
           renderer('ParticipantMultiplicityMarker')(parentGfx, element);
@@ -3532,7 +3901,7 @@
           ...attrs
         });
 
-        var semantic = getSemantic(element);
+        var semantic = getBusinessObject(element);
 
         if (semantic.$type === 'bpmn:Lane') {
           var text = semantic.name;
@@ -3623,7 +3992,7 @@
       },
       'bpmn:EventBasedGateway': function(parentGfx, element) {
 
-        var semantic = getSemantic(element);
+        var semantic = getBusinessObject(element);
 
         var diamond = renderer('bpmn:Gateway')(parentGfx, element);
 
@@ -3705,7 +4074,7 @@
           stroke: getStrokeColor(element, defaultStrokeColor)
         });
 
-        var sequenceFlow = getSemantic(element);
+        var sequenceFlow = getBusinessObject(element);
 
         var source;
 
@@ -3732,7 +4101,7 @@
       },
       'bpmn:Association': function(parentGfx, element, attrs) {
 
-        var semantic = getSemantic(element);
+        var semantic = getBusinessObject(element);
 
         var fill = getFillColor(element, defaultFillColor),
             stroke = getStrokeColor(element, defaultStrokeColor);
@@ -3772,7 +4141,7 @@
       },
       'bpmn:MessageFlow': function(parentGfx, element) {
 
-        var semantic = getSemantic(element),
+        var semantic = getBusinessObject(element),
             di = getDi(element);
 
         var fill = getFillColor(element, defaultFillColor),
@@ -3847,7 +4216,7 @@
           stroke: getStrokeColor(element, defaultStrokeColor)
         });
 
-        var semantic = getSemantic(element);
+        var semantic = getBusinessObject(element);
 
         if (isCollection(semantic)) {
           renderDataItemCollection(parentGfx, element);
@@ -3903,7 +4272,7 @@
       },
       'bpmn:BoundaryEvent': function(parentGfx, element) {
 
-        var semantic = getSemantic(element),
+        var semantic = getBusinessObject(element),
             cancel = semantic.cancelActivity;
 
         var attrs = {
@@ -3969,7 +4338,7 @@
           stroke: getStrokeColor(element, defaultStrokeColor)
         });
 
-        var text = getSemantic(element).text || '';
+        var text = getBusinessObject(element).text || '';
         renderLabel(parentGfx, text, {
           box: element,
           align: 'left-top',
@@ -4118,7 +4487,7 @@
     };
 
     function attachTaskMarkers(parentGfx, element, taskMarkers) {
-      var obj = getSemantic(element);
+      var obj = getBusinessObject(element);
 
       var subprocess = taskMarkers && taskMarkers.indexOf('SubProcessMarker') !== -1;
       var position;
@@ -4212,10 +4581,23 @@
   ];
 
 
+  /**
+   * @param {DiagramElement} element
+   *
+   * @return {boolean}
+   */
   BpmnRenderer.prototype.canRender = function(element) {
     return is$1(element, 'bpmn:BaseElement');
   };
 
+  /**
+   * Draw shape into parentGfx.
+   *
+   * @param {SVGElement} parentGfx
+   * @param {DiagramElement} element
+   *
+   * @return {SVGElement} mainGfx
+   */
   BpmnRenderer.prototype.drawShape = function(parentGfx, element) {
     var type = element.type;
     var h = this._renderer(type);
@@ -4224,6 +4606,14 @@
     return h(parentGfx, element);
   };
 
+  /**
+   * Draw connection into parentGfx.
+   *
+   * @param {SVGElement} parentGfx
+   * @param {DiagramElement} element
+   *
+   * @return {SVGElement} mainGfx
+   */
   BpmnRenderer.prototype.drawConnection = function(parentGfx, element) {
     var type = element.type;
     var h = this._renderer(type);
@@ -4232,6 +4622,13 @@
     return h(parentGfx, element);
   };
 
+  /**
+   * Get shape path.
+   *
+   * @param {DiagramElement} element
+   *
+   * @return {string} path
+   */
   BpmnRenderer.prototype.getShapePath = function(element) {
 
     if (is$1(element, 'bpmn:Event')) {
@@ -4251,16 +4648,55 @@
 
   /**
    * @typedef {import('../util/Types').Dimensions} Dimensions
+   *
+   * @typedef { {
+   *   top: number;
+   *   left: number;
+   *   right: number;
+   *   bottom: number;
+   * } } Padding
+   *
+   * @typedef { number | Partial<Padding> } PaddingConfig
+   *
+   * @typedef { {
+   *   horizontal: 'center' | 'left';
+   *   vertical: 'top' | 'center';
+   * } } Alignment
+   *
+   *  @typedef { 'center-middle' | 'center-top' } AlignmentConfig
+   *
+   * @typedef { Partial<{
+   *   align: AlignmentConfig;
+   *   style: Record<string, number | string>;
+   *   padding: PaddingConfig;
+   * }> } BaseTextConfig
+   *
+   * @typedef { BaseTextConfig & Partial<{
+   *   size: Dimensions;
+   * }> } TextConfig
+   *
+   * @typedef { BaseTextConfig & Partial<{
+   *   box: Dimensions;
+   *   fitBox: boolean;
+   * }> } TextLayoutConfig
+   *
+   *  @typedef { Dimensions & {
+   *  text: string;
+   * } } LineDescriptor
    */
 
   var DEFAULT_BOX_PADDING = 0;
 
-  var DEFAULT_LABEL_SIZE$1 = {
+  var DEFAULT_LABEL_SIZE = {
     width: 150,
     height: 50
   };
 
 
+  /**
+   * @param {AlignmentConfig} align
+   * @return {Alignment}
+   */
   function parseAlign(align) {
 
     var parts = align.split('-');
@@ -4271,6 +4707,11 @@
     };
   }
 
+  /**
+   * @param {PaddingConfig} padding
+   *
+   * @return {Padding}
+   */
   function parsePadding(padding) {
 
     if (isObject(padding)) {
@@ -4285,6 +4726,12 @@
     }
   }
 
+  /**
+   * @param {string} text
+   * @param {SVGTextElement} fakeText
+   *
+   * @return {import('../util/Types').Dimensions}
+   */
   function getTextBBox(text, fakeText) {
 
     fakeText.textContent = text;
@@ -4327,8 +4774,10 @@
    * Alters the lines passed.
    *
    * @param {string[]} lines
+   * @param {number} maxWidth
+   * @param {SVGTextElement} fakeText
    *
-   * @return {Object} the line descriptor, an object { width, height, text }
+   * @return {LineDescriptor} the line descriptor
    */
   function layoutNext(lines, maxWidth, fakeText) {
 
@@ -4351,6 +4800,14 @@
     }
   }
 
+  /**
+   * @param {string[]} lines
+   * @param {string} fitLine
+   * @param {string} originalLine
+   * @param {Dimensions} textBBox
+   *
+   * @return {LineDescriptor}
+   */
   function fit(lines, fitLine, originalLine, textBBox) {
     if (fitLine.length < originalLine.length) {
       var remainder = originalLine.slice(fitLine.length).trim();
@@ -4414,6 +4871,13 @@
   }
 
 
+  /**
+   * @param {string} line
+   * @param {number} width
+   * @param {number} maxWidth
+   *
+   * @return {string}
+   */
   function shortenLine(line, width, maxWidth) {
     var length = Math.max(line.length * (maxWidth / width), 1);
 
@@ -4430,6 +4894,9 @@
   }
 
 
+  /**
+   * @return {SVGSVGElement}
+   */
   function getHelperSvg() {
     var helperSvg = document.getElementById('helper-svg');
 
@@ -4457,16 +4924,12 @@
   /**
    * Creates a new label utility
    *
-   * @param {Object} config
-   * @param {Dimensions} config.size
-   * @param {number} config.padding
-   * @param {Object} config.style
-   * @param {string} config.align
+   * @param {TextConfig} config
    */
   function Text(config) {
 
     this._config = assign$1({}, {
-      size: DEFAULT_LABEL_SIZE$1,
+      size: DEFAULT_LABEL_SIZE,
       padding: DEFAULT_BOX_PADDING,
       style: {},
       align: 'center-top'
@@ -4477,7 +4940,7 @@
    * Returns the layouted text as an SVG element.
    *
    * @param {string} text
-   * @param {Object} options
+   * @param {TextLayoutConfig} options
    *
    * @return {SVGElement}
    */
@@ -4489,7 +4952,7 @@
    * Returns a labels layouted dimensions.
    *
    * @param {string} text to layout
-   * @param {Object} options
+   * @param {TextLayoutConfig} options
    *
    * @return {Dimensions}
    */
@@ -4500,18 +4963,13 @@
   /**
    * Creates and returns a label and its bounding box.
    *
-   * @method Text#createText
-   *
    * @param {string} text the text to render on the label
-   * @param {Object} options
-   * @param {string} options.align how to align in the bounding box.
-   *                               Any of { 'center-middle', 'center-top' },
-   *                               defaults to 'center-top'.
-   * @param {string} options.style style to be applied to the text
-   * @param {boolean} options.fitBox indicates if box will be recalculated to
-   *                                 fit text
+   * @param {TextLayoutConfig} options
    *
-   * @return {Object} { element, dimensions }
+   * @return { {
+   *   element: SVGElement,
+   *   dimensions: Dimensions
+   * } }
    */
   Text.prototype.layoutText = function(text, options) {
     var box = assign$1({}, this._config.size, options.box),
@@ -4627,7 +5085,30 @@
 
   var MIN_TEXT_ANNOTATION_HEIGHT = 30;
 
+  /**
+   * @typedef { {
+   *   fontFamily: string;
+   *   fontSize: number;
+   *   fontWeight: string;
+   *   lineHeight: number;
+   * } } TextRendererStyle
+   *
+   * @typedef { {
+   *   defaultStyle?: Partial<TextRendererStyle>;
+   *   externalStyle?: Partial<TextRendererStyle>;
+   * } } TextRendererConfig
+   *
+   * @typedef { import('diagram-js/lib/util/Text').TextLayoutConfig } TextLayoutConfig
+   *
+   * @typedef { import('diagram-js/lib/util/Types').Rect } Rect
+   */
+
 
+  /**
+   * Renders text and computes text bounding boxes.
+   *
+   * @param {TextRendererConfig} [config]
+   */
   function TextRenderer(config) {
 
     var defaultStyle = assign$1({
@@ -4651,19 +5132,17 @@
      * Get the new bounds of an externally rendered,
      * layouted label.
      *
-     * @param  {Bounds} bounds
-     * @param  {string} text
+     * @param {Rect} bounds
+     * @param {string} text
      *
-     * @return {Bounds}
+     * @return {Rect}
      */
     this.getExternalLabelBounds = function(bounds, text) {
 
       var layoutedDimensions = textUtil.getDimensions(text, {
         box: {
           width: 90,
-          height: 30,
-          x: bounds.width / 2 + bounds.x,
-          y: bounds.height / 2 + bounds.y
+          height: 30
         },
         style: externalStyle
       });
@@ -4681,10 +5160,10 @@
     /**
      * Get the new bounds of text annotation.
      *
-     * @param  {Bounds} bounds
-     * @param  {string} text
+     * @param {Rect} bounds
+     * @param {string} text
      *
-     * @return {Bounds}
+     * @return {Rect}
      */
     this.getTextAnnotationBounds = function(bounds, text) {
 
@@ -4707,7 +5186,7 @@
      * Create a layouted text element.
      *
      * @param {string} text
-     * @param {Object} [options]
+     * @param {TextLayoutConfig} [options]
      *
      * @return {SVGElement} rendered text
      */
@@ -4736,9 +5215,8 @@
   ];
 
   /**
-   * Map containing SVG paths needed by BpmnRenderer.
+   * Map containing SVG paths needed by BpmnRenderer
    */
-
   function PathMap() {
 
     /**
@@ -5080,6 +5558,13 @@
       }
     };
 
+    /**
+     * Return raw path for the given ID.
+     *
+     * @param {string} pathId
+     *
+     * @return {string} raw path
+     */
     this.getRawPath = function getRawPath(pathId) {
       return this.pathMap[pathId].d;
     };
@@ -5132,6 +5617,7 @@
      *   </ul>
      * </p>
      *
+     * @return {string} scaled path
      */
     this.getScaledPath = function getScaledPath(pathId, param) {
       var rawPath = this.pathMap[pathId];
@@ -5215,7 +5701,9 @@
   };
 
   /**
-   * @typedef {import('./').Replacements} Replacements
+   * @typedef { {
+   *   [key: string]: string;
+   * } } TranslateReplacements
    */
 
   /**
@@ -5225,14 +5713,16 @@
    *
    * @example
    *
+   * ```javascript
    * // use it inside any diagram component by injecting `translate`.
    *
    * function MyService(translate) {
    *   alert(translate('HELLO {you}', { you: 'You!' }));
    * }
+   * ```
    *
    * @param {string} template to interpolate
-   * @param {Replacements} [replacements] a map with substitutes
+   * @param {TranslateReplacements} [replacements] a map with substitutes
    *
    * @return {string} the translated string
    */
@@ -5245,150 +5735,22 @@
     });
   }
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var TranslateModule = {
     translate: [ 'value', translate ]
   };
 
-  var DEFAULT_LABEL_SIZE = {
-    width: 90,
-    height: 20
-  };
-
-  var FLOW_LABEL_INDENT = 15;
-
-
-  /**
-   * Returns true if the given semantic has an external label
-   *
-   * @param {BpmnElement} semantic
-   * @return {boolean} true if has label
-   */
-  function isLabelExternal(semantic) {
-    return is$1(semantic, 'bpmn:Event') ||
-           is$1(semantic, 'bpmn:Gateway') ||
-           is$1(semantic, 'bpmn:DataStoreReference') ||
-           is$1(semantic, 'bpmn:DataObjectReference') ||
-           is$1(semantic, 'bpmn:DataInput') ||
-           is$1(semantic, 'bpmn:DataOutput') ||
-           is$1(semantic, 'bpmn:SequenceFlow') ||
-           is$1(semantic, 'bpmn:MessageFlow') ||
-           is$1(semantic, 'bpmn:Group');
-  }
-
-  /**
-   * Get the position for sequence flow labels
-   *
-   * @param  {Array<Point>} waypoints
-   * @return {Point} the label position
-   */
-  function getFlowLabelPosition(waypoints) {
-
-    // get the waypoints mid
-    var mid = waypoints.length / 2 - 1;
-
-    var first = waypoints[Math.floor(mid)];
-    var second = waypoints[Math.ceil(mid + 0.01)];
-
-    // get position
-    var position = getWaypointsMid(waypoints);
-
-    // calculate angle
-    var angle = Math.atan((second.y - first.y) / (second.x - first.x));
-
-    var x = position.x,
-        y = position.y;
-
-    if (Math.abs(angle) < Math.PI / 2) {
-      y -= FLOW_LABEL_INDENT;
-    } else {
-      x += FLOW_LABEL_INDENT;
-    }
-
-    return { x: x, y: y };
-  }
-
-
-  /**
-   * Get the middle of a number of waypoints
-   *
-   * @param  {Array<Point>} waypoints
-   * @return {Point} the mid point
-   */
-  function getWaypointsMid(waypoints) {
-
-    var mid = waypoints.length / 2 - 1;
-
-    var first = waypoints[Math.floor(mid)];
-    var second = waypoints[Math.ceil(mid + 0.01)];
-
-    return {
-      x: first.x + (second.x - first.x) / 2,
-      y: first.y + (second.y - first.y) / 2
-    };
-  }
-
-
-  function getExternalLabelMid(element) {
-
-    if (element.waypoints) {
-      return getFlowLabelPosition(element.waypoints);
-    } else if (is$1(element, 'bpmn:Group')) {
-      return {
-        x: element.x + element.width / 2,
-        y: element.y + DEFAULT_LABEL_SIZE.height / 2
-      };
-    } else {
-      return {
-        x: element.x + element.width / 2,
-        y: element.y + element.height + DEFAULT_LABEL_SIZE.height / 2
-      };
-    }
+  function getDefaultExportFromCjs (x) {
+  	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
   }
 
-
   /**
-   * Returns the bounds of an elements label, parsed from the elements DI or
-   * generated from its bounds.
+   * @param {Point} point
    *
-   * @param {BpmndDi} di
-   * @param {djs.model.Base} element
+   * @returns {Point}
    */
-  function getExternalLabelBounds(di, element) {
-
-    var mid,
-        size,
-        bounds,
-        label = di.label;
-
-    if (label && label.bounds) {
-      bounds = label.bounds;
-
-      size = {
-        width: Math.max(DEFAULT_LABEL_SIZE.width, bounds.width),
-        height: bounds.height
-      };
-
-      mid = {
-        x: bounds.x + bounds.width / 2,
-        y: bounds.y + bounds.height / 2
-      };
-    } else {
-
-      mid = getExternalLabelMid(element);
-
-      size = DEFAULT_LABEL_SIZE;
-    }
-
-    return assign$1({
-      x: mid.x - size.width / 2,
-      y: mid.y - size.height / 2
-    }, size);
-  }
-
-  function getDefaultExportFromCjs (x) {
-  	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
-  }
-
   function roundPoint(point) {
 
     return {
@@ -5509,7 +5871,7 @@
   /**
    * Get the mid of the given Element.
    *
-   * @param {Connection} connection
+   * @param {Element} element
    *
    * @return {Point}
    */
@@ -5539,6 +5901,23 @@
     return '<' + e.$type + (e.id ? ' id="' + e.id : '') + '" />';
   }
 
+  /**
+   * @typedef {import('diagram-js/lib/core/Canvas').default} Canvas
+   * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+   * @typedef {import('diagram-js/lib/i18n/translate/translate').default} Translate
+   *
+   * @typedef {import('../features/modeling/ElementFactory').default} ElementFactory
+   * @typedef {import('../draw/TextRenderer').default} TextRenderer
+   *
+   * @typedef {import('../model/Types').Element} Element
+   * @typedef {import('../model/Types').Label} Label
+   * @typedef {import('../model/Types').Shape} Shape
+   * @typedef {import('../model/Types').Connection} Connection
+   * @typedef {import('../model/Types').Root} Root
+   * @typedef {import('../model/Types').ModdleElement} ModdleElement
+   */
+
   /**
    * @param {ModdleElement} semantic
    * @param {ModdleElement} di
@@ -5610,8 +5989,14 @@
 
 
   /**
-   * Add bpmn element (semantic) to the canvas onto the
-   * specified parent shape.
+   * Add a BPMN element (semantic) to the canvas making it a child of the
+   * given parent.
+   *
+   * @param {ModdleElement} semantic
+   * @param {ModdleElement} di
+   * @param {Shape} parentElement
+   *
+   * @return {Shape | Root | Connection}
    */
   BpmnImporter.prototype.add = function(semantic, di, parentElement) {
     var element,
@@ -5720,10 +6105,10 @@
 
 
   /**
-   * Attach the boundary element to the given host
+   * Attach a boundary element to the given host.
    *
    * @param {ModdleElement} boundarySemantic
-   * @param {djs.model.Base} boundaryElement
+   * @param {Shape} boundaryElement
    */
   BpmnImporter.prototype._attachBoundary = function(boundarySemantic, boundaryElement) {
     var translate = this._translate;
@@ -5756,7 +6141,13 @@
 
 
   /**
-   * add label for an element
+   * Add a label to a given element.
+   *
+   * @param {ModdleElement} semantic
+   * @param {ModdleElement} di
+   * @param {Element} element
+   *
+   * @return {Label}
    */
   BpmnImporter.prototype.addLabel = function(semantic, di, element) {
     var bounds,
@@ -5788,11 +6179,14 @@
   };
 
   /**
-   * Return the drawn connection end based on the given side.
+   * Get the source or target of the given connection.
+   *
+   * @param {ModdleElement} semantic
+   * @param {'source' | 'target'} side
    *
-   * @throws {Error} if the end is not yet drawn
+   * @return {Element}
    */
-  BpmnImporter.prototype._getEnd = function(semantic, side) {
+  BpmnImporter.prototype._getConnectedElement = function(semantic, side) {
 
     var element,
         refSemantic,
@@ -5830,11 +6224,11 @@
   };
 
   BpmnImporter.prototype._getSource = function(semantic) {
-    return this._getEnd(semantic, 'source');
+    return this._getConnectedElement(semantic, 'source');
   };
 
   BpmnImporter.prototype._getTarget = function(semantic) {
-    return this._getEnd(semantic, 'target');
+    return this._getConnectedElement(semantic, 'target');
   };
 
 
@@ -5873,6 +6267,15 @@
     ]
   };
 
+  /**
+   * @typedef {import('../util/Types').Point} Point
+   */
+
+  /**
+   * @param {import('../core/EventBus').Event} event
+   *
+   * @return {Event}
+   */
   function getOriginal(event) {
     return event.originalEvent || event.srcEvent;
   }
@@ -5881,22 +6284,43 @@
     return (/mac/i).test(navigator.platform);
   }
 
+  /**
+   * @param {MouseEvent} event
+   * @param {string} button
+   *
+   * @return {boolean}
+   */
   function isButton(event, button) {
     return (getOriginal(event) || event).button === button;
   }
 
+  /**
+   * @param {MouseEvent} event
+   *
+   * @return {boolean}
+   */
   function isPrimaryButton(event) {
 
     // button === 0 -> left áka primary mouse button
     return isButton(event, 0);
   }
 
+  /**
+   * @param {MouseEvent} event
+   *
+   * @return {boolean}
+   */
   function isAuxiliaryButton(event) {
 
     // button === 1 -> auxiliary áka wheel button
     return isButton(event, 1);
   }
 
+  /**
+   * @param {MouseEvent} event
+   *
+   * @return {boolean}
+   */
   function hasPrimaryModifier(event) {
     var originalEvent = getOriginal(event) || event;
 
@@ -5912,7 +6336,11 @@
     }
   }
 
-
+  /**
+   * @param {MouseEvent} event
+   *
+   * @return {boolean}
+   */
   function hasSecondaryModifier(event) {
     var originalEvent = getOriginal(event) || event;
 
@@ -5920,11 +6348,13 @@
   }
 
   /**
-   * @typedef {import('../../model').Base} Base
+   * @typedef {import('../../model/Types').Element} Element
    *
    * @typedef {import('../../core/ElementRegistry').default} ElementRegistry
    * @typedef {import('../../core/EventBus').default} EventBus
    * @typedef {import('../../draw/Styles').default} Styles
+   *
+   * @typedef {import('../../util/Types').Point} Point
    */
 
   function allowAll(event) { return true; }
@@ -5968,7 +6398,7 @@
      *
      * @param {string} type local event name, e.g. element.click.
      * @param {MouseEvent|TouchEvent} event native event
-     * @param {Base} [element] the diagram element to emit the event on;
+     * @param {Element} [element] the diagram element to emit the event on;
      *                                   defaults to the event target
      */
     function fire(type, event, element) {
@@ -6051,7 +6481,7 @@
      *
      * @param {string} eventName the name of the triggered DOM event
      * @param {MouseEvent|TouchEvent} event
-     * @param {Base} targetElement
+     * @param {Element} targetElement
      */
     function triggerMouseEvent(eventName, event, targetElement) {
 
@@ -6217,7 +6647,7 @@
     /**
      * Create default hit for the given element.
      *
-     * @param {Base} element
+     * @param {Element} element
      * @param {SVGElement} gfx
      *
      * @return {SVGElement} created hit
@@ -6244,7 +6674,7 @@
      * Create hits for the given waypoints.
      *
      * @param {SVGElement} gfx
-     * @param {Array<Point>} waypoints
+     * @param {Point[]} waypoints
      *
      * @return {SVGElement}
      */
@@ -6263,7 +6693,7 @@
      * Create hits for a box.
      *
      * @param {SVGElement} gfx
-     * @param {string} hitType
+     * @param {string} type
      * @param {Object} attrs
      *
      * @return {SVGElement}
@@ -6289,7 +6719,7 @@
     /**
      * Update default hit of the element.
      *
-     * @param {Base} element
+     * @param {Element} element
      * @param {SVGElement} gfx
      *
      * @return {SVGElement} updated hit
@@ -6338,7 +6768,7 @@
    * @event element.hover
    *
    * @type {Object}
-   * @property {Base} element
+   * @property {Element} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6349,7 +6779,7 @@
    * @event element.out
    *
    * @type {Object}
-   * @property {Base} element
+   * @property {Element} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6360,7 +6790,7 @@
    * @event element.click
    *
    * @type {Object}
-   * @property {Base} element
+   * @property {Element} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6371,7 +6801,7 @@
    * @event element.dblclick
    *
    * @type {Object}
-   * @property {Base} element
+   * @property {Element} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6382,7 +6812,7 @@
    * @event element.mousedown
    *
    * @type {Object}
-   * @property {Base} element
+   * @property {Element} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6393,7 +6823,7 @@
    * @event element.mouseup
    *
    * @type {Object}
-   * @property {Base} element
+   * @property {Element} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
@@ -6405,11 +6835,14 @@
    * @event element.contextmenu
    *
    * @type {Object}
-   * @property {Base} element
+   * @property {Element} element
    * @property {SVGElement} gfx
    * @property {Event} originalEvent
    */
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var InteractionEventsModule = {
     __init__: [ 'interactionEvents' ],
     interactionEvents: [ 'type', InteractionEvents ]
@@ -6419,7 +6852,7 @@
    * Returns the surrounding bbox for all elements in
    * the array or the element primitive.
    *
-   * @param {Base|Base[]} elements
+   * @param {Element|Element[]} elements
    * @param {boolean} [stopRecursion=false]
    *
    * @return {Rect}
@@ -6472,7 +6905,13 @@
     };
   }
 
-
+  /**
+   * Get the element's type
+   *
+   * @param {Element} element
+   *
+   * @return {'connection' | 'shape' | 'root'}
+   */
   function getType(element) {
 
     if ('waypoints' in element) {
@@ -6486,15 +6925,19 @@
     return 'root';
   }
 
+  /**
+   * @param {Element} element
+   *
+   * @return {boolean}
+   */
   function isFrameElement(element) {
-
     return !!(element && element.isFrame);
   }
 
   var LOW_PRIORITY$2 = 500;
 
   /**
-   * @typedef {import('../../model').Base} Base
+   * @typedef {import('../../model/Types').Element} Element
    *
    * @typedef {import('../../core/EventBus').default} EventBus
    * @typedef {import('../../draw/Styles').default} Styles
@@ -6568,7 +7011,7 @@
    * element and an outline offset.
    *
    * @param {SVGElement} outline
-   * @param {Base} element
+   * @param {Element} element
    */
   Outline.prototype.updateShapeOutline = function(outline, element) {
 
@@ -6587,7 +7030,7 @@
    * the connection and an outline offset.
    *
    * @param {SVGElement} outline
-   * @param {Base} element
+   * @param {Element} connection
    */
   Outline.prototype.updateConnectionOutline = function(outline, connection) {
 
@@ -6605,12 +7048,16 @@
 
   Outline.$inject = [ 'eventBus', 'styles', 'elementRegistry' ];
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var OutlineModule = {
     __init__: [ 'outline' ],
     outline: [ 'type', Outline ]
   };
 
   /**
+   * @typedef {import('../../core/Canvas').default} Canvas
    * @typedef {import('../../core/EventBus').default} EventBus
    */
 
@@ -6618,15 +7065,17 @@
    * A service that offers the current selection in a diagram.
    * Offers the api to control the selection, too.
    *
-   * @class
-   *
    * @param {EventBus} eventBus
+   * @param {Canvas} canvas
    */
   function Selection(eventBus, canvas) {
 
     this._eventBus = eventBus;
     this._canvas = canvas;
 
+    /**
+     * @type {Object[]}
+     */
     this._selectedElements = [];
 
     var self = this;
@@ -6643,7 +7092,11 @@
 
   Selection.$inject = [ 'eventBus', 'canvas' ];
 
-
+  /**
+   * Deselect an element.
+   *
+   * @param {Object} element The element to deselect.
+   */
   Selection.prototype.deselect = function(element) {
     var selectedElements = this._selectedElements;
 
@@ -6658,26 +7111,33 @@
     }
   };
 
-
+  /**
+   * Get the selected elements.
+   *
+   * @return {Object[]} The selected elements.
+   */
   Selection.prototype.get = function() {
     return this._selectedElements;
   };
 
+  /**
+   * Check whether an element is selected.
+   *
+   * @param {Object} element The element.
+   *
+   * @return {boolean} Whether the element is selected.
+   */
   Selection.prototype.isSelected = function(element) {
     return this._selectedElements.indexOf(element) !== -1;
   };
 
 
   /**
-   * This method selects one or more elements on the diagram.
-   *
-   * By passing an additional add parameter you can decide whether or not the element(s)
-   * should be added to the already existing selection or not.
+   * Select one or many elements.
    *
-   * @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 The element(s) to select.
+   * @param {boolean} [add] Whether to add the element(s) to the selected elements.
+   * Defaults to `false`.
    */
   Selection.prototype.select = function(elements, add) {
     var selectedElements = this._selectedElements,
@@ -6963,6 +7423,9 @@
     return !element.hidden;
   }
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var SelectionModule = {
     __init__: [ 'selectionVisuals', 'selectionBehavior' ],
     __depends__: [
@@ -6982,7 +7445,7 @@
    *
    * The ids can be customized via a given prefix and contain a random value to avoid collisions.
    *
-   * @param {string} prefix a prefix to prepend to generated ids (for better readability)
+   * @param {string} [prefix] a prefix to prepend to generated ids (for better readability)
    */
   function IdGenerator(prefix) {
 
@@ -6993,7 +7456,7 @@
   /**
    * Returns a next unique ID.
    *
-   * @returns {string} the id
+   * @return {string} the id
    */
   IdGenerator.prototype.next = function() {
     return this._prefix + (++this._counter);
@@ -7009,12 +7472,54 @@
    * @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
+   * @typedef {import('../../model/Types').Element} Element
+   *
+   * @typedef { {
+   *   minZoom?: number,
+   *   maxZoom?: number
+   * } } OverlaysConfigShow
+   *
+   * @typedef { {
+   *   min?: number,
+   *   max?: number
+   * } } OverlaysConfigScale
+   *
+   * @typedef { {
+  *   id: string,
+  *   type: string | null,
+  *   element: Element | string
+  * } & OverlayAttrs } Overlay
+  *
+   * @typedef { {
+   *   html: HTMLElement | string,
+   *   position: {
+   *     top?: number,
+   *     right?: number,
+   *     bottom?: number,
+   *     left?: number
+   *   }
+   * } & OverlaysConfigDefault } OverlayAttrs
+   *
+   * @typedef { {
+   *   html: HTMLElement,
+   *   element: Element,
+   *   overlays: Overlay[]
+   * } } OverlayContainer
+   *
+   * @typedef {{
+   *   defaults?: OverlaysConfigDefault
+   * }} OverlaysConfig
+   *
+   * @typedef { {
+   *  show?: OverlaysConfigShow,
+   *  scale?: OverlaysConfigScale | boolean
+   * } } OverlaysConfigDefault
+   *
+   * @typedef { {
+   *   id?: string;
+   *   element?: Element | string;
+   *   type?: string;
+   * } | string } OverlaysFilter
    */
 
   /**
@@ -7024,6 +7529,7 @@
    *
    * @example
    *
+   * ```javascript
    * // add a pink badge on the top left of the shape
    *
    * overlays.add(someShape, {
@@ -7053,8 +7559,9 @@
    *   }
    *   html: '<div style="width: 10px; background: fuchsia; color: white;">0</div>'
    * });
+   * ```
    *
-   *
+   * ```javascript
    * // remove an overlay
    *
    * var id = overlays.add(...);
@@ -7076,6 +7583,7 @@
    *       }
    *     }
    * }
+   * ```
    *
    * @param {OverlaysConfig} config
    * @param {EventBus} eventBus
@@ -7134,6 +7642,7 @@
    *
    * @example
    *
+   * ```javascript
    * // return the single overlay with the given ID
    * overlays.get('some-id');
    *
@@ -7145,6 +7654,7 @@
    *
    * // 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).
    *
@@ -7182,7 +7692,7 @@
   /**
    * Adds an HTML overlay to an element.
    *
-   * @param {Base|string} element The element to add the overlay to.
+   * @param {Element|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.
    *
@@ -7270,7 +7780,7 @@
   /**
    * Checks whether overlays are shown.
    *
-   * @returns {boolean} Whether overlays are shown.
+   * @return {boolean} Whether overlays are shown.
    */
   Overlays.prototype.isShown = function() {
     return this._overlayRoot.style.display !== 'none';
@@ -7663,6 +8173,9 @@
     });
   }
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var OverlaysModule = {
     __init__: [ 'overlays' ],
     overlays: [ 'type', Overlays ]
@@ -7739,15 +8252,22 @@
     'graphicsFactory'
   ];
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var ChangeSupportModule = {
     __init__: [ 'changeSupport' ],
     changeSupport: [ 'type', ChangeSupport ]
   };
 
   /**
+   * @typedef {import('../core/Types').ElementLike} ElementLike
    * @typedef {import('../core/EventBus').default} EventBus
-   * @typedef {import(./CommandInterceptor).HandlerFunction} HandlerFunction
-   * @typedef {import(./CommandInterceptor).ComposeHandlerFunction} ComposeHandlerFunction
+   * @typedef {import('./CommandStack').CommandContext} CommandContext
+   *
+   * @typedef {string|string[]} Events
+   * @typedef { (context: CommandContext) => ElementLike[] | void } HandlerFunction
+   * @typedef { (context: CommandContext) => void } ComposeHandlerFunction
    */
 
   var DEFAULT_PRIORITY$1 = 1000;
@@ -7759,10 +8279,9 @@
    * @class
    * @constructor
    *
-   * @param {EventBus} eventBus
-   *
    * @example
    *
+   * ```javascript
    * import CommandInterceptor from 'diagram-js/lib/command/CommandInterceptor';
    *
    * class CommandLogger extends CommandInterceptor {
@@ -7773,6 +8292,9 @@
    *     console.log('commandStack.shape-create.preExecute', event);
    *   });
    * }
+   * ```
+   *
+   * @param {EventBus} eventBus
    */
   function CommandInterceptor(eventBus) {
 
@@ -7790,16 +8312,17 @@
     };
   }
 
+
   /**
-     * 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.
-     */
+   * Intercept a command during one of the phases.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {string} [hook] phase to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
   CommandInterceptor.prototype.on = function(events, hook, priority, handlerFn, unwrap, that) {
 
     if (isFunction(hook) || isNumber(hook)) {
@@ -7841,35 +8364,130 @@
     });
   };
 
+  /**
+   * Add a <canExecute> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.canExecute = createHook('canExecute');
+
+  /**
+   * Add a <preExecute> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.preExecute = createHook('preExecute');
 
-  var hooks = [
-    'canExecute',
-    'preExecute',
-    'preExecuted',
-    'execute',
-    'executed',
-    'postExecute',
-    'postExecuted',
-    'revert',
-    'reverted'
-  ];
+  /**
+   * Add a <preExecuted> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.preExecuted = createHook('preExecuted');
+
+  /**
+   * Add a <execute> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.execute = createHook('execute');
+
+  /**
+   * Add a <executed> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.executed = createHook('executed');
+
+  /**
+   * Add a <postExecute> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.postExecute = createHook('postExecute');
+
+  /**
+   * Add a <postExecuted> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.postExecuted = createHook('postExecuted');
+
+  /**
+   * Add a <revert> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.revert = createHook('revert');
+
+  /**
+   * Add a <reverted> phase of command interceptor.
+   *
+   * @param {Events} [events] command(s) to intercept
+   * @param {number} [priority]
+   * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+   * @param {boolean} [unwrap] whether the event should be unwrapped
+   * @param {any} [that]
+   */
+  CommandInterceptor.prototype.reverted = createHook('reverted');
 
   /*
    * Add prototype methods for each phase of command execution (e.g. execute,
    * revert).
+   *
+   * @param {string} hook
+   *
+   * @return { (
+   *   events?: Events,
+   *   priority?: number,
+   *   handlerFn: ComposeHandlerFunction|HandlerFunction,
+   *   unwrap?: boolean
+   * ) => any }
    */
-  forEach$1(hooks, function(hook) {
+  function createHook(hook) {
 
     /**
-     * Add prototype method for a specific phase of command execution.
+     * @this {CommandInterceptor}
      *
-     * @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.
+     * @param {Events} [events]
+     * @param {number} [priority]
+     * @param {ComposeHandlerFunction|HandlerFunction} handlerFn
+     * @param {boolean} [unwrap]
+     * @param {any} [that]
      */
-    CommandInterceptor.prototype[hook] = function(events, priority, handlerFn, unwrap, that) {
+    const hookFn = function(events, priority, handlerFn, unwrap, that) {
 
       if (isFunction(events) || isNumber(events)) {
         that = unwrap;
@@ -7881,7 +8499,9 @@
 
       this.on(events, hook, priority, handlerFn, unwrap, that);
     };
-  });
+
+    return hookFn;
+  }
 
   /**
    * @typedef {import('didi').Injector} Injector
@@ -7923,6 +8543,9 @@
 
   RootElementsBehavior.$inject = [ 'canvas', 'injector' ];
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var RootElementsModule = {
     __init__: [ 'rootElementsBehavior' ],
     rootElementsBehavior: [ 'type', RootElementsBehavior ]
@@ -7930,7 +8553,8 @@
 
   /**
    * @param {string} str
-   * @returns {string}
+   *
+   * @return {string}
    */
 
   var HTML_ESCAPE_MAP = {
@@ -7941,6 +8565,11 @@
     '\'': '&#39;'
   };
 
+  /**
+   * @param {string} str
+   *
+   * @return {string}
+   */
   function escapeHTML(str) {
     str = '' + str;
 
@@ -7949,14 +8578,19 @@
     });
   }
 
+  /**
+   * @typedef {import('../model/Types').Element} Element
+   * @typedef {import('../model/Types').ModdleElement} ModdleElement
+   */
+
   var planeSuffix = '_plane';
 
   /**
    * Get plane ID for a primary shape.
    *
-   * @param  {djs.model.Base|ModdleElement} element
+   * @param  {Element|ModdleElement} element
    *
-   * @returns {String}
+   * @return {string}
    */
   function getPlaneIdFromShape(element) {
     var id = element.id;
@@ -7972,32 +8606,40 @@
     return id + planeSuffix;
   }
 
+  /**
+   * @typedef {import('diagram-js/lib/core/Canvas').default} Canvas
+   * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+   *
+   * @typedef {import('../../model/Types').Element} Element
+   * @typedef {import('../../model/Types').Shape} Shape
+   */
+
   var OPEN_CLASS = 'bjs-breadcrumbs-shown';
 
 
   /**
    * Adds overlays that allow switching planes on collapsed subprocesses.
    *
-   * @param {eventBus} eventBus
-   * @param {elementRegistry} elementRegistry
-   * @param {overlays} overlays
-   * @param {canvas} canvas
+   * @param {EventBus} eventBus
+   * @param {ElementRegistry} elementRegistry
+   * @param {Canvas} canvas
    */
-  function DrilldownBreadcrumbs(eventBus, elementRegistry, overlays, canvas) {
+  function DrilldownBreadcrumbs(eventBus, elementRegistry, canvas) {
     var breadcrumbs = domify$1('<ul class="bjs-breadcrumbs"></ul>');
     var container = canvas.getContainer();
     var containerClasses = classes(container);
     container.appendChild(breadcrumbs);
 
-    var boParents = [];
+    var businessObjectParents = [];
 
     // update breadcrumbs if name or ID of the primary shape changes
-    eventBus.on('element.changed', function(e) {
-      var shape = e.element,
-          bo = getBusinessObject(shape);
+    eventBus.on('element.changed', function(event) {
+      var shape = event.element,
+          businessObject = getBusinessObject(shape);
 
-      var isPresent = find(boParents, function(el) {
-        return el === bo;
+      var isPresent = find(businessObjectParents, function(element) {
+        return element === businessObject;
       });
 
       if (!isPresent) {
@@ -8011,14 +8653,14 @@
      * Updates the displayed breadcrumbs. If no element is provided, only the
      * labels are updated.
      *
-     * @param {djs.model.Base} [element]
+     * @param {Element} [element]
      */
     function updateBreadcrumbs(element) {
       if (element) {
-        boParents = getBoParentChain(element);
+        businessObjectParents = getBusinessObjectParentChain(element);
       }
 
-      var path = boParents.map(function(parent) {
+      var path = businessObjectParents.map(function(parent) {
         var title = escapeHTML(parent.name || parent.id);
         var link = domify$1('<li><span class="bjs-crumb"><a title="' + title + '">' + title + '</a></span></li>');
 
@@ -8028,8 +8670,9 @@
         // element in the elementRegisty. Instead, we search for the corresponding participant
         if (!parentPlane && is$1(parent, 'bpmn:Process')) {
           var participant = elementRegistry.find(function(element) {
-            var bo = getBusinessObject(element);
-            return bo && bo.processRef && bo.processRef === parent;
+            var businessObject = getBusinessObject(element);
+
+            return businessObject && businessObject.get('processRef') && businessObject.get('processRef') === parent;
           });
 
           parentPlane = canvas.findRoot(participant.id);
@@ -8046,10 +8689,11 @@
 
       // show breadcrumbs and expose state to .djs-container
       var visible = path.length > 1;
+
       containerClasses.toggle(OPEN_CLASS, visible);
 
-      path.forEach(function(el) {
-        breadcrumbs.appendChild(el);
+      path.forEach(function(element) {
+        breadcrumbs.appendChild(element);
       });
     }
 
@@ -8059,7 +8703,7 @@
 
   }
 
-  DrilldownBreadcrumbs.$inject = [ 'eventBus', 'elementRegistry', 'overlays', 'canvas' ];
+  DrilldownBreadcrumbs.$inject = [ 'eventBus', 'elementRegistry', 'canvas' ];
 
 
   // helpers //////////
@@ -8068,16 +8712,16 @@
    * Returns the parents for the element using the business object chain,
    * starting with the root element.
    *
-   * @param {djs.model.Shape} child
+   * @param {Shape} child
    *
-   * @returns {Array<djs.model.Shape>} parents
+   * @return {Shape}
    */
-  function getBoParentChain(child) {
-    var bo = getBusinessObject(child);
+  function getBusinessObjectParentChain(child) {
+    var businessObject = getBusinessObject(child);
 
     var parents = [];
 
-    for (var element = bo; element; element = element.$parent) {
+    for (var element = businessObject; element; element = element.$parent) {
       if (is$1(element, 'bpmn:SubProcess') || is$1(element, 'bpmn:Process')) {
         parents.push(element);
       }
@@ -8086,13 +8730,18 @@
     return parents.reverse();
   }
 
+  /**
+   * @typedef {import('diagram-js/lib/core/Canvas').default} Canvas
+   * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+   */
+
   /**
    * Move collapsed subprocesses into view when drilling down.
    *
    * Zoom and scroll are saved in a session.
    *
-   * @param {eventBus} eventBus
-   * @param {canvas} canvas
+   * @param {EventBus} eventBus
+   * @param {Canvas} canvas
    */
   function DrilldownCentering(eventBus, canvas) {
 
@@ -8203,6 +8852,18 @@
     };
   }
 
+  /**
+   * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+   * @typedef {import('../../model/Types').Moddle} Moddle
+   *
+   * @typedef {import('../../model/Types').Element} Element
+   * @typedef {import('../../model/Types').Shape} Shape
+   *
+   * @typedef {import('diagram-js/lib/core/Canvas').CanvasPlane} CanvasPlane
+   *
+   * @typedef {import('diagram-js/lib/util/Types').Rect} Rect
+   */
+
   var DEFAULT_POSITION = {
     x: 180,
     y: 160
@@ -8210,10 +8871,10 @@
 
   /**
    * Hook into `import.render.start` and create new planes for diagrams with
-   * collapsed subprocesses and all dis on the same plane.
+   * collapsed subprocesses and all DI elements on the same plane.
    *
-   * @param {eventBus} eventBus
-   * @param {moddle} moddle
+   * @param {EventBus} eventBus
+   * @param {Moddle} moddle
    */
   function SubprocessCompatibility(eventBus, moddle) {
     this._eventBus = eventBus;
@@ -8222,11 +8883,14 @@
     var self = this;
 
     eventBus.on('import.render.start', 1500, function(e, context) {
-      self.handleImport(context.definitions);
+      self._handleImport(context.definitions);
     });
   }
 
-  SubprocessCompatibility.prototype.handleImport = function(definitions) {
+  /**
+   * @param {ModdleElement} definitions
+   */
+  SubprocessCompatibility.prototype._handleImport = function(definitions) {
     if (!definitions.diagrams) {
       return;
     }
@@ -8245,12 +8909,12 @@
 
     var newDiagrams = [];
     definitions.diagrams.forEach(function(diagram) {
-      var createdDiagrams = self.createNewDiagrams(diagram.plane);
+      var createdDiagrams = self._createNewDiagrams(diagram.plane);
       Array.prototype.push.apply(newDiagrams, createdDiagrams);
     });
 
     newDiagrams.forEach(function(diagram) {
-      self.movePlaneElementsToOrigin(diagram.plane);
+      self._movePlaneElementsToOrigin(diagram.plane);
     });
   };
 
@@ -8258,29 +8922,30 @@
   /**
    * Moves all DI elements from collapsed subprocesses to a new plane.
    *
-   * @param {Object} plane
-   * @return {Array} new diagrams created for the collapsed subprocesses
+   * @param {CanvasPlane} plane
+   *
+   * @return {ModdleElement[]} new diagrams created for the collapsed subprocesses
    */
-  SubprocessCompatibility.prototype.createNewDiagrams = function(plane) {
+  SubprocessCompatibility.prototype._createNewDiagrams = function(plane) {
     var self = this;
 
     var collapsedElements = [];
     var elementsToMove = [];
 
     plane.get('planeElement').forEach(function(diElement) {
-      var bo = diElement.bpmnElement;
+      var businessObject = diElement.bpmnElement;
 
-      if (!bo) {
+      if (!businessObject) {
         return;
       }
 
-      var parent = bo.$parent;
+      var parent = businessObject.$parent;
 
-      if (is$1(bo, 'bpmn:SubProcess') && !diElement.isExpanded) {
-        collapsedElements.push(bo);
+      if (is$1(businessObject, 'bpmn:SubProcess') && !diElement.isExpanded) {
+        collapsedElements.push(businessObject);
       }
 
-      if (shouldMoveToPlane(bo, plane)) {
+      if (shouldMoveToPlane(businessObject, plane)) {
 
         // don't change the array while we iterate over it
         elementsToMove.push({ diElement: diElement, parent: parent });
@@ -8291,9 +8956,11 @@
 
     // create new planes for all collapsed subprocesses, even when they are empty
     collapsedElements.forEach(function(element) {
-      if (!self._processToDiagramMap[element.id]) {
-        var diagram = self.createDiagram(element);
+      if (!self._processToDiagramMap[ element.id ]) {
+        var diagram = self._createDiagram(element);
+
         self._processToDiagramMap[element.id] = diagram;
+
         newDiagrams.push(diagram);
       }
     });
@@ -8312,14 +8979,18 @@
         return;
       }
 
-      var diagram = self._processToDiagramMap[parent.id];
-      self.moveToDiPlane(diElement, diagram.plane);
+      var diagram = self._processToDiagramMap[ parent.id ];
+
+      self._moveToDiPlane(diElement, diagram.plane);
     });
 
     return newDiagrams;
   };
 
-  SubprocessCompatibility.prototype.movePlaneElementsToOrigin = function(plane) {
+  /**
+   * @param {CanvasPlane} plane
+   */
+  SubprocessCompatibility.prototype._movePlaneElementsToOrigin = function(plane) {
     var elements = plane.get('planeElement');
 
     // get bounding box of all elements
@@ -8343,33 +9014,50 @@
     });
   };
 
-
-  SubprocessCompatibility.prototype.moveToDiPlane = function(diElement, newPlane) {
+  /**
+   * @param {ModdleElement} diElement
+   * @param {CanvasPlane} newPlane
+   */
+  SubprocessCompatibility.prototype._moveToDiPlane = function(diElement, newPlane) {
     var containingDiagram = findRootDiagram(diElement);
 
     // remove DI from old Plane and add it to the new one
     var parentPlaneElement = containingDiagram.plane.get('planeElement');
+
     parentPlaneElement.splice(parentPlaneElement.indexOf(diElement), 1);
+
     newPlane.get('planeElement').push(diElement);
   };
 
+  /**
+   * @param {ModdleElement} businessObject
+   *
+   * @return {ModdleElement}
+   */
+  SubprocessCompatibility.prototype._createDiagram = function(businessObject) {
+    var plane = this._moddle.create('bpmndi:BPMNPlane', {
+      bpmnElement: businessObject
+    });
 
-  SubprocessCompatibility.prototype.createDiagram = function(bo) {
-    var plane = this._moddle.create('bpmndi:BPMNPlane', { bpmnElement: bo });
     var diagram = this._moddle.create('bpmndi:BPMNDiagram', {
       plane: plane
     });
+
     plane.$parent = diagram;
-    plane.bpmnElement = bo;
+
+    plane.bpmnElement = businessObject;
+
     diagram.$parent = this._definitions;
+
     this._definitions.diagrams.push(diagram);
+
     return diagram;
   };
 
   SubprocessCompatibility.$inject = [ 'eventBus', 'moddle' ];
 
 
-  // helpers //////////////////////////
+  // helpers //////////
 
   function findRootDiagram(element) {
     if (is$1(element, 'bpmndi:BPMNDiagram')) {
@@ -8379,6 +9067,11 @@
     }
   }
 
+  /**
+   * @param {CanvasPlane} plane
+   *
+   * @return {Rect}
+   */
   function getPlaneBounds(plane) {
     var planeTrbl = {
       top: Infinity,
@@ -8401,8 +9094,14 @@
     return asBounds(planeTrbl);
   }
 
-  function shouldMoveToPlane(bo, plane) {
-    var parent = bo.$parent;
+  /**
+   * @param {ModdleElement} businessObject
+   * @param {CanvasPlane} plane
+   *
+   * @return {boolean}
+   */
+  function shouldMoveToPlane(businessObject, plane) {
+    var parent = businessObject.$parent;
 
     // don't move elements that are already on the plane
     if (!is$1(parent, 'bpmn:SubProcess') || parent === plane.bpmnElement) {
@@ -8411,18 +9110,35 @@
 
     // dataAssociations are children of the subprocess but rendered on process level
     // cf. https://github.com/bpmn-io/bpmn-js/issues/1619
-    if (isAny(bo, [ 'bpmn:DataInputAssociation', 'bpmn:DataOutputAssociation' ])) {
+    if (isAny(businessObject, [ 'bpmn:DataInputAssociation', 'bpmn:DataOutputAssociation' ])) {
       return false;
     }
 
     return true;
   }
 
+  /**
+   * @typedef {import('diagram-js/lib/core/Canvas').default} Canvas
+   * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+   * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+   * @typedef {import('diagram-js/lib/features/overlays/Overlays').default} Overlays
+   *
+   * @typedef {import('../../model/Types').Element} Element
+   * @typedef {import('../../model/Types').Parent} Parent
+   * @typedef {import('../../model/Types').Shape} Shape
+   */
+
   var LOW_PRIORITY = 250;
   var ARROW_DOWN_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M4.81801948,3.50735931 L10.4996894,9.1896894 L10.5,4 L12,4 L12,12 L4,12 L4,10.5 L9.6896894,10.4996894 L3.75735931,4.56801948 C3.46446609,4.27512627 3.46446609,3.80025253 3.75735931,3.50735931 C4.05025253,3.21446609 4.52512627,3.21446609 4.81801948,3.50735931 Z"/></svg>';
 
   var EMPTY_MARKER = 'bjs-drilldown-empty';
 
+  /**
+   * @param {Canvas} canvas
+   * @param {EventBus} eventBus
+   * @param {ElementRegistry} elementRegistry
+   * @param {Overlays} overlays
+   */
   function DrilldownOverlayBehavior(
       canvas, eventBus, elementRegistry, overlays
   ) {
@@ -8439,10 +9155,10 @@
       var shape = context.shape;
 
       // Add overlay to the collapsed shape
-      if (self.canDrillDown(shape)) {
-        self.addOverlay(shape);
+      if (self._canDrillDown(shape)) {
+        self._addOverlay(shape);
       } else {
-        self.removeOverlay(shape);
+        self._removeOverlay(shape);
       }
     }, true);
 
@@ -8451,10 +9167,10 @@
       var shape = context.shape;
 
       // Add overlay to the collapsed shape
-      if (self.canDrillDown(shape)) {
-        self.addOverlay(shape);
+      if (self._canDrillDown(shape)) {
+        self._addOverlay(shape);
       } else {
-        self.removeOverlay(shape);
+        self._removeOverlay(shape);
       }
     }, true);
 
@@ -8466,13 +9182,13 @@
             shape = context.shape;
 
         // Add overlay to the collapsed shape
-        if (self.canDrillDown(shape)) {
-          self.addOverlay(shape);
+        if (self._canDrillDown(shape)) {
+          self._addOverlay(shape);
         }
 
-        self.updateDrilldownOverlay(oldParent);
-        self.updateDrilldownOverlay(newParent);
-        self.updateDrilldownOverlay(shape);
+        self._updateDrilldownOverlay(oldParent);
+        self._updateDrilldownOverlay(newParent);
+        self._updateDrilldownOverlay(shape);
       }, true);
 
 
@@ -8483,21 +9199,21 @@
             shape = context.shape;
 
         // Add overlay to the collapsed shape
-        if (self.canDrillDown(shape)) {
-          self.addOverlay(shape);
+        if (self._canDrillDown(shape)) {
+          self._addOverlay(shape);
         }
 
-        self.updateDrilldownOverlay(oldParent);
-        self.updateDrilldownOverlay(newParent);
-        self.updateDrilldownOverlay(shape);
+        self._updateDrilldownOverlay(oldParent);
+        self._updateDrilldownOverlay(newParent);
+        self._updateDrilldownOverlay(shape);
       }, true);
 
 
     eventBus.on('import.render.complete', function() {
       elementRegistry.filter(function(e) {
-        return self.canDrillDown(e);
+        return self._canDrillDown(e);
       }).map(function(el) {
-        self.addOverlay(el);
+        self._addOverlay(el);
       });
     });
 
@@ -8505,7 +9221,10 @@
 
   e(DrilldownOverlayBehavior, CommandInterceptor);
 
-  DrilldownOverlayBehavior.prototype.updateDrilldownOverlay = function(shape) {
+  /**
+   * @param {Shape} shape
+   */
+  DrilldownOverlayBehavior.prototype._updateDrilldownOverlay = function(shape) {
     var canvas = this._canvas;
 
     if (!shape) {
@@ -8513,51 +9232,61 @@
     }
 
     var root = canvas.findRoot(shape);
+
     if (root) {
-      this.updateOverlayVisibility(root);
+      this._updateOverlayVisibility(root);
     }
   };
 
-
-  DrilldownOverlayBehavior.prototype.canDrillDown = function(element) {
+  /**
+   * @param {Element} element
+   *
+   * @return {boolean}
+   */
+  DrilldownOverlayBehavior.prototype._canDrillDown = function(element) {
     var canvas = this._canvas;
+
     return is$1(element, 'bpmn:SubProcess') && canvas.findRoot(getPlaneIdFromShape(element));
   };
 
   /**
-   * Updates visibility of the drilldown overlay. If the plane has no elements,
-   * the drilldown will be only shown when the element is selected.
+   * Update the visibility of the drilldown overlay. If the plane has no elements,
+   * the drilldown will only be shown when the element is selected.
    *
-   * @param {djs.model.Shape|djs.model.Root} element collapsed shape or root element
+   * @param {Parent} element The collapsed root or shape.
    */
-  DrilldownOverlayBehavior.prototype.updateOverlayVisibility = function(element) {
+  DrilldownOverlayBehavior.prototype._updateOverlayVisibility = function(element) {
     var overlays = this._overlays;
 
-    var bo = element.businessObject;
+    var businessObject = getBusinessObject(element);
 
-    var overlay = overlays.get({ element: bo.id, type: 'drilldown' })[0];
+    var overlay = overlays.get({ element: businessObject.id, type: 'drilldown' })[0];
 
     if (!overlay) {
       return;
     }
 
-    var hasContent = bo && bo.flowElements && bo.flowElements.length;
-    classes(overlay.html).toggle(EMPTY_MARKER, !hasContent);
+    var hasFlowElements = businessObject
+      && businessObject.get('flowElements')
+      && businessObject.get('flowElements').length;
+
+    classes(overlay.html).toggle(EMPTY_MARKER, !hasFlowElements);
   };
 
   /**
-   * Attaches a drilldown button to the given element. We assume that the plane has
-   * the same id as the element.
+   * Add a drilldown button to the given element assuming the plane has the same
+   * ID as the element.
    *
-   * @param {djs.model.Shape} element collapsed shape
+   * @param {Shape} element The collapsed shape.
    */
-  DrilldownOverlayBehavior.prototype.addOverlay = function(element) {
-    var canvas = this._canvas;
-    var overlays = this._overlays;
+  DrilldownOverlayBehavior.prototype._addOverlay = function(element) {
+    var canvas = this._canvas,
+        overlays = this._overlays;
 
     var existingOverlays = overlays.get({ element: element, type: 'drilldown' });
+
     if (existingOverlays.length) {
-      this.removeOverlay(element);
+      this._removeOverlay(element);
     }
 
     var button = domify$1('<button class="bjs-drilldown">' + ARROW_DOWN_SVG + '</button>');
@@ -8574,10 +9303,10 @@
       html: button
     });
 
-    this.updateOverlayVisibility(element);
+    this._updateOverlayVisibility(element);
   };
 
-  DrilldownOverlayBehavior.prototype.removeOverlay = function(element) {
+  DrilldownOverlayBehavior.prototype._removeOverlay = function(element) {
     var overlays = this._overlays;
 
     overlays.remove({
@@ -9083,7 +9812,6 @@
    */
   function DefaultRenderer(eventBus, styles) {
 
-    //
     BaseRenderer.call(this, eventBus, DEFAULT_RENDER_PRIORITY);
 
     this.CONNECTION_STYLE = styles.style([ 'no-fill' ], { strokeWidth: 5, stroke: 'fuchsia' });
@@ -9094,10 +9822,16 @@
   e(DefaultRenderer, BaseRenderer);
 
 
+  /**
+   * @private
+   */
   DefaultRenderer.prototype.canRender = function() {
     return true;
   };
 
+  /**
+   * @private
+   */
   DefaultRenderer.prototype.drawShape = function drawShape(visuals, element, attrs) {
     var rect = create$1('rect');
 
@@ -9119,6 +9853,9 @@
     return rect;
   };
 
+  /**
+   * @private
+   */
   DefaultRenderer.prototype.drawConnection = function drawConnection(visuals, connection, attrs) {
 
     var line = createLine(connection.waypoints, assign$1({}, this.CONNECTION_STYLE, attrs || {}));
@@ -9127,6 +9864,9 @@
     return line;
   };
 
+  /**
+   * @private
+   */
   DefaultRenderer.prototype.getShapePath = function getShapePath(shape) {
 
     var x = shape.x,
@@ -9145,6 +9885,9 @@
     return componentsToPath(shapePath);
   };
 
+  /**
+   * @private
+   */
   DefaultRenderer.prototype.getConnectionPath = function getConnectionPath(connection) {
     var waypoints = connection.waypoints;
 
@@ -9162,7 +9905,6 @@
     return componentsToPath(connectionPath);
   };
 
-
   DefaultRenderer.$inject = [ 'eventBus', 'styles' ];
 
   /**
@@ -9186,13 +9928,14 @@
     var self = this;
 
     /**
-     * Builds a style definition from a className, a list of traits and an object of additional attributes.
+     * 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[]} [traits]
+     * @param {Object} [additionalAttrs]
      *
-     * @return {Object} the style defintion
+     * @return {Object} the style definition
      */
     this.cls = function(className, traits, additionalAttrs) {
       var attrs = this.style(traits, additionalAttrs);
@@ -9201,12 +9944,13 @@
     };
 
     /**
-     * Builds a style definition from a list of traits and an object of additional attributes.
+     * Builds a style definition from a list of traits and an object of additional
+     * attributes.
      *
-     * @param {Array<string>} traits
+     * @param {string[]} [traits]
      * @param {Object} additionalAttrs
      *
-     * @return {Object} the style defintion
+     * @return {Object} the style definition
      */
     this.style = function(traits, additionalAttrs) {
 
@@ -9222,6 +9966,17 @@
       return additionalAttrs ? assign$1(attrs, additionalAttrs) : attrs;
     };
 
+
+    /**
+     * Computes a style definition from a list of traits and an object of
+     * additional attributes, with custom style definition object.
+     *
+     * @param {Object} custom
+     * @param {string[]} [traits]
+     * @param {Object} defaultStyles
+     *
+     * @return {Object} the style definition
+     */
     this.computeStyle = function(custom, traits, defaultStyles) {
       if (!isArray$2(traits)) {
         defaultStyles = traits;
@@ -9232,6 +9987,9 @@
     };
   }
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var DrawModule = {
     __init__: [ 'defaultRenderer' ],
     defaultRenderer: [ 'type', DefaultRenderer ],
@@ -9267,7 +10025,7 @@
    *
    * @param {Array<Object>} collection
    * @param {Object} element
-   * @param {number} idx
+   * @param {number} [idx]
    */
   function add(collection, element, idx) {
 
@@ -9313,15 +10071,34 @@
   }
 
   /**
-   * @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('./Types').ConnectionLike} ConnectionLike
+   * @typedef {import('./Types').RootLike} RootLike
+   * @typedef {import('./Types').ParentLike } ParentLike
+   * @typedef {import('./Types').ShapeLike} ShapeLike
+   *
+   * @typedef { {
+   *   container?: HTMLElement;
+   *   deferUpdate?: boolean;
+   *   width?: number;
+   *   height?: number;
+   * } } CanvasConfig
+   * @typedef { {
+   *   group: SVGElement;
+   *   index: number;
+   *   visible: boolean;
+   * } } CanvasLayer
+   * @typedef { {
+   *   [key: string]: CanvasLayer;
+   * } } CanvasLayers
+   * @typedef { {
+   *   rootElement: ShapeLike;
+   *   layer: CanvasLayer;
+   * } } CanvasPlane
+   * @typedef { {
+   *   scale: number;
+   *   inner: Rect;
+   *   outer: Dimensions;
+   * } & Rect } CanvasViewbox
    *
    * @typedef {import('./ElementRegistry').default} ElementRegistry
    * @typedef {import('./EventBus').default} EventBus
@@ -9662,7 +10439,7 @@
   /**
    * Shows a given layer.
    *
-   * @param {string} layer The name of the layer.
+   * @param {string} name The name of the layer.
    *
    * @return {SVGElement} The SVG element of the layer.
    */
@@ -9698,7 +10475,7 @@
   /**
    * Hides a given layer.
    *
-   * @param {string} layer The name of the layer.
+   * @param {string} name The name of the layer.
    *
    * @return {SVGElement} The SVG element of the layer.
    */
@@ -9840,7 +10617,7 @@
      *
      * @event element.marker.update
      * @type {Object}
-     * @property {Base} element the shape
+     * @property {Element} 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
@@ -9857,11 +10634,13 @@
    *
    * @example
    *
+   * ```javascript
    * canvas.addMarker('foo', 'some-marker');
    *
    * const fooGfx = canvas.getGraphics('foo');
    *
    * fooGfx; // <g class="... some-marker"> ... </g>
+   * ```
    *
    * @param {ShapeLike|ConnectionLike|string} element The element or its ID.
    * @param {string} marker The marker.
@@ -9946,7 +10725,7 @@
   /**
    * Adds a given root element and returns it.
    *
-   * @param {ShapeLike} [rootElement] The root element to be added.
+   * @param {RootLike} [rootElement] The root element to be added.
    *
    * @return {RootLike} The added root element or an implicit root element.
    */
@@ -9982,9 +10761,9 @@
   /**
    * Removes a given root element and returns it.
    *
-   * @param {ShapeLike|string} rootElement The root element or its ID.
+   * @param {RootLike|string} rootElement element or element ID
    *
-   * @return {ShapeLike|undefined} The removed root element.
+   * @return {RootLike|undefined} removed element
    */
   Canvas.prototype.removeRootElement = function(rootElement) {
 
@@ -10026,11 +10805,7 @@
    *
    * @return {RootLike} The set root element.
    */
-  Canvas.prototype.setRootElement = function(rootElement, override) {
-
-    if (isDefined(override)) {
-      throw new Error('override not supported');
-    }
+  Canvas.prototype.setRootElement = function(rootElement) {
 
     if (rootElement === this._rootElement) {
       return;
@@ -10187,7 +10962,7 @@
    * Adds a shape to the canvas.
    *
    * @param {ShapeLike} shape The shape to be added
-   * @param {ShapeLike} [parent] The shape's parent.
+   * @param {ParentLike} [parent] The shape's parent.
    * @param {number} [parentIndex] The index at which to add the shape to the parent's children.
    *
    * @return {ShapeLike} The added shape.
@@ -10200,7 +10975,7 @@
    * Adds a connection to the canvas.
    *
    * @param {ConnectionLike} connection The connection to be added.
-   * @param {ShapeLike} [parent] The connection's parent.
+   * @param {ParentLike} [parent] The connection's parent.
    * @param {number} [parentIndex] The index at which to add the connection to the parent's children.
    *
    * @return {ConnectionLike} The added connection.
@@ -10271,7 +11046,7 @@
      *
      * @memberOf Canvas
      *
-     * @event ShapeRemoved
+     * @event ShapeRemovedEvent
      * @type {Object}
      * @property {ShapeLike} element The shape.
      * @property {SVGElement} gfx The graphical element.
@@ -10308,7 +11083,7 @@
      *
      * @memberOf Canvas
      *
-     * @event connection.removed
+     * @event ConnectionRemovedEvent
      * @type {Object}
      * @property {ConnectionLike} element The connection.
      * @property {SVGElement} gfx The graphical element.
@@ -10367,6 +11142,7 @@
    *
    * @example
    *
+   * ```javascript
    * canvas.viewbox({ x: 100, y: 100, width: 500, height: 500 })
    *
    * // sets the visible area of the diagram to (100|100) -> (600|100)
@@ -10394,6 +11170,7 @@
    *   width: zoomedAndScrolledViewbox.outer.width,
    *   height: zoomedAndScrolledViewbox.outer.height
    * });
+   * ```
    *
    * @param {Rect} [box] The viewbox to be set.
    *
@@ -10567,7 +11344,7 @@
    * The getter may return a cached zoom level. Call it with `false` as the first
    * argument to force recomputation of the current level.
    *
-   * @param {number|string} [newScale] The new zoom level, either a number,
+   * @param {number|'fit-viewport'} [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.
    *
@@ -10762,11 +11539,12 @@
   var ELEMENT_ID = 'data-element-id';
 
   /**
-   * @typedef {import('.').ElementLike} ElementLike
+   * @typedef {import('./Types').ElementLike} ElementLike
    *
    * @typedef {import('./EventBus').default} EventBus
    *
-   * @typedef {import('./ElementRegistry').ElementRegistryCallback} ElementRegistryCallback
+   * @typedef { (element: ElementLike, gfx: SVGElement) => boolean|any } ElementRegistryFilterCallback
+   * @typedef { (element: ElementLike, gfx: SVGElement) => any } ElementRegistryForEachCallback
    */
 
   /**
@@ -10778,6 +11556,16 @@
    * @param {EventBus} eventBus
    */
   function ElementRegistry(eventBus) {
+
+    /**
+     * @type { {
+     *   [id: string]: {
+     *     element: ElementLike;
+     *     gfx?: SVGElement;
+     *     secondaryGfx?: SVGElement;
+     *   }
+     * } }
+     */
     this._elements = {};
 
     this._eventBus = eventBus;
@@ -10863,7 +11651,7 @@
   /**
    * Update the graphical representation of an element.
    *
-   * @param {ElementLike|string} element The element or its ID.
+   * @param {ElementLike|string} filter The element or its ID.
    * @param {SVGElement} gfx The new graphical representation.
    * @param {boolean} [secondary=false] Whether to update the secondary graphical representation.
    */
@@ -10890,9 +11678,11 @@
    *
    * @example
    *
+   * ```javascript
    * elementRegistry.get('SomeElementId_1');
    *
    * elementRegistry.get(gfx);
+   * ```
    *
    * @param {string|SVGElement} filter The elements ID or graphical representation.
    *
@@ -10914,7 +11704,7 @@
   /**
    * Return all elements that match a given filter function.
    *
-   * @param {ElementRegistryCallback} fn The filter function.
+   * @param {ElementRegistryFilterCallback} fn The filter function.
    *
    * @return {ElementLike[]} The matching elements.
    */
@@ -10934,7 +11724,7 @@
   /**
    * Return the first element that matches the given filter function.
    *
-   * @param {Function} fn The filter function.
+   * @param {ElementRegistryFilterCallback} fn The filter function.
    *
    * @return {ElementLike|undefined} The matching element.
    */
@@ -10966,7 +11756,7 @@
   /**
    * Execute a given function for each element.
    *
-   * @param {Function} fn The function to execute.
+   * @param {ElementRegistryForEachCallback} fn The function to execute.
    */
   ElementRegistry.prototype.forEach = function(fn) {
 
@@ -10986,11 +11776,13 @@
    *
    * @example
    *
+   * ```javascript
    * 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.
@@ -11353,19 +12145,26 @@
       outgoingRefs = new Refs({ name: 'outgoing', collection: true }, { name: 'source' }),
       incomingRefs = new Refs({ name: 'incoming', collection: true }, { name: 'target' });
 
+  /**
+   * @typedef {import('./Types').Element} Element
+   * @typedef {import('./Types').Shape} Shape
+   * @typedef {import('./Types').Root} Root
+   * @typedef {import('./Types').Label} Label
+   * @typedef {import('./Types').Connection} Connection
+   */
+
   /**
    * The basic graphical representation
    *
    * @class
-   *
-   * @abstract
+   * @constructor
    */
-  function Base$1() {
+  function ElementImpl() {
 
     /**
      * The object that backs up the shape
      *
-     * @name Base#businessObject
+     * @name Element#businessObject
      * @type Object
      */
     Object.defineProperty(this, 'businessObject', {
@@ -11376,7 +12175,7 @@
     /**
      * Single label support, will mapped to multi label array
      *
-     * @name Base#label
+     * @name Element#label
      * @type Object
      */
     Object.defineProperty(this, 'label', {
@@ -11399,7 +12198,7 @@
     /**
      * The parent shape
      *
-     * @name Base#parent
+     * @name Element#parent
      * @type Shape
      */
     parentRefs.bind(this, 'parent');
@@ -11407,7 +12206,7 @@
     /**
      * The list of labels
      *
-     * @name Base#labels
+     * @name Element#labels
      * @type Label
      */
     labelRefs.bind(this, 'labels');
@@ -11415,7 +12214,7 @@
     /**
      * The list of outgoing connections
      *
-     * @name Base#outgoing
+     * @name Element#outgoing
      * @type Array<Connection>
      */
     outgoingRefs.bind(this, 'outgoing');
@@ -11423,7 +12222,7 @@
     /**
      * The list of incoming connections
      *
-     * @name Base#incoming
+     * @name Element#incoming
      * @type Array<Connection>
      */
     incomingRefs.bind(this, 'incoming');
@@ -11436,40 +12235,40 @@
    * @class
    * @constructor
    *
-   * @extends Base
+   * @extends ElementImpl
    */
-  function Shape() {
-    Base$1.call(this);
+  function ShapeImpl() {
+    ElementImpl.call(this);
 
     /**
      * Indicates frame shapes
      *
-     * @name Shape#isFrame
+     * @name ShapeImpl#isFrame
      * @type boolean
      */
 
     /**
      * The list of children
      *
-     * @name Shape#children
-     * @type Array<Base>
+     * @name ShapeImpl#children
+     * @type Element[]
      */
     parentRefs.bind(this, 'children');
 
     /**
-     * @name Shape#host
+     * @name ShapeImpl#host
      * @type Shape
      */
     attacherRefs.bind(this, 'host');
 
     /**
-     * @name Shape#attachers
+     * @name ShapeImpl#attachers
      * @type Shape
      */
     attacherRefs.bind(this, 'attachers');
   }
 
-  e(Shape, Base$1);
+  e(ShapeImpl, ElementImpl);
 
 
   /**
@@ -11478,13 +12277,21 @@
    * @class
    * @constructor
    *
-   * @extends Shape
+   * @extends ElementImpl
    */
-  function Root() {
-    Shape.call(this);
+  function RootImpl() {
+    ElementImpl.call(this);
+
+    /**
+     * The list of children
+     *
+     * @name RootImpl#children
+     * @type Element[]
+     */
+    parentRefs.bind(this, 'children');
   }
 
-  e(Root, Shape);
+  e(RootImpl, ShapeImpl);
 
 
   /**
@@ -11493,21 +12300,21 @@
    * @class
    * @constructor
    *
-   * @extends Shape
+   * @extends ShapeImpl
    */
-  function Label() {
-    Shape.call(this);
+  function LabelImpl() {
+    ShapeImpl.call(this);
 
     /**
      * The labeled element
      *
-     * @name Label#labelTarget
-     * @type Base
+     * @name LabelImpl#labelTarget
+     * @type Element
      */
     labelRefs.bind(this, 'labelTarget');
   }
 
-  e(Label, Shape);
+  e(LabelImpl, ShapeImpl);
 
 
   /**
@@ -11516,45 +12323,69 @@
    * @class
    * @constructor
    *
-   * @extends Base
+   * @extends ElementImpl
    */
-  function Connection() {
-    Base$1.call(this);
+  function ConnectionImpl() {
+    ElementImpl.call(this);
 
     /**
      * The element this connection originates from
      *
-     * @name Connection#source
-     * @type Base
+     * @name ConnectionImpl#source
+     * @type Element
      */
     outgoingRefs.bind(this, 'source');
 
     /**
      * The element this connection points to
      *
-     * @name Connection#target
-     * @type Base
+     * @name ConnectionImpl#target
+     * @type Element
      */
     incomingRefs.bind(this, 'target');
   }
 
-  e(Connection, Base$1);
+  e(ConnectionImpl, ElementImpl);
 
 
   var types$6 = {
-    connection: Connection,
-    shape: Shape,
-    label: Label,
-    root: Root
+    connection: ConnectionImpl,
+    shape: ShapeImpl,
+    label: LabelImpl,
+    root: RootImpl
   };
 
   /**
-   * Creates a model element of the given type.
+   * Creates a root element.
+   *
+   * @overlord
+   *
+   * @example
+   *
+   * ```javascript
+   * import * as Model from 'diagram-js/lib/model';
+   *
+   * const root = Model.create('root', {
+   *   x: 100,
+   *   y: 100,
+   *   width: 100,
+   *   height: 100
+   * });
+   * ```
+   *
+   * @param {'root'} type
+   * @param {any} [attrs]
+   *
+   * @return {Root}
+   */
+  /**
+   * Creates a connection.
    *
-   * @method create
+   * @overlord
    *
    * @example
    *
+   * ```javascript
    * import * as Model from 'diagram-js/lib/model';
    *
    * const connection = Model.create('connection', {
@@ -11563,33 +12394,56 @@
    *     { x: 200, y: 100 }
    *   ]
    * });
+   * ```
    *
-   * const label = Model.create('label', {
-   *   x: 100,
-   *   y: 100,
-   *   width: 100,
-   *   height: 100,
-   *   labelTarget: shape
-   * });
+   * @param {'connection'} type
+   * @param {any} [attrs]
    *
-   * const root = Model.create('root', {
+   * @return {Connection}
+   */
+  /**
+   * Creates a shape.
+   *
+   * @overlord
+   *
+   * @example
+   *
+   * ```javascript
+   * import * as Model from 'diagram-js/lib/model';
+   *
+   * const shape = Model.create('shape', {
    *   x: 100,
    *   y: 100,
    *   width: 100,
    *   height: 100
    * });
+   * ```
    *
-   * const shape = Model.create('shape', {
+   * @param {'shape'} type
+   * @param {any} [attrs]
+   *
+   * @return {Shape}
+   */
+  /**
+   * Creates a label.
+   *
+   * @example
+   *
+   * ```javascript
+   * import * as Model from 'diagram-js/lib/model';
+   *
+   * const label = Model.create('label', {
    *   x: 100,
    *   y: 100,
    *   width: 100,
-   *   height: 100
+   *   height: 100,
+   *   labelTarget: shape
    * });
+   * ```
    *
-   * @param {string} type The type of model element to be created.
-   * @param {Object} attrs Attributes to create the model element with.
-   *
-   * @return {Connection|Label|Root|Shape} The created model element.
+   * @param {'label'} type
+   * @param {Object} [attrs]
+   * @return {Label}
    */
   function create(type, attrs) {
     var Type = types$6[type];
@@ -11600,22 +12454,20 @@
   }
 
   /**
-   * @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
+   * @typedef {import('../model/Types').Element} Element
+   * @typedef {import('../model/Types').Connection} Connection
+   * @typedef {import('../model/Types').Label} Label
+   * @typedef {import('../model/Types').Root} Root
+   * @typedef {import('../model/Types').Shape} Shape
    */
 
   /**
    * A factory for model elements.
    *
-   * @class
-   * @constructor
+   * @template {Connection} [T=Connection]
+   * @template {Label} [U=Label]
+   * @template {Root} [V=Root]
+   * @template {Shape} [W=Shape]
    */
   function ElementFactory() {
     this._uid = 12;
@@ -11624,9 +12476,9 @@
   /**
    * Create a root element.
    *
-   * @param {ModelAttrsRoot} attrs The attributes of the root element to be created.
+   * @param {Partial<Root>} [attrs]
    *
-   * @return {Root} The created root element.
+   * @return {V} The created root element.
    */
   ElementFactory.prototype.createRoot = function(attrs) {
     return this.create('root', attrs);
@@ -11635,9 +12487,9 @@
   /**
    * Create a label.
    *
-   * @param {ModelAttrsLabel} attrs The attributes of the label to be created.
+   * @param {Partial<Label>} [attrs]
    *
-   * @return {Label} The created label.
+   * @return {U} The created label.
    */
   ElementFactory.prototype.createLabel = function(attrs) {
     return this.create('label', attrs);
@@ -11646,9 +12498,9 @@
   /**
    * Create a shape.
    *
-   * @param {ModelAttrsShape} attrs The attributes of the shape to be created.
+   * @param {Partial<Shape>} [attrs]
    *
-   * @return {Shape} The created shape.
+   * @return {W} The created shape.
    */
   ElementFactory.prototype.createShape = function(attrs) {
     return this.create('shape', attrs);
@@ -11657,21 +12509,44 @@
   /**
    * Create a connection.
    *
-   * @param {ModelAttrsConnection} attrs The attributes of the connection to be created.
+   * @param {Partial<Connection>} [attrs]
    *
-   * @return {Connection} The created connection.
+   * @return {T} The created connection.
    */
   ElementFactory.prototype.createConnection = function(attrs) {
     return this.create('connection', attrs);
   };
 
   /**
-   * Create a model element of the given type with the given attributes.
+   * Create a root element.
+   *
+   * @overlord
+   * @param {'root'} type
+   * @param {Partial<Root>} [attrs]
+   * @return {V}
+   */
+  /**
+   * Create a shape.
+   *
+   * @overlord
+   * @param {'shape'} type
+   * @param {Partial<Shape>} [attrs]
+   * @return {W}
+   */
+  /**
+   * Create a connection.
    *
-   * @param {string} type The type of the model element.
-   * @param {Object} attrs The attributes of the model element.
+   * @overlord
+   * @param {'connection'} type
+   * @param {Partial<Connection>} [attrs]
+   * @return {T}
+   */
+  /**
+   * Create a label.
    *
-   * @return {Connection|Label|Root|Shape} The created model element.
+   * @param {'label'} type
+   * @param {Partial<Label>} [attrs]
+   * @return {U}
    */
   ElementFactory.prototype.create = function(type, attrs) {
 
@@ -11691,13 +12566,27 @@
   var slice = Array.prototype.slice;
 
   /**
-   * @typedef {import('./EventBus').Event} Event
-   * @typedef {import('./EventBus').EventCallback} EventCallback
+   * @typedef { {
+   *   stopPropagation(): void;
+   *   preventDefault(): void;
+   *   cancelBubble: boolean;
+   *   defaultPrevented: boolean;
+   *   returnValue: any;
+   * } } Event
+   */
+
+  /**
+   * @template E
    *
-   * @typedef {Object} EventListener
-   * @property {Function} callback
-   * @property {EventListener|null} next
-   * @property {number} priority
+   * @typedef { (event: E & Event, ...any) => any } EventBusEventCallback
+   */
+
+  /**
+   * @typedef { {
+   *  priority: number;
+   *  next: EventBusListener | null;
+   *  callback: EventBusEventCallback<any>;
+   * } } EventBusListener
    */
 
   /**
@@ -11784,6 +12673,10 @@
    * ```
    */
   function EventBus() {
+
+    /**
+     * @type { Record<string, EventBusListener> }
+     */
     this._listeners = {};
 
     // cleanup on destroy on lowest priority to allow
@@ -11804,10 +12697,12 @@
    *
    * Returning anything but `undefined` from a listener will stop the listener propagation.
    *
-   * @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.
+   * @template T
+   *
+   * @param {string|string[]} events to subscribe to
+   * @param {number} [priority=1000] listen priority
+   * @param {EventBusEventCallback<T>} callback
+   * @param {any} [that] callback context
    */
   EventBus.prototype.on = function(events, priority, callback, that) {
 
@@ -11845,16 +12740,17 @@
     });
   };
 
-
   /**
    * Register an event listener that is called only once.
    *
-   * @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.
+   * @template T
+   *
+   * @param {string|string[]} events to subscribe to
+   * @param {number} [priority=1000] the listen priority
+   * @param {EventBusEventCallback<T>} callback
+   * @param {any} [that] callback context
    */
-  EventBus.prototype.once = function(event, priority, callback, that) {
+  EventBus.prototype.once = function(events, priority, callback, that) {
     var self = this;
 
     if (isFunction(priority)) {
@@ -11872,7 +12768,7 @@
 
       var result = callback.apply(that, arguments);
 
-      self.off(event, wrappedCallback);
+      self.off(events, wrappedCallback);
 
       return result;
     }
@@ -11882,7 +12778,7 @@
     // callback
     wrappedCallback[FN_REF] = callback;
 
-    this.on(event, priority, wrappedCallback);
+    this.on(events, priority, wrappedCallback);
   };
 
 
@@ -11891,8 +12787,8 @@
    *
    * If no callback is given, all listeners for a given event name are being removed.
    *
-   * @param {string|string[]} events The events.
-   * @param {EventCallback} [callback] The callback.
+   * @param {string|string[]} events
+   * @param {EventBusEventCallback} [callback]
    */
   EventBus.prototype.off = function(events, callback) {
 
@@ -11928,6 +12824,7 @@
    *
    * @example
    *
+   * ```javascript
    * // fire event by name
    * events.fire('foo');
    *
@@ -11945,12 +12842,13 @@
    * });
    *
    * events.fire({ type: 'foo' }, 'I am bar!');
+   * ```
    *
-   * @param {string} [type] The event type.
-   * @param {Object} [data] The event or event data.
-   * @param {...*} additional Additional arguments the callback will be called with.
+   * @param {string} [type] event type
+   * @param {Object} [data] event or event data
+   * @param {...any} [args] additional arguments the callback will be called with.
    *
-   * @return {*} The return value. Will be set to `false` if the default was prevented.
+   * @return {any} The return value. Will be set to `false` if the default was prevented.
    */
   EventBus.prototype.fire = function(type, data) {
     var event,
@@ -12031,6 +12929,13 @@
     this._listeners = {};
   };
 
+  /**
+   * @param {Event} event
+   * @param {any[]} args
+   * @param {EventBusListener} listener
+   *
+   * @return {any}
+   */
   EventBus.prototype._invokeListeners = function(event, args, listener) {
 
     var returnValue;
@@ -12050,6 +12955,13 @@
     return returnValue;
   };
 
+  /**
+   * @param {Event} event
+   * @param {any[]} args
+   * @param {EventBusListener} listener
+   *
+   * @return {any}
+   */
   EventBus.prototype._invokeListener = function(event, args, listener) {
 
     var returnValue;
@@ -12098,7 +13010,7 @@
    *    * after: [ 1500, 1500, (new=1300), 1000, 1000, (new=1000) ]
    *
    * @param {string} event
-   * @param {EventListener} listener
+   * @param {EventBusListener} newListener
    */
   EventBus.prototype._addListener = function(event, newListener) {
 
@@ -12138,10 +13050,19 @@
   };
 
 
+  /**
+   * @param {string} name
+   *
+   * @return {EventBusListener}
+   */
   EventBus.prototype._getListeners = function(name) {
     return this._listeners[name];
   };
 
+  /**
+   * @param {string} name
+   * @param {EventBusListener} listener
+   */
   EventBus.prototype._setListeners = function(name, listener) {
     this._listeners[name] = listener;
   };
@@ -12204,9 +13125,9 @@
    * Invoke function. Be fast...
    *
    * @param {Function} fn
-   * @param {*[]} args
+   * @param {any[]} args
    *
-   * @return {*}
+   * @return {any}
    */
   function invokeFunction(fn, args) {
     return fn.apply(null, args);
@@ -12241,13 +13162,9 @@
   }
 
   /**
-   * @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('./Types').ConnectionLike} ConnectionLike
+   * @typedef {import('./Types').ElementLike} ElementLike
+   * @typedef {import('./Types').ShapeLike} ShapeLike
    *
    * @typedef {import('./ElementRegistry').default} ElementRegistry
    * @typedef {import('./EventBus').default} EventBus
@@ -12266,7 +13183,10 @@
 
   GraphicsFactory.$inject = [ 'eventBus' , 'elementRegistry' ];
 
-
+  /**
+   * @param { { parent?: any } } element
+   * @return {SVGElement}
+   */
   GraphicsFactory.prototype._getChildrenContainer = function(element) {
 
     var gfx = this._elementRegistry.getGraphics(element);
@@ -12363,7 +13283,7 @@
   /**
    * Create a graphical element.
    *
-   * @param {ModelType} type The type of the element.
+   * @param { 'shape' | 'connection' | 'label' | 'root' } 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.
    *
@@ -12419,6 +13339,8 @@
    *
    * @param {SVGElement} visual The graphical element.
    * @param {ShapeLike} element The shape.
+   *
+   * @return {SVGElement}
    */
   GraphicsFactory.prototype.drawShape = function(visual, element) {
     var eventBus = this._eventBus;
@@ -12444,6 +13366,8 @@
    *
    * @param {SVGElement} visual The graphical element.
    * @param {ConnectionLike} element The connection.
+   *
+   * @return {SVGElement}
    */
   GraphicsFactory.prototype.drawConnection = function(visual, element) {
     var eventBus = this._eventBus;
@@ -12454,7 +13378,7 @@
   /**
    * Get the path of a connection.
    *
-   * @param {ConnectionLike} element The connection.
+   * @param {ConnectionLike} connection The connection.
    *
    * @return {string} The path of the connection.
    */
@@ -12467,9 +13391,9 @@
   /**
    * 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.
+   * @param {'shape'|'connection'} type
+   * @param {ElementLike} element
+   * @param {SVGElement} gfx
    */
   GraphicsFactory.prototype.update = function(type, element, gfx) {
 
@@ -12527,6 +13451,9 @@
     parentNode.insertBefore(newNode, node);
   }
 
+  /**
+   * @type { import('didi').ModuleDeclaration }
+   */
   var CoreModule = {
     __depends__: [ DrawModule ],
     __init__: [ 'canvas' ],
@@ -12542,7 +13469,9 @@
    * @typedef {import('didi').LocalsMap} LocalsMap
    * @typedef {import('didi').ModuleDeclaration} ModuleDeclaration
    *
-   * @typedef {import('./Diagram').DiagramOptions} DiagramOptions
+   * @typedef { {
+   *   modules?: ModuleDeclaration[];
+   * } & Record<string, any> } DiagramOptions
    */
 
   /**
@@ -12571,6 +13500,9 @@
 
     options = options || {};
 
+    /**
+     * @type { ModuleDeclaration }
+     */
     var configModule = {
       'config': [ 'value', options ]
     };
@@ -12590,11 +13522,10 @@
    * @class
    * @constructor
    *
-   * @example
-   *
-   * <caption>Creating a plug-in that logs whenever a shape is added to the canvas.</caption>
+   * @example Creating a plug-in that logs whenever a shape is added to the canvas.
    *
-   * // plug-in implemenentation
+   * ```javascript
+   * // plug-in implementation
    * function MyLoggingPlugin(eventBus) {
    *   eventBus.on('shape.added', function(event) {
    *     console.log('shape ', event.shape, ' was added to the diagram');
@@ -12606,10 +13537,11 @@
    *   __init__: [ 'myLoggingPlugin' ],
    *     myLoggingPlugin: [ 'type', MyLoggingPlugin ]
    * };
+   * ```
    *
+   * Use the plug-in in a Diagram instance:
    *
-   * // instantiate the diagram with the new plug-in
-   *
+   * ```javascript
    * import MyLoggingModule from 'path-to-my-logging-plugin';
    *
    * var diagram = new Diagram({
@@ -12624,36 +13556,39 @@
    * });
    *
    * // 'shape ... was added to the diagram' logged to console
+   * ```
    *
    * @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) {
 
-    // create injector unless explicitly specified
-    this.injector = injector = injector || createInjector(options);
+    this._injector = injector = injector || createInjector(options);
 
     // API
 
     /**
      * Resolves a diagram service.
      *
-     * @method Diagram#get
+     * @template T
      *
      * @param {string} name The name of the service to get.
      * @param {boolean} [strict=true] If false, resolve missing services to null.
+     *
+     * @return {T|null}
      */
     this.get = injector.get;
 
     /**
      * Executes a function with its dependencies injected.
      *
-     * @method Diagram#invoke
+     * @template T
+     *
+     * @param {Function} func function to be invoked
+     * @param {InjectionContext} [context] context of the invocation
+     * @param {LocalsMap} [locals] locals provided
      *
-     * @param {Function} fn The function to be executed.
-     * @param {InjectionContext} [context] The context.
-     * @param {LocalsMap} [locals] The locals.
+     * @return {T|null}
      */
     this.invoke = injector.invoke;
 
@@ -12673,9 +13608,11 @@
      *
      * @example
      *
+     * ```javascript
      * eventBus.on('diagram.init', function() {
      *   eventBus.fire('my-custom-event', { foo: 'BAR' });
      * });
+     * ```
      *
      * @type {Object}
      */
@@ -12685,8 +13622,6 @@
 
   /**
    * Destroys the diagram
-   *
-   * @method  Diagram#destroy
    */
   Diagram.prototype.destroy = function() {
     this.get('eventBus').fire('diagram.destroy');
@@ -20224,6 +21159,10 @@
     return new BpmnModdle(pks, options);
   }
 
+  /**
+   * @typedef {import('../model/Types').ModdleElement} ModdleElement
+   */
+
   // TODO(nikku): remove with future bpmn-js version
 
   /**
@@ -20233,6 +21172,10 @@
    * 2) If Promise class is implemented in current environment.
    *
    * @private
+   *
+   * @param {Function} api
+   *
+   * @return {Function}
    */
   function wrapForCompatibility(api) {
 
@@ -20281,6 +21224,11 @@
 
   var DI_ERROR_MESSAGE = 'Tried to access di from the businessObject. The di is available through the diagram element only. For more information, see https://github.com/bpmn-io/bpmn-js/issues/1472';
 
+  /**
+   * @private
+   *
+   * @param {ModdleElement} businessObject
+   */
   function ensureCompatDiRef(businessObject) {
 
     // bpmnElement can have multiple independent DIs
@@ -20295,10 +21243,16 @@
   }
 
   /**
-   * Returns true if an element has the given meta-model type
+   * @typedef {import('diagram-js/lib/i18n/translate/translate').default} Translate
+   *
+   * @typedef {import('../model/Types').ModdleElement} ModdleElement
+   */
+
+  /**
+   * Returns true if an element is of the given meta-model type.
    *
-   * @param  {ModdleElement}  element
-   * @param  {string}         type
+   * @param {ModdleElement} element
+   * @param {string} type
    *
    * @return {boolean}
    */
@@ -20310,6 +21264,10 @@
   /**
    * Find a suitable display candidate for definitions where the DI does not
    * correctly specify one.
+   *
+   * @param {ModdleElement} definitions
+   *
+   * @return {ModdleElement}
    */
   function findDisplayCandidate(definitions) {
     return find(definitions.rootElements, function(e) {
@@ -20317,7 +21275,10 @@
     });
   }
 
-
+  /**
+   * @param {Record<'element' | 'root' | 'error', Function>} handler
+   * @param {Translate} translate
+   */
   function BpmnTreeWalker(handler, translate) {
 
     // list of containers already walked
@@ -20386,7 +21347,7 @@
 
     // DI handling //////////////////////
 
-    function registerDi(di) {
+    var registerDi = this.registerDi = function registerDi(di) {
       var bpmnElement = di.bpmnElement;
 
       if (bpmnElement) {
@@ -20410,7 +21371,7 @@
           { element: di }
         );
       }
-    }
+    };
 
     function handleDiagram(diagram) {
       handlePlane(diagram.plane);
@@ -20430,14 +21391,14 @@
     // Semantic handling //////////////////////
 
     /**
-     * Handle definitions and return the rendered diagram (if any)
+     * Handle definitions and return the rendered diagram (if any).
      *
      * @param {ModdleElement} definitions to walk and import
      * @param {ModdleElement} [diagram] specific diagram to import and display
      *
      * @throws {Error} if no diagram to display could be found
      */
-    function handleDefinitions(definitions, diagram) {
+    this.handleDefinitions = function handleDefinitions(definitions, diagram) {
 
       // make sure we walk the correct bpmnElement
 
@@ -20514,10 +21475,10 @@
       }
 
       // handle all deferred elements
-      handleDeferred();
-    }
+      handleDeferred(deferred);
+    };
 
-    function handleDeferred() {
+    var handleDeferred = this.handleDeferred = function handleDeferred() {
 
       var fn;
 
@@ -20527,7 +21488,7 @@
 
         fn();
       }
-    }
+    };
 
     function handleProcess(process, context) {
       handleFlowElementsContainer(process, context);
@@ -20603,10 +21564,10 @@
       forEach$1(ioSpecification.dataOutputs, contextual(handleDataOutput, context));
     }
 
-    function handleSubProcess(subProcess, context) {
+    var handleSubProcess = this.handleSubProcess = function handleSubProcess(subProcess, context) {
       handleFlowElementsContainer(subProcess, context);
       handleArtifacts(subProcess.artifacts, context);
-    }
+    };
 
     function handleFlowNode(flowNode, context) {
       var childCtx = visitIfDi(flowNode, context);
@@ -20731,44 +21692,29 @@
         }
       });
     }
-
-    // API //////////////////////
-
-    return {
-      handleDeferred: handleDeferred,
-      handleDefinitions: handleDefinitions,
-      handleSubProcess: handleSubProcess,
-      registerDi: registerDi
-    };
   }
 
   /**
-   * The importBpmnDiagram result.
+   * @typedef {import('../model/Types').ModdleElement} ModdleElement
    *
-   * @typedef {Object} ImportBPMNDiagramResult
+   * @typedef { {
+   *   warnings: string[];
+   * } } ImportBPMNDiagramResult
    *
-   * @property {Array<string>} warnings
+   * @typedef {ImportBPMNDiagramResult & Error} ImportBPMNDiagramError
    */
 
-  /**
-  * The importBpmnDiagram error.
-  *
-  * @typedef {Error} ImportBPMNDiagramError
-  *
-  * @property {Array<string>} warnings
-  */
-
   /**
    * Import the definitions into a diagram.
    *
    * Errors and warnings are reported through the specified callback.
    *
-   * @param  {djs.Diagram} diagram
-   * @param  {ModdleElement<Definitions>} definitions
-   * @param  {ModdleElement<BPMNDiagram>} [bpmnDiagram] the diagram to be rendered
-   * (if not provided, the first one will be rendered)
+   * @param {ModdleElement} diagram
+   * @param {ModdleElement} definitions
+   * @param {ModdleElement} [bpmnDiagram] The diagram to be rendered (if not
+   * provided, the first one will be rendered).
    *
-   * Returns {Promise<ImportBPMNDiagramResult, ImportBPMNDiagramError>}
+   * @return {Promise<ImportBPMNDiagramResult>}
    */
   function importBpmnDiagram(diagram, definitions, bpmnDiagram) {
 
@@ -20784,8 +21730,8 @@
      * Walk the diagram semantically, importing (=drawing)
      * all elements you encounter.
      *
-     * @param {ModdleElement<Definitions>} definitions
-     * @param {ModdleElement<BPMNDiagram>} bpmnDiagram
+     * @param {ModdleElement} definitions
+     * @param {ModdleElement} bpmnDiagram
      */
     function render(definitions, bpmnDiagram) {
 
@@ -20860,10 +21806,10 @@
    * Returns all diagrams in the same hierarchy as the requested diagram.
    * Includes all parent and sub process diagrams.
    *
-   * @param {Array} definitions
-   * @param {Object} bpmnDiagram
+   * @param {ModdleElement} definitions
+   * @param {ModdleElement} bpmnDiagram
    *
-   * @returns {Array<Object>}
+   * @return {ModdleElement[]}
    */
   function getDiagramsToImport(definitions, bpmnDiagram) {
     if (!bpmnDiagram) {
@@ -21015,7 +21961,7 @@
           BPMNIO_IMG +
         '</a>' +
         '<span>' +
-          'Web-based tooling for BPMN, DMN and CMMN diagrams ' +
+          'Web-based tooling for BPMN, DMN and forms ' +
           'powered by <a href="https://bpmn.io" target="_blank" rel="noopener">bpmn.io</a>.' +
         '</span>' +
       '</div>' +
@@ -21057,22 +22003,89 @@
    * @see http://bpmn.io/license for more information.
    */
 
+  /**
+   * @template T
+   *
+   * @typedef {import('diagram-js/lib/core/EventBus').EventBusEventCallback<T>} EventBusEventCallback
+   */
 
   /**
    * @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
+   * @typedef {import('./model/Types').Moddle} Moddle
+   * @typedef {import('./model/Types').ModdleElement} ModdleElement
+   * @typedef {import('./model/Types').ModdleExtension} ModdleExtension
+   *
+   * @typedef { {
+   *   width?: number|string;
+   *   height?: number|string;
+   *   position?: string;
+   *   container?: string|HTMLElement;
+   *   moddleExtensions?: ModdleExtensions;
+   *   additionalModules?: ModuleDeclaration[];
+   * } & Record<string, any> } BaseViewerOptions
+   *
+   * @typedef {Record<string, ModdleElement>} ModdleElementsById
+   *
+   * @typedef { {
+   *   [key: string]: ModdleExtension;
+   * } } ModdleExtensions
+   *
+   * @typedef { {
+   *   warnings: string[];
+   * } } ImportXMLResult
+   *
+   * @typedef {ImportXMLResult & Error} ImportXMLError
+   *
+   * @typedef {ImportXMLResult} ImportDefinitionsResult
+   *
+   * @typedef {ImportXMLError} ImportDefinitionsError
+   *
+   * @typedef {ImportXMLResult} OpenResult
+   *
+   * @typedef {ImportXMLError} OpenError
+   *
+   * @typedef { {
+   *   format?: boolean;
+   *   preamble?: boolean;
+   * } } SaveXMLOptions
+   *
+   * @typedef { {
+   *   xml?: string;
+   *   error?: Error;
+   * } } SaveXMLResult
+   *
+   * @typedef { {
+   *   svg: string;
+   * } } SaveSVGResult
+   *
+   * @typedef { {
+   *   xml: string;
+   * } } ImportParseStartEvent
+   *
+   * @typedef { {
+   *   error?: ImportXMLError;
+   *   definitions?: ModdleElement;
+   *   elementsById?: ModdleElementsById;
+   *   references?: ModdleElement[];
+   *   warnings: string[];
+   * } } ImportParseCompleteEvent
+   *
+   * @typedef { {
+   *   error?: ImportXMLError;
+   *   warnings: string[];
+   * } } ImportDoneEvent
+   *
+   * @typedef { {
+   *   definitions: ModdleElement;
+   * } } SaveXMLStartEvent
+   *
+   * @typedef {SaveXMLResult} SaveXMLDoneEvent
+   *
+   * @typedef { {
+   *   error?: Error;
+   *   svg: string;
+   * } } SaveSVGDoneEvent
    */
 
   /**
@@ -21081,15 +22094,18 @@
    * Have a look at {@link Viewer}, {@link NavigatedViewer} or {@link Modeler} for
    * bundles that include actual features.
    *
-   * @param {BaseModelerOptions} [options] The options to configure the viewer.
+   * @param {BaseViewerOptions} [options] The options to configure the viewer.
    */
   function BaseViewer(options) {
 
     /**
-     * @type {BaseModelerOptions}
+     * @type {BaseViewerOptions}
      */
     options = assign$1({}, DEFAULT_OPTIONS, options);
 
+    /**
+     * @type {Moddle}
+     */
     this._moddle = this._createModdle(options);
 
     /**
@@ -21128,18 +22144,18 @@
    *
    * @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
+   * @fires BaseViewer#ImportParseStartEvent
+   * @fires BaseViewer#ImportParseCompleteEvent
+   * @fires Importer#ImportRenderStartEvent
+   * @fires Importer#ImportRenderCompleteEvent
+   * @fires BaseViewer#ImportDoneEvent
    *
    * @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) {
+  BaseViewer.prototype.importXML = async function importXML(xml, bpmnDiagram) {
 
     const self = this;
 
@@ -21177,9 +22193,8 @@
       /**
        * A `import.parse.start` event.
        *
-       * @event BaseViewer#ImportParseStart
-       * @type {Object}
-       * @property {string} xml The XML that is to be parsed.
+       * @event BaseViewer#ImportParseStartEvent
+       * @type {ImportParseStartEvent}
        */
       xml = this._emit('import.parse.start', { xml: xml }) || xml;
 
@@ -21207,13 +22222,8 @@
       /**
        * 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.
+       * @event BaseViewer#ImportParseCompleteEvent
+       * @type {ImportParseCompleteEvent}
        */
       definitions = this._emit('import.parse.complete', ParseCompleteEvent({
         error: null,
@@ -21230,10 +22240,8 @@
       /**
        * A `import.parse.complete` event.
        *
-       * @event BaseViewer#ImportDone
-       * @type {Object}
-       * @property {ImportXMLError|null} error An error thrown during import.
-       * @property {string[]} warnings The warnings.
+       * @event BaseViewer#ImportDoneEvent
+       * @type {ImportDoneEvent}
        */
       this._emit('import.done', { error: null, warnings: aggregatedWarnings });
 
@@ -21249,7 +22257,9 @@
 
       throw error;
     }
-  });
+  };
+
+  BaseViewer.prototype.importXML = wrapForCompatibility(BaseViewer.prototype.importXML);
 
 
   /**
@@ -21274,12 +22284,14 @@
    *
    * @return {Promise<ImportDefinitionsResult>} A promise resolving with warnings that were produced during the import.
    */
-  BaseViewer.prototype.importDefinitions = wrapForCompatibility(async function importDefinitions(definitions, bpmnDiagram) {
+  BaseViewer.prototype.importDefinitions = async function importDefinitions(definitions, bpmnDiagram) {
     this._setDefinitions(definitions);
     const result = await this.open(bpmnDiagram);
 
     return { warnings: result.warnings };
-  });
+  };
+
+  BaseViewer.prototype.importDefinitions = wrapForCompatibility(BaseViewer.prototype.importDefinitions);
 
 
   /**
@@ -21303,7 +22315,7 @@
    *
    * @return {Promise<OpenResult>} A promise resolving with warnings that were produced during opening.
    */
-  BaseViewer.prototype.open = wrapForCompatibility(async function open(bpmnDiagramOrId) {
+  BaseViewer.prototype.open = async function open(bpmnDiagramOrId) {
 
     const definitions = this._definitions;
     let bpmnDiagram = bpmnDiagramOrId;
@@ -21340,7 +22352,9 @@
     const { warnings } = await importBpmnDiagram(this, definitions, bpmnDiagram);
 
     return { warnings };
-  });
+  };
+
+  BaseViewer.prototype.open = wrapForCompatibility(BaseViewer.prototype.open);
 
   /**
    * Export the currently displayed BPMN 2.0 diagram as
@@ -21365,7 +22379,7 @@
    *
    * @return {Promise<SaveXMLResult>} A promise resolving with the XML.
    */
-  BaseViewer.prototype.saveXML = wrapForCompatibility(async function saveXML(options) {
+  BaseViewer.prototype.saveXML = async function saveXML(options) {
 
     options = options || {};
 
@@ -21382,9 +22396,8 @@
       /**
        * A `saveXML.start` event.
        *
-       * @event BaseViewer#SaveXMLStart
-       * @type {Object}
-       * @property {ModdleElement} definitions The definitions model element.
+       * @event BaseViewer#SaveXMLStartEvent
+       * @type {SaveXMLStartEvent}
        */
       definitions = this._emit('saveXML.start', {
         definitions
@@ -21405,10 +22418,8 @@
     /**
      * 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.
+     * @event BaseViewer#SaveXMLDoneEvent
+     * @type {SaveXMLDoneEvent}
      */
     this._emit('saveXML.done', result);
 
@@ -21417,7 +22428,9 @@
     }
 
     return result;
-  });
+  };
+
+  BaseViewer.prototype.saveXML = wrapForCompatibility(BaseViewer.prototype.saveXML);
 
 
   /**
@@ -21439,7 +22452,7 @@
    *
    * @return {Promise<SaveSVGResult>} A promise resolving with the SVG.
    */
-  BaseViewer.prototype.saveSVG = wrapForCompatibility(async function saveSVG() {
+  BaseViewer.prototype.saveSVG = async function saveSVG() {
     this._emit('saveSVG.start');
 
     let svg, err;
@@ -21471,10 +22484,8 @@
     /**
      * 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.
+     * @event BaseViewer#SaveSVGDoneEvent
+     * @type {SaveSVGDoneEvent}
      */
     this._emit('saveSVG.done', {
       error: err,
@@ -21486,7 +22497,9 @@
     }
 
     return { svg };
-  });
+  };
+
+  BaseViewer.prototype.saveSVG = wrapForCompatibility(BaseViewer.prototype.saveSVG);
 
   /**
    * Get a named diagram service.
@@ -21568,10 +22581,12 @@
    *
    * Remove an event listener via {@link BaseViewer#off}.
    *
+   * @template T
+   *
    * @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.
+   * @param {EventBusEventCallback<T>} callback The callback.
+   * @param {any} [that] Value of `this` the callback will be called with.
    */
   BaseViewer.prototype.on = function(events, priority, callback, that) {
     return this.get('eventBus').on(events, priority, callback, that);
@@ -21621,7 +22636,7 @@
   /**
    * Get the definitions model element.
    *
-   * @returns {ModdleElement} The definitions model element.
+   * @return {ModdleElement} The definitions model element.
    */
   BaseViewer.prototype.getDefinitions = function() {
     return this._definitions;
@@ -21690,6 +22705,11 @@
     return this.get('eventBus').fire(type, event);
   };
 
+  /**
+   * @param {BaseViewerOptions} options
+   *
+   * @return {HTMLElement}
+   */
   BaseViewer.prototype._createContainer = function(options) {
 
     const container = domify$1('<div class="bjs-container"></div>');
@@ -21703,6 +22723,11 @@
     return container;
   };
 
+  /**
+   * @param {BaseViewerOptions} options
+   *
+   * @return {Moddle}
+   */
   BaseViewer.prototype._createModdle = function(options) {
     const moddleOptions = assign$1({}, this._moddleExtensions, options.moddleExtensions);