bpmn-js 18.22.1 → 18.24.0

package/dist/bpmn-modeler.development.js

@@ -1,5 +1,5 @@
 /*!
- * bpmn-js - bpmn-modeler v18.22.1
+ * bpmn-js - bpmn-modeler v18.24.0
  *
  * Copyright (c) 2014-present, camunda Services GmbH
  *
@@ -8,7 +8,7 @@
  *
  * Source Code: https://github.com/bpmn-io/bpmn-js
  *
- * Date: 2026-07-29
+ * Date: 2026-08-11
  */
 (function (global, factory) {
 	typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
@@ -22571,7 +22571,7 @@
 	// document wide unique overlay ids
 	var ids$2 = new IdGenerator('ov');
 
-	var LOW_PRIORITY$q = 500;
+	var LOW_PRIORITY$s = 500;
 
 	/**
 	 * @typedef {import('../../core/Canvas.js').default} Canvas
@@ -23201,7 +23201,7 @@
 
 	  // move integration
 
-	  eventBus.on('element.changed', LOW_PRIORITY$q, function(e) {
+	  eventBus.on('element.changed', LOW_PRIORITY$s, function(e) {
 	    var element = e.element;
 
 	    var container = self._getOverlayContainer(element, true);
@@ -24283,7 +24283,7 @@
 	 * @typedef {import('../../model/Types').Shape} Shape
 	 */
 
-	var LOW_PRIORITY$p = 250;
+	var LOW_PRIORITY$r = 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';
@@ -24308,7 +24308,7 @@
 
 	  var self = this;
 
-	  this.executed('shape.toggleCollapse', LOW_PRIORITY$p, function(context) {
+	  this.executed('shape.toggleCollapse', LOW_PRIORITY$r, function(context) {
 	    var shape = context.shape;
 
 	    // Add overlay to the collapsed shape
@@ -24320,7 +24320,7 @@
 	  }, true);
 
 
-	  this.reverted('shape.toggleCollapse', LOW_PRIORITY$p, function(context) {
+	  this.reverted('shape.toggleCollapse', LOW_PRIORITY$r, function(context) {
 	    var shape = context.shape;
 
 	    // Add overlay to the collapsed shape
@@ -24332,7 +24332,7 @@
 	  }, true);
 
 
-	  this.executed([ 'shape.create', 'shape.move', 'shape.delete' ], LOW_PRIORITY$p,
+	  this.executed([ 'shape.create', 'shape.move', 'shape.delete' ], LOW_PRIORITY$r,
 	    function(context) {
 	      var oldParent = context.oldParent,
 	          newParent = context.newParent || context.parent,
@@ -24349,7 +24349,7 @@
 	    }, true);
 
 
-	  this.reverted([ 'shape.create', 'shape.move', 'shape.delete' ], LOW_PRIORITY$p,
+	  this.reverted([ 'shape.create', 'shape.move', 'shape.delete' ], LOW_PRIORITY$r,
 	    function(context) {
 	      var oldParent = context.oldParent,
 	          newParent = context.newParent || context.parent,
@@ -24626,7 +24626,7 @@
 	  return isPrimaryButton(event) || isAuxiliaryButton(event);
 	}
 
-	var LOW_PRIORITY$o = 500;
+	var LOW_PRIORITY$q = 500;
 
 
 	/**
@@ -24823,7 +24823,7 @@
 	  eventBus.on([
 	    'shape.changed',
 	    'connection.changed'
-	  ], LOW_PRIORITY$o, function(event) {
+	  ], LOW_PRIORITY$q, function(event) {
 
 	    var element = event.element,
 	        gfx = event.gfx;
@@ -24831,7 +24831,7 @@
 	    eventBus.fire('interactionEvents.updateHit', { element: element, gfx: gfx });
 	  });
 
-	  eventBus.on('interactionEvents.createHit', LOW_PRIORITY$o, function(event) {
+	  eventBus.on('interactionEvents.createHit', LOW_PRIORITY$q, function(event) {
 	    var element = event.element,
 	        gfx = event.gfx;
 
@@ -25794,7 +25794,7 @@
 	Keyboard.prototype.isShift = isShift;
 	Keyboard.prototype.isKey = isKey;
 
-	var LOW_PRIORITY$n = 500;
+	var LOW_PRIORITY$p = 500;
 
 
 	/**
@@ -25810,7 +25810,7 @@
 
 	  var self = this;
 
-	  eventBus.on('editorActions.init', LOW_PRIORITY$n, function(event) {
+	  eventBus.on('editorActions.init', LOW_PRIORITY$p, function(event) {
 
 	    var editorActions = event.editorActions;
 
@@ -27977,7 +27977,17 @@
               ${ entry.label }
             </span>
           ` : null }
-
+        </span>
+        ${ entry.description && m$1`
+          <span
+            class="djs-popup-entry-description"
+          >
+            ${ entry.description }
+          </span>
+        ` }
+      </div>
+      ${ (entry.documentationRef || entry.entries) && m$1`
+        <div class="djs-popup-entry-actions">
           ${ entry.documentationRef && m$1`
             <a
               class="djs-popup-entry-docs"
@@ -27990,24 +28000,17 @@
               rel="noopener"
             >
               <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
-                <path fill-rule="evenodd" clip-rule="evenodd" d="M10.6368 10.6375V5.91761H11.9995V10.6382C11.9995 10.9973 11.8623 11.3141 11.5878 11.5885C11.3134 11.863 10.9966 12.0002 10.6375 12.0002H1.36266C0.982345 12.0002 0.660159 11.8681 0.396102 11.6041C0.132044 11.34 1.52588e-05 11.0178 1.52588e-05 10.6375V1.36267C1.52588e-05 0.98236 0.132044 0.660173 0.396102 0.396116C0.660159 0.132058 0.982345 2.95639e-05 1.36266 2.95639e-05H5.91624V1.36267H1.36266V10.6375H10.6368ZM12 0H7.2794L7.27873 1.36197H9.68701L3.06507 7.98391L4.01541 8.93425L10.6373 2.31231V4.72059H12V0Z" fill="#818798"/>
+                <path fill-rule="evenodd" clip-rule="evenodd" d="M10.6368 10.6375V5.91761H11.9995V10.6382C11.9995 10.9973 11.8623 11.3141 11.5878 11.5885C11.3134 11.863 10.9966 12.0002 10.6375 12.0002H1.36266C0.982345 12.0002 0.660159 11.8681 0.396102 11.6041C0.132044 11.34 1.52588e-05 11.0178 1.52588e-05 10.6375V1.36267C1.52588e-05 0.98236 0.132044 0.660173 0.396102 0.396116C0.660159 0.132058 0.982345 2.95639e-05 1.36266 2.95639e-05H5.91624V1.36267H1.36266V10.6375H10.6368ZM12 0H7.2794L7.27873 1.36197H9.68701L3.06507 7.98391L4.01541 8.93425L10.6373 2.31231V4.72059H12V0Z" fill="currentColor"/>
               </svg>
             </a>
           ` }
-        </span>
-        ${ entry.description && m$1`
-          <span
-            class="djs-popup-entry-description"
-          >
-            ${ entry.description }
-          </span>
-        ` }
-      </div>
-      ${ entry.entries && m$1`
-        <div class="djs-popup-entry-chevron" aria-hidden="true">
-          <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
-            <path fill-rule="evenodd" clip-rule="evenodd" d="M3.96967 1.46967C4.26256 1.17678 4.73744 1.17678 5.03033 1.46967L9.03033 5.46967C9.32322 5.76256 9.32322 6.23744 9.03033 6.53033L5.03033 10.5303C4.73744 10.8232 4.26256 10.8232 3.96967 10.5303C3.67678 10.2374 3.67678 9.76256 3.96967 9.46967L7.43934 6L3.96967 2.53033C3.67678 2.23744 3.67678 1.76256 3.96967 1.46967Z" fill="currentColor"/>
-          </svg>
+          ${ entry.entries && m$1`
+            <div class="djs-popup-entry-chevron" aria-hidden="true">
+              <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+                <path fill-rule="evenodd" clip-rule="evenodd" d="M3.96967 1.46967C4.26256 1.17678 4.73744 1.17678 5.03033 1.46967L9.03033 5.46967C9.32322 5.76256 9.32322 6.23744 9.03033 6.53033L5.03033 10.5303C4.73744 10.8232 4.26256 10.8232 3.96967 10.5303C3.67678 10.2374 3.67678 9.76256 3.96967 9.46967L7.43934 6L3.96967 2.53033C3.67678 2.23744 3.67678 1.76256 3.96967 1.46967Z" fill="currentColor"/>
+              </svg>
+            </div>
+          ` }
         </div>
       ` }
     </li>
@@ -28063,7 +28066,7 @@
 	    const selectedEl = containerEl.querySelector('.selected');
 
 	    if (selectedEl) {
-	      scrollIntoView(selectedEl);
+	      scrollIntoView$1(selectedEl);
 	    }
 	  }, [ selectedEntry ]);
 
@@ -28137,7 +28140,7 @@
 	  return `${ idPrefix }-group-${ group.id }`;
 	}
 
-	function scrollIntoView(el) {
+	function scrollIntoView$1(el) {
 	  if (typeof el.scrollIntoViewIfNeeded === 'function') {
 	    el.scrollIntoViewIfNeeded();
 	  } else {
@@ -28179,6 +28182,7 @@
 	 * @param {PopupMenuEmptyPlaceholder} [props.emptyPlaceholder]
 	 * @param {number|string} [props.width]
 	 * @param {searchFn} props.searchFn
+	 * @param {import('./PopupMenuProvider.js').PopupMenuTab} [props.defaultTab]
 	 */
 	function PopupMenuComponent(props) {
 	  const {
@@ -28195,7 +28199,8 @@
 	    searchFn,
 	    entries,
 	    onOpened,
-	    onClosed
+	    onClosed,
+	    defaultTab
 	  } = props;
 
 	  /**
@@ -28210,12 +28215,183 @@
 
 	  /**
 	   * On `PopupMenu#refresh()` (i.e. when `entries` change)
-	   * the stack is reset to root.
+	   * the stack and active tab are reset to root.
 	   */
 	  y(() => {
 	    setNavigationStack([]);
+	    setActiveTab(null);
 	  }, [ entries ]);
 
+	  /**
+	   * Tabs partition root-level entries. They are derived from the entries'
+	   * `tab` property; entries without a `tab` belong to the default tab. The
+	   * tab strip only renders when at least two distinct tabs exist.
+	   *
+	   * @type {import('./PopupMenuProvider.js').PopupMenuTab[]}
+	   */
+	  const tabs = T(() => {
+	    const tabbed = [];
+	    const seen = new Set();
+
+	    let hasUntagged = false;
+
+	    entries.forEach(({ tab }) => {
+	      if (!tab) {
+	        hasUntagged = true;
+
+	        return;
+	      }
+
+	      if (!seen.has(tab.id)) {
+	        seen.add(tab.id);
+	        tabbed.push(tab);
+	      }
+	    });
+
+	    if (!tabbed.length) {
+	      return [];
+	    }
+
+	    // untagged entries need a tab to live in; without a configured
+	    // `defaultTab` there is no name to give it, so stay untabbed rather
+	    // than invent one
+	    if (hasUntagged && !defaultTab) {
+	      return [];
+	    }
+
+	    if (!hasUntagged) {
+	      return tabbed;
+	    }
+
+	    return [
+	      defaultTab,
+	      ...tabbed.filter(tab => tab.id !== defaultTab.id)
+	    ];
+	  }, [ entries, defaultTab ]);
+
+	  const [ activeTabOverride, setActiveTab ] = d(null);
+
+	  // the override may name a tab that no longer exists, e.g. on the render
+	  // following a `PopupMenu#refresh()` that dropped it
+	  const activeTabId = tabs.some(tab => tab.id === activeTabOverride)
+	    ? activeTabOverride
+	    : (tabs.length ? tabs[0].id : null);
+
+	  const tabsRef = A();
+
+	  _(() => {
+	    const tabsEl = tabsRef.current;
+
+	    if (!tabsEl) {
+	      return;
+	    }
+
+	    const activeTabEl = tabsEl.querySelector('[aria-selected="true"]');
+
+	    if (activeTabEl) {
+	      scrollIntoView(activeTabEl);
+	    }
+	  }, [ activeTabId ]);
+
+	  /**
+	   * Which directions the tab strip can still be scrolled in. Drives the
+	   * scroll controls, so they only show when there is somewhere to scroll.
+	   *
+	   * @type {[ { start: boolean, end: boolean }, (overflow: { start: boolean, end: boolean }) => void ]}
+	   */
+	  const [ overflow, setOverflow ] = d({ start: false, end: false });
+
+	  // only ever called while the strip is rendered, so the ref is set
+	  const updateOverflow = q(() => {
+	    const { scrollLeft, scrollWidth, clientWidth } = tabsRef.current;
+
+	    setOverflow({
+	      start: scrollLeft > 0,
+
+	      // sub-pixel widths leave a fractional remainder at the end
+	      end: scrollWidth - clientWidth - scrollLeft > 1
+	    });
+	  }, []);
+
+	  // horizontal scroll on tabs
+	  const handleWheel = q(event => {
+	    const tabsEl = tabsRef.current;
+
+	    const delta = Math.abs(event.deltaX) > Math.abs(event.deltaY)
+	      ? event.deltaX
+	      : event.deltaY;
+
+	    if (!delta) {
+	      return;
+	    }
+
+	    const { scrollLeft, scrollWidth, clientWidth } = tabsEl;
+
+	    if (scrollWidth - clientWidth < 1) {
+	      return;
+	    }
+
+	    event.preventDefault();
+
+	    tabsEl.scrollLeft = scrollLeft + delta;
+
+	    updateOverflow();
+	  }, [ updateOverflow ]);
+
+	  _(() => {
+	    const tabsEl = tabsRef.current;
+
+	    if (!tabsEl) {
+	      return;
+	    }
+
+	    updateOverflow();
+
+	    tabsEl.addEventListener('scroll', updateOverflow);
+	    tabsEl.addEventListener('wheel', handleWheel, { passive: false });
+
+	    return () => {
+	      tabsEl.removeEventListener('scroll', updateOverflow);
+	      tabsEl.removeEventListener('wheel', handleWheel);
+	    };
+	  }, [ tabs, activeTabId, updateOverflow, handleWheel ]);
+
+	  /**
+	   * Scroll the nearest tab that is cut off in `direction` into view, so a
+	   * click always lands on a fully visible tab.
+	   *
+	   * @param {number} direction
+	   */
+	  const scrollTabs = q(direction => {
+	    const tabsEl = tabsRef.current;
+
+	    const tabEls = direction > 0
+	      ? [ ...tabsEl.children ]
+	      : [ ...tabsEl.children ].reverse();
+
+	    const stripBounds = tabsEl.getBoundingClientRect();
+
+	    const cutOff = tabEls.find(tabEl => {
+	      const bounds = tabEl.getBoundingClientRect();
+
+	      return direction > 0
+	        ? bounds.right > stripBounds.right + 1
+	        : bounds.left < stripBounds.left - 1;
+	    });
+
+	    if (cutOff) {
+	      scrollIntoView(cutOff);
+
+	      // recompute directly: a programmatic scroll does not reliably emit a
+	      // `scroll` event, so the controls would otherwise go stale
+	      updateOverflow();
+	    }
+	  }, [ updateOverflow ]);
+
+	  const getEntryTabId = q(entry => {
+	    return (entry.tab && entry.tab.id) || (defaultTab && defaultTab.id);
+	  }, [ defaultTab ]);
+
 	  const [ searchValue, setSearchValue ] = d('');
 	  const isSearching = searchValue.trim().length > 0;
 
@@ -28231,9 +28407,15 @@
 
 	  const entriesToShow = T(() => {
 
+	    // the tab filter applies at the root level only; drill-down
+	    // (step entries) and search operate on the full entry set
 	    const availableEntries = navigationStack.length
 	      ? navigationStack[navigationStack.length - 1].entries
-	      : entries;
+	      : (
+	        tabs.length > 1
+	          ? entries.filter(entry => getEntryTabId(entry) === activeTabId)
+	          : entries
+	      );
 
 	    if (!searchable) return availableEntries;
 
@@ -28246,7 +28428,7 @@
 	    }
 
 	    return availableEntries.filter(({ rank = 0 }) => rank >= 0);
-	  }, [ searchable, isSearching, actionableEntries, searchValue, searchFn, navigationStack, entries ]);
+	  }, [ searchable, isSearching, actionableEntries, searchValue, searchFn, navigationStack, entries, tabs, activeTabId, getEntryTabId ]);
 
 	  const groupedEntries = T(() => {
 	    if (isSearching) {
@@ -28387,6 +28569,77 @@
 	    }
 	  }, [ selectedEntry, keyboardSelect, keyboardDrilldown, handleEntryAction ]);
 
+	  const selectTab = q((event, tabId) => {
+	    setActiveTab(tabId);
+
+	    // a keyboard activation reports no click detail; keep focus in the strip
+	    // so arrow navigation keeps working. A pointer click hands focus back to
+	    // the search input so typing continues to work
+	    if (!event.detail) {
+	      return;
+	    }
+
+	    const popupEl = closest(event.currentTarget, '.djs-popup', true);
+	    const inputEl = popupEl && popupEl.querySelector('input');
+
+	    inputEl && inputEl.focus();
+	  }, []);
+
+	  // left/right/Home/End navigate between tabs while the strip has focus; stop
+	  // propagation so the global drill-down and entry-action bindings do not fire.
+	  // Up/down leave the strip instead
+	  const handleTabKeyDown = q(event => {
+	    if (event.key === 'Enter' || event.key === ' ') {
+
+	      // let the button's native click happen, but keep the event
+	      // from reaching the global Enter handler (entry action)
+	      event.stopPropagation();
+
+	      return;
+	    }
+
+	    // <ArrowDown> / <ArrowUp> hand focus to the panel so the menu's own
+	    // bindings take over — notably <ArrowRight> to step into an entry, which
+	    // would otherwise keep switching tabs. The event still bubbles, so the
+	    // selection moves on the same keystroke
+	    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+	      const popupEl = closest(event.currentTarget, '.djs-popup', true);
+
+	      const focusEl = popupEl.querySelector('input')
+	        || popupEl.querySelector('[role="listbox"]');
+
+	      focusEl && focusEl.focus();
+
+	      return;
+	    }
+
+	    const idx = tabs.findIndex(tab => tab.id === activeTabId);
+
+	    let nextIdx;
+
+	    if (event.key === 'ArrowLeft') {
+	      nextIdx = (idx - 1 + tabs.length) % tabs.length;
+	    } else if (event.key === 'ArrowRight') {
+	      nextIdx = (idx + 1) % tabs.length;
+	    } else if (event.key === 'Home') {
+	      nextIdx = 0;
+	    } else if (event.key === 'End') {
+	      nextIdx = tabs.length - 1;
+	    } else {
+	      return;
+	    }
+
+	    event.preventDefault();
+	    event.stopPropagation();
+
+	    setActiveTab(tabs[nextIdx].id);
+
+	    const strip = event.currentTarget.parentNode;
+	    const nextButton = strip && strip.children[nextIdx];
+
+	    nextButton && nextButton.focus();
+	  }, [ tabs, activeTabId ]);
+
 	  const handleKey = q(event => {
 	    if (matches(event.target, 'input')) {
 	      setSearchValue(() => event.target.value);
@@ -28402,6 +28655,7 @@
 	  }, []);
 
 	  const displayBreadcrumbs = !isSearching && navigationStack.length > 0;
+	  const displayTabs = tabs.length > 1 && !isSearching && navigationStack.length === 0;
 	  const displayHeader = (title || headerEntries.length > 0) && !displayBreadcrumbs;
 
 	  return m$1`
@@ -28451,6 +28705,43 @@
           </div>
           ` }
 
+          ${ displayTabs && m$1`
+            <div class="djs-popup-tabs-container">
+              <div class="djs-popup-tabs" ref=${ tabsRef } role="tablist">
+                ${ tabs.map(tab => m$1`
+                  <button
+                    type="button"
+                    class="djs-popup-tab"
+                    role="tab"
+                    title=${ tab.title || undefined }
+                    aria-controls=${ resultsId }
+                    aria-selected=${ tab.id === activeTabId }
+                    tabIndex=${ tab.id === activeTabId ? 0 : -1 }
+                    onClick=${ (event) => selectTab(event, tab.id) }
+                    onKeydown=${ handleTabKeyDown }
+                  >${ tab.label }</button>
+                `) }
+              </div>
+
+              ${ /* outside the tablist: its children must be tabs. Keyboard
+                     users navigate with the arrow keys instead */ '' }
+              ${ [ -1, 1 ].map(direction => (direction < 0 ? overflow.start : overflow.end) && m$1`
+                <button
+                  type="button"
+                  class=${ `djs-popup-tabs-scroll djs-popup-tabs-scroll-${ direction < 0 ? 'start' : 'end' }` }
+                  aria-hidden="true"
+                  tabIndex="-1"
+                  onMousedown=${ (event) => event.preventDefault() }
+                  onClick=${ () => scrollTabs(direction) }
+                >
+                  <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+                    <path fill-rule="evenodd" clip-rule="evenodd" d="M3.96967 1.46967C4.26256 1.17678 4.73744 1.17678 5.03033 1.46967L9.03033 5.46967C9.32322 5.76256 9.32322 6.23744 9.03033 6.53033L5.03033 10.5303C4.73744 10.8232 4.26256 10.8232 3.96967 10.5303C3.67678 10.2374 3.67678 9.76256 3.96967 9.46967L7.43934 6L3.96967 2.53033C3.67678 2.23744 3.67678 1.76256 3.96967 1.46967Z" fill="currentColor"/>
+                  </svg>
+                </button>
+              `) }
+            </div>
+          ` }
+
           ${ isSearching && m$1`
             <div class="djs-popup-search-count" aria-live="polite">
               ${ entriesToShow.length } ${ entriesToShow.length === 1 ? 'result' : 'results' } found
@@ -28497,6 +28788,18 @@
   `;
 	}
 
+	function scrollIntoView(el) {
+	  if (typeof el.scrollIntoViewIfNeeded === 'function') {
+	    el.scrollIntoViewIfNeeded();
+	  } else {
+	    el.scrollIntoView({
+	      scrollMode: 'if-needed',
+	      block: 'nearest',
+	      inline: 'nearest'
+	    });
+	  }
+	}
+
 	/**
 	 * A component that wraps the popup menu.
 	 *
@@ -28693,11 +28996,14 @@
 	 *
 	 * @typedef {import('../../model/Types.js').Element} Element
 	 *
+	 * @typedef {import('./PopupMenuProvider.js').PopupMenuTab} PopupMenuTab
+	 *
 	 * @typedef { {
 	 *   scale?: {
 	 *     min?: number;
 	 *     max?: number;
 	 *   } | boolean;
+	 *   defaultTab?: PopupMenuTab;
 	 * } } PopupMenuConfig
 	 *
 	 * @typedef {Element|Element[]} PopupMenuTarget;
@@ -28734,7 +29040,8 @@
 	  };
 
 	  this._config = {
-	    scale: scale
+	    scale: scale,
+	    defaultTab: config && config.defaultTab
 	  };
 
 
@@ -28800,6 +29107,7 @@
         onOpened=${ this._onOpened.bind(this) }
         onClosed=${ this._onClosed.bind(this) }
         searchFn=${ this._search }
+        defaultTab=${ this._config.defaultTab }
         ...${{ ...options }}
       />
     `,
@@ -29804,7 +30112,7 @@
 	 * @typedef {import('diagram-js/lib/features/context-pad/ContextPadProvider').default<Element>} ContextPadProvider
 	 */
 
-	var LOW_PRIORITY$m = 900;
+	var LOW_PRIORITY$o = 900;
 
 	/**
 	 * A provider for the `Align elements` context pad entry.
@@ -29818,7 +30126,7 @@
 	 */
 	function AlignElementsContextPadProvider(contextPad, popupMenu, translate, canvas) {
 
-	  contextPad.registerProvider(LOW_PRIORITY$m, this);
+	  contextPad.registerProvider(LOW_PRIORITY$o, this);
 
 	  this._contextPad = contextPad;
 	  this._popupMenu = popupMenu;
@@ -30448,7 +30756,7 @@
 	 * @typedef {import('../modeling/Modeling.js').default} Modeling
 	 */
 
-	var LOW_PRIORITY$l = 100;
+	var LOW_PRIORITY$n = 100;
 
 
 	/**
@@ -30461,7 +30769,7 @@
 	 */
 	function AutoPlace$1(eventBus, modeling, canvas) {
 
-	  eventBus.on('autoPlace', LOW_PRIORITY$l, function(context) {
+	  eventBus.on('autoPlace', LOW_PRIORITY$n, function(context) {
 	    var shape = context.shape,
 	        source = context.source;
 
@@ -31324,7 +31632,7 @@
 	 * @typedef {import('../../core/EventBus.js').default} EventBus
 	 */
 
-	var HIGH_PRIORITY$l = 1500;
+	var HIGH_PRIORITY$m = 1500;
 
 
 	/**
@@ -31392,7 +31700,7 @@
 	     */
 	    eventBus.on('drag.start', function(event) {
 
-	      eventBus.once('drag.move', HIGH_PRIORITY$l, function(event) {
+	      eventBus.once('drag.move', HIGH_PRIORITY$m, function(event) {
 
 	        ensureHover(event);
 
@@ -31423,7 +31731,7 @@
 	      hover = event.element;
 	    });
 
-	    eventBus.on('element.hover', HIGH_PRIORITY$l, function(event) {
+	    eventBus.on('element.hover', HIGH_PRIORITY$m, function(event) {
 
 	      // (3) am I on an element still?
 	      if (hover) {
@@ -33402,7 +33710,7 @@
 	    MARKER_CONNECT_UPDATING$1 = 'djs-updating',
 	    MARKER_DRAGGER = 'djs-dragging';
 
-	var HIGH_PRIORITY$k = 1100;
+	var HIGH_PRIORITY$l = 1100;
 
 	/**
 	 * Preview connection while moving bendpoints.
@@ -33470,7 +33778,7 @@
 	  eventBus.on([
 	    'bendpoint.move.out',
 	    'bendpoint.move.cleanup'
-	  ], HIGH_PRIORITY$k, function(event) {
+	  ], HIGH_PRIORITY$l, function(event) {
 	    var context = event.context,
 	        hover = context.hover,
 	        target = context.target;
@@ -33556,7 +33864,7 @@
 	  eventBus.on([
 	    'bendpoint.move.end',
 	    'bendpoint.move.cancel'
-	  ], HIGH_PRIORITY$k, function(event) {
+	  ], HIGH_PRIORITY$l, function(event) {
 	    var context = event.context,
 	        connection = context.connection,
 	        draggerGfx = context.draggerGfx,
@@ -34572,8 +34880,8 @@
 	 * @typedef {import('../../core/EventBus.js').default} EventBus
 	 */
 
-	var HIGH_PRIORITY$j = 1100,
-	    LOW_PRIORITY$k = 900;
+	var HIGH_PRIORITY$k = 1100,
+	    LOW_PRIORITY$m = 900;
 
 	var MARKER_OK$3 = 'connect-ok',
 	    MARKER_NOT_OK$3 = 'connect-not-ok';
@@ -34617,7 +34925,7 @@
 	    });
 	  });
 
-	  eventBus.on('connect.hover', LOW_PRIORITY$k, function(event) {
+	  eventBus.on('connect.hover', LOW_PRIORITY$m, function(event) {
 	    var context = event.context,
 	        hover = event.hover,
 	        canExecute = context.canExecute;
@@ -34633,7 +34941,7 @@
 	  eventBus.on([
 	    'connect.out',
 	    'connect.cleanup'
-	  ], HIGH_PRIORITY$j, function(event) {
+	  ], HIGH_PRIORITY$k, function(event) {
 	    var hover = event.hover;
 
 	    if (hover) {
@@ -35685,7 +35993,7 @@
 	 * @typedef {import('../../../model/Types').Element} Element
 	 */
 
-	var HIGH_PRIORITY$i = 1500;
+	var HIGH_PRIORITY$j = 1500;
 
 	/**
 	 * A behavior that ensures that visually enclosed artifacts are affected
@@ -35706,7 +36014,7 @@
 	  injector.invoke(CommandInterceptor, this);
 
 	  // enclosed artifacts are deleted with a container element
-	  this.preExecute('elements.delete', HIGH_PRIORITY$i, function(event) {
+	  this.preExecute('elements.delete', HIGH_PRIORITY$j, function(event) {
 	    var context = event.context,
 	        elements = context.elements;
 
@@ -35819,7 +36127,7 @@
 	 * @typedef {import('didi').Injector} Injector
 	 */
 
-	var LOW_PRIORITY$j = 500;
+	var LOW_PRIORITY$l = 500;
 
 
 	/**
@@ -35835,7 +36143,7 @@
 
 	  var self = this;
 
-	  this.postExecuted('elements.create', LOW_PRIORITY$j, function(context) {
+	  this.postExecuted('elements.create', LOW_PRIORITY$l, function(context) {
 	    var elements = context.elements;
 
 	    elements = elements.filter(function(shape) {
@@ -35858,7 +36166,7 @@
 	  }, true);
 
 
-	  this.preExecute('elements.move', LOW_PRIORITY$j, function(context) {
+	  this.preExecute('elements.move', LOW_PRIORITY$l, function(context) {
 	    var shapes = context.shapes,
 	        host = context.newHost;
 
@@ -35976,6 +36284,255 @@
 
 	e$3(BoundaryEventBehavior, CommandInterceptor);
 
+	/**
+	 * @typedef {import('../../BpmnFactory').default} BpmnFactory
+	 *
+	 * @typedef {import('../../../../model/Types').ModdleElement} ModdleElement
+	 */
+
+	/**
+	 * Creates a new bpmn:CategoryValue inside a new bpmn:Category
+	 *
+	 * @param {BpmnFactory} bpmnFactory
+	 *
+	 * @return {ModdleElement}
+	 */
+	function createCategory(bpmnFactory) {
+	  return bpmnFactory.create('bpmn:Category');
+	}
+
+	/**
+	 * Creates a new bpmn:CategoryValue inside a new bpmn:Category
+	 *
+	 * @param {BpmnFactory} bpmnFactory
+	 *
+	 * @return {ModdleElement}
+	 */
+	function createCategoryValue(bpmnFactory) {
+	  return bpmnFactory.create('bpmn:CategoryValue');
+	}
+
+	/**
+	 * Returns a group's category value, creating one (including a
+	 * category) if needed.
+	 *
+	 * @param {BpmnFactory} bpmnFactory
+	 * @param {ModdleElement} groupBo
+	 *
+	 * @return {ModdleElement}
+	 */
+	function getOrCreateCategoryValueForGroup(bpmnFactory, groupBo) {
+	  var categoryValue = groupBo.get('categoryValueRef');
+
+	  if (!categoryValue) {
+	    categoryValue = groupBo.categoryValueRef = createCategoryValue(bpmnFactory);
+	  }
+
+	  if (!categoryValue.$parent) {
+	    categoryValue.$parent = createCategory(bpmnFactory);
+	  }
+
+	  return categoryValue;
+	}
+
+	/**
+	 * Adds category value to definitions
+	 *
+	 * @param {ModdleElement} categoryValue
+	 * @param {ModdleElement} category
+	 * @param {ModdleElement} definitions
+	 *
+	 * @return {ModdleElement}
+	 */
+	function linkCategoryValue(categoryValue, category, definitions) {
+	  add(category.get('categoryValue'), categoryValue);
+	  categoryValue.$parent = category;
+
+	  add(definitions.get('rootElements'), category);
+	  category.$parent = definitions;
+
+	  return categoryValue;
+	}
+
+	/**
+	 * Unlink category value from parent
+	 *
+	 * @param {ModdleElement} categoryValue
+	 *
+	 * @return {ModdleElement}
+	 */
+	function unlinkCategoryValue(categoryValue) {
+	  var category = categoryValue.$parent;
+
+	  if (category) {
+	    remove(category.get('categoryValue'), categoryValue);
+	    categoryValue.$parent = null;
+	  }
+
+	  return categoryValue;
+	}
+
+	/**
+	 * Unlink category from parent
+	 *
+	 * @param {ModdleElement} category
+	 *
+	 * @return {ModdleElement}
+	 */
+	function unlinkCategory(category) {
+	  var definitions = category.$parent;
+
+	  if (definitions) {
+	    remove(definitions.get('rootElements'), category);
+	    category.$parent = null;
+	  }
+
+	  return category;
+	}
+
+	var LOW_PRIORITY$k = 500;
+
+	/**
+	 * @typedef {import('../../../Modeler').default} Modeler
+	 * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+	 * @typedef {import('didi').Injector} Injector
+	 */
+
+	/**
+	 * Maintains a group's category (value) inside definitions#rootElements.
+	 *
+	 * @param {Modeler} bpmnjs
+	 * @param {ElementRegistry} elementRegistry
+	 * @param {Injector} injector
+	 */
+	function CategoryRootElementReferenceBehavior(
+	    bpmnjs, elementRegistry, injector
+	) {
+	  injector.invoke(CommandInterceptor, this);
+
+	  function getGroupBusinessObjects(ignoredBusinessObject) {
+	    return elementRegistry.filter(function(element) {
+	      return is(element, 'bpmn:Group') && !element.labelTarget;
+	    }).map(getBusinessObject).filter(function(businessObject) {
+	      return businessObject !== ignoredBusinessObject;
+	    });
+	  }
+
+	  function isCategoryValueReferenced(categoryValue, ignoredBusinessObject) {
+	    return getGroupBusinessObjects(ignoredBusinessObject).some(function(businessObject) {
+	      return businessObject.get('categoryValueRef') === categoryValue;
+	    });
+	  }
+
+	  function isCategoryReferenced(category, ignoredBusinessObject) {
+	    return getGroupBusinessObjects(ignoredBusinessObject).some(function(businessObject) {
+	      var categoryValue = businessObject.get('categoryValueRef');
+
+	      return categoryValue && categoryValue.$parent === category;
+	    });
+	  }
+
+	  function link(categoryValue, category) {
+	    if (categoryValue && category) {
+	      linkCategoryValue(categoryValue, category, bpmnjs.getDefinitions());
+	    }
+	  }
+
+	  function unlink(categoryValue, category, ignoredBusinessObject) {
+	    if (category && !isCategoryReferenced(category, ignoredBusinessObject)) {
+	      unlinkCategory(category);
+	    }
+
+	    if (categoryValue && !isCategoryValueReferenced(categoryValue, ignoredBusinessObject)) {
+	      unlinkCategoryValue(categoryValue);
+	    }
+	  }
+
+
+	  this.executed([ 'shape.create', 'label.create' ], function(context) {
+	    var shape = context.labelTarget || context.shape;
+
+	    if (!is(shape, 'bpmn:Group') || shape.labelTarget) {
+	      return;
+	    }
+
+	    link(context.categoryValue, context.category);
+	  }, true);
+
+	  this.reverted([ 'shape.create', 'label.create' ], function(context) {
+	    var shape = context.labelTarget || context.shape;
+
+	    if (!is(shape, 'bpmn:Group') || shape.labelTarget) {
+	      return;
+	    }
+
+	    unlink(context.categoryValue, context.category, getBusinessObject(shape));
+	  }, true);
+
+	  this.executed([ 'shape.move', 'shape.resize' ], LOW_PRIORITY$k, function(context) {
+	    link(context.categoryValue, context.category);
+	  }, true);
+
+	  this.reverted([ 'shape.move', 'shape.resize' ], function(context) {
+	    var shape = context.shape;
+
+	    if (context.categoryValue) {
+	      unlink(context.categoryValue, context.category, getBusinessObject(shape));
+	    }
+	  }, true);
+
+	  this.executed('group.updateRefs', function(context) {
+	    getGroupUpdates(context).forEach(function(update) {
+	      link(update.categoryValue, update.category);
+	    });
+	  }, true);
+
+	  this.reverted('group.updateRefs', function(context) {
+	    getGroupUpdates(context).forEach(function(update) {
+	      unlink(
+	        update.categoryValue,
+	        update.category,
+	        getBusinessObject(update.groupShape)
+	      );
+	    });
+	  }, true);
+
+	  this.executed('shape.delete', function(context) {
+	    var shape = context.shape;
+
+	    if (!is(shape, 'bpmn:Group') || shape.labelTarget) {
+	      return;
+	    }
+
+	    unlink(context.categoryValue, context.category, getBusinessObject(shape));
+	  }, true);
+
+	  this.reverted('shape.delete', function(context) {
+	    var shape = context.shape;
+
+	    if (!is(shape, 'bpmn:Group') || shape.labelTarget) {
+	      return;
+	    }
+
+	    link(context.categoryValue, context.category);
+	  }, true);
+	}
+
+	CategoryRootElementReferenceBehavior.$inject = [
+	  'bpmnjs',
+	  'elementRegistry',
+	  'injector'
+	];
+
+	e$3(CategoryRootElementReferenceBehavior, CommandInterceptor);
+
+
+	// helpers //////////
+
+	function getGroupUpdates(context) {
+	  return context.updates?.groups || [];
+	}
+
 	/**
 	 * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
 	 * @typedef {import('../lib/features/modeling/Modeling').default} Modeling
@@ -36272,7 +36829,7 @@
 
 	var PARTICIPANT_BORDER_WIDTH = 30;
 
-	var HIGH_PRIORITY$h = 2000;
+	var HIGH_PRIORITY$i = 2000;
 
 
 	/**
@@ -36289,7 +36846,7 @@
 	  eventBus.on([
 	    'create.start',
 	    'shape.move.start'
-	  ], HIGH_PRIORITY$h, function(event) {
+	  ], HIGH_PRIORITY$i, function(event) {
 	    var context = event.context,
 	        shape = context.shape,
 	        rootElement = canvas.getRootElement();
@@ -36324,7 +36881,7 @@
 	  });
 
 	  // force hovering process when creating first participant
-	  eventBus.on('create.start', HIGH_PRIORITY$h, function(event) {
+	  eventBus.on('create.start', HIGH_PRIORITY$i, function(event) {
 	    var context = event.context,
 	        shape = context.shape,
 	        rootElement = canvas.getRootElement(),
@@ -36336,7 +36893,7 @@
 	    }
 
 	    if (is(shape, 'bpmn:Participant') && is(rootElement, 'bpmn:Process')) {
-	      eventBus.on('element.hover', HIGH_PRIORITY$h, ensureHoveringProcess);
+	      eventBus.on('element.hover', HIGH_PRIORITY$i, ensureHoveringProcess);
 
 	      eventBus.once('create.cleanup', function() {
 	        eventBus.off('element.hover', ensureHoveringProcess);
@@ -36357,7 +36914,7 @@
 
 	  // when creating mutliple elements through `elements.create` parent must be set to collaboration
 	  // and passed to `shape.create` as hint
-	  this.preExecute('elements.create', HIGH_PRIORITY$h, function(context) {
+	  this.preExecute('elements.create', HIGH_PRIORITY$i, function(context) {
 	    var elements = context.elements,
 	        parent = context.parent,
 	        participant = findParticipant(elements),
@@ -37293,7 +37850,7 @@
 	 * @typedef {import('../../space-tool/BpmnSpaceTool').default} SpaceTool
 	 */
 
-	var LOW_PRIORITY$i = 500;
+	var LOW_PRIORITY$j = 500;
 
 
 	/**
@@ -37406,7 +37963,7 @@
 	  /**
 	   * Adjust sizes of other lanes after lane deletion
 	   */
-	  this.postExecuted('shape.delete', LOW_PRIORITY$i, function(event) {
+	  this.postExecuted('shape.delete', LOW_PRIORITY$j, function(event) {
 
 	    var context = event.context,
 	        hints = context.hints,
@@ -37439,7 +37996,7 @@
 	 * @typedef {import('didi').Injector} Injector
 	 */
 
-	var LOW_PRIORITY$h = 500;
+	var LOW_PRIORITY$i = 500;
 
 
 	/**
@@ -37455,7 +38012,7 @@
 
 	  var self = this;
 
-	  this.postExecuted('elements.create', LOW_PRIORITY$h, function(context) {
+	  this.postExecuted('elements.create', LOW_PRIORITY$i, function(context) {
 	    var elements = context.elements;
 
 	    elements.filter(function(shape) {
@@ -37469,7 +38026,7 @@
 	    });
 	  }, true);
 
-	  this.preExecute('elements.move', LOW_PRIORITY$h, function(context) {
+	  this.preExecute('elements.move', LOW_PRIORITY$i, function(context) {
 	    var shapes = context.shapes,
 	        newHost = context.newHost;
 
@@ -37842,7 +38399,7 @@
 	 * @typedef {import('diagram-js/lib/core/Canvas').default} Canvas
 	 */
 
-	var HIGH_PRIORITY$g = 1500;
+	var HIGH_PRIORITY$h = 1500;
 	var HIGHEST_PRIORITY = 2000;
 
 
@@ -37864,7 +38421,7 @@
 	    'shape.move.move',
 	    'shape.move.out',
 	    'shape.move.end'
-	  ], HIGH_PRIORITY$g, function(event) {
+	  ], HIGH_PRIORITY$h, function(event) {
 	    var context = event.context,
 	        shape = context.shape || event.shape,
 	        hover = event.hover;
@@ -37896,7 +38453,7 @@
 	    'global-connect.out',
 	    'global-connect.end',
 	    'global-connect.cleanup'
-	  ], HIGH_PRIORITY$g, function(event) {
+	  ], HIGH_PRIORITY$h, function(event) {
 	    var hover = event.hover;
 
 	    // ensure connections start/end on bpmn:Participant,
@@ -37910,7 +38467,7 @@
 
 	  eventBus.on([
 	    'bendpoint.move.hover'
-	  ], HIGH_PRIORITY$g, function(event) {
+	  ], HIGH_PRIORITY$h, function(event) {
 	    var context = event.context,
 	        hover = event.hover,
 	        type = context.type;
@@ -37926,7 +38483,7 @@
 
 	  eventBus.on([
 	    'connect.start'
-	  ], HIGH_PRIORITY$g, function(event) {
+	  ], HIGH_PRIORITY$h, function(event) {
 	    var context = event.context,
 	        start = context.start;
 
@@ -37965,101 +38522,12 @@
 	  'canvas'
 	];
 
-	/**
-	 * @typedef {import('../../BpmnFactory').default} BpmnFactory
-	 *
-	 * @typedef {import('../../../model/Types').ModdleElement} ModdleElement
-	 */
-
-	/**
-	 * Creates a new bpmn:CategoryValue inside a new bpmn:Category
-	 *
-	 * @param {BpmnFactory} bpmnFactory
-	 *
-	 * @return {ModdleElement}
-	 */
-	function createCategory(bpmnFactory) {
-	  return bpmnFactory.create('bpmn:Category');
-	}
-
-	/**
-	 * Creates a new bpmn:CategoryValue inside a new bpmn:Category
-	 *
-	 * @param {BpmnFactory} bpmnFactory
-	 *
-	 * @return {ModdleElement}
-	 */
-	function createCategoryValue(bpmnFactory) {
-	  return bpmnFactory.create('bpmn:CategoryValue');
-	}
-
-	/**
-	 * Adds category value to definitions
-	 *
-	 * @param {ModdleElement} categoryValue
-	 * @param {ModdleElement} category
-	 * @param {ModdleElement} definitions
-	 *
-	 * @return {ModdleElement}
-	 */
-	function linkCategoryValue(categoryValue, category, definitions) {
-	  add(category.get('categoryValue'), categoryValue);
-	  categoryValue.$parent = category;
-
-	  add(definitions.get('rootElements'), category);
-	  category.$parent = definitions;
-
-	  return categoryValue;
-	}
-
-	/**
-	 * Unlink category value from parent
-	 *
-	 * @param {ModdleElement} categoryValue
-	 *
-	 * @return {ModdleElement}
-	 */
-	function unlinkCategoryValue(categoryValue) {
-	  var category = categoryValue.$parent;
-
-	  if (category) {
-	    remove(category.get('categoryValue'), categoryValue);
-	    categoryValue.$parent = null;
-	  }
-
-	  return categoryValue;
-	}
-
-	/**
-	 * Unlink category from parent
-	 *
-	 * @param {ModdleElement} category
-	 *
-	 * @return {ModdleElement}
-	 */
-	function unlinkCategory(category) {
-	  var definitions = category.$parent;
-
-	  if (definitions) {
-	    remove(definitions.get('rootElements'), category);
-	    category.$parent = null;
-	  }
-
-	  return category;
-	}
-
 	/**
 	 * @typedef {import('../BpmnFactory').default} BpmnFactory
-	 * @typedef {import('../../../Modeler').default} Modeler
-	 * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
 	 * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+	 * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
 	 * @typedef {import('didi').Injector} Injector
 	 * @typedef {import('../../copy-paste/ModdleCopy').default} ModdleCopy
-	 *
-	 * @typedef {import('../../../model/Types').Element} Element
-	 * @typedef {import('../../../model/Types').Shape} Shape
-	 *
-	 * @typedef {import('diagram-js/lib/util/Types').DirectionTRBL} DirectionTRBL
 	 */
 
 	var LOWER_PRIORITY$1 = 770;
@@ -38069,137 +38537,45 @@
 	 * BPMN specific group behavior.
 	 *
 	 * @param {BpmnFactory} bpmnFactory
-	 * @param {Modeler} bpmnjs
-	 * @param {ElementRegistry} elementRegistry
 	 * @param {EventBus} eventBus
 	 * @param {Injector} injector
 	 * @param {ModdleCopy} moddleCopy
 	 */
 	function GroupBehavior(
 	    bpmnFactory,
-	    bpmnjs,
-	    elementRegistry,
 	    eventBus,
 	    injector,
 	    moddleCopy
 	) {
 	  injector.invoke(CommandInterceptor, this);
 
-	  /**
-	   * Returns all group element in the current registry.
-	   *
-	   * @return {Shape[]}
-	   */
-	  function getGroupElements() {
-	    return elementRegistry.filter(function(e) {
-	      return is(e, 'bpmn:Group');
-	    });
-	  }
-
-	  /**
-	   * Returns true if given category is referenced in one of the given elements.
-	   *
-	   * @param {Element[]} elements
-	   * @param {ModdleElement} category
-	   *
-	   * @return {boolean}
-	   */
-	  function isReferencedCategory(elements, category) {
-	    return elements.some(function(element) {
-	      var businessObject = getBusinessObject(element);
-
-	      var _category = businessObject.categoryValueRef && businessObject.categoryValueRef.$parent;
-
-	      return _category === category;
-	    });
-	  }
-
-	  /**
-	   * Returns true if given categoryValue is referenced in one of the given elements.
-	   *
-	   * @param {Element[]} elements
-	   * @param {ModdleElement} categoryValue
-	   *
-	   * @return {boolean}
-	   */
-	  function isReferencedCategoryValue(elements, categoryValue) {
-	    return elements.some(function(element) {
-	      var businessObject = getBusinessObject(element);
-
-	      return businessObject.categoryValueRef === categoryValue;
-	    });
-	  }
-
-	  /**
-	   * Remove category value unless it is still referenced.
-	   *
-	   * @param {ModdleElement} categoryValue
-	   * @param {ModdleElement} category
-	   * @param {ModdleElement} businessObject
-	   */
-	  function removeCategoryValue(categoryValue, category, businessObject) {
-
-	    var groups = getGroupElements().filter(function(element) {
-	      return element.businessObject !== businessObject;
-	    });
-
-	    if (category && !isReferencedCategory(groups, category)) {
-	      unlinkCategory(category);
-	    }
-
-	    if (categoryValue && !isReferencedCategoryValue(groups, categoryValue)) {
-	      unlinkCategoryValue(categoryValue);
-	    }
-	  }
-
-	  /**
-	   * Add category value.
-	   *
-	   * @param {ModdleElement} categoryValue
-	   * @param {ModdleElement} category
-	   *
-	   * @return {ModdleElement}
-	   */
-	  function addCategoryValue(categoryValue, category) {
-	    return linkCategoryValue(categoryValue, category, bpmnjs.getDefinitions());
-	  }
-
 	  function setCategoryValue(element, context) {
 	    var businessObject = getBusinessObject(element),
-	        categoryValue = businessObject.categoryValueRef;
+	        categoryValue = context.categoryValue || businessObject.categoryValueRef;
 
 	    if (!categoryValue) {
-	      categoryValue =
-	      businessObject.categoryValueRef =
-	      context.categoryValue = (
-	        context.categoryValue || createCategoryValue(bpmnFactory)
-	      );
+	      categoryValue = getOrCreateCategoryValueForGroup(bpmnFactory, businessObject);
 	    }
 
-	    var category = categoryValue.$parent;
+	    var category = context.category || categoryValue.$parent || createCategory(bpmnFactory);
 
-	    if (!category) {
-	      category =
-	      categoryValue.$parent =
-	      context.category = (
-	        context.category || createCategory(bpmnFactory)
-	      );
-	    }
+	    businessObject.categoryValueRef = categoryValue;
+	    categoryValue.$parent = category;
 
-	    addCategoryValue(categoryValue, category, bpmnjs.getDefinitions());
+	    context.categoryValue = categoryValue;
+	    context.category = category;
 	  }
 
 	  function unsetCategoryValue(element, context) {
-	    var category = context.category,
-	        categoryValue = context.categoryValue,
-	        businessObject = getBusinessObject(element);
+	    var businessObject = getBusinessObject(element),
+	        categoryValue = context.categoryValue || businessObject.categoryValueRef,
+	        category = context.category || (categoryValue && categoryValue.$parent);
 
 	    if (categoryValue) {
-	      businessObject.categoryValueRef = null;
+	      context.categoryValue = categoryValue;
+	      context.category = category;
 
-	      removeCategoryValue(categoryValue, category, businessObject);
-	    } else {
-	      removeCategoryValue(null, businessObject.categoryValueRef.$parent, businessObject);
+	      businessObject.categoryValueRef = null;
 	    }
 	  }
 
@@ -38241,14 +38617,10 @@
 	      return;
 	    }
 
-	    var categoryValue = context.categoryValue = businessObject.categoryValueRef,
-	        category;
+	    var categoryValue = context.categoryValue = businessObject.categoryValueRef;
 
 	    if (categoryValue) {
-	      category = context.category = categoryValue.$parent;
-
-	      removeCategoryValue(categoryValue, category, businessObject);
-
+	      context.category = categoryValue.$parent;
 	      businessObject.categoryValueRef = null;
 	    }
 	  });
@@ -38268,39 +38640,77 @@
 
 	    if (categoryValue) {
 	      businessObject.categoryValueRef = categoryValue;
-
-	      addCategoryValue(categoryValue, category);
+	      categoryValue.$parent = category;
 	    }
 	  });
 
 
-	  // create new category + value when group was created
+	  // create new category + value when group was created so that visually
+	  // enclosed elements can be categorized against it, even if it is unlabeled
 
 	  this.execute('shape.create', function(event) {
 	    var context = event.context,
-	        shape = context.shape;
+	        shape = context.shape,
+	        hints = context.hints || {};
 
 	    if (!is(shape, 'bpmn:Group') || shape.labelTarget) {
 	      return;
 	    }
 
-	    if (getBusinessObject(shape).categoryValueRef) {
-	      setCategoryValue(shape, context);
+	    // during paste the category value (if any) is carried over from the
+	    // source; only fabricate one for genuinely new groups
+	    if (hints.createElementsBehavior === false &&
+	        !getBusinessObject(shape).categoryValueRef &&
+	        !context.categoryValue) {
+	      return;
 	    }
+
+	    setCategoryValue(shape, context);
 	  });
 
 	  this.reverted('shape.create', function(event) {
 
 	    var context = event.context,
-	        shape = context.shape;
+	        shape = context.shape,
+	        hints = context.hints || {};
 
 	    if (!is(shape, 'bpmn:Group') || shape.labelTarget) {
 	      return;
 	    }
 
-	    if (getBusinessObject(shape).categoryValueRef) {
-	      unsetCategoryValue(shape, context);
+	    if (hints.createElementsBehavior === false &&
+	        !getBusinessObject(shape).categoryValueRef &&
+	        !context.categoryValue) {
+	      return;
+	    }
+
+	    unsetCategoryValue(shape, context);
+	  });
+
+
+	  // add category -> categoryValue for groups when they change
+
+	  this.executed([ 'shape.move', 'shape.resize' ], function(event) {
+	    var context = event.context,
+	        shape = context.shape;
+
+	    if (!is(shape, 'bpmn:Group') || shape.labelTarget ||
+	        getBusinessObject(shape).categoryValueRef) {
+	      return;
 	    }
+
+	    setCategoryValue(shape, context);
+	  });
+
+	  this.reverted([ 'shape.move', 'shape.resize' ], function(event) {
+	    var context = event.context,
+	        shape = context.shape;
+
+	    if (!is(shape, 'bpmn:Group') || shape.labelTarget || !context.categoryValue) {
+	      return;
+	    }
+
+	    unsetCategoryValue(shape, context);
 	  });
 
 
@@ -38356,8 +38766,6 @@
 
 	GroupBehavior.$inject = [
 	  'bpmnFactory',
-	  'bpmnjs',
-	  'elementRegistry',
 	  'eventBus',
 	  'injector',
 	  'moddleCopy'
@@ -40412,7 +40820,7 @@
 	  'selection'
 	];
 
-	var HIGH_PRIORITY$f = 1500;
+	var HIGH_PRIORITY$g = 1500;
 
 	/**
 	 * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
@@ -40465,7 +40873,7 @@
 	 * @param {EventBus} eventBus
 	 */
 	function ResizeBehavior$1(eventBus) {
-	  eventBus.on('resize.start', HIGH_PRIORITY$f, function(event) {
+	  eventBus.on('resize.start', HIGH_PRIORITY$g, function(event) {
 	    var context = event.context,
 	        shape = context.shape,
 	        direction = context.direction,
@@ -40737,7 +41145,7 @@
 	 * @typedef {import('diagram-js/lib/util/Types').DirectionTRBL} DirectionTRBL
 	 */
 
-	var LOW_PRIORITY$g = 500;
+	var LOW_PRIORITY$h = 500;
 
 
 	/**
@@ -40867,7 +41275,7 @@
 	    }
 	  });
 
-	  eventBus.on('copyPaste.pasteElement', LOW_PRIORITY$g, function(context) {
+	  eventBus.on('copyPaste.pasteElement', LOW_PRIORITY$h, function(context) {
 	    var descriptor = context.descriptor,
 	        businessObject = descriptor.businessObject,
 	        referencedRootElement = descriptor.referencedRootElement;
@@ -41112,8 +41520,8 @@
 	 * @typedef {import('../../../model/Types').ModdleElement} ModdleElement
 	 */
 
-	var LOW_PRIORITY$f = 400;
-	var HIGH_PRIORITY$e = 600;
+	var LOW_PRIORITY$g = 400;
+	var HIGH_PRIORITY$f = 600;
 
 	var DEFAULT_POSITION = {
 	  x: 180,
@@ -41387,7 +41795,7 @@
 
 
 	  // create/remove plane for the subprocess
-	  this.executed('shape.toggleCollapse', LOW_PRIORITY$f, function(context) {
+	  this.executed('shape.toggleCollapse', LOW_PRIORITY$g, function(context) {
 	    var shape = context.shape;
 
 	    if (!is(shape, 'bpmn:SubProcess')) {
@@ -41405,7 +41813,7 @@
 
 
 	  // create/remove plane for the subprocess
-	  this.reverted('shape.toggleCollapse', LOW_PRIORITY$f, function(context) {
+	  this.reverted('shape.toggleCollapse', LOW_PRIORITY$g, function(context) {
 	    var shape = context.shape;
 
 	    if (!is(shape, 'bpmn:SubProcess')) {
@@ -41422,7 +41830,7 @@
 	  }, true);
 
 	  // move elements between planes
-	  this.postExecuted('shape.toggleCollapse', HIGH_PRIORITY$e, function(context) {
+	  this.postExecuted('shape.toggleCollapse', HIGH_PRIORITY$f, function(context) {
 	    var shape = context.shape;
 
 	    if (!is(shape, 'bpmn:SubProcess')) {
@@ -41969,7 +42377,7 @@
 	 * @typedef {import('../Modeling').default} Modeling
 	 */
 
-	var LOW_PRIORITY$e = 500;
+	var LOW_PRIORITY$f = 500;
 
 	/**
 	 * @param {EventBus} eventBus
@@ -42030,7 +42438,7 @@
 	    };
 	  }
 
-	  this.executed([ 'shape.toggleCollapse' ], LOW_PRIORITY$e, function(e) {
+	  this.executed([ 'shape.toggleCollapse' ], LOW_PRIORITY$f, function(e) {
 
 	    var context = e.context,
 	        shape = context.shape;
@@ -42053,7 +42461,7 @@
 	    }
 	  });
 
-	  this.reverted([ 'shape.toggleCollapse' ], LOW_PRIORITY$e, function(e) {
+	  this.reverted([ 'shape.toggleCollapse' ], LOW_PRIORITY$f, function(e) {
 
 	    var context = e.context;
 	    var shape = context.shape;
@@ -42068,7 +42476,7 @@
 	    }
 	  });
 
-	  this.postExecuted([ 'shape.toggleCollapse' ], LOW_PRIORITY$e, function(e) {
+	  this.postExecuted([ 'shape.toggleCollapse' ], LOW_PRIORITY$f, function(e) {
 	    var shape = e.context.shape,
 	        defaultSize = elementFactory.getDefaultSize(shape),
 	        newBounds;
@@ -42223,12 +42631,31 @@
 	 * @typedef {import('../Modeling').default} Modeling
 	 */
 
-	var LOW_PRIORITY$d = 500,
-	    HIGH_PRIORITY$d = 5000;
+	var LOW_PRIORITY$e = 500,
+	    HIGH_PRIORITY$e = 5000;
+
+	// Commands that provide a shape whose lane references must be updated.
+	var laneRefShapeEvents = [
+	  'shape.create',
+	  'shape.delete',
+	  'shape.move',
+	  'shape.resize'
+	];
 
+	// Commands that bracket a complete lane reference update, including nested commands.
+	var laneRefUpdateEvents = [
+	  ...laneRefShapeEvents,
+	  'spaceTool',
+	  'lane.add',
+	  'lane.resize',
+	  'lane.split',
+	  'elements.create',
+	  'elements.delete',
+	  'elements.move'
+	];
 
 	/**
-	 * BPMN specific delete lane behavior.
+	 * Synchronizes lane flow node references after geometry changes.
 	 *
 	 * @param {EventBus} eventBus
 	 * @param {Modeling} modeling
@@ -42237,18 +42664,11 @@
 
 	  CommandInterceptor.call(this, eventBus);
 
-	  /**
-	   * Update Lane#flowNodeRefs and FlowNode#lanes with every flow node
-	   * move/resize and lane move/resize. Groups elements to recompute containments
-	   * as efficient as possible.
-	   */
-
-	  // the update context
 	  var context;
 
 
 	  function initContext() {
-	    context = context || new UpdateContext();
+	    context = context || new UpdateContext$1();
 	    context.enter();
 
 	    return context;
@@ -42280,40 +42700,26 @@
 	  }
 
 
-	  var laneRefUpdateEvents = [
-	    'spaceTool',
-	    'lane.add',
-	    'lane.resize',
-	    'lane.split',
-	    'elements.create',
-	    'elements.delete',
-	    'elements.move',
-	    'shape.create',
-	    'shape.delete',
-	    'shape.move',
-	    'shape.resize'
-	  ];
-
-
-	  // listen to a lot of stuff to group lane updates
-
-	  this.preExecute(laneRefUpdateEvents, HIGH_PRIORITY$d, function(event) {
+	  /**
+	   * Sets up the context for lane reference updates before executing commands
+	   * that may affect them.
+	   */
+	  this.preExecute(laneRefUpdateEvents, HIGH_PRIORITY$e, function() {
 	    initContext();
 	  });
 
-	  this.postExecuted(laneRefUpdateEvents, LOW_PRIORITY$d, function(event) {
+	  /**
+	   * Releases the context for lane reference updates after executing commands
+	   * that may affect them.
+	   */
+	  this.postExecuted(laneRefUpdateEvents, LOW_PRIORITY$e, function() {
 	    releaseContext();
 	  });
 
-
-	  // Mark flow nodes + lanes that need an update
-
-	  this.preExecute([
-	    'shape.create',
-	    'shape.move',
-	    'shape.delete',
-	    'shape.resize'
-	  ], function(event) {
+	  /**
+	   * Handles updates to lane references for shapes.
+	   */
+	  this.preExecute(laneRefShapeEvents, function(event) {
 
 	    var context = event.context,
 	        shape = context.shape;
@@ -42321,7 +42727,7 @@
 	    var updateContext = getContext();
 
 	    // no need to update labels
-	    if (shape.labelTarget) {
+	    if (!shape || shape.labelTarget) {
 	      return;
 	    }
 
@@ -42343,7 +42749,7 @@
 	e$3(UpdateFlowNodeRefsBehavior, CommandInterceptor);
 
 
-	function UpdateContext() {
+	function UpdateContext$1() {
 
 	  this.flowNodes = [];
 	  this.lanes = [];
@@ -42369,6 +42775,168 @@
 	  };
 	}
 
+	/**
+	 * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+	 * @typedef {import('../Modeling').default} Modeling
+	 */
+
+	var LOW_PRIORITY$d = 500,
+	    HIGH_PRIORITY$d = 5000;
+
+	// Commands that provide a shape or connection whose references must be updated.
+	var categoryValueRefShapeAndConnectionEvents = [
+	  'connection.create',
+	  'connection.delete',
+	  'connection.layout',
+	  'connection.move',
+	  'connection.reconnect',
+	  'connection.updateWaypoints',
+	  'shape.create',
+	  'shape.delete',
+	  'shape.move',
+	  'shape.resize'
+	];
+
+	// Commands that bracket a complete reference update, including nested commands.
+	var categoryValueRefUpdateEvents = [
+	  ...categoryValueRefShapeAndConnectionEvents,
+	  'elements.create',
+	  'elements.delete',
+	  'elements.move',
+	  'label.create',
+	  'spaceTool'
+	];
+
+	/**
+	 * Synchronizes group category references after geometry changes.
+	 *
+	 * @param {EventBus} eventBus
+	 * @param {Modeling} modeling
+	 */
+	function UpdateCategoryValueRefsBehavior(eventBus, modeling) {
+
+	  CommandInterceptor.call(this, eventBus);
+
+	  var context;
+
+	  function initContext() {
+	    context = context || new UpdateContext();
+	    context.enter();
+
+	    return context;
+	  }
+
+	  function getContext() {
+	    if (!context) {
+	      throw new Error('out of bounds release');
+	    }
+
+	    return context;
+	  }
+
+	  function releaseContext() {
+	    if (!context) {
+	      throw new Error('out of bounds release');
+	    }
+
+	    var triggerUpdate = context.leave();
+
+	    if (triggerUpdate) {
+	      modeling.updateCategoryValueRefs(
+	        Array.from(context.affectedFlowElements),
+	        Array.from(context.affectedGroupEntries.values())
+	      );
+
+	      context = null;
+	    }
+
+	    return triggerUpdate;
+	  }
+
+	  /**
+	   * Sets up the context for category value reference updates before executing
+	   * commands that may affect them.
+	   */
+	  this.preExecute(categoryValueRefUpdateEvents, HIGH_PRIORITY$d, function() {
+	    initContext();
+	  });
+
+	  /**
+	   * Releases the context for category value reference updates after executing
+	   * commands that may affect them.
+	   */
+	  this.postExecuted(categoryValueRefUpdateEvents, LOW_PRIORITY$d, function() {
+	    releaseContext();
+	  });
+
+	  /**
+	   * Handles updates to category value references for shapes and connections.
+	   */
+	  this.preExecute(categoryValueRefShapeAndConnectionEvents, function(event) {
+	    var shape = event.context.connection || event.context.shape,
+	        updateContext = getContext();
+
+	    if (!shape || shape.labelTarget) {
+	      return;
+	    }
+
+	    if (is(shape, 'bpmn:FlowElement')) {
+	      updateContext.addFlowElement(shape);
+	    }
+
+	    if (is(shape, 'bpmn:Group')) {
+	      updateContext.addGroup(shape);
+	    }
+	  });
+
+	  this.preExecute('label.create', function(event) {
+	    var labelTarget = event.context.labelTarget;
+
+	    if (is(labelTarget, 'bpmn:Group')) {
+	      getContext().addGroup(labelTarget);
+	    }
+	  });
+	}
+
+	UpdateCategoryValueRefsBehavior.$inject = [
+	  'eventBus',
+	  'modeling'
+	];
+
+	e$3(UpdateCategoryValueRefsBehavior, CommandInterceptor);
+
+
+	function UpdateContext() {
+
+	  this.affectedFlowElements = new Set();
+	  this.affectedGroupEntries = new Map();
+
+	  this.counter = 0;
+
+	  this.addFlowElement = function(flowElement) {
+	    this.affectedFlowElements.add(flowElement);
+	  };
+
+	  this.addGroup = function(group) {
+	    if (!this.affectedGroupEntries.has(group)) {
+	      this.affectedGroupEntries.set(group, {
+	        categoryValue: group.businessObject.categoryValueRef,
+	        groupShape: group
+	      });
+	    }
+	  };
+
+	  this.enter = function() {
+	    this.counter++;
+	  };
+
+	  this.leave = function() {
+	    this.counter--;
+
+	    return !this.counter;
+	  };
+	}
+
 	/**
 	 * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
 	 * @typedef {import('../../rules/BpmnRules').default} BpmnRules
@@ -42440,6 +43008,7 @@
 	    'associationBehavior',
 	    'attachEventBehavior',
 	    'boundaryEventBehavior',
+	    'categoryRootElementReferenceBehavior',
 	    'compensateBoundaryEventBehaviour',
 	    'createBehavior',
 	    'createDataObjectBehavior',
@@ -42474,6 +43043,7 @@
 	    'toggleElementCollapseBehaviour',
 	    'unclaimIdBehavior',
 	    'updateFlowNodeRefsBehavior',
+	    'updateCategoryValueRefsBehavior',
 	    'unsetDefaultFlowBehavior',
 	    'setCompensationActivityAfterPasteBehavior'
 	  ],
@@ -42483,6 +43053,7 @@
 	  attachEventBehavior: [ 'type', AttachEventBehavior ],
 	  artifactBehavior: [ 'type', ArtifactBehavior ],
 	  boundaryEventBehavior: [ 'type', BoundaryEventBehavior ],
+	  categoryRootElementReferenceBehavior: [ 'type', CategoryRootElementReferenceBehavior ],
 	  compensateBoundaryEventBehaviour: [ 'type', CompensateBoundaryEventBehavior ],
 	  createBehavior: [ 'type', CreateBehavior ],
 	  createDataObjectBehavior: [ 'type', CreateDataObjectBehavior ],
@@ -42518,6 +43089,7 @@
 	  unclaimIdBehavior: [ 'type', UnclaimIdBehavior ],
 	  unsetDefaultFlowBehavior: [ 'type', DeleteSequenceFlowBehavior ],
 	  updateFlowNodeRefsBehavior: [ 'type', UpdateFlowNodeRefsBehavior ],
+	  updateCategoryValueRefsBehavior: [ 'type', UpdateCategoryValueRefsBehavior ],
 	  setCompensationActivityAfterPasteBehavior: [ 'type', SetCompensationActivityAfterPasteBehavior ]
 	};
 
@@ -43696,9 +44268,47 @@
 	    return false;
 	  }
 
+	  // do not copy message flows unless both connected participants are copied,
+	  // too; otherwise they would end up in an invalid organizational context
+	  if (is(element, 'bpmn:MessageFlow') && !canCopyMessageFlow(elements, element)) {
+	    return false;
+	  }
+
 	  return true;
 	}
 
+	/**
+	 * A message flow may only be copied if both of its participants are copied,
+	 * too. Otherwise it would be pasted into an invalid organizational context,
+	 * e.g. a plain process.
+	 *
+	 * @param {Element[]} elements
+	 * @param {Connection} connection
+	 *
+	 * @return {boolean}
+	 */
+	function canCopyMessageFlow(elements, connection) {
+	  var sourceParticipant = getParticipant(connection.source),
+	      targetParticipant = getParticipant(connection.target);
+
+	  return includes$2(elements, sourceParticipant) && includes$2(elements, targetParticipant);
+	}
+
+	/**
+	 * @param {Element} element
+	 *
+	 * @return {Element|null}
+	 */
+	function getParticipant(element) {
+	  for (; element; element = element.parent) {
+	    if (is(element, 'bpmn:Participant')) {
+	      return element;
+	    }
+	  }
+
+	  return null;
+	}
+
 	/**
 	 * @param {Element} element
 	 *
@@ -53603,8 +54213,6 @@
 	/**
 	 * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
 	 *
-	 * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
-	 *
 	 * @typedef {import('../../../model/Types').Shape} Shape
 	 */
 
@@ -53617,15 +54225,9 @@
 	 *
 	 * @implements {CommandHandler}
 	 *
-	 * @param {ElementRegistry} elementRegistry
 	 */
-	function UpdateFlowNodeRefsHandler(elementRegistry) {
-	  this._elementRegistry = elementRegistry;
-	}
+	function UpdateFlowNodeRefsHandler() {}
 
-	UpdateFlowNodeRefsHandler.$inject = [
-	  'elementRegistry'
-	];
 
 	/**
 	 * @param {Shape} flowNodeShapes
@@ -53801,6 +54403,409 @@
 	  return [];
 	};
 
+	/**
+	 * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
+	 * @typedef {import('diagram-js/lib/core/ElementRegistry').default} ElementRegistry
+	 * @typedef {import('../BpmnFactory').default} BpmnFactory
+	 *
+	 * @typedef {import('../../../model/Types').Element} Element
+	 * @typedef {import('../../../model/Types').ModdleElement} ModdleElement
+	 *
+	 * @typedef { {
+	 *   categoryValue: ModdleElement;
+	 *   root?: Element;
+	 * } } CategoryGroupEntry
+	 */
+
+	var CATEGORY_VALUE_REFS_ATTR = 'categoryValueRef';
+
+
+	/**
+	 * Updates category value references for flow elements visually enclosed by groups.
+	 *
+	 * A flow element is grouped only when it shares the group's diagram root and
+	 * is geometrically enclosed by the group. Consequently, visible children of an
+	 * expanded subprocess are grouped, while children of a collapsed subprocess
+	 * are not.
+	 *
+	 * Groups without a category value are auto-healed: if such a group visually
+	 * encloses an affected flow element a category value is created for it on the
+	 * fly, so that legacy diagrams (groups modeled without a category value) start
+	 * to categorize their contents as soon as they are interacted with.
+	 *
+	 * @implements {CommandHandler}
+	 *
+	 * @param {BpmnFactory} bpmnFactory
+	 * @param {ElementRegistry} elementRegistry
+	 */
+	function UpdateCategoryValueRefsHandler(bpmnFactory, elementRegistry) {
+	  this._bpmnFactory = bpmnFactory;
+	  this._elementRegistry = elementRegistry;
+	}
+
+	UpdateCategoryValueRefsHandler.$inject = [
+	  'bpmnFactory',
+	  'elementRegistry'
+	];
+
+
+	/**
+	 * @param { Element[] } affectedFlowElements
+	 * @param { {
+	 *   categoryValue: ModdleElement;
+	 *   groupShape: Element;
+	 * }[] } affectedGroupEntries
+	 *
+	 * @return { {
+	 *   flowElements: {
+	 *     businessObject: ModdleElement;
+	 *     categoryValuesToAdd: ModdleElement[];
+	 *     categoryValuesToRemove: ModdleElement[];
+	 *   }[];
+	 *   groups: {
+	 *     groupShape: Element;
+	 *     categoryValue: ModdleElement;
+	 *     category: ModdleElement;
+	 *   }[];
+	 * } }
+	 */
+	UpdateCategoryValueRefsHandler.prototype._computeUpdates = function(affectedFlowElements, affectedGroupEntries) {
+	  var elementRegistry = this._elementRegistry,
+	      bpmnFactory = this._bpmnFactory;
+
+	  /** @type {Map<Element, ModdleElement>} */
+	  var flowElementBusinessObjects = new Map();
+
+	  var groupUpdates = [];
+
+	  /**
+	   * @type {Map<Element, {
+	   *   present?: CategoryGroupEntry;
+	   *   past?: CategoryGroupEntry;
+	   * }>}
+	   */
+	  var categoryGroups = new Map();
+
+	  /**
+	   * Adds a group to the list of groups to consider for category value updates.
+	   *
+	   * @param {Element} groupShape
+	   * @param {ModdleElement} categoryValue
+	   * @param {boolean} isPresent
+	   */
+	  function addGroup(groupShape, categoryValue, isPresent) {
+	    if (!categoryValue) {
+	      return;
+	    }
+
+	    var categoryGroup = categoryGroups.get(groupShape);
+
+	    if (!categoryGroup) {
+	      categoryGroup = {};
+	      categoryGroups.set(groupShape, categoryGroup);
+	    }
+
+	    if (isPresent && categoryGroup.present) {
+	      return;
+	    }
+
+	    if (!isPresent && categoryGroup.past) {
+	      return;
+	    }
+
+	    if (isPresent) {
+	      categoryGroup.present = {
+	        categoryValue: categoryValue,
+	        root: getRoot(groupShape)
+	      };
+	    } else {
+	      categoryGroup.past = {
+	        categoryValue: categoryValue
+	      };
+	    }
+	  }
+
+	  /**
+	   * Adds a flow element to the list of flow elements to consider for category
+	   * value updates.
+	   *
+	   * @param {Element} flowElement
+	   */
+	  function addFlowElement(flowElement) {
+	    flowElementBusinessObjects.set(
+	      flowElement,
+	      getBusinessObject(flowElement)
+	    );
+	  }
+
+	  /**
+	   * Adds all flow elements on the diagram to the list of flow elements to
+	   * consider; skips root elements (e.g. sub process planes) which share a
+	   * business object with their collapsed shape but carry no diagram position.
+	   */
+	  function addAllFlowElements() {
+	    elementRegistry.filter(function(element) {
+	      return is(element, 'bpmn:FlowElement') && !isLabel(element) && element.parent;
+	    }).forEach(addFlowElement);
+	  }
+
+	  /**
+	   * Returns a group's category value, creating one on the fly for
+	   * legacy groups modeled without one. Retrieving the value in order to
+	   * reference it materializes it; the fresh value is recorded as a heal so
+	   * CategoryRootElementReferenceBehavior can maintain its root element.
+	   *
+	   * @param {Element} groupShape
+	   *
+	   * @return {ModdleElement}
+	   */
+	  function getCategoryValue(groupShape) {
+	    var groupBo = getBusinessObject(groupShape),
+	        categoryValue = groupBo.get('categoryValueRef');
+
+	    if (!categoryValue) {
+	      categoryValue = getOrCreateCategoryValueForGroup(bpmnFactory, groupBo);
+
+	      groupUpdates.push(createGroupUpdate(groupShape, categoryValue));
+	    }
+
+	    return categoryValue;
+	  }
+
+	  function getElementsByRoot(elements) {
+	    return elements.reduce(function(elementsByRoot, element) {
+	      var root = getRoot(element),
+	          elementsInRoot = elementsByRoot.get(root);
+
+	      if (!elementsInRoot) {
+	        elementsInRoot = [];
+	        elementsByRoot.set(root, elementsInRoot);
+	      }
+
+	      elementsInRoot.push(element);
+
+	      return elementsByRoot;
+	    }, new Map());
+	  }
+
+	  affectedFlowElements = Array.from(affectedFlowElements || []);
+
+	  var affectedFlowElementsByRoot = getElementsByRoot(affectedFlowElements);
+
+	  // when a group is moved, resized, added or removed, the category value
+	  // references of all flow elements must be rechecked
+	  if (affectedGroupEntries.length) {
+	    addAllFlowElements();
+	  }
+
+	  // flow elements that were genuinely moved or created; unrelated groups
+	  // will not be touched
+	  affectedFlowElements.forEach(addFlowElement);
+
+	  // add all present groups to the list of groups to consider for category
+	  // value updates, auto-healing legacy groups only when an affected flow
+	  // element moves into them
+	  elementRegistry.filter(function(element) {
+	    return is(element, 'bpmn:Group') && !isLabel(element) && element.parent;
+	  }).forEach(function(groupShape) {
+	    var categoryValue = getBusinessObject(groupShape).get('categoryValueRef');
+
+	    if (!categoryValue) {
+	      var groupRoot = getRoot(groupShape),
+	          affectedFlowElementsInRoot = affectedFlowElementsByRoot.get(groupRoot) || [],
+	          enclosedAffectedFlowElements = getEnclosedElements(
+	            affectedFlowElementsInRoot,
+	            groupShape
+	          ),
+	          enclosesAffectedFlowElement = Object.keys(enclosedAffectedFlowElements).length > 0;
+
+	      if (enclosesAffectedFlowElement) {
+	        categoryValue = getCategoryValue(groupShape);
+	      }
+	    }
+
+	    addGroup(groupShape, categoryValue, true);
+	  });
+
+	  affectedGroupEntries.forEach(function(groupEntry) {
+	    addGroup(groupEntry.groupShape, groupEntry.categoryValue, false);
+	  });
+
+	  // a healed group receives a fresh category value; recheck all flow elements
+	  // so that everything it visually encloses is tagged consistently, not just
+	  // the flow element that triggered the healing
+	  if (groupUpdates.length) {
+	    addAllFlowElements();
+	  }
+
+	  var flowElements = Array.from(flowElementBusinessObjects.keys());
+
+	  var managedCategoryValues = Array.from(categoryGroups.values()).reduce(function(set, group) {
+	    if (group.present) {
+	      set.add(group.present.categoryValue);
+	    }
+
+	    if (group.past) {
+	      set.add(group.past.categoryValue);
+	    }
+
+	    return set;
+	  }, new Set());
+
+	  var categoryValuesByFlowElement = new Map(),
+	      flowElementsByRoot = getElementsByRoot(flowElements);
+
+	  // Containment is calculated once per group and diagram root. This avoids
+	  // allocating an enclosure result for every flow element / group pair.
+	  categoryGroups.forEach(function(categoryGroup, groupShape) {
+	    var presentGroup = categoryGroup.present;
+
+	    if (!presentGroup) {
+	      return;
+	    }
+
+	    var flowElementsInRoot = flowElementsByRoot.get(presentGroup.root) || [],
+	        enclosedFlowElements = getEnclosedElements(flowElementsInRoot, groupShape);
+
+	    flowElementsInRoot.forEach(function(flowElement) {
+	      if (!enclosedFlowElements[flowElement.id]) {
+	        return;
+	      }
+
+	      var categoryValues = categoryValuesByFlowElement.get(flowElement);
+
+	      if (!categoryValues) {
+	        categoryValues = new Set();
+	        categoryValuesByFlowElement.set(flowElement, categoryValues);
+	      }
+
+	      categoryValues.add(presentGroup.categoryValue);
+	    });
+	  });
+
+	  // compute updates for all flow elements based on the groups they are inside
+	  var flowElementUpdates = flowElements.reduce(function(flowElementUpdates, flowElement) {
+	    var flowElementBo = flowElementBusinessObjects.get(flowElement),
+	        categoryValueRefs = flowElementBo.get(CATEGORY_VALUE_REFS_ATTR),
+	        categoryValueRefSet = new Set(categoryValueRefs),
+	        enclosingCategoryValues = categoryValuesByFlowElement.get(flowElement) || new Set(),
+	        categoryValuesToAdd = Array.from(enclosingCategoryValues).filter(function(categoryValue) {
+	          return !categoryValueRefSet.has(categoryValue);
+	        }),
+	        categoryValuesToRemove = categoryValueRefs.filter(function(categoryValue) {
+	          return managedCategoryValues.has(categoryValue) &&
+	            !enclosingCategoryValues.has(categoryValue);
+	        });
+
+	    if (categoryValuesToAdd.length || categoryValuesToRemove.length) {
+	      flowElementUpdates.push({
+	        businessObject: flowElementBo,
+	        categoryValuesToAdd,
+	        categoryValuesToRemove
+	      });
+	    }
+
+	    return flowElementUpdates;
+	  }, []);
+
+	  return {
+	    flowElements: flowElementUpdates,
+	    groups: groupUpdates
+	  };
+	};
+
+
+	UpdateCategoryValueRefsHandler.prototype.execute = function(context) {
+	  var updates = context.updates;
+
+	  if (!updates) {
+	    updates = context.updates = this._computeUpdates(
+	      context.affectedFlowElements,
+	      context.affectedGroupEntries
+	    );
+	  }
+
+	  // set auto-healed category values first so that flow element updates can
+	  // reference them; root element linking is handled by
+	  // CategoryRootElementReferenceBehavior
+	  applyGroupUpdates(updates.groups);
+
+	  applyFlowElementUpdates(updates.flowElements);
+
+	  return [];
+	};
+
+
+	UpdateCategoryValueRefsHandler.prototype.revert = function(context) {
+	  var updates = context.updates;
+
+	  revertFlowElementUpdates(updates.flowElements);
+
+	  revertGroupUpdates(updates.groups);
+
+	  return [];
+	};
+
+
+	function createGroupUpdate(groupShape, categoryValue) {
+	  return {
+	    groupShape: groupShape,
+	    categoryValue: categoryValue,
+	    category: categoryValue.$parent
+	  };
+	}
+
+	function applyGroupUpdates(groupUpdates) {
+	  groupUpdates.forEach(function(groupUpdate) {
+	    getBusinessObject(groupUpdate.groupShape).categoryValueRef = groupUpdate.categoryValue;
+	    groupUpdate.categoryValue.$parent = groupUpdate.category;
+	  });
+	}
+
+	function revertGroupUpdates(groupUpdates) {
+	  groupUpdates.forEach(function(groupUpdate) {
+	    getBusinessObject(groupUpdate.groupShape).categoryValueRef = null;
+	  });
+	}
+
+	function applyFlowElementUpdates(flowElementUpdates) {
+	  flowElementUpdates.forEach(function(flowElementUpdate) {
+	    var businessObject = flowElementUpdate.businessObject,
+	        categoryValueRefs = businessObject.get(CATEGORY_VALUE_REFS_ATTR);
+
+	    flowElementUpdate.categoryValuesToRemove.forEach(function(categoryValue) {
+	      remove(categoryValueRefs, categoryValue);
+	    });
+
+	    flowElementUpdate.categoryValuesToAdd.forEach(function(categoryValue) {
+	      add(categoryValueRefs, categoryValue, true);
+	    });
+	  });
+	}
+
+	function revertFlowElementUpdates(flowElementUpdates) {
+	  flowElementUpdates.forEach(function(flowElementUpdate) {
+	    var businessObject = flowElementUpdate.businessObject,
+	        categoryValueRefs = businessObject.get(CATEGORY_VALUE_REFS_ATTR);
+
+	    flowElementUpdate.categoryValuesToAdd.forEach(function(categoryValue) {
+	      remove(categoryValueRefs, categoryValue);
+	    });
+
+	    flowElementUpdate.categoryValuesToRemove.forEach(function(categoryValue) {
+	      add(categoryValueRefs, categoryValue, true);
+	    });
+	  });
+	}
+
+	function getRoot(element) {
+	  while (element.parent) {
+	    element = element.parent;
+	  }
+
+	  return element;
+	}
+
 	/**
 	 * @typedef {import('diagram-js/lib/command/CommandHandler').default} CommandHandler
 	 *
@@ -54161,6 +55166,11 @@
 	 * @typedef { {
 	 *   removeShape?: boolean;
 	 * } } UpdateLabelHints
+	 *
+	 * @typedef { {
+	 *   categoryValue?: ModdleElement;
+	 *   groupShape: Shape;
+	 * } } GroupEntry
 	 */
 
 	/**
@@ -54211,6 +55221,7 @@
 	  handlers['lane.resize'] = ResizeLaneHandler;
 	  handlers['lane.split'] = SplitLaneHandler;
 	  handlers['lane.updateRefs'] = UpdateFlowNodeRefsHandler;
+	  handlers['group.updateRefs'] = UpdateCategoryValueRefsHandler;
 	  handlers['id.updateClaim'] = IdClaimHandler;
 	  handlers['element.setColor'] = SetColorHandler;
 	  handlers['element.updateLabel'] = UpdateLabelHandler;
@@ -54388,6 +55399,20 @@
 	  });
 	};
 
+	/**
+	 * Update the referenced category values of each flow element.
+	 *
+	 * @param {Element[]} affectedFlowElements The flow elements to update.
+	 * @param {GroupEntry[]} affectedGroupEntries The groups to update.
+	 */
+	Modeling.prototype.updateCategoryValueRefs = function(affectedFlowElements, affectedGroupEntries) {
+
+	  this._commandStack.execute('group.updateRefs', {
+	    affectedFlowElements: affectedFlowElements,
+	    affectedGroupEntries: affectedGroupEntries
+	  });
+	};
+
 	/**
 	 * Claim an ID.
 	 *