bpmn-js 18.25.0 → 18.26.0

package/dist/bpmn-viewer.development.js

@@ -1,5 +1,5 @@
 /*!
- * bpmn-js - bpmn-viewer v18.25.0
+ * bpmn-js - bpmn-viewer v18.26.0
  *
  * Copyright (c) 2014-present, camunda Services GmbH
  *
@@ -8,7 +8,7 @@
  *
  * Source Code: https://github.com/bpmn-io/bpmn-js
  *
- * Date: 2026-08-19
+ * Date: 2026-08-28
  */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
@@ -8048,14 +8048,7 @@
           return [];
         }
 
-        var title = escapeHTML(parent.name || parent.id);
-        var link = domify('<li><span class="bjs-crumb"><a title="' + title + '">' + title + '</a></span></li>');
-
-        link.addEventListener('click', function() {
-          canvas.setRootElement(parentPlane);
-        });
-
-        return link;
+        return [ { parent: parent, parentPlane: parentPlane } ];
       });
 
       breadcrumbs.innerHTML = '';
@@ -8065,8 +8058,39 @@
 
       containerClasses.toggle(OPEN_CLASS, visible);
 
-      path.forEach(function(element) {
-        breadcrumbs.appendChild(element);
+      path.forEach(function(entry, index) {
+        var parent = entry.parent,
+            parentPlane = entry.parentPlane,
+            title = escapeHTML(parent.name || parent.id);
+
+        // the last crumb represents the current plane; render it as
+        // plain, non-interactive text
+        var isCurrent = index === path.length - 1;
+
+        var crumb;
+
+        if (isCurrent) {
+          crumb = domify(
+            '<li><span class="bjs-crumb" title="' + title + '">' + title + '</span></li>'
+          );
+        } else {
+
+          // render navigable crumbs as local links so they are focusable
+          // and keyboard-operable
+          var href = '#' + escapeHTML(parent.id);
+
+          crumb = domify(
+            '<li><a class="bjs-crumb" href="' + href + '" title="' + title + '">' + title + '</a></li>'
+          );
+
+          crumb.addEventListener('click', function(event) {
+            event.preventDefault();
+
+            canvas.setRootElement(parentPlane);
+          });
+        }
+
+        breadcrumbs.appendChild(crumb);
       });
     }
 
@@ -14120,14 +14144,109 @@
    */
   function Base() { }
 
+  /**
+   * @template { keyof this } K
+   *
+   * Get property value (typed)
+   *
+   * @overload
+   *
+   * @param {K} name
+   *
+   * @return { this[K] }
+   */
+  /**
+   * @template T
+   *
+   * Get property value
+   *
+   * @overload
+   *
+   * @param {string} name
+   *
+   * @return {T}
+   */
+  /**
+   * Get property value
+   *
+   * @overload
+   *
+   * @param {string} name
+   *
+   * @return {unknown}
+   */
   Base.prototype.get = function(name) {
     return this.$model.properties.get(this, name);
   };
 
+  /**
+   * @template { keyof this } K
+   * @template { this[K] } V
+   *
+   * Set property value
+   *
+   * @overload
+   *
+   * @param {K} name
+   * @param {V} value
+   */
+  /**
+   * @template { string } S
+   *
+   * Set property value
+   *
+   * @overload
+   *
+   * @param { S extends keyof this ? never : S } name
+   * @param { any } value
+   */
   Base.prototype.set = function(name, value) {
     this.$model.properties.set(this, name, value);
   };
 
+  /**
+   * @typedef {import('./ns.js').Namespace} Namespace
+   * @typedef {import('./moddle.js').default} Moddle
+   * @typedef {import('./properties.js').default} Properties
+   * @typedef {import('./registry.js').EffectiveDescriptor} EffectiveDescriptor
+   * @typedef {import('./base.js').default} BaseElement
+   * @typedef {import('./descriptor-builder.js').AnyTypeDescriptor} AnyTypeDescriptor
+   */
+
+  /**
+   * @template [T=Record<string,any>]
+   * @typedef {{
+   *   new(attrs?: Partial<T>): ModdleElement<T>;
+   *   prototype: ModdleElement<T>;
+   *   readonly $model: Moddle;
+   *   readonly $descriptor: EffectiveDescriptor;
+   * }} ModdleElementType
+   */
+
+  /**
+   * @template [T=Record<string,any>]
+   * @typedef {BaseElement & T & {
+   *   readonly $model: Moddle;
+   *   readonly $descriptor: EffectiveDescriptor;
+   *   readonly $type: Namespace['name'];
+   *   readonly $attrs: Record<string, any>;
+   *   $parent?: ModdleElement | AnyModdleElement;
+   *   hasType: Moddle['hasType'];
+   *   $instanceOf: Moddle['hasType'];
+   * }} ModdleElement
+   */
+
+  /**
+   * @template [T=Record<string,any>]
+   * @typedef {BaseElement & T & {
+   *   $type: string;
+   *   $instanceOf: (type: string) => boolean;
+   *   $parent?: ModdleElement | AnyModdleElement;
+   *   readonly $model: Moddle;
+   *   readonly $descriptor: AnyTypeDescriptor;
+   * }} AnyModdleElement
+   */
+
   /**
    * A model element factory.
    *
@@ -14135,11 +14254,23 @@
    * @param {Properties} properties
    */
   function Factory(model, properties) {
+
+    /**
+     * @private
+     */
     this.model = model;
+
+    /**
+     * @private
+     */
     this.properties = properties;
   }
 
-
+  /**
+   * @template [T=Record<string,any>]
+   * @param {EffectiveDescriptor} descriptor
+   * @return {ModdleElementType<T>}
+   */
   Factory.prototype.createType = function(descriptor) {
 
     var model = this.model;
@@ -14161,6 +14292,8 @@
 
     /**
      * The new type constructor
+     *
+     * @type { ModdleElementType }
      */
     function ModdleElement(attrs) {
       props.define(this, '$type', { value: name, enumerable: true });
@@ -14186,26 +14319,62 @@
   /**
    * Built-in moddle types
    */
-  var BUILTINS = {
+  var BUILTINS = assign$1(Object.create(null), {
     String: true,
     Boolean: true,
     Integer: true,
     Real: true,
     Element: true
-  };
+  });
 
   /**
-   * Converters for built in types from string representations
+   * Converters for built-in types from string representations
    */
-  var TYPE_CONVERTERS = {
+  var TYPE_CONVERTERS = assign$1(Object.create(null), {
     String: function(s) { return s; },
     Boolean: function(s) { return s === 'true'; },
     Integer: function(s) { return parseInt(s, 10); },
     Real: function(s) { return parseFloat(s); }
-  };
+  });
+
+  /**
+   * @typedef {'String'} StringType
+   * @typedef {'Boolean'} BooleanType
+   * @typedef {'Integer'} IntegerType
+   * @typedef {'Real'} RealType
+   * @typedef {'Element'} ElementType
+   * @typedef {StringType | BooleanType | IntegerType | RealType} BuiltInSimpleType
+   * @typedef {BuiltInSimpleType | ElementType} BuiltInType
+   */
 
+  /**
+   * Convert given value to string
+   * @overlord
+   * @param {StringType} type
+   * @param {any} value
+   * @return {string}
+   */
+  /**
+   * Convert given value to boolean
+   * @overlord
+   * @param {BooleanType} type
+   * @param {any} value
+   * @return {boolean}
+   */
+  /**
+   * Convert given value to number
+   * @overlord
+   * @param {IntegerType | RealType} type
+   * @param {any} value
+   * @return {number}
+   */
   /**
    * Convert a type to its real representation
+   * @template T
+   * @overlord
+   * @param {Exclude<string,BuiltInSimpleType>} type
+   * @param {T} value
+   * @return {T}
    */
   function coerceType(type, value) {
 
@@ -14220,18 +14389,44 @@
 
   /**
    * Return whether the given type is built-in
+   * @overload
+   * @param {BuiltInType} type
+   * @return {true}
+   */
+  /**
+   * Return whether the given type is built-in
+   * @overload
+   * @param {Exclude<string,BuiltInType>} type
+   * @return {false}
    */
   function isBuiltIn(type) {
     return !!BUILTINS[type];
   }
 
   /**
-   * Return whether the given type is simple
+   * Return true if the given type is simple
+   * @overload
+   * @param {BuiltInSimpleType} type
+   * @return {true}
+   */
+  /**
+   * Return false the given type is not simple
+   * @overload
+   * @param {Exclude<string,BuiltInSimpleType>} type
+   * @return {false}
    */
   function isSimple(type) {
     return !!TYPE_CONVERTERS[type];
   }
 
+  /**
+   * @typedef {{
+   *   name: string;
+   *   prefix: string;
+   *   localName: string;
+   * }} Namespace
+   */
+
   /**
    * Parses a namespaced attribute name of the form (ns:)localName to an object,
    * given a default prefix to assume in case no explicit namespace is given.
@@ -14239,7 +14434,7 @@
    * @param {String} name
    * @param {String} [defaultPrefix] the default prefix to take, if none is present.
    *
-   * @return {Object} the parsed name
+   * @return {Namespace} the parsed name
    */
   function parseName(name, defaultPrefix) {
     var parts = name.split(/:/),
@@ -14270,19 +14465,98 @@
     };
   }
 
+  /**
+   * @typedef {import('./ns.js').Namespace} Namespace
+   * @typedef {import('./registry.js').RegisteredPackage} RegisteredPackage
+   * @typedef {import('./registry.js').RegisteredTypeDef} RegisteredTypeDef
+   * @typedef {import('./registry.js').RegisteredPropertyDef} RegisteredPropertyDef
+   */
+
+  /**
+   * Effective element descriptor
+   * aka element type descriptor
+   * aka element descriptor
+   * @typedef {{
+   *   readonly ns: Namespace;
+   *   readonly name: Namespace['name'];
+   *   readonly allTypes: Array<RegisteredTypeDef>;
+   *   readonly allTypesByName: Record<string, RegisteredTypeDef>;
+   *   readonly properties: Array<PropertyDescriptor>;
+   *   readonly propertiesByName: Record<string, PropertyDescriptor>;
+   *   readonly bodyProperty?: PropertyDescriptor;
+   *   readonly idProperty?: PropertyDescriptor;
+   *   readonly $pkg?: RegisteredPackage;
+   * }} EffectiveDescriptor
+   */
+
+  /**
+   * Property descriptor
+   * @typedef {RegisteredPropertyDef & {
+   *   localName: Namespace['localName'];
+   *   inherited?: boolean;
+   *   definedBy?: RegisteredTypeDef;
+   * }} PropertyDescriptor
+   */
+
+  /**
+   * @typedef {{
+   *   name: string;
+   *   isGeneric: true;
+   *   ns: {
+   *     prefix: string;
+   *     localName: string;
+   *     uri: string;
+   *   };
+   * }} AnyTypeDescriptor
+   */
+
   /**
    * A utility to build element descriptors.
+   * @class DescriptorBuilder
+   * @param {Namespace} nameNs
    */
   function DescriptorBuilder(nameNs) {
+
+    /**
+     * @private
+     * @type {Namespace}
+     */
     this.ns = nameNs;
+
+    /**
+     * @private
+     * @type {Namespace['name']}
+     */
     this.name = nameNs.name;
+
+    /**
+     * @private
+     * @type {Array<RegisteredTypeDef>}
+     */
     this.allTypes = [];
-    this.allTypesByName = {};
+
+    /**
+     * @private
+     * @type {Record<string, RegisteredTypeDef>}
+     */
+    this.allTypesByName = Object.create(null);
+
+    /**
+     * @private
+     * @type {Array<PropertyDescriptor>}
+     */
     this.properties = [];
-    this.propertiesByName = {};
-  }
 
+    /**
+     * @private
+     * @type {Record<string, PropertyDescriptor>}
+     */
+    this.propertiesByName = Object.create(null);
+  }
 
+  /**
+   * @return {EffectiveDescriptor}
+   */
   DescriptorBuilder.prototype.build = function() {
     return pick(this, [
       'ns',
@@ -14299,7 +14573,7 @@
   /**
    * Add property at given index.
    *
-   * @param {Object} p
+   * @param {PropertyDescriptor} p
    * @param {Number} [idx]
    * @param {Boolean} [validate=true]
    */
@@ -14321,7 +14595,11 @@
     }
   };
 
-
+  /**
+   * @param {PropertyDescriptor} oldProperty
+   * @param {PropertyDescriptor} newProperty
+   * @param {string} replace
+   */
   DescriptorBuilder.prototype.replaceProperty = function(oldProperty, newProperty, replace) {
     var oldNameNs = oldProperty.ns;
 
@@ -14371,7 +14649,11 @@
     propertiesByName[oldNameNs.name] = propertiesByName[oldNameNs.localName] = newProperty;
   };
 
-
+  /**
+   * @param {PropertyDescriptor} p
+   * @param {string} targetPropertyName
+   * @param {string} replace
+   */
   DescriptorBuilder.prototype.redefineProperty = function(p, targetPropertyName, replace) {
 
     var nsPrefix = p.ns.prefix;
@@ -14390,6 +14672,10 @@
     delete p.redefines;
   };
 
+  /**
+   * @param {PropertyDescriptor} p
+   * @param {boolean} validate
+   */
   DescriptorBuilder.prototype.addNamedProperty = function(p, validate) {
     var ns = p.ns,
         propsByName = this.propertiesByName;
@@ -14402,6 +14688,9 @@
     propsByName[ns.name] = propsByName[ns.localName] = p;
   };
 
+  /**
+   * @param {RegisteredPropertyDef} p
+   */
   DescriptorBuilder.prototype.removeNamedProperty = function(p) {
     var ns = p.ns,
         propsByName = this.propertiesByName;
@@ -14410,6 +14699,10 @@
     delete propsByName[ns.localName];
   };
 
+  /**
+   * @param {PropertyDescriptor} p
+   * @param {boolean} [validate]
+   */
   DescriptorBuilder.prototype.setBodyProperty = function(p, validate) {
 
     if (validate && this.bodyProperty) {
@@ -14421,6 +14714,10 @@
     this.bodyProperty = p;
   };
 
+  /**
+   * @param {PropertyDescriptor} p
+   * @param {boolean} [validate]
+   */
   DescriptorBuilder.prototype.setIdProperty = function(p, validate) {
 
     if (validate && this.idProperty) {
@@ -14432,6 +14729,9 @@
     this.idProperty = p;
   };
 
+  /**
+   * @param {RegisteredTypeDef} typeDescriptor
+   */
   DescriptorBuilder.prototype.assertNotTrait = function(typeDescriptor) {
 
     const _extends = typeDescriptor.extends || [];
@@ -14443,6 +14743,9 @@
     }
   };
 
+  /**
+   * @param {PropertyDescriptor} p
+   */
   DescriptorBuilder.prototype.assertNotDefined = function(p, name) {
     var propertyName = p.name,
         definedProperty = this.propertiesByName[propertyName];
@@ -14455,10 +14758,18 @@
     }
   };
 
+  /**
+   * @param {string} name
+   * @return {PropertyDescriptor}
+   */
   DescriptorBuilder.prototype.hasProperty = function(name) {
     return this.propertiesByName[name];
   };
 
+  /**
+   * @param {RegisteredTypeDef} t
+   * @param {boolean} inherited
+   */
   DescriptorBuilder.prototype.addTrait = function(t, inherited) {
 
     if (inherited) {
@@ -14507,33 +14818,94 @@
     typesByName[typeName] = t;
   };
 
+  /**
+   * @typedef {import('./ns.js').Namespace} Namespace
+   * @typedef {import('./moddle.js').PackageDefinition} PackageDefinition
+   * @typedef {import('./moddle.js').TypeDefinition} TypeDefinition
+   * @typedef {import('./moddle.js').PropertyDefinition} PropertyDefinition
+   * @typedef {import('./properties.js').default} Properties
+   * @typedef {import('./descriptor-builder.js').EffectiveDescriptor} EffectiveDescriptor
+   */
+
+  /**
+   * Registered package definition
+   * @typedef {Omit<PackageDefinition, 'types'> & {
+   *   types?: Array<RegisteredTypeDef>;
+   * }} RegisteredPackage
+   */
+
+  /**
+   * Registered type definition
+   * @typedef {Omit<TypeDefinition, 'properties'> & {
+   *   properties?: Array<RegisteredPropertyDef>;
+   *   propertiesByName?: Record<string, RegisteredPropertyDef>;
+   *   superClass?: Array<string>;
+   *   extends?: Array<string>;
+   *   meta?: Record<string, *>;
+   *   traits?: Array<string>;
+   *   ns?: Namespace;
+   *   readonly $pkg?: RegisteredPackage;
+   * }} RegisteredTypeDef
+   */
+
+  /**
+   * Registered property definition
+   * @typedef {PropertyDefinition & { ns: Namespace }} RegisteredPropertyDef
+   */
+
   /**
    * A registry of Moddle packages.
    *
-   * @param {Array<Package>} packages
+   * @param {Array<PackageDefinition> | Record<string,PackageDefinition>} packages
    * @param {Properties} properties
    */
   function Registry(packages, properties) {
-    this.packageMap = {};
-    this.typeMap = {};
 
+    /**
+     * @private
+     * @type {Record<string, RegisteredPackage>} registered packages map
+     */
+    this.packageMap = Object.create(null);
+
+    /**
+     * @type {Record<string,RegisteredTypeDef>}
+     */
+    this.typeMap = Object.create(null);
+
+    /**
+     * @private
+     * @type {Array<RegisteredPackage>} all registered packages
+     */
     this.packages = [];
 
+    /**
+     * @private
+     * @type {Properties}
+     */
     this.properties = properties;
 
     forEach(packages, bind$1(this.registerPackage, this));
   }
 
-
+  /**
+   * @param {string} uriOrPrefix uri or prefix of package
+   * @return {RegisteredPackage} registered package
+   */
   Registry.prototype.getPackage = function(uriOrPrefix) {
     return this.packageMap[uriOrPrefix];
   };
 
+  /**
+   * @return {Array<RegisteredPackage>} all registered packages
+   */
   Registry.prototype.getPackages = function() {
     return this.packages;
   };
 
-
+  /**
+   * @private
+   * @param {PackageDefinition} pkg registering package
+   */
   Registry.prototype.registerPackage = function(pkg) {
 
     // copy package
@@ -14553,22 +14925,23 @@
     this.packages.push(pkg);
   };
 
-
   /**
+   * @private
    * Register a type from a specific package with us
+   * @param {TypeDefinition} type
+   * @param {RegisteredPackage} pkg
    */
   Registry.prototype.registerType = function(type, pkg) {
-
     type = assign$1({}, type, {
       superClass: (type.superClass || []).slice(),
       extends: (type.extends || []).slice(),
       properties: (type.properties || []).slice(),
-      meta: assign$1((type.meta || {}))
+      meta: assign$1({}, type.meta || {})
     });
 
     var ns = parseName(type.name, pkg.prefix),
         name = ns.name,
-        propertiesByName = {};
+        /** @type {Record<string, RegisteredPropertyDef>} */ propertiesByName = Object.create(null);
 
     // parse properties
     forEach(type.properties, bind$1(function(p) {
@@ -14613,18 +14986,24 @@
     this.typeMap[name] = type;
   };
 
+  /**
+   * @callback IteratorFn
+   * @param {RegisteredTypeDef} type
+   * @param {boolean} inherited
+   */
 
   /**
    * Traverse the type hierarchy from bottom to top,
    * calling iterator with (type, inherited) for all elements in
    * the inheritance chain.
-   *
-   * @param {Object} nsName
-   * @param {Function} iterator
+   * @private
+   * @param {Namespace} nsName
+   * @param {IteratorFn} iterator
    * @param {Boolean} [trait=false]
    */
   Registry.prototype.mapTypes = function(nsName, iterator, trait) {
 
+    /** @type {RegisteredTypeDef} */
     var type = isBuiltIn(nsName.name) ? { name: nsName.name } : this.typeMap[nsName.name];
 
     var self = this;
@@ -14670,13 +15049,10 @@
     forEach(type.traits, traverseTrait);
   };
 
-
   /**
    * Returns the effective descriptor for a type.
-   *
-   * @param  {String} type the namespaced name (ns:localName) of the type
-   *
-   * @return {Descriptor} the resulting effective descriptor
+   * @param  {Namespace['name']} name the namespaced name (ns:localName) of the type
+   * @return {EffectiveDescriptor} the resulting effective descriptor
    */
   Registry.prototype.getEffectiveDescriptor = function(name) {
 
@@ -14696,15 +15072,23 @@
     return descriptor;
   };
 
-
+  /**
+   * @private
+   * @param {RegisteredTypeDef | EffectiveDescriptor} target
+   * @param {RegisteredPackage} pkg
+   */
   Registry.prototype.definePackage = function(target, pkg) {
     this.properties.define(target, '$pkg', { value: pkg });
   };
 
-
-
   // helpers ////////////////////////////
 
+  /**
+   * Checking already defined packages
+   * @param {Record<string, RegisteredPackage>} packageMap
+   * @param {PackageDefinition} pkg
+   * @param {'prefix' | 'uri'} identifierKey
+   */
   function ensureAvailable(packageMap, pkg, identifierKey) {
 
     var value = pkg[identifierKey];
@@ -14714,21 +15098,30 @@
     }
   }
 
+  /**
+   * @typedef {import('./moddle.js').default} Moddle
+   * @typedef {import('./descriptor-builder.js').PropertyDescriptor} PropertyDesc
+   * @typedef {import('./registry.js').EffectiveDescriptor} EffectiveDescriptor
+   * @typedef {import('./factory.js').ModdleElement} ModdleElement
+   * @typedef {import('./descriptor-builder.js').AnyTypeDescriptor} AnyTypeDescriptor
+   */
+
   /**
    * A utility that gets and sets properties of model elements.
    *
-   * @param {Model} model
+   * @param {Moddle} model
    */
   function Properties(model) {
+
+    /** @type {Moddle} */
     this.model = model;
   }
 
-
   /**
    * Sets a named property on the target element.
    * If the value is undefined, the property gets deleted.
    *
-   * @param {Object} target
+   * @param {ModdleElement} target
    * @param {String} name
    * @param {Object} value
    */
@@ -14770,7 +15163,7 @@
   /**
    * Returns the named property of the given element
    *
-   * @param  {Object} target
+   * @param  {ModdleElement} target
    * @param  {String} name
    *
    * @return {Object}
@@ -14793,13 +15186,12 @@
     return target[propertyName];
   };
 
-
   /**
    * Define a property on the target element
-   *
-   * @param  {Object} target
+   * @template [T=any]
+   * @param  {NonNullable<T>} target
    * @param  {String} name
-   * @param  {Object} options
+   * @param  {PropertyDescriptor} options
    */
   Properties.prototype.define = function(target, name, options) {
 
@@ -14819,9 +15211,11 @@
     Object.defineProperty(target, name, options);
   };
 
-
   /**
    * Define the descriptor for an element
+   * @template [T=any]
+   * @param {NonNullable<T>} target
+   * @param {EffectiveDescriptor | AnyTypeDescriptor} descriptor
    */
   Properties.prototype.defineDescriptor = function(target, descriptor) {
     this.define(target, '$descriptor', { value: descriptor });
@@ -14829,6 +15223,9 @@
 
   /**
    * Define the model for an element
+   * @template [T=any]
+   * @param {NonNullable<T>} target
+   * @param {Moddle} model
    */
   Properties.prototype.defineModel = function(target, model) {
     this.define(target, '$model', { value: model });
@@ -14837,10 +15234,10 @@
   /**
    * Return property with the given name on the element.
    *
-   * @param {any} target
+   * @param {ModdleElement} target
    * @param {string} name
    *
-   * @return {object | null} property
+   * @return {PropertyDesc | null} property
    */
   Properties.prototype.getProperty = function(target, name) {
 
@@ -14889,6 +15286,83 @@
     return name.replace(/^:/, '');
   }
 
+  /**
+   * @typedef {import('./registry.js').RegisteredTypeDef} RegisteredTypeDef
+   * @typedef {import('./registry.js').RegisteredPackage} RegisteredPackage
+   * @typedef {import('./base.js').default} BaseElement
+   * @typedef {import('./descriptor-builder.js').EffectiveDescriptor} EffectiveDescriptor
+   * @typedef {import('./descriptor-builder.js').AnyTypeDescriptor} AnyTypeDescriptor
+   * @typedef {import('./descriptor-builder.js').PropertyDescriptor} PropertyDescriptor
+   */
+
+  /**
+   * @template [T=Record<string,any>]
+   * @typedef {import('./factory.js').ModdleElement<T>} ModdleElement
+   * @typedef {import('./factory.js').ModdleElementType<T>} ModdleElementType
+   * @typedef {import('./factory.js').AnyModdleElement<T>} AnyModdleElement
+   */
+
+  /**
+   * Package definition
+   * @typedef {{
+   *   $schema?: string;
+   *   name: string;
+   *   prefix: string;
+   *   types?: Array<TypeDefinition>;
+   *   [key: string]: any;
+   * } & PackageDefinitionXmlExtension} PackageDefinition
+   */
+
+  /**
+   * Set of extended parameters for package definition used in moddle-xml.
+   * @typedef {{
+   *   uri?: string;
+   *   xml?: {
+   *     tagAlias?: 'lowerCase';
+   *     typePrefix?: string;
+   *   };
+   * }} PackageDefinitionXmlExtension
+   */
+
+  /**
+   * Type definition in declaration in package
+   * @typedef {{
+   *   name: string;
+   *   isAbstract?: boolean;
+   *   properties?: Array<PropertyDefinition>;
+   *   superClass?: Array<string>;
+   *   extends?: Array<string>;
+   *   meta?: Record<string, *>;
+   *   [key: string]: any;
+   * }} TypeDefinition
+   */
+
+  /**
+   * Set of extended parameters for property definition used in moddle-xml.
+   * @typedef {{
+   *   isBody?: boolean;
+   *   isAttr?: boolean;
+   *   xml?: {
+   *     serialize?: string;
+   *   };
+   * }} PropertyDefinitionXmlExtension
+   */
+
+  /**
+   * Property definition of type definition
+   * @typedef {{
+   *   name: string;
+   *   type: 'String' | 'Boolean' | 'Integer' | 'Real' | string;
+   *   default?: string | boolean | number;
+   *   isMany?: boolean;
+   *   isReference?: boolean;
+   *   isId?: boolean;
+   *   redefines?: string;
+   *   replaces?: string;
+   *   [key: string]: any;
+   * } & PropertyDefinitionXmlExtension} PropertyDefinition
+   */
+
   // Moddle implementation /////////////////////////////////////////////////
 
   /**
@@ -14898,7 +15372,7 @@
    *
    * @example
    *
-   * var Moddle = require('moddle');
+   * import Moddle from 'moddle';
    *
    * var pkg = {
    *   name: 'mypackage',
@@ -14910,23 +15384,31 @@
    *
    * var moddle = new Moddle([pkg]);
    *
-   * @param {Array<Package>} packages the packages to contain
-   *
-   * @param { { strict?: boolean } } [config] moddle configuration
+   * @param {Array<PackageDefinition> | Record<string,PackageDefinition>} packages the packages to contain
+   * @param {{ strict?: boolean }} [config={}] moddle configuration
    */
   function Moddle(packages, config = {}) {
 
+    /** @type Readonly<Properties> */
     this.properties = new Properties(this);
 
+    /** @type Readonly<Factory> */
     this.factory = new Factory(this, this.properties);
-    this.registry = new Registry(packages, this.properties);
 
-    this.typeCache = {};
+    /** @type Readonly<Registry> */
+    this.registry = new Registry(packages, this.properties);
 
+    /**
+     * @type {Record<string,ModdleElementType>}
+     */
+    this.typeCache = Object.create(null);
+
+    /**
+     * @type {Readonly<{readonly strict?: boolean}>}
+     */
     this.config = config;
   }
 
-
   /**
    * Create an instance of the specified type.
    *
@@ -14937,9 +15419,10 @@
    * var foo = moddle.create('my:Foo');
    * var bar = moddle.create('my:Bar', { id: 'BAR_1' });
    *
-   * @param  {String|Object} descriptor the type descriptor or name know to the model
-   * @param  {Object} attrs   a number of attributes to initialize the model instance with
-   * @return {Object}         model instance
+   * @template [T=Record<string,any>]
+   * @param  {String|EffectiveDescriptor} descriptor the type descriptor or name know to the model
+   * @param  {Partial<T>} [attrs] a number of attributes to initialize the model instance with
+   * @return {ModdleElement<T>} model instance
    */
   Moddle.prototype.create = function(descriptor, attrs) {
     var Type = this.getType(descriptor);
@@ -14951,7 +15434,6 @@
     return new Type(attrs);
   };
 
-
   /**
    * Returns the type representing a given descriptor
    *
@@ -14962,8 +15444,9 @@
    * var Foo = moddle.getType('my:Foo');
    * var foo = new Foo({ 'id' : 'FOO_1' });
    *
-   * @param  {String|Object} descriptor the type descriptor or name know to the model
-   * @return {Object}         the type representing the descriptor
+   * @template [T=Record<string,any>]
+   * @param  {String|EffectiveDescriptor} descriptor the type descriptor or name know to the model
+   * @return {ModdleElementType<T>} the type representing the descriptor
    */
   Moddle.prototype.getType = function(descriptor) {
 
@@ -14981,7 +15464,6 @@
     return type;
   };
 
-
   /**
    * Creates an any-element type to be used within model instances.
    *
@@ -15003,16 +15485,17 @@
    *
    * // go ahead and serialize the stuff
    *
-   *
+   * @template [T=Record<string, any>]
    * @param  {String} name  the name of the element
    * @param  {String} nsUri the namespace uri of the element
-   * @param  {Object} [properties] a map of properties to initialize the instance with
-   * @return {Object} the any type instance
+   * @param  {T} [properties] a map of properties to initialize the instance with
+   * @return {AnyModdleElement<T>} the any type instance
    */
   Moddle.prototype.createAny = function(name, nsUri, properties) {
 
     var nameNs = parseName(name);
 
+    /** @type AnyModdleElement */
     var element = {
       $type: name,
       $instanceOf: function(type) {
@@ -15026,6 +15509,7 @@
       }
     };
 
+    /** @type AnyTypeDescriptor */
     var descriptor = {
       name: name,
       isGeneric: true,
@@ -15056,8 +15540,8 @@
 
   /**
    * Returns a registered package by uri or prefix
-   *
-   * @return {Object} the package
+   * @param {string} uriOrPrefix
+   * @return {RegisteredPackage} the package
    */
   Moddle.prototype.getPackage = function(uriOrPrefix) {
     return this.registry.getPackage(uriOrPrefix);
@@ -15066,7 +15550,7 @@
   /**
    * Returns a snapshot of all known packages
    *
-   * @return {Object} the package
+   * @return {Readonly<Array<RegisteredPackage>>} the package
    */
   Moddle.prototype.getPackages = function() {
     return this.registry.getPackages();
@@ -15074,16 +15558,25 @@
 
   /**
    * Returns the descriptor for an element
+   * @param {ModdleElement | ModdleElementType} element
+   * @return {EffectiveDescriptor}
    */
   Moddle.prototype.getElementDescriptor = function(element) {
     return element.$descriptor;
   };
 
   /**
+   * @overload
    * Returns true if the given descriptor or instance
    * represents the given type.
-   *
-   * May be applied to this, if element is omitted.
+   * @param {ModdleElement | ModdleElementType} element
+   * @param {string} type
+   * @return {boolean}
+   */
+  /**
+   * @overload
+   * @param {string} type
+   * @return {boolean}
    */
   Moddle.prototype.hasType = function(element, type) {
     if (type === undefined) {
@@ -15098,13 +15591,18 @@
 
   /**
    * Returns the descriptor of an elements named property
+   * @param {ModdleElement | ModdleElementType} element
+   * @param {string} property
+   * @return {PropertyDescriptor}
    */
   Moddle.prototype.getPropertyDescriptor = function(element, property) {
     return this.getElementDescriptor(element).propertiesByName[property];
   };
 
   /**
-   * Returns a mapped type's descriptor
+   * Return registered type definition
+   * @param {string} type
+   * @return {RegisteredTypeDef}
    */
   Moddle.prototype.getTypeDescriptor = function(type) {
     return this.registry.typeMap[type];
@@ -15188,19 +15686,24 @@
   }
 
   function cloneNsMatrix(nsMatrix) {
-    var clone = {}, key;
+    var clone = Object.create(null), key;
     for (key in nsMatrix) {
       clone[key] = nsMatrix[key];
     }
     return clone;
   }
 
+  // per-matrix element name cache; stored under a symbol so it is
+  // invisible to the `for (key in nsMatrix)` clone above and gets
+  // collected together with the matrix it belongs to
+  var NAME_CACHE = Symbol('nameCache');
+
   function uriPrefix(prefix) {
     return prefix + '$uri';
   }
 
   function buildNsMatrix(nsUriToPrefix) {
-    var nsMatrix = {},
+    var nsMatrix = Object.create(null),
         uri,
         prefix;
 
@@ -15248,6 +15751,33 @@
 
     var getContext = noopGetContext;
 
+    /**
+     * Are we currently consuming a chunked stream of XML,
+     * i.e. is a `write` call in progress that may be followed
+     * by more chunks?
+     *
+     * @type {boolean}
+     */
+    var streaming = false;
+
+    /**
+     * Did we already encounter the root tag?
+     *
+     * Persisted across `write` calls so we can detect a missing
+     * start tag once the stream ends.
+     *
+     * @type {boolean}
+     */
+    var rootTagFound = false;
+
+    /**
+     * Not yet parsed remainder of the previously written chunk,
+     * i.e. an incomplete token that awaits more input.
+     *
+     * @type {string}
+     */
+    var leftoverXml = '';
+
     /**
      * Do we need to parse the current elements attributes for namespaces?
      *
@@ -15276,6 +15806,13 @@
      */
     var parseStop = false;
 
+    /**
+     * Namespace + node state shared across (streamed) parse runs.
+     */
+    var nsMatrixStack,
+        nsMatrix,
+        nodeStack;
+
     /**
      * A map of { uri: prefix } used by the parser.
      *
@@ -15374,7 +15911,7 @@
         throw error$1('required args <nsMap={}>');
       }
 
-      var _nsUriToPrefix = {}, k;
+      var _nsUriToPrefix = Object.create(null), k;
 
       for (k in nsMap) {
         _nsUriToPrefix[k] = nsMap[k];
@@ -15387,7 +15924,22 @@
     };
 
     /**
-     * Parse xml string.
+     * Reset the parser state before a (streamed) parse run.
+     */
+    function resetState() {
+      nsMatrixStack = isNamespace ? [] : null;
+      nsMatrix = isNamespace ? buildNsMatrix(nsUriToPrefix) : null;
+      nodeStack = [];
+
+      getContext = noopGetContext;
+      parseStop = false;
+      returnError = null;
+      rootTagFound = false;
+      leftoverXml = '';
+    }
+
+    /**
+     * Parse a complete xml string.
      *
      * @param  {string} xml
      *
@@ -15398,7 +15950,11 @@
         throw error$1('required args <xml=string>');
       }
 
-      returnError = null;
+      if (streaming) {
+        throw error$1('parse during stream; call end() first');
+      }
+
+      resetState();
 
       parse(xml);
 
@@ -15408,6 +15964,60 @@
       return returnError;
     };
 
+    /**
+     * Write the next chunk of a streamed xml string.
+     *
+     * Parse events are emitted for all complete tokens; an
+     * incomplete trailing token is buffered until the next
+     * `write` or, ultimately, reported as an error on `end`.
+     *
+     * @param  {string} xml
+     *
+     * @return {Parser} self
+     */
+    this['write'] = function(xml) {
+      if (typeof xml !== 'string') {
+        throw error$1('required args <xml=string>');
+      }
+
+      if (!streaming) {
+        resetState();
+        streaming = true;
+      }
+
+      if (!returnError) {
+        leftoverXml = parse(leftoverXml + xml, true) || '';
+      }
+
+      return this;
+    };
+
+    /**
+     * Finish parsing a streamed xml string, i.e. signal that
+     * no more chunks will be written.
+     *
+     * @return {Error} returnError, if not thrown
+     */
+    this['end'] = function() {
+      if (!streaming) {
+        resetState();
+      }
+
+      // flush the buffered remainder, now treating an incomplete
+      // trailing token as a hard error
+      streaming = false;
+
+      if (!returnError) {
+        parse(leftoverXml);
+      }
+
+      leftoverXml = '';
+      getContext = noopGetContext;
+      parseStop = false;
+
+      return returnError;
+    };
+
     /**
      * Stop parsing.
      */
@@ -15418,13 +16028,26 @@
     /**
      * Parse string, invoking configured listeners on element.
      *
-     * @param  {string} xml
+     * Namespace and node stack state is shared across (streamed)
+     * invocations via the enclosing parser scope.
+     *
+     * Internal note: while `streaming`, an incomplete trailing token
+     * is not treated as an error but returned so `write` can buffer it
+     * and prepend it to the next chunk. This buffered remainder is an
+     * implementation detail of the streaming buffer, not a public API;
+     * outside of that case the return value is `undefined`.
+     *
+     * @param {string} xml
+     * @param {boolean} streaming
+     *
+     * @return {string|undefined} buffered remainder, streaming internal use only
      */
-    function parse(xml) {
-      var nsMatrixStack = isNamespace ? [] : null,
-          nsMatrix = isNamespace ? buildNsMatrix(nsUriToPrefix) : null,
-          _nsMatrix,
-          nodeStack = [],
+    function parse(xml, streaming = false) {
+
+      var elNameCache = null,
+          elNameCacheMatrix = null;
+
+      var _nsMatrix,
           anonymousNsCount = 0,
           tagStart = false,
           tagEnd = false,
@@ -15441,6 +16064,36 @@
           cachedAttrs // false = parsed with errors, null = needs parsing
           ;
 
+      /**
+       * Normalize a namespaced attribute name against the current
+       * namespace matrix.
+       *
+       * @param {string} name
+       * @param {string|boolean} defaultAlias
+       *
+       * @return {string|null} normalized name, or `null` when the prefix
+       *                       has no namespace (a warning is emitted)
+       */
+      function normalizeAttrName(name, defaultAlias) {
+        var w = name.indexOf(':');
+
+        if (w === -1) {
+          return name;
+        }
+
+        // normalize ns attribute name
+        var nsName = nsMatrix[name.substring(0, w)];
+
+        if (!nsName) {
+          handleWarning(missingNamespaceForPrefix(name.substring(0, w)));
+          return null;
+        }
+
+        return defaultAlias === nsName
+          ? name.substr(w + 1)
+          : nsName + name.substr(w);
+      }
+
       /**
        * Parse attributes on demand and returns the parsed attributes.
        *
@@ -15456,7 +16109,6 @@
 
         var nsUri,
             nsUriPrefix,
-            nsName,
             defaultAlias = isNamespace && nsMatrix['xmlns'],
             attrList = isNamespace && maybeNS ? [] : null,
             i = attrsStart,
@@ -15468,7 +16120,7 @@
             alias,
             name,
             attrs = {},
-            seenAttrs = {},
+            seenAttrs = new Set(),
             skipAttr,
             w,
             j;
@@ -15608,12 +16260,12 @@
           }
 
           // check attribute re-declaration
-          if (name in seenAttrs) {
+          if (seenAttrs.has(name)) {
             handleWarning('attribute <' + name + '> already defined');
             continue;
           }
 
-          seenAttrs[name] = true;
+          seenAttrs.add(name);
 
           if (!isNamespace) {
             attrs[name] = value;
@@ -15685,24 +16337,12 @@
 
           // handle attributes on element without
           // namespace declarations
-          w = name.indexOf(':');
-          if (w === -1) {
-            attrs[name] = value;
-            continue;
-          }
+          name = normalizeAttrName(name, defaultAlias);
 
-          // normalize ns attribute name
-          if (!(nsName = nsMatrix[name.substring(0, w)])) {
-            handleWarning(missingNamespaceForPrefix(name.substring(0, w)));
+          if (name === null) {
             continue;
           }
 
-          name = defaultAlias === nsName
-            ? name.substr(w + 1)
-            : nsName + name.substr(w);
-
-          // end: normalize ns attribute name
-
           attrs[name] = value;
         }
 
@@ -15713,24 +16353,11 @@
           // normalize captured attributes
           for (i = 0, l = attrList.length; i < l; i++) {
 
-            name = attrList[i++];
+            name = normalizeAttrName(attrList[i++], defaultAlias);
             value = attrList[i];
 
-            w = name.indexOf(':');
-
-            if (w !== -1) {
-
-              // normalize ns attribute name
-              if (!(nsName = nsMatrix[name.substring(0, w)])) {
-                handleWarning(missingNamespaceForPrefix(name.substring(0, w)));
-                continue;
-              }
-
-              name = defaultAlias === nsName
-                ? name.substr(w + 1)
-                : nsName + name.substr(w);
-
-              // end: normalize ns attribute name
+            if (name === null) {
+              continue;
             }
 
             attrs[name] = value;
@@ -15830,13 +16457,19 @@
           i = xml.indexOf('<', j);
         }
 
-        // parse end
+        // no (more) tags found
         if (i === -1) {
+
+          // buffer the remainder for the next chunk
+          if (streaming) {
+            return xml.substring(j);
+          }
+
           if (nodeStack.length) {
             return handleError('unexpected end of file');
           }
 
-          if (j === 0) {
+          if (!rootTagFound) {
             return handleError('missing start tag');
           }
 
@@ -15849,6 +16482,11 @@
           return;
         }
 
+        // remember that we saw the root tag
+        if (!rootTagFound) {
+          rootTagFound = true;
+        }
+
         // parse text
         if (j !== i) {
 
@@ -15881,6 +16519,9 @@
           if (q === 91 && xml.substr(i + 3, 6) === 'CDATA[') { // 91 == "["
             j = xml.indexOf(']]>', i);
             if (j === -1) {
+              if (streaming) {
+                return xml.substring(i);
+              }
               return handleError('unclosed cdata');
             }
 
@@ -15899,6 +16540,9 @@
           if (q === 45 && xml.charCodeAt(i + 3) === 45) { // 45 == "-"
             j = xml.indexOf('-->', i);
             if (j === -1) {
+              if (streaming) {
+                return xml.substring(i);
+              }
               return handleError('unclosed comment');
             }
 
@@ -15919,6 +16563,9 @@
         if (w === 63) { // "?"
           j = xml.indexOf('?>', i);
           if (j === -1) {
+            if (streaming) {
+              return xml.substring(i);
+            }
             return handleError('unclosed question');
           }
 
@@ -15939,6 +16586,9 @@
         for (x = i + 1; ; x++) {
           v = xml.charCodeAt(x);
           if (isNaN(v)) {
+            if (streaming) {
+              return xml.substring(i);
+            }
             j = -1;
             return handleError('unclosed tag');
           }
@@ -16078,30 +16728,49 @@
 
           _elementName = elementName;
 
-          w = elementName.indexOf(':');
-          if (w !== -1) {
-            xmlns = nsMatrix[elementName.substring(0, w)];
-
-            // prefix given; namespace must exist
-            if (!xmlns) {
-              return handleError('missing namespace on <' + _elementName + '>');
+          // memoize normalized names per namespace matrix; tag names
+          // typically repeat heavily and the matrix rarely changes.
+          if (elNameCacheMatrix !== nsMatrix) {
+            elNameCache = nsMatrix[NAME_CACHE];
+            if (elNameCache === undefined) {
+              elNameCache = nsMatrix[NAME_CACHE] = Object.create(null);
             }
+            elNameCacheMatrix = nsMatrix;
+          }
+
+          var _cachedName = elNameCache[elementName];
 
-            elementName = elementName.substr(w + 1);
+          if (_cachedName !== undefined) {
+            elementName = _cachedName;
           } else {
-            xmlns = nsMatrix['xmlns'];
-
-            // if no default namespace is defined,
-            // we'll import the element as anonymous.
-            //
-            // it is up to users to correct that to the document defined
-            // targetNamespace, or whatever their undersanding of the
-            // XML spec mandates.
-          }
 
-          // adjust namespace prefixs as configured
-          if (xmlns) {
-            elementName = xmlns + ':' + elementName;
+            w = elementName.indexOf(':');
+            if (w !== -1) {
+              xmlns = nsMatrix[elementName.substring(0, w)];
+
+              // prefix given; namespace must exist
+              if (!xmlns) {
+                return handleError('missing namespace on <' + _elementName + '>');
+              }
+
+              elementName = elementName.substr(w + 1);
+            } else {
+              xmlns = nsMatrix['xmlns'];
+
+              // if no default namespace is defined,
+              // we'll import the element as anonymous.
+              //
+              // it is up to users to correct that to the document defined
+              // targetNamespace, or whatever their undersanding of the
+              // XML spec mandates.
+            }
+
+            // adjust namespace prefixs as configured
+            if (xmlns) {
+              elementName = xmlns + ':' + elementName;
+            }
+
+            elNameCache[_elementName] = elementName;
           }
 
         }
@@ -17125,10 +17794,48 @@
     return this.defaultPrefixMap[prefix];
   };
 
+  /**
+   * Return the first truthy `fn(scope)` walking this scope and its ancestors.
+   *
+   * @param {(scope: Namespaces) => any} fn
+   *
+   * @return {any}
+   */
+  Namespaces.prototype.resolve = function(fn) {
+
+    var scope = this;
+
+    while (scope) {
+      var resolved = fn(scope);
+
+      if (resolved) {
+        return resolved;
+      }
+
+      scope = scope.parent;
+    }
+  };
+
+  /**
+   * Call `fn(scope)` for this scope and each of its ancestors.
+   *
+   * @param {(scope: Namespaces) => void} fn
+   */
+  Namespaces.prototype.eachScope = function(fn) {
+
+    var scope = this;
+
+    while (scope) {
+      fn(scope);
+
+      scope = scope.parent;
+    }
+  };
+
   Namespaces.prototype.byUri = function(uri) {
-    return this.uriMap[uri] || (
-      this.parent && this.parent.byUri(uri)
-    );
+    return this.resolve(function(scope) {
+      return scope.uriMap[uri];
+    });
   };
 
   Namespaces.prototype.add = function(ns, isWellknown) {
@@ -17145,9 +17852,11 @@
   };
 
   Namespaces.prototype.uriByPrefix = function(prefix) {
-    return this.prefixMap[prefix || 'xmlns'] || (
-      this.parent && this.parent.uriByPrefix(prefix)
-    );
+    var key = prefix || 'xmlns';
+
+    return this.resolve(function(scope) {
+      return scope.prefixMap[key];
+    });
   };
 
   Namespaces.prototype.mapPrefix = function(prefix, uri) {
@@ -17163,12 +17872,9 @@
     var uri = ns.uri;
     var nsKey = this.getNSKey(ns);
 
-    this.used[nsKey] = this.byUri(uri);
-
-    // Inform parent recursively about the usage of this NS
-    if (this.parent) {
-      this.parent.logUsed(ns);
-    }
+    this.eachScope(function(scope) {
+      scope.used[nsKey] = scope.byUri(uri);
+    });
   };
 
   Namespaces.prototype.getUsed = function(ns) {
@@ -17385,20 +18091,32 @@
   }
 
   ElementSerializer.prototype.build = function(element) {
+    buildTree(this, element);
+
+    return this;
+  };
+
+  /**
+   * Enter the element during the build walk: register its namespaces, tag
+   * name and attributes, then return the deferred, ordered work to build its
+   * child nodes (empty when it has none).
+   *
+   * @param {Object} element
+   *
+   * @return {Array<Object>} ordered, deferred work items to build the children
+   */
+  ElementSerializer.prototype.enter = function(element) {
     this.element = element;
 
     var elementDescriptor = element.$descriptor,
         propertyDescriptor = this.propertyDescriptor;
 
-    var otherAttrs,
-        properties;
-
     var isGeneric = elementDescriptor.isGeneric;
 
     if (isGeneric) {
-      otherAttrs = this.parseGenericNsAttributes(element);
+      this.otherAttrs = this.parseGenericNsAttributes(element);
     } else {
-      otherAttrs = this.parseNsAttributes(element);
+      this.otherAttrs = this.parseNsAttributes(element);
     }
 
     if (propertyDescriptor) {
@@ -17407,21 +18125,26 @@
       this.ns = this.nsTagName(elementDescriptor);
     }
 
-    // compute tag name
     this.tagName = this.addTagName(this.ns);
 
     if (isGeneric) {
-      this.parseGenericContainments(element);
-    } else {
-      properties = getSerializableProperties(element);
-
-      this.parseAttributes(filterAttributes(properties));
-      this.parseContainments(filterContained(properties));
+      return this.collectGenericContainments(element);
     }
 
-    this.parseGenericAttributes(element, otherAttrs);
+    var properties = getSerializableProperties(element);
 
-    return this;
+    this.parseAttributes(filterAttributes(properties));
+
+    return this.collectContainments(filterContained(properties));
+  };
+
+  /**
+   * Exit the element during the build walk: register its generic attributes,
+   * which must happen after the children so namespace usage is logged in
+   * document order.
+   */
+  ElementSerializer.prototype.exit = function() {
+    this.parseGenericAttributes(this.element, this.otherAttrs);
   };
 
   ElementSerializer.prototype.nsTagName = function(descriptor) {
@@ -17484,20 +18207,34 @@
     );
   };
 
-  ElementSerializer.prototype.parseGenericContainments = function(element) {
-    var body = element.$body;
+  ElementSerializer.prototype.collectGenericContainments = function(element) {
+    var self = this,
+        children = [];
+
+    var bodyText = element.$body;
 
-    if (body) {
-      this.body.push(new BodySerializer().build({ type: 'String' }, body));
+    if (bodyText) {
+      children.push({
+        create: function() {
+          return new BodySerializer().build({ type: 'String' }, bodyText);
+        }
+      });
     }
 
-    var children = element.$children;
+    var genericChildren = element.$children;
 
-    if (children) {
-      forEach(children, child => {
-        this.body.push(new ElementSerializer(this).build(child));
+    if (genericChildren) {
+      forEach(genericChildren, function(child) {
+        children.push({
+          create: function() {
+            return new ElementSerializer(self);
+          },
+          element: child
+        });
       });
     }
+
+    return children;
   };
 
   ElementSerializer.prototype.parseNsAttribute = function(element, name, value) {
@@ -17576,7 +18313,6 @@
         self.addAttribute(self.nsAttributeName(attr.name), attr.value);
       } catch (e) {
 
-        // eslint-disable-next-line no-undef
         typeof console !== 'undefined' && console.warn(
           `missing namespace information for <${
           attr.name
@@ -17586,11 +18322,11 @@
     });
   };
 
-  ElementSerializer.prototype.parseContainments = function(properties) {
+  ElementSerializer.prototype.collectContainments = function(properties) {
 
     var self = this,
-        body = this.body,
-        element = this.element;
+        element = this.element,
+        children = [];
 
     forEach(properties, function(p) {
       var value = element.get(p.name),
@@ -17602,14 +18338,26 @@
       }
 
       if (p.isBody) {
-        body.push(new BodySerializer().build(p, value[0]));
+        children.push({
+          create: function() {
+            return new BodySerializer().build(p, value[0]);
+          }
+        });
       } else if (isSimple(p.type)) {
         forEach(value, function(v) {
-          body.push(new ValueSerializer(self.addTagName(self.nsPropertyTagName(p))).build(p, v));
+          children.push({
+            create: function() {
+              return new ValueSerializer(self.addTagName(self.nsPropertyTagName(p))).build(p, v);
+            }
+          });
         });
       } else if (isReference) {
         forEach(value, function(v) {
-          body.push(new ReferenceSerializer(self.addTagName(self.nsPropertyTagName(p))).build(v));
+          children.push({
+            create: function() {
+              return new ReferenceSerializer(self.addTagName(self.nsPropertyTagName(p))).build(v);
+            }
+          });
         });
       } else {
 
@@ -17618,32 +18366,33 @@
         var serialization = getSerialization(p);
 
         forEach(value, function(v) {
-          var serializer;
+          children.push({
+            create: function() {
+              if (serialization) {
+                if (serialization === SERIALIZE_PROPERTY) {
+                  return new ElementSerializer(self, p);
+                }
 
-          if (serialization) {
-            if (serialization === SERIALIZE_PROPERTY) {
-              serializer = new ElementSerializer(self, p);
-            } else {
-              serializer = new TypeSerializer(self, p, serialization);
-            }
-          } else {
-            serializer = new ElementSerializer(self);
-          }
+                return new TypeSerializer(self, p, serialization);
+              }
 
-          body.push(serializer.build(v));
+              return new ElementSerializer(self);
+            },
+            element: v
+          });
         });
       }
     });
+
+    return children;
   };
 
   ElementSerializer.prototype.getNamespaces = function(local) {
 
-    var namespaces = this.namespaces,
-        parent = this.parent,
-        parentNamespaces;
+    var namespaces = this.namespaces;
 
     if (!namespaces) {
-      parentNamespaces = parent && parent.getNamespaces();
+      var parentNamespaces = this.getParentNamespaces();
 
       if (local || !parentNamespaces) {
         this.namespaces = namespaces = new Namespaces(parentNamespaces);
@@ -17655,6 +18404,38 @@
     return namespaces;
   };
 
+  /**
+   * Resolve, and memoize, the namespaces scope owned by the closest
+   * ancestor serializer.
+   *
+   * @return {Namespaces|null}
+   */
+  ElementSerializer.prototype.getParentNamespaces = function() {
+
+    if (this.parentNamespaces !== undefined) {
+      return this.parentNamespaces;
+    }
+
+    var scope = null,
+        ancestor = this.parent;
+
+    while (ancestor) {
+      if (ancestor.namespaces) {
+        scope = ancestor.namespaces;
+        break;
+      }
+
+      if (ancestor.parentNamespaces !== undefined) {
+        scope = ancestor.parentNamespaces;
+        break;
+      }
+
+      ancestor = ancestor.parent;
+    }
+
+    return (this.parentNamespaces = scope);
+  };
+
   ElementSerializer.prototype.logNamespace = function(ns, wellknown, local) {
     var namespaces = this.getNamespaces(local);
 
@@ -17803,40 +18584,77 @@
   };
 
   ElementSerializer.prototype.serializeTo = function(writer) {
-    var firstBody = this.body[0],
-        indent = firstBody && firstBody.constructor !== BodySerializer;
+    serializeTree(this, writer);
+  };
 
-    writer
-      .appendIndent()
-      .append('<' + this.tagName);
+  /**
+   * Serialize the serializer tree rooted at the given element serializer to
+   * the writer, using an explicit stack to stay flat for nested documents.
+   *
+   * @param {ElementSerializer} root
+   * @param {Object} writer
+   */
+  function serializeTree(root, writer) {
 
-    this.serializeAttributes(writer);
+    var stack = [ { serializer: root, index: 0, opened: false, indent: false } ];
 
-    writer.append(firstBody ? '>' : ' />');
+    while (stack.length) {
+      var frame = stack[stack.length - 1],
+          serializer = frame.serializer;
 
-    if (firstBody) {
+      if (!frame.opened) {
+        var firstBody = serializer.body[0];
+
+        frame.indent = firstBody && firstBody.constructor !== BodySerializer;
 
-      if (indent) {
         writer
-          .appendNewLine()
-          .indent();
+          .appendIndent()
+          .append('<' + serializer.tagName);
+
+        serializer.serializeAttributes(writer);
+
+        writer.append(firstBody ? '>' : ' />');
+
+        frame.opened = true;
+
+        if (!firstBody) {
+          writer.appendNewLine();
+          stack.pop();
+          continue;
+        }
+
+        if (frame.indent) {
+          writer
+            .appendNewLine()
+            .indent();
+        }
       }
 
-      forEach(this.body, function(b) {
-        b.serializeTo(writer);
-      });
+      if (frame.index < serializer.body.length) {
+        var child = serializer.body[frame.index++];
 
-      if (indent) {
+        if (child instanceof ElementSerializer) {
+          stack.push({ serializer: child, index: 0, opened: false, indent: false });
+        } else {
+          child.serializeTo(writer);
+        }
+
+        continue;
+      }
+
+      if (frame.indent) {
         writer
           .unindent()
           .appendIndent();
       }
 
-      writer.append('</' + this.tagName + '>');
-    }
+      writer
+        .append('</' + serializer.tagName + '>')
+        .appendNewLine();
 
-    writer.appendNewLine();
-  };
+      stack.pop();
+    }
+  }
 
   /**
    * A serializer for types that handles serialization of data types
@@ -17968,6 +18786,51 @@
 
   // helpers ///////////
 
+  /**
+   * Build the serializer tree for the given root element, iterating an
+   * explicit stack rather than recursing so deeply nested documents stay
+   * flat.
+   *
+   * Elements are visited pre-order so namespaces register in document order:
+   * `enter` opens an element and returns its children, `exit` runs once its
+   * subtree is built.
+   *
+   * @param {ElementSerializer} rootSerializer
+   * @param {Object} rootElement
+   */
+  function buildTree(rootSerializer, rootElement) {
+
+    var stack = [ {
+      serializer: rootSerializer,
+      children: rootSerializer.enter(rootElement),
+      index: 0
+    } ];
+
+    while (stack.length) {
+      var frame = stack[stack.length - 1];
+
+      if (frame.index >= frame.children.length) {
+        frame.serializer.exit();
+        stack.pop();
+        continue;
+      }
+
+      var child = frame.children[frame.index++];
+
+      var childSerializer = child.create();
+
+      frame.serializer.body.push(childSerializer);
+
+      if (child.element) {
+        stack.push({
+          serializer: childSerializer,
+          children: childSerializer.enter(child.element),
+          index: 0
+        });
+      }
+    }
+  }
+
   /**
    * @param {Moddle} model
    *