@speclynx/apidom-overlay 6.1.0 → 6.1.2

package/dist/apidom-overlay.browser.js

@@ -724,9 +724,10 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(97071);
 /* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(44673);
 /* harmony import */ var _speclynx_apidom_json_path__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(84637);
-/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(35937);
-/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(39505);
-/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(18436);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(13786);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(35937);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(39505);
+/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(18436);
 
 
 
@@ -745,8 +746,22 @@ const defaultDiffOptions = {
     version: '0.0.0'
   }
 };
+
+// generated actions update primitive values and concatenate arrays, which Overlay 1.0.0 doesn't allow
+const supportedOverlayVersions = _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__["default"].filterByFormat('generic').map(mediaType => mediaType.split('version=')[1]).filter(version => version !== '1.0.0');
+
+/**
+ * Throws {@link OverlayError} when the overlay version option is unsupported.
+ * Shared with the URI realm, which checks it before parsing any document.
+ */
+const assertSupportedOverlayVersion = overlay => {
+  const overlayVersion = overlay ?? defaultDiffOptions.overlay;
+  if (!supportedOverlayVersions.includes(overlayVersion)) {
+    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_12__["default"](`Unsupported overlay version "${overlayVersion}": diff supports ${supportedOverlayVersions.join(', ')}`);
+  }
+};
 const createUpdateAction = (segments, value) => {
-  const action = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__.ActionElement();
+  const action = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.ActionElement();
   action.target = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](_speclynx_apidom_json_path__WEBPACK_IMPORTED_MODULE_8__.NormalizedPath.from(segments));
   /**
    * Every update value is built from nodes of the right document. Cloning here
@@ -758,22 +773,27 @@ const createUpdateAction = (segments, value) => {
   return action;
 };
 const createRemoveAction = segments => {
-  const action = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__.ActionElement();
+  const action = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.ActionElement();
   action.target = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](_speclynx_apidom_json_path__WEBPACK_IMPORTED_MODULE_8__.NormalizedPath.from(segments));
   action.removeField = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"](true);
   return action;
 };
 
-// elements are compared by their serialized values, which tell an empty YAML node (null) from an
-// empty string; Element#equals compares the elements' own values, where both are an empty string
+// elements are compared by their values, read with the core toValue
 const isEqual = (left, right) => (0,ramda__WEBPACK_IMPORTED_MODULE_0__["default"])((0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_7__["default"])(left), (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_7__["default"])(right));
+
+// a null (as an empty YAML node is) filled in with a scalar, or a scalar emptied to a null, is
+// updated in place like a value, keeping its position; any other change of type is structural
+const isStructuralChange = (left, right) => {
+  const kinds = [left.primitive(), right.primitive()];
+  const isCollection = kinds.some(kind => kind === 'object' || kind === 'array');
+  return kinds[0] !== kinds[1] && (isCollection || !kinds.includes('null'));
+};
 const diffElements = (left, right, segments, actions) => {
   if (isEqual(left, right)) return;
-  const leftKind = left.primitive();
-  const rightKind = right.primitive();
-  if (leftKind !== rightKind) {
+  if (isStructuralChange(left, right)) {
     if (segments.length === 0) {
-      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_11__["default"]('Cannot diff documents with incompatible root types');
+      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_12__["default"]('Cannot diff documents with incompatible root types');
     }
     // structural type change: remove old, re-add new via parent update.
     // only reachable from diffObjects — segments tail is always a string key
@@ -834,7 +854,7 @@ const diffArrays = (left, right, segments, actions) => {
     const leftItem = left.get(i);
     const rightItem = right.get(i);
     if (isEqual(leftItem, rightItem)) continue;
-    if (leftItem.primitive() !== rightItem.primitive()) {
+    if (isStructuralChange(leftItem, rightItem)) {
       // structural type change at index i — reconstruct tail:
       // remove from end down to i (reverse order preserves index stability),
       // then batch-append right[i..] as a single ArrayElement (Overlay concat semantics)
@@ -889,14 +909,15 @@ const diff = (leftElement, rightElement, options = {}) => {
   const infoTitle = options.info?.title ?? defaultDiffOptions.info.title;
   const infoVersion = options.info?.version ?? defaultDiffOptions.info.version;
   const infoDescription = options.info?.description;
+  assertSupportedOverlayVersion(overlayVersion);
   const actions = [];
   diffElements(leftElement, rightElement, [], actions);
   if (actions.length === 0 && options.onEmptyDiff === 'throw') {
-    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_11__["default"]('Diff produced no actions: documents are identical');
+    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_12__["default"]('Diff produced no actions: documents are identical');
   }
-  const overlay = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__.Overlay1Element();
-  overlay.overlay = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__.OverlayElement(overlayVersion);
-  const info = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__.InfoElement();
+  const overlay = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.Overlay1Element();
+  overlay.overlay = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.OverlayElement(overlayVersion);
+  const info = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.InfoElement();
   info.title = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](infoTitle);
   info.version = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](infoVersion);
   if (infoDescription !== undefined) {
@@ -906,10 +927,11 @@ const diff = (leftElement, rightElement, options = {}) => {
   if (options.extends !== undefined) {
     overlay.extends = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"](options.extends);
   }
-  overlay.actions = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__["default"](actions);
+  overlay.actions = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_11__["default"](actions);
   return overlay;
 };
 /* harmony export */ __webpack_require__.d(__webpack_exports__, [
+/* harmony export */   "assertSupportedOverlayVersion", 0, /* binding */ assertSupportedOverlayVersion,
 /* harmony export */   "diff", 0, /* binding */ diff
 /* harmony export */ ]);
 
@@ -995,6 +1017,8 @@ const defaultOptions = {
  * @public
  */
 const diff = async (leftURI, rightURI, options = defaultOptions) => {
+  // fail on an unsupported version before fetching and parsing the documents
+  (0,_apidom_ts__WEBPACK_IMPORTED_MODULE_1__.assertSupportedOverlayVersion)(options.overlay);
   const mergedRefOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_0__.mergeOptions)(defaultReferenceOptions, options.reference ?? {});
   const [leftParseResult, rightParseResult] = await Promise.all([(0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_0__.parse)(leftURI, mergedRefOptions), (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_0__.parse)(rightURI, mergedRefOptions)]);
   const leftElement = leftParseResult.api;
@@ -42827,11 +42851,8 @@ const serializer = (element, replacer, space, options) => {
 __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(25162);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(96911);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(18252);
-/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(10977);
+/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(10977);
 
- // an empty YAML node (YAML 1.2 §7.2) is a null parsed as an empty string with the yaml-e-node class
-const isEmptyNode = element => (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isStringElement)(element) && element.toValue() === '' && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.includesClasses)(element, ['yaml-e-node']);
 
 /**
  * Transforms the ApiDOM into JavaScript POJO.
@@ -42841,7 +42862,6 @@ const isEmptyNode = element => (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_M
  */
 const serializer = element => {
   if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isElement)(element)) return element;
-  if (isEmptyNode(element)) return null;
 
   // Shortcut optimization for primitive element types
   if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isStringElement)(element) || (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isNumberElement)(element) || (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isBooleanElement)(element) || (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isNullElement)(element)) {
@@ -42859,8 +42879,8 @@ const serializer = element => {
       node.forEach((value, key) => {
         const k = serialize(key);
         const v = serialize(value);
-        const name = (0,_util_mjs__WEBPACK_IMPORTED_MODULE_3__.toPropertyName)(k);
-        if (name !== undefined) (0,_util_mjs__WEBPACK_IMPORTED_MODULE_3__["default"])(obj, name, v);
+        const name = (0,_util_mjs__WEBPACK_IMPORTED_MODULE_2__.toPropertyName)(k);
+        if (name !== undefined) (0,_util_mjs__WEBPACK_IMPORTED_MODULE_2__["default"])(obj, name, v);
       });
       return obj;
     }
@@ -42875,7 +42895,6 @@ const serializer = element => {
     if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isLinkElement)(node)) {
       return (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isStringElement)(node.href) ? node.href.toValue() : '';
     }
-    if (isEmptyNode(node)) return null;
     return node.toValue();
   };
   return serialize(element);
@@ -43243,9 +43262,10 @@ const toYAMLNode = (element, context) => {
   // scalar element (string, number, boolean, null)
   const scalarType = style.scalarStyle ? scalarStyleMap[style.scalarStyle] : undefined;
   const scalar = new yaml__WEBPACK_IMPORTED_MODULE_0__.Scalar((0,_value_mjs__WEBPACK_IMPORTED_MODULE_5__["default"])(element));
-  // an empty node (YAML 1.2 §7.2) is serialized to null; while it's still empty, write it back as
-  // it was written: with no content, after its anchor and tag if it had them
-  const isEmptyNode = scalar.value === null && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__.includesClasses)(element, ['yaml-e-node']);
+  // an empty node (YAML 1.2 §7.2) is serialized to null, or to the empty string as a key; while it's
+  // still empty, write it back as it was written: with no content, after its anchor and tag if it
+  // had them
+  const isEmptyNode = (scalar.value === null || scalar.value === '' && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__.includesClasses)(element, ['yaml-e-key'])) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__.includesClasses)(element, ['yaml-e-node']);
   if (isEmptyNode) {
     const anchor = claimAnchor(style, context);
     const properties = [anchor && `&${anchor}`, style.tag].filter(Boolean).join(' ');
@@ -43284,7 +43304,10 @@ const toYAMLNode = (element, context) => {
     }
   }
   if ((style.scalarStyle === 'Literal' || style.scalarStyle === 'Folded') && typeof style.rawContent === 'string' && typeof scalar.value === 'string') {
-    const text = style.rawContent.replace(/\r\n/g, '\n').replace(/\n$/, '');
+    const raw = style.rawContent.replace(/\r\n/g, '\n');
+    // the empty lines after a clip or strip block aren't part of its value, but separate it from
+    // what follows in its source, so they're dropped; a keep block's are part of its value
+    const text = raw.replace(/^[|>][1-9]?\+/.test(raw) ? /\n$/ : /\n+$/, '');
     scalar.value = new RawBlockScalar(scalar.value, text);
   }
   if (style.styleGroup === 'Flow' && typeof style.rawContent === 'string' && typeof scalar.value === 'string' && scalar.value !== '') {
@@ -45399,11 +45422,10 @@ class CollectionElement extends _Element_mjs__WEBPACK_IMPORTED_MODULE_0__["defau
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(53654);
 /* harmony import */ var _Metadata_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(51844);
-/* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(36663);
-/* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(38504);
+/* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(36663);
+/* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(38504);
 
 
 
@@ -45573,13 +45595,13 @@ class Element {
     }
 
     // KeyValuePair
-    if (value instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
+    if (value instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
       this._content = value;
       return;
     }
 
     // ObjectSlice - extract elements array
-    if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_4__["default"]) {
+    if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
       this._content = value.elements;
       return;
     }
@@ -45698,7 +45720,7 @@ class Element {
     if (Array.isArray(content)) {
       return content;
     }
-    if (content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
+    if (content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
       const children = [];
       if (content.key) children.push(content.key);
       if (content.value) children.push(content.value);
@@ -45762,7 +45784,7 @@ class Element {
     if (_content instanceof Element) {
       return _content.toValue();
     }
-    if (_content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
+    if (_content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
       return _content.toValue();
     }
     if (Array.isArray(_content)) {
@@ -46858,14 +46880,13 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   parse: () => (/* reexport safe */ _swaggerexpert_jsonpath__WEBPACK_IMPORTED_MODULE_0__.parse),
 /* harmony export */   test: () => (/* reexport safe */ _swaggerexpert_jsonpath__WEBPACK_IMPORTED_MODULE_0__.test)
 /* harmony export */ });
-/* empty/unused harmony star reexport */
 /* harmony import */ var _swaggerexpert_jsonpath__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(84637);
-/* harmony import */ var _realm_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(84925);
+/* harmony import */ var _realm_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(84925);
 
 
 
 
-const realm = new _realm_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]();
+const realm = new _realm_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]();
 
 /**
  * Options for ApiDOM JSONPath evaluation.
@@ -47100,14 +47121,13 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   testReferenceToken: () => (/* reexport safe */ _swaggerexpert_json_pointer__WEBPACK_IMPORTED_MODULE_0__.testReferenceToken),
 /* harmony export */   unescape: () => (/* reexport safe */ _swaggerexpert_json_pointer__WEBPACK_IMPORTED_MODULE_0__.unescape)
 /* harmony export */ });
-/* empty/unused harmony star reexport */
 /* harmony import */ var _swaggerexpert_json_pointer__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(61198);
-/* harmony import */ var _realm_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(60545);
+/* harmony import */ var _realm_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(60545);
 
 
 
 
-const realm = new _realm_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]();
+const realm = new _realm_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]();
 
 /**
  * @public
@@ -78044,25 +78064,24 @@ class AllOfVisitor extends JSONSchemaAllOfVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
-/* harmony import */ var _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(86059);
-/* harmony import */ var _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(26207);
+/* harmony import */ var _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(86059);
+/* harmony import */ var _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(26207);
 
 
 
 /**
  * @public
  */
-class ItemsVisitor extends _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_2__["default"] {
+class ItemsVisitor extends _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__["default"] {
   ObjectElement(path) {
-    _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_2__["default"].prototype.ObjectElement.call(this, path);
-    if ((0,_speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__.isJSONReferenceElement)(this.element)) {
+    _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__["default"].prototype.ObjectElement.call(this, path);
+    if ((0,_speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_0__.isJSONReferenceElement)(this.element)) {
       this.element.meta.set('referenced-element', 'schema');
     }
   }
   ArrayElement(path) {
-    _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_2__["default"].prototype.ArrayElement.call(this, path);
-    this.element.filter(_speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__.isJSONReferenceElement)
+    _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__["default"].prototype.ArrayElement.call(this, path);
+    this.element.filter(_speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_0__.isJSONReferenceElement)
     // @ts-ignore
     .forEach(referenceElement => {
       referenceElement.meta.set('referenced-element', 'schema');
@@ -86326,9 +86345,8 @@ class AnyOfVisitor extends JSONSchemaAnyOfVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
-/* harmony import */ var _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(26207);
-/* harmony import */ var _predicates_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(32131);
+/* harmony import */ var _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(26207);
+/* harmony import */ var _predicates_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(32131);
 
 
 
@@ -86336,10 +86354,10 @@ __webpack_require__.r(__webpack_exports__);
 /**
  * @public
  */
-class ItemsVisitor extends _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__["default"] {
+class ItemsVisitor extends _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_0__["default"] {
   ObjectElement(path) {
-    _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_1__["default"].prototype.ObjectElement.call(this, path);
-    if ((0,_predicates_mjs__WEBPACK_IMPORTED_MODULE_2__.isReferenceElement)(this.element)) {
+    _speclynx_apidom_ns_json_schema_draft_4__WEBPACK_IMPORTED_MODULE_0__["default"].prototype.ObjectElement.call(this, path);
+    if ((0,_predicates_mjs__WEBPACK_IMPORTED_MODULE_1__.isReferenceElement)(this.element)) {
       this.element.meta.set('referenced-element', 'schema');
     }
   }
@@ -93043,15 +93061,13 @@ const yamlMediaTypes = new _speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODU
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   mediaTypes: () => (/* reexport safe */ _media_types_mjs__WEBPACK_IMPORTED_MODULE_5__["default"])
+/* harmony export */   mediaTypes: () => (/* reexport safe */ _media_types_mjs__WEBPACK_IMPORTED_MODULE_4__["default"])
 /* harmony export */ });
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(55156);
 /* harmony import */ var _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(20746);
 /* harmony import */ var _native_index_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(38600);
 /* harmony import */ var _tree_sitter_index_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(34885);
-/* harmony import */ var _media_types_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(49968);
+/* harmony import */ var _media_types_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(49968);
 
 
 
@@ -93207,10 +93223,8 @@ const parse = async source => {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* harmony import */ var _lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(19305);
-/* harmony import */ var _syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(13615);
+/* harmony import */ var _lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(19305);
+/* harmony import */ var _syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(13615);
 
 
 
@@ -93231,7 +93245,7 @@ const detect = async source => {
   }
   let cst = null;
   try {
-    cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__["default"])(source);
+    cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(source);
     return cst.rootNode.type !== 'ERROR';
   } catch {
     return false;
@@ -93251,9 +93265,9 @@ const parse = async (source, {
   sourceMap = false,
   style = false
 } = {}) => {
-  const cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__["default"])(source);
+  const cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(source);
   try {
-    return (0,_syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_2__["default"])(cst, {
+    return (0,_syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__["default"])(cst, {
       sourceMap,
       style
     });
@@ -94352,15 +94366,13 @@ const yamlMediaTypes = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODUL
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   mediaTypes: () => (/* reexport safe */ _media_types_mjs__WEBPACK_IMPORTED_MODULE_5__["default"])
+/* harmony export */   mediaTypes: () => (/* reexport safe */ _media_types_mjs__WEBPACK_IMPORTED_MODULE_4__["default"])
 /* harmony export */ });
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(55156);
 /* harmony import */ var _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(20746);
 /* harmony import */ var _yaml_index_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(69124);
 /* harmony import */ var _tree_sitter_index_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(10405);
-/* harmony import */ var _media_types_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(16688);
+/* harmony import */ var _media_types_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(16688);
 
 
 
@@ -94463,10 +94475,8 @@ const mediaTypes = new YamlMediaTypes('text/yaml', 'application/yaml');
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* harmony import */ var _lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(47657);
-/* harmony import */ var _syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(67919);
+/* harmony import */ var _lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(47657);
+/* harmony import */ var _syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(67919);
 
 
 
@@ -94477,7 +94487,7 @@ __webpack_require__.r(__webpack_exports__);
 const detect = async source => {
   let cst = null;
   try {
-    cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__["default"])(source);
+    cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(source);
     return !cst.rootNode.isError;
   } catch {
     return false;
@@ -94497,9 +94507,9 @@ const parse = async (source, {
   sourceMap = false,
   style = false
 } = {}) => {
-  const cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__["default"])(source);
+  const cst = await (0,_lexical_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(source);
   try {
-    return (0,_syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_2__["default"])(cst, {
+    return (0,_syntactic_analysis_index_mjs__WEBPACK_IMPORTED_MODULE_1__["default"])(cst, {
       sourceMap,
       style
     });
@@ -95405,15 +95415,19 @@ const transformCstToYamlAst = (cursor, ctx) => {
 __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(55156);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(25162);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(97601);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(31770);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(97071);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(84660);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(40094);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(4823);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(25810);
-/* harmony import */ var _ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(90594);
-/* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(21544);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(55297);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(28121);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18252);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(97601);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(31770);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(97071);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(84660);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(40094);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(4823);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(25810);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(49686);
+/* harmony import */ var _ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(90594);
+/* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__ = __webpack_require__(21544);
 
 
  // Transform context passed through transformation
@@ -95423,7 +95437,7 @@ const maybeAddSourceMap = (node, element, ctx) => {
   if (!ctx.sourceMap) {
     return;
   }
-  _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__["default"].transfer(node, element);
+  _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_11__["default"].transfer(node, element);
 };
 
 // find the first descendant matching a type path through the AST
@@ -95441,7 +95455,7 @@ const findFirst = (node, path) => {
 // detect indent from first nested block mapping (stream > document > mapping > keyValuePair > mapping)
 const detectIndent = node => {
   const nested = findFirst(node, ['document', 'mapping', 'keyValuePair', 'mapping']);
-  if (nested?.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Block && typeof nested.startCharacter === 'number' && nested.startCharacter > 0) {
+  if (nested?.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__.YamlStyleGroup.Block && typeof nested.startCharacter === 'number' && nested.startCharacter > 0) {
     return nested.startCharacter;
   }
   return 2;
@@ -95573,7 +95587,7 @@ const buildYamlStyle = (node, ctx, extras) => {
   // an untagged node has the non-specific tag '?' when it's a plain scalar and '!' otherwise
   // (YAML 1.2 §6.9.1); an explicit '!' on any other node means the same as no tag
   const tag = node.tag?.explicitName;
-  if (tag !== undefined && tag !== (node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyle.Plain ? '?' : '!')) {
+  if (tag !== undefined && tag !== (node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__.YamlStyle.Plain ? '?' : '!')) {
     yamlStyle.tag = tag;
   }
   // the anchor's name, without the & indicator
@@ -95687,17 +95701,17 @@ const collectStreamComments = node => {
     if (!root) comments.before.push(text);else if (comment.startLine === root.endLine) comments.inline.push(text);else comments.after.push(text);
   };
   for (const child of node.children) {
-    if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isDocument)(child)) {
+    if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_13__.isDocument)(child)) {
       if (root) break;
       // comments after an explicit document start (---) or before an explicit document end (...)
       // are the document's own children, around its root node
       const children = child.children || [];
-      const rootIndex = children.findIndex(c => !(0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isComment)(c));
+      const rootIndex = children.findIndex(c => !(0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_13__.isComment)(c));
       if (rootIndex === -1) break;
-      children.slice(0, rootIndex).filter(_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isComment).forEach(collect);
+      children.slice(0, rootIndex).filter(_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_13__.isComment).forEach(collect);
       root = children[rootIndex];
-      children.slice(rootIndex + 1).filter(_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isComment).forEach(collect);
-    } else if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isComment)(child)) {
+      children.slice(rootIndex + 1).filter(_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_13__.isComment).forEach(collect);
+    } else if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_13__.isComment)(child)) {
       collect(child);
     }
   }
@@ -95710,7 +95724,7 @@ const transformStream = (node, ctx) => {
   if (ctx.style) {
     ctx.indent = detectIndent(node);
   }
-  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__["default"]();
+  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_10__["default"]();
 
   // Transform all children
   const children = transformChildren(node.children || [], ctx);
@@ -95770,7 +95784,7 @@ const transformDocument = (node, ctx) => {
   const shouldSkipVisitingMoreDocuments = ctx.processedDocumentCount >= 1;
   if (shouldWarnAboutMoreDocuments) {
     const message = 'Only first document within YAML stream will be used. Rest will be discarded.';
-    const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__["default"](message);
+    const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__["default"](message);
     element.classes.push('warning');
     maybeAddSourceMap(node, element, ctx);
     ctx.annotations.push(element);
@@ -95789,7 +95803,7 @@ const transformCollection = (element, node, ctx) => {
   const typedNode = node;
   const children = node.children || [];
   if (ctx.style) {
-    if (ctx.flowCollectionPadding === null && node.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Flow) {
+    if (ctx.flowCollectionPadding === null && node.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__.YamlStyleGroup.Flow) {
       ctx.flowCollectionPadding = detectFlowPadding(typedNode);
     }
     const comments = collectComments(children, typedNode.startCharacter);
@@ -95800,7 +95814,7 @@ const transformCollection = (element, node, ctx) => {
     element.style = buildYamlStyle(node, ctx, {
       comment: comments.trailing,
       // a single pair written directly in a flow sequence (e.g. [a: 1])
-      singlePair: node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyle.SinglePair || undefined
+      singlePair: node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__.YamlStyle.SinglePair || undefined
     });
     if (comments.outOfScope.length > 0) {
       ctx.promotedComments.push(...comments.outOfScope);
@@ -95813,14 +95827,14 @@ const transformCollection = (element, node, ctx) => {
 
 // Mapping: Transforms to ObjectElement
 const transformMapping = (node, ctx) => {
-  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"]();
+  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__["default"]();
   transformCollection(element, node, ctx);
   return element;
 };
 
 // KeyValuePair: Transforms to MemberElement
 const transformKeyValuePair = (node, ctx) => {
-  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]();
+  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__["default"]();
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const {
     key,
@@ -95831,15 +95845,25 @@ const transformKeyValuePair = (node, ctx) => {
       styleGroup,
       startCharacter
     } = value;
-    if (styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Block) {
+    if (styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__.YamlStyleGroup.Block) {
       ctx.indentSeq = startCharacter > node.startCharacter;
     }
   }
 
   // Transform key and value (these are dynamically defined properties)
-  const keyResult = transform(key, ctx);
+  let keyResult = transform(key, ctx);
   const valueResult = transform(value, ctx);
 
+  // an empty key is a null in YAML, but a JavaScript property name can't be null, so it's the empty
+  // string it's named by, marked as an empty key
+  if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isNullElement)(keyResult) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__.includesClasses)(keyResult, ['yaml-e-node'])) {
+    const emptyKey = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"]('', keyResult.meta, keyResult.attributes);
+    emptyKey.classes.push('yaml-e-key');
+    _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_11__["default"].transfer(keyResult, emptyKey);
+    _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_12__["default"].transfer(keyResult, emptyKey);
+    keyResult = emptyKey;
+  }
+
   // @ts-ignore
   element.content.key = keyResult;
   // @ts-ignore
@@ -95859,19 +95883,18 @@ const transformKeyValuePair = (node, ctx) => {
 
 // Sequence: Transforms to ArrayElement
 const transformSequence = (node, ctx) => {
-  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]();
+  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__["default"]();
   transformCollection(element, node, ctx);
   return element;
 };
 
 // Scalar: Converts to Element via namespace
 const transformScalar = (node, ctx) => {
-  const element = ctx.namespace.toElement(node.content);
-
-  // Translate style information about empty nodes; an empty node (YAML 1.2 §7.2) is a null unless
-  // a tag other than the null tag makes it something else (e.g. !!str makes it an empty string)
+  // an empty node (YAML 1.2 §7.2) is a null unless a tag other than the null tag makes it
+  // something else (e.g. !!str makes it an empty string); its classes tell it from an explicit null
   const tag = node.tag?.explicitName;
-  const isEmptyNode = node.content === '' && node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyle.Plain && [undefined, '?', '!!null', '!<tag:yaml.org,2002:null>'].includes(tag);
+  const isEmptyNode = node.content === '' && node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__.YamlStyle.Plain && [undefined, '?', '!!null', '!<tag:yaml.org,2002:null>'].includes(tag);
+  const element = isEmptyNode ? new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]() : ctx.namespace.toElement(node.content);
   if (isEmptyNode) {
     element.classes.push('yaml-e-node');
     element.classes.push('yaml-e-scalar');
@@ -95899,7 +95922,7 @@ const transformComment = (node, ctx) => {
   // Only interested in stream comments before the first document
   if (isStreamComment) {
     // @ts-ignore
-    const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__["default"](node.content);
+    const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_9__["default"](node.content);
     maybeAddSourceMap(node, element, ctx);
     return element;
   }
@@ -95910,7 +95933,7 @@ const transformComment = (node, ctx) => {
 const transformLiteral = (node, ctx) => {
   if (node.isMissing) {
     const message = `(Missing ${node.value})`;
-    const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__["default"](message);
+    const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__["default"](message);
     element.classes.push('warning');
     maybeAddSourceMap(node, element, ctx);
     ctx.annotations.push(element);
@@ -95921,7 +95944,7 @@ const transformLiteral = (node, ctx) => {
 // Error as annotation (used by keyValuePair)
 const transformErrorAsAnnotation = (node, ctx) => {
   const message = node.isUnexpected ? '(Unexpected YAML syntax error)' : '(Error YAML syntax error)';
-  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__["default"](message);
+  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__["default"](message);
   element.classes.push('error');
   maybeAddSourceMap(node, element, ctx);
   ctx.annotations.push(element);
@@ -95930,7 +95953,7 @@ const transformErrorAsAnnotation = (node, ctx) => {
 // Error: Creates error annotation (adds to annotations array)
 const transformError = (node, ctx) => {
   const message = node.isUnexpected ? '(Unexpected YAML syntax error)' : '(Error YAML syntax error)';
-  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__["default"](message);
+  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__["default"](message);
   element.classes.push('error');
   maybeAddSourceMap(node, element, ctx);
   ctx.annotations.push(element);
@@ -95940,10 +95963,10 @@ const transformError = (node, ctx) => {
 // Error at root level: Creates ParseResultElement with error annotation
 const transformRootError = (node, ctx) => {
   const message = node.isUnexpected ? '(Unexpected YAML syntax error)' : '(Error YAML syntax error)';
-  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__["default"](message);
+  const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__["default"](message);
   element.classes.push('error');
   maybeAddSourceMap(node, element, ctx);
-  const parseResultElement = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__["default"]();
+  const parseResultElement = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_10__["default"]();
   parseResultElement.push(element);
   return parseResultElement;
 };
@@ -95970,7 +95993,7 @@ const transformYamlAstToApiDOM = (yamlAst, {
 
   // Handle empty parse result
   if (!rootNode) {
-    return new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__["default"]();
+    return new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_10__["default"]();
   }
 
   // Handle root-level error (no valid stream, just an error node)
@@ -95980,12 +96003,12 @@ const transformYamlAstToApiDOM = (yamlAst, {
   const result = transform(rootNode, ctx);
 
   // Result should be a ParseResultElement from transformStream
-  if (result instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__["default"]) {
+  if (result instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_10__["default"]) {
     return result;
   }
 
   // Fallback: wrap in ParseResultElement
-  const parseResult = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__["default"]();
+  const parseResult = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_10__["default"]();
   if (result !== null) {
     if (Array.isArray(result)) {
       result.forEach(el => parseResult.push(el));
@@ -97926,7 +97949,6 @@ class BundleStrategy {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(80796);
 /* harmony import */ var _speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(53787);
@@ -98574,7 +98596,6 @@ class Arazzo1BundleVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(80796);
 /* harmony import */ var _speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(46417);
@@ -99052,6 +99073,11 @@ class AsyncAPI2BundleVisitor {
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;
@@ -99288,7 +99314,6 @@ class AsyncAPI2BundleVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(80796);
 /* harmony import */ var _speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(3677);
@@ -99723,6 +99748,10 @@ class OpenAPI2BundleVisitor {
    * and refraction helpers, so the shared logic is parameterized here.
    */
   async bundleReference(path, referencingElement, isSemanticReference, isReferenceLike, refractReferenceFn, label) {
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;
@@ -99979,7 +100008,6 @@ class OpenAPI2BundleVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(80796);
 /* harmony import */ var _speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(43151);
@@ -100432,6 +100460,11 @@ class OpenAPI3_0BundleVisitor {
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;
@@ -100567,98 +100600,108 @@ class OpenAPI3_0BundleVisitor {
    * Path Item Object is not a Components Object field in OpenAPI 3.0
    * (unlike 3.1 which has `components.pathItems`). An external Path Item
    * reference therefore cannot be hoisted; it is inlined in place instead,
-   * after bundling its own external references.
+   * after bundling its own external references. It is inlined on leave, once
+   * the sibling fields of the referencing Path Item have been bundled, so the
+   * traversal doesn't descend into the inlined copy and inline the `$ref` left
+   * in it to break a cycle again.
    */
-  async PathItemElement(path) {
-    const pathItemElement = path.node;
-
-    // ignore Path Item Objects without a $ref field
-    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(pathItemElement.$ref)) {
-      return;
-    }
-    const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(pathItemElement.$ref);
-    const retrievalURI = this.toBaseURI($ref);
-    const isInternalReference = this.entryURI === retrievalURI;
-    const isExternalReference = !isInternalReference;
-    if (isInternalReference) {
-      // normalize self-references to a bare fragment so the bundled
-      // document stays transferable; bare fragments are left untouched
-      pathItemElement.set('$ref', this.normalizeSelfReference($ref));
-      return;
-    }
-
-    // honor the resolve.external switch
-    if (!this.options.resolve.external && isExternalReference) {
-      return;
-    }
-    const $refBaseURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_29__.resolve(retrievalURI, $ref);
-    const jsonPointer = _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_11__.URIFragmentIdentifier.fromURIReference($refBaseURI);
-    const canonicalKey = `${retrievalURI}#${jsonPointer}`;
+  PathItemElement = {
+    leave: async path => {
+      const pathItemElement = path.node;
 
-    // a circular external Path Item reference cannot be inlined without
-    // recursing forever; leave the $ref in place to break the cycle
-    if (this.inlineStack.has(canonicalKey)) {
-      return;
-    }
-    try {
-      // detect maximum depth of bundling
-      if (this.reference.depth >= this.options.bundle.maxDepth) {
-        throw new _errors_MaximumBundleDepthError_mjs__WEBPACK_IMPORTED_MODULE_27__["default"](`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
-          maxDepth: this.options.bundle.maxDepth,
-          uri: this.reference.uri
-        });
+      // ignore Path Item Objects without a $ref field
+      if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(pathItemElement.$ref)) {
+        return;
+      }
+      const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(pathItemElement.$ref);
+      const retrievalURI = this.toBaseURI($ref);
+      const isInternalReference = this.entryURI === retrievalURI;
+      const isExternalReference = !isInternalReference;
+      if (isInternalReference) {
+        // normalize self-references to a bare fragment so the bundled
+        // document stays transferable; bare fragments are left untouched
+        pathItemElement.set('$ref', this.normalizeSelfReference($ref));
+        return;
       }
-      const reference = await this.toReference($ref);
-      let referencedElement = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_10__.evaluate)(reference.value.result, jsonPointer);
 
-      // apply Path Item semantics to the referenced fragment
-      if (!(0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_13__.isPathItemElement)(referencedElement)) {
-        const cached = this.getRefracted(referencedElement, 'pathItem');
-        if (cached !== undefined) {
-          referencedElement = cached;
-        } else {
-          const sourceElement = referencedElement;
-          referencedElement = (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.refractPathItem)(referencedElement);
-          this.setRefracted(sourceElement, 'pathItem', referencedElement);
+      // honor the resolve.external switch
+      if (!this.options.resolve.external && isExternalReference) {
+        return;
+      }
+      const $refBaseURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_29__.resolve(retrievalURI, $ref);
+      const jsonPointer = _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_11__.URIFragmentIdentifier.fromURIReference($refBaseURI);
+      const canonicalKey = `${retrievalURI}#${jsonPointer}`;
+
+      // a circular external Path Item reference cannot be inlined without
+      // recursing forever; leave the $ref in place to break the cycle. It ends
+      // up in the entry document, so it has to resolve from there
+      if (this.inlineStack.has(canonicalKey)) {
+        const targetURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_29__.resolve(this.reference.uri, $ref);
+        if (_util_url_mjs__WEBPACK_IMPORTED_MODULE_29__.resolve(this.entryURI, $ref) !== targetURI) {
+          pathItemElement.set('$ref', _util_url_mjs__WEBPACK_IMPORTED_MODULE_29__.relative(this.entryURI, targetURI));
         }
+        return;
       }
-
-      // own a copy and bundle the external references it contains
-      const inlinedElement = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.cloneDeep)(referencedElement);
-      this.inlineStack.add(canonicalKey);
-      const visitor = new OpenAPI3_0BundleVisitor({
-        reference,
-        options: this.options,
-        assignments: this.assignments,
-        reservedNames: this.reservedNames,
-        refractCache: this.refractCache,
-        inlineStack: this.inlineStack
-      });
-      let bundledElement;
       try {
-        bundledElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_9__.traverseAsync)(inlinedElement, visitor, {
-          mutable: true
+        // detect maximum depth of bundling
+        if (this.reference.depth >= this.options.bundle.maxDepth) {
+          throw new _errors_MaximumBundleDepthError_mjs__WEBPACK_IMPORTED_MODULE_27__["default"](`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+            maxDepth: this.options.bundle.maxDepth,
+            uri: this.reference.uri
+          });
+        }
+        const reference = await this.toReference($ref);
+        let referencedElement = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_10__.evaluate)(reference.value.result, jsonPointer);
+
+        // apply Path Item semantics to the referenced fragment
+        if (!(0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_13__.isPathItemElement)(referencedElement)) {
+          const cached = this.getRefracted(referencedElement, 'pathItem');
+          if (cached !== undefined) {
+            referencedElement = cached;
+          } else {
+            const sourceElement = referencedElement;
+            referencedElement = (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.refractPathItem)(referencedElement);
+            this.setRefracted(sourceElement, 'pathItem', referencedElement);
+          }
+        }
+
+        // own a copy and bundle the external references it contains
+        const inlinedElement = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.cloneDeep)(referencedElement);
+        this.inlineStack.add(canonicalKey);
+        const visitor = new OpenAPI3_0BundleVisitor({
+          reference,
+          options: this.options,
+          assignments: this.assignments,
+          reservedNames: this.reservedNames,
+          refractCache: this.refractCache,
+          inlineStack: this.inlineStack
         });
-      } finally {
-        this.inlineStack.delete(canonicalKey);
-      }
+        let bundledElement;
+        try {
+          bundledElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_9__.traverseAsync)(inlinedElement, visitor, {
+            mutable: true
+          });
+        } finally {
+          this.inlineStack.delete(canonicalKey);
+        }
 
-      // merge sibling fields from the referencing Path Item over the referenced
-      // one. The referencing `$ref` is being resolved away and is skipped; the
-      // referenced element keeps its own `$ref` if one survived (i.e. it was
-      // left in place to break a circular external Path Item chain).
-      pathItemElement.forEach((_value, keyElement, item) => {
-        const key = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(keyElement);
-        if (key === '$ref') return;
-        bundledElement.remove(key);
-        bundledElement.content.push(item);
-      });
-      bundledElement.meta.set('ref-origin', reference.uri);
-      path.replaceWith(bundledElement);
-    } catch (error) {
-      this.handleError(`Error while bundling Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, pathItemElement, '$ref', $ref, path);
+        // merge sibling fields from the referencing Path Item over the referenced
+        // one. The referencing `$ref` is being resolved away and is skipped; the
+        // referenced element keeps its own `$ref` if one survived (i.e. it was
+        // left in place to break a circular external Path Item chain).
+        pathItemElement.forEach((_value, keyElement, item) => {
+          const key = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_6__["default"])(keyElement);
+          if (key === '$ref') return;
+          bundledElement.remove(key);
+          bundledElement.content.push(item);
+        });
+        bundledElement.meta.set('ref-origin', reference.uri);
+        path.replaceWith(bundledElement);
+      } catch (error) {
+        this.handleError(`Error while bundling Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, pathItemElement, '$ref', $ref, path);
+      }
     }
-  }
+  };
 
   /**
    * Example Object `externalValue` points at arbitrary external content that
@@ -100760,7 +100803,6 @@ class OpenAPI3_0BundleVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(80796);
 /* harmony import */ var _speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(7822);
@@ -101319,6 +101361,11 @@ class OpenAPI3_1BundleVisitor {
   };
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_8__["default"])(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;
@@ -102293,7 +102340,6 @@ class DereferenceStrategy {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(25162);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(80796);
@@ -102396,7 +102442,6 @@ class ApiDOMDereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPORT
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var ramda_adjunct__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(33031);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(25162);
 /* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(44673);
@@ -102742,13 +102787,6 @@ class ApiDOMDereferenceVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(96911);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(18252);
@@ -102759,8 +102797,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _Reference_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(82302);
 /* harmony import */ var _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(88526);
 /* harmony import */ var _visitor_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(55890);
-/* harmony import */ var _openapi_3_1_util_mjs__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(29587);
-/* harmony import */ var _source_descriptions_mjs__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(54553);
+/* harmony import */ var _openapi_3_1_util_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(29587);
+/* harmony import */ var _source_descriptions_mjs__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(54553);
 
 
 
@@ -102824,7 +102862,7 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPOR
     const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
       reference,
       options,
-      ancestorSchema$ids: (0,_openapi_3_1_util_mjs__WEBPACK_IMPORTED_MODULE_11__.detachedRootSchema$ids)(refSet.rootRef.value.result)
+      ancestorSchema$ids: (0,_openapi_3_1_util_mjs__WEBPACK_IMPORTED_MODULE_10__.detachedRootSchema$ids)(refSet.rootRef.value.result)
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.traverseAsync)(refSet.rootRef.value, visitor, {
       mutable: true,
@@ -102854,7 +102892,7 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPOR
       // drop any existing parse-phase source description results before pushing
       const cleaned = parseResult.reject(item => (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isParseResultElement)(item) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.includesClasses)(item, ['source-description']));
       parseResult.content = cleaned.content;
-      const sourceDescriptions = await (0,_source_descriptions_mjs__WEBPACK_IMPORTED_MODULE_12__.dereferenceSourceDescriptions)(parseResult, reference.uri, options, this.name);
+      const sourceDescriptions = await (0,_source_descriptions_mjs__WEBPACK_IMPORTED_MODULE_11__.dereferenceSourceDescriptions)(parseResult, reference.uri, options, this.name);
       parseResult.push(...sourceDescriptions);
     }
 
@@ -103947,7 +103985,6 @@ class Arazzo1DereferenceVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(80796);
 /* harmony import */ var _speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(46417);
@@ -104276,6 +104313,11 @@ class AsyncAPI2DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();
@@ -104605,7 +104647,6 @@ class AsyncAPI2DereferenceVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(3677);
 /* harmony import */ var _speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(26365);
@@ -104938,6 +104979,11 @@ class OpenAPI2DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();
@@ -105241,6 +105287,11 @@ class OpenAPI2DereferenceVisitor {
   async JSONReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();
@@ -105403,7 +105454,6 @@ class OpenAPI2DereferenceVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(80796);
 /* harmony import */ var _speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(43151);
@@ -105735,6 +105785,11 @@ class OpenAPI3_0DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();
@@ -106184,10 +106239,6 @@ class OpenAPI3_0DereferenceVisitor {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(6352);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(12111);
 /* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(80796);
@@ -106197,7 +106248,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _Reference_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(82302);
 /* harmony import */ var _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(88526);
 /* harmony import */ var _visitor_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(56519);
-/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(29587);
+/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(29587);
 
 
 
@@ -106261,7 +106312,7 @@ class OpenAPI3_1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IM
     const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]({
       reference: reference,
       options,
-      ancestorSchema$ids: (0,_util_mjs__WEBPACK_IMPORTED_MODULE_10__.detachedRootSchema$ids)(refSet.rootRef.value.result)
+      ancestorSchema$ids: (0,_util_mjs__WEBPACK_IMPORTED_MODULE_9__.detachedRootSchema$ids)(refSet.rootRef.value.result)
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_2__.traverseAsync)(refSet.rootRef.value, visitor, {
       mutable: true,
@@ -106923,6 +106974,11 @@ class OpenAPI3_1DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been accessed
     if (this.indirections.includes(referencingElement)) {
       path.skip();
@@ -107700,6 +107756,8 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+const STRATEGY_NAME = 'overlay-1';
+
 /**
  * Dereferences the `extends` target document from an Overlay document's ParseResult.
  *
@@ -107741,39 +107799,61 @@ async function dereferenceExtends(parseResult, parseResultRetrievalURI, options)
   const extendsDereferenceResult = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"]();
   extendsDereferenceResult.classes.push('extends');
   extendsDereferenceResult.setMetaProperty('retrievalURI', retrievalURI);
-  try {
-    let extendsDereferenced;
 
-    // check if extends was already parsed (e.g., during parse phase with extends: true)
-    const existingParseResult = extendsElement.meta.get('parseResult');
-    if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isParseResultElement)(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      extendsDereferenced = await (0,_index_mjs__WEBPACK_IMPORTED_MODULE_10__.dereferenceApiDOM)(existingParseResult, (0,_options_util_mjs__WEBPACK_IMPORTED_MODULE_9__.merge)(options, {
-        parse: {
-          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
-        },
-        resolve: {
-          baseURI: retrievalURI
-        }
-      }));
-    } else {
-      // no existing parse result - fetch, parse, and dereference
-      extendsDereferenced = await (0,_index_mjs__WEBPACK_IMPORTED_MODULE_10__["default"])(retrievalURI, (0,_options_util_mjs__WEBPACK_IMPORTED_MODULE_9__.merge)(options, {
-        parse: {
-          mediaType: 'text/plain' // allow parser plugin detection
+  // URIs of the Overlays currently being dereferenced, from the root down to the current one
+  const ancestors = [...(options?.dereference?.strategyOpts?.[STRATEGY_NAME]?.extendsAncestors ?? []), file.uri];
+  const nestedOptions = {
+    dereference: {
+      strategyOpts: {
+        [STRATEGY_NAME]: {
+          extendsAncestors: ancestors
         }
-      }));
+      }
     }
+  };
 
-    // merge dereferenced result into our wrapper
-    for (const item of extendsDereferenced) {
-      extendsDereferenceResult.push(item);
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`Error dereferencing extends target "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
+  // skip if the target is still being dereferenced higher up the chain (cycle detection)
+  if (ancestors.includes(retrievalURI)) {
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`Extends target "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
+    annotation.classes.push('warning');
     extendsDereferenceResult.push(annotation);
+  } else {
+    try {
+      let extendsDereferenced;
+
+      // check if extends was already parsed (e.g., during parse phase with extends: true)
+      const existingParseResult = extendsElement.meta.get('parseResult');
+      if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isParseResultElement)(existingParseResult)) {
+        // use existing parsed result - just dereference it (no re-fetch/re-parse)
+        extendsDereferenced = await (0,_index_mjs__WEBPACK_IMPORTED_MODULE_10__.dereferenceApiDOM)(existingParseResult, (0,_options_util_mjs__WEBPACK_IMPORTED_MODULE_9__.merge)(options, {
+          ...nestedOptions,
+          parse: {
+            mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
+          },
+          resolve: {
+            baseURI: retrievalURI
+          }
+        }));
+      } else {
+        // no existing parse result - fetch, parse, and dereference
+        extendsDereferenced = await (0,_index_mjs__WEBPACK_IMPORTED_MODULE_10__["default"])(retrievalURI, (0,_options_util_mjs__WEBPACK_IMPORTED_MODULE_9__.merge)(options, {
+          ...nestedOptions,
+          parse: {
+            mediaType: 'text/plain' // allow parser plugin detection
+          }
+        }));
+      }
+
+      // merge dereferenced result into our wrapper
+      for (const item of extendsDereferenced) {
+        extendsDereferenceResult.push(item);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](`Error dereferencing extends target "${retrievalURI}": ${message}`);
+      annotation.classes.push('error');
+      extendsDereferenceResult.push(annotation);
+    }
   }
 
   // always attach result to extends element meta (even on failure - contains annotations)
@@ -107792,17 +107872,16 @@ async function dereferenceExtends(parseResult, parseResultRetrievalURI, options)
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
-/* empty/unused harmony star reexport */
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
-/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(13786);
-/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(26432);
-/* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(80796);
-/* harmony import */ var _DereferenceStrategy_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(12993);
-/* harmony import */ var _Reference_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(82302);
-/* harmony import */ var _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(88526);
-/* harmony import */ var _extends_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(51826);
-/* harmony import */ var _visitor_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(64595);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(96911);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(12111);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(13786);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(26432);
+/* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(80796);
+/* harmony import */ var _DereferenceStrategy_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(12993);
+/* harmony import */ var _Reference_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(82302);
+/* harmony import */ var _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(88526);
+/* harmony import */ var _extends_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(51826);
+/* harmony import */ var _visitor_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(64595);
 
 
 
@@ -107817,7 +107896,7 @@ __webpack_require__.r(__webpack_exports__);
 /**
  * @public
  */
-class Overlay1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPORTED_MODULE_4__["default"] {
+class Overlay1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPORTED_MODULE_5__["default"] {
   constructor(options) {
     super({
       ...(options ?? {}),
@@ -107827,18 +107906,18 @@ class Overlay1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPO
   canDereference(file) {
     // assert by media type
     if (file.mediaType !== 'text/plain') {
-      return _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__["default"].includes(file.mediaType);
+      return _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__["default"].includes(file.mediaType);
     }
 
     // assert by inspecting ApiDOM
-    return (0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.isOverlay1Element)(file.parseResult?.result);
+    return (0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_3__.isOverlay1Element)(file.parseResult?.result);
   }
   async dereference(file, options) {
-    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]();
-    const mutableRefSet = new _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]();
+    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]();
+    const mutableRefSet = new _ReferenceSet_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]();
     let reference;
     if (!immutableRefSet.has(file.uri)) {
-      reference = new _Reference_mjs__WEBPACK_IMPORTED_MODULE_5__["default"]({
+      reference = new _Reference_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]({
         uri: file.uri,
         value: file.parseResult
       });
@@ -107853,39 +107932,51 @@ class Overlay1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPO
      * We don't want to mutate the original refSet and the references.
      */
     if (options.dereference.immutable) {
-      immutableRefSet.refs.map(ref => new _Reference_mjs__WEBPACK_IMPORTED_MODULE_5__["default"]({
+      immutableRefSet.refs.map(ref => new _Reference_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]({
         ...ref,
-        value: (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(ref.value)
+        value: (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(ref.value)
       })).forEach(ref => mutableRefSet.add(ref));
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
     }
-    const dereferencedElement = reference.value;
-
-    /**
-     * Reusable Action References only occur within `actions`, so the root element is never
-     * replaced and traversing it keeps reported locations relative to the document.
-     */
-    const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]({
+    const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
       reference,
       options
     });
-    await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.traverseAsync)(dereferencedElement.result, visitor, {
-      mutable: true
-    });
+    /**
+     * The reference for the dereferenced file is traversed rather than the refSet's root
+     * reference: dereferencing the extends target shares the refSet, whose root is then
+     * the extending Overlay. The reference may hold a lone element.
+     */
+    let dereferencedElement = reference.value;
+
+    /**
+     * A ParseResult may also carry the extends target parsed in the parse phase, whose
+     * references belong to that document, so only its result is traversed. Reusable Action
+     * References only occur within `actions`, so the result itself is never replaced.
+     */
+    if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isParseResultElement)(dereferencedElement)) {
+      await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_4__.traverseAsync)(dereferencedElement.result, visitor, {
+        mutable: true
+      });
+    } else {
+      dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_4__.traverseAsync)(dereferencedElement, visitor, {
+        mutable: true
+      });
+    }
 
     /**
      * Dereference extends target if option is enabled.
      */
     const shouldDereferenceExtends = options?.dereference?.strategyOpts?.[this.name]?.extends ?? options?.dereference?.strategyOpts?.extends;
-    if (shouldDereferenceExtends) {
-      await (0,_extends_mjs__WEBPACK_IMPORTED_MODULE_7__.dereferenceExtends)(dereferencedElement, reference.uri, options);
+    if (shouldDereferenceExtends && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isParseResultElement)(dereferencedElement)) {
+      await (0,_extends_mjs__WEBPACK_IMPORTED_MODULE_8__.dereferenceExtends)(dereferencedElement, reference.uri, options);
     }
 
     /**
      * If immutable option is set, replay refs from the refSet.
      */
     if (options.dereference.immutable) {
-      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference_mjs__WEBPACK_IMPORTED_MODULE_5__["default"]({
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]({
         ...ref,
         uri: ref.uri.replace(/^immutable:\/\//, '')
       })).forEach(ref => immutableRefSet.add(ref));
@@ -107917,17 +108008,22 @@ class Overlay1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPO
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(12111);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(18252);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(25810);
-/* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(44673);
-/* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(16280);
-/* harmony import */ var _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(44641);
-/* harmony import */ var _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(12020);
-/* harmony import */ var _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(61198);
-/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(26432);
-/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(35937);
-/* harmony import */ var _errors_UnresolvableReferenceError_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(34968);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(25162);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(12111);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(18252);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(25810);
+/* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(44673);
+/* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(16280);
+/* harmony import */ var _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(44641);
+/* harmony import */ var _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(12020);
+/* harmony import */ var _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(61198);
+/* harmony import */ var _speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(80796);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(26432);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(35937);
+/* harmony import */ var _errors_UnresolvableReferenceError_mjs__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(34968);
+/* harmony import */ var _util_url_mjs__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(18917);
+
+
 
 
 
@@ -107958,25 +108054,32 @@ class Overlay1DereferenceVisitor {
       path.skip();
       return;
     }
-    const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(referencingElement.$ref);
-    const overlayElement = this.reference.value.result;
-    const actionElement = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_9__.ActionElement();
+    const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.$ref);
+    // the reference may hold a lone element; same-document references resolve against the
+    // document registered in the refSet under the reference's URI without fragment
+    const {
+      refSet
+    } = this.reference;
+    const documentURI = _util_url_mjs__WEBPACK_IMPORTED_MODULE_13__.stripHash(this.reference.uri);
+    const documentReference = refSet.find(ref => ref.uri === documentURI) ?? this.reference;
+    const overlayElement = documentReference.value.result;
+    const actionElement = new _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_11__.ActionElement();
     try {
       if (typeof $ref !== 'string') {
-        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_5__["default"]('Reusable Action Reference "$ref" field must be a string');
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_6__["default"]('Reusable Action Reference "$ref" field must be a string');
       }
 
       // only `target`, `description` and extensions may accompany `$ref`
       const disallowedField = ['update', 'copy', 'remove'].find(field => referencingElement.hasKey(field));
       if (disallowedField !== undefined) {
-        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_5__["default"](`Reusable Action Reference "${$ref}" must not define "${disallowedField}"`, {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_6__["default"](`Reusable Action Reference "${$ref}" must not define "${disallowedField}"`, {
           $ref
         });
       }
 
       // same-document reference only; external references are not supported
       if (!$ref.startsWith('#')) {
-        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_5__["default"](`Reusable Action Reference "${$ref}" must be a same-document reference`, {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_6__["default"](`Reusable Action Reference "${$ref}" must be a same-document reference`, {
           $ref
         });
       }
@@ -107987,25 +108090,25 @@ class Overlay1DereferenceVisitor {
        */
       let reusableAction;
       try {
-        reusableAction = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_6__.evaluate)(overlayElement, _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_7__.URIFragmentIdentifier.from($ref));
+        reusableAction = (0,_speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_7__.evaluate)(overlayElement, _speclynx_apidom_json_pointer__WEBPACK_IMPORTED_MODULE_8__.URIFragmentIdentifier.from($ref));
       } catch {
         reusableAction = undefined;
       }
-      if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_8__.isReusableActionElement)(reusableAction)) {
-        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_5__["default"](`Reusable Action Reference "${$ref}" cannot be resolved`, {
+      if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.isReusableActionElement)(reusableAction)) {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_6__["default"](`Reusable Action Reference "${$ref}" cannot be resolved`, {
           $ref
         });
       }
       const {
         fields
       } = reusableAction;
-      if (fields !== undefined && !(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_8__.isActionElement)(fields)) {
-        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_5__["default"](`Reusable Action "${$ref}" must define "fields" as an object`, {
+      if (fields !== undefined && !(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.isActionElement)(fields)) {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_6__["default"](`Reusable Action "${$ref}" must define "fields" as an object`, {
           $ref
         });
       }
-      if ((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_8__.isActionElement)(fields) && fields.hasKey('target')) {
-        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_5__["default"](`Reusable Action "${$ref}" must not define "target" in its "fields"`, {
+      if ((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.isActionElement)(fields) && fields.hasKey('target')) {
+        throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_6__["default"](`Reusable Action "${$ref}" must not define "target" in its "fields"`, {
           $ref
         });
       }
@@ -108016,26 +108119,41 @@ class Overlay1DereferenceVisitor {
         description
       } = referencingElement;
       if (target !== undefined) {
-        actionElement.set('target', (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(target));
+        actionElement.set('target', (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(target));
       }
-      if ((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_8__.isActionElement)(fields)) {
+      if ((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_10__.isActionElement)(fields)) {
         fields.forEach((value, keyElement) => {
-          actionElement.set((0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(keyElement), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(value));
+          actionElement.set((0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(keyElement), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(value));
         });
       }
       if (description !== undefined) {
-        actionElement.set('description', (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(description));
+        actionElement.set('description', (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(description));
       }
     } catch (error) {
       const {
         continueOnError
       } = this.options.dereference;
-      const unresolvedError = new _errors_UnresolvableReferenceError_mjs__WEBPACK_IMPORTED_MODULE_10__["default"](`Error while dereferencing Reusable Action Reference "${$ref}": ${error.message}`, {
+
+      // find element location by identity in the document tree;
+      // falls back to the visitor path when the document doesn't contain the element
+      let location;
+      if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isElement)(overlayElement)) {
+        (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_9__.traverse)(overlayElement, {
+          enter: p => {
+            if (p.node === referencingElement) {
+              location = p.formatPath();
+              p.stop();
+            }
+          }
+        });
+      }
+      location ??= path.formatPath();
+      const unresolvedError = new _errors_UnresolvableReferenceError_mjs__WEBPACK_IMPORTED_MODULE_12__["default"](`Error while dereferencing Reusable Action Reference "${$ref}": ${error.message}`, {
         cause: error,
         type: referencingElement.element,
         uri: this.reference.uri,
-        location: path.formatPath(),
-        codeFrame: (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement),
+        location,
+        codeFrame: (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_5__["default"])(referencingElement),
         refFieldName: '$ref',
         refFieldValue: $ref,
         trace: []
@@ -108047,14 +108165,14 @@ class Overlay1DereferenceVisitor {
     }
 
     // the action takes the place of the reference in `actions`, so it inherits its source position
-    if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.hasElementSourceMap)(referencingElement)) {
-      _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"].transfer(referencingElement, actionElement);
+    if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.hasElementSourceMap)(referencingElement)) {
+      _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"].transfer(referencingElement, actionElement);
     }
 
     // annotate with info about original referencing element
     actionElement.meta.set('ref-fields', {
       $ref,
-      description: (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(referencingElement.description)
+      description: (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.description)
     });
     // annotate with info about origin
     actionElement.meta.set('ref-origin', this.reference.uri);
@@ -109300,7 +109418,6 @@ class ApiDOMJSONParser extends _Parser_mjs__WEBPACK_IMPORTED_MODULE_4__["default
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(14494);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_json_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6017);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_json_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(29028);
@@ -109611,7 +109728,6 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(14494);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_yaml_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(16206);
 /* harmony import */ var _speclynx_apidom_parser_adapter_arazzo_yaml_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(43195);
@@ -110374,6 +110490,8 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+ // shared key for recursion state (works across JSON/YAML parsers)
+const OVERLAY_RECURSION_KEY = 'overlay-1';
 
 /**
  * Parses the `extends` target document from an Overlay document's ParseResult.
@@ -110411,21 +110529,38 @@ async function parseExtends(parseResult, parseResultRetrievalURI, options) {
   const extendsParseResult = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]();
   extendsParseResult.classes.push('extends');
   extendsParseResult.setMetaProperty('retrievalURI', retrievalURI);
-  try {
-    const targetParseResult = await (0,_index_mjs__WEBPACK_IMPORTED_MODULE_8__["default"])(retrievalURI, (0,_options_util_mjs__WEBPACK_IMPORTED_MODULE_7__.merge)(options, {
-      parse: {
-        mediaType: 'text/plain' // force auto-detection
+
+  // URIs of the Overlays currently being parsed, from the root down to the current one
+  const ancestors = [...(options?.parse?.parserOpts?.[OVERLAY_RECURSION_KEY]?.extendsAncestors ?? []), file.uri];
+
+  // skip if the target is still being parsed higher up the chain (cycle detection)
+  if (ancestors.includes(retrievalURI)) {
+    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__["default"](`Extends target "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
+    annotation.classes.push('warning');
+    extendsParseResult.push(annotation);
+  } else {
+    try {
+      const targetParseResult = await (0,_index_mjs__WEBPACK_IMPORTED_MODULE_8__["default"])(retrievalURI, (0,_options_util_mjs__WEBPACK_IMPORTED_MODULE_7__.merge)(options, {
+        parse: {
+          mediaType: 'text/plain',
+          // force auto-detection
+          parserOpts: {
+            [OVERLAY_RECURSION_KEY]: {
+              extendsAncestors: ancestors
+            }
+          }
+        }
+      }));
+      // merge parsed result into our wrapper
+      for (const item of targetParseResult) {
+        extendsParseResult.push(item);
       }
-    }));
-    // merge parsed result into our wrapper
-    for (const item of targetParseResult) {
-      extendsParseResult.push(item);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__["default"](`Error parsing extends target "${retrievalURI}": ${message}`);
+      annotation.classes.push('error');
+      extendsParseResult.push(annotation);
     }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const annotation = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__["default"](`Error parsing extends target "${retrievalURI}": ${message}`);
-    annotation.classes.push('error');
-    extendsParseResult.push(annotation);
   }
 
   // always attach result to extends element meta (even on failure - contains annotations)
@@ -110440,7 +110575,6 @@ async function parseExtends(parseResult, parseResultRetrievalURI, options) {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(14494);
 /* harmony import */ var _speclynx_apidom_parser_adapter_overlay_json_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(85086);
 /* harmony import */ var _speclynx_apidom_parser_adapter_overlay_json_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(54827);
@@ -110522,7 +110656,6 @@ class OverlayJSON1Parser extends _Parser_mjs__WEBPACK_IMPORTED_MODULE_4__["defau
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
-/* empty/unused harmony star reexport */
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(14494);
 /* harmony import */ var _speclynx_apidom_parser_adapter_overlay_yaml_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(98585);
 /* harmony import */ var _speclynx_apidom_parser_adapter_overlay_yaml_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(83004);