npm - @speclynx/apidom-overlay - Versions diffs - 6.1.0 → 6.1.1 - Mend

@speclynx/apidom-overlay 6.1.0 → 6.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md +7 -0
package/README.md +1 -1
package/dist/apidom-overlay.browser.js +467 -337
package/dist/apidom-overlay.browser.min.js +1 -1
package/package.json +9 -9
package/src/diff/realms/apidom.cjs +28 -7
package/src/diff/realms/apidom.mjs +27 -7
package/src/diff/realms/uri.cjs +2 -0
package/src/diff/realms/uri.mjs +3 -1
package/types/apidom-overlay.d.ts +5 -0

package/dist/apidom-overlay.browser.js CHANGED Viewed

@@ -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(' ');
@@ -45399,11 +45419,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 +45592,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 +45717,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 +45781,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 +46877,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 +47118,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 +78061,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 +86342,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 +86351,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 +93058,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 +93220,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 +93242,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 +93262,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 +94363,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 +94472,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 +94484,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 +94504,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 +95412,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 +95434,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 +95452,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 +95584,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 +95698,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 +95721,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 +95781,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 +95800,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 +95811,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 +95824,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 +95842,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 +95880,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 +95919,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 +95930,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 +95941,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 +95950,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 +95960,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 +95990,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 +96000,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 +97946,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 +98593,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 +99070,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 +99311,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 +99745,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 +100005,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 +100457,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 +100597,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 +100800,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 +101358,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 +102337,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 +102439,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 +102784,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 +102794,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 +102859,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 +102889,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 +103982,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 +104310,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 +104644,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 +104976,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 +105284,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 +105451,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 +105782,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 +106236,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 +106245,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 +106309,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 +106971,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 +107753,8 @@ __webpack_require__.r(__webpack_exports__);
+const STRATEGY_NAME = 'overlay-1';
 /**
  * Dereferences the `extends` target document from an Overlay document's ParseResult.
  *
@@ -107741,39 +107796,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 +107869,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 +107893,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 +107903,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 +107929,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 +108005,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 +108051,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 +108087,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 +108116,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 +108162,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 +109415,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 +109725,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 +110487,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 +110526,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 +110572,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 +110653,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);