@speclynx/apidom-overlay 4.7.1 → 4.9.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.9.0](https://github.com/speclynx/apidom/compare/v4.8.0...v4.9.0) (2026-04-17)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+# [4.8.0](https://github.com/speclynx/apidom/compare/v4.7.1...v4.8.0) (2026-04-17)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
 ## [4.7.1](https://github.com/speclynx/apidom/compare/v4.7.0...v4.7.1) (2026-04-16)
 
 **Note:** Version bump only for package @speclynx/apidom-overlay

package/dist/apidom-overlay.browser.js

@@ -39759,13 +39759,14 @@ const dispatchPluginsSync = (element, plugins, options = {}) => {
   const mergedOptions = (0,ramda__WEBPACK_IMPORTED_MODULE_1__["default"])(defaultDispatchPluginsOptions, options);
   const {
     toolboxCreator,
-    visitorOptions
+    visitorOptions,
+    traverseOptions
   } = mergedOptions;
   const toolbox = toolboxCreator();
   const pluginsSpecs = plugins.map(plugin => plugin(toolbox));
   const mergedPluginsVisitor = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_0__.mergeVisitors)(pluginsSpecs.map((0,ramda__WEBPACK_IMPORTED_MODULE_2__["default"])({}, 'visitor')), visitorOptions);
   pluginsSpecs.forEach((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_3__["default"])(['pre'], []));
-  const newElement = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, mergedPluginsVisitor);
+  const newElement = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, mergedPluginsVisitor, traverseOptions);
   pluginsSpecs.forEach((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_3__["default"])(['post'], []));
   return newElement;
 };
@@ -39774,13 +39775,14 @@ const dispatchPluginsAsync = async (element, plugins, options = {}) => {
   const mergedOptions = (0,ramda__WEBPACK_IMPORTED_MODULE_1__["default"])(defaultDispatchPluginsOptions, options);
   const {
     toolboxCreator,
-    visitorOptions
+    visitorOptions,
+    traverseOptions
   } = mergedOptions;
   const toolbox = toolboxCreator();
   const pluginsSpecs = plugins.map(plugin => plugin(toolbox));
   const mergedPluginsVisitor = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_0__.mergeVisitorsAsync)(pluginsSpecs.map((0,ramda__WEBPACK_IMPORTED_MODULE_2__["default"])({}, 'visitor')), visitorOptions);
   await Promise.allSettled(pluginsSpecs.map((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_3__["default"])(['pre'], [])));
-  const newElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_0__.traverseAsync)(element, mergedPluginsVisitor);
+  const newElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_0__.traverseAsync)(element, mergedPluginsVisitor, traverseOptions);
   await Promise.allSettled(pluginsSpecs.map((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_3__["default"])(['post'], [])));
   return newElement;
 };
@@ -91289,12 +91291,16 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPOR
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
       reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -91718,6 +91724,7 @@ class Arazzo1DereferenceVisitor {
   indirections;
   reference;
   options;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -91729,12 +91736,14 @@ class Arazzo1DereferenceVisitor {
     reference,
     options,
     indirections = [],
-    ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_26__.AncestorLineage()
+    ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_26__.AncestorLineage(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_26__.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -92125,17 +92134,23 @@ class Arazzo1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_22__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_11__.isJSONSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_arazzo_1__WEBPACK_IMPORTED_MODULE_11__.isJSONSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new Arazzo1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -92267,12 +92282,16 @@ class AsyncAPI2DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMP
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]({
       reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -92355,6 +92374,7 @@ class AsyncAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -92367,13 +92387,15 @@ class AsyncAPI2DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_17__.AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_17__.AncestorLineage(...ancestors);
     this.refractCache = refractCache;
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -92622,7 +92644,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_18__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.isReferenceElement)(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new AsyncAPI2DereferenceVisitor({
@@ -92630,10 +92656,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -92774,7 +92802,11 @@ class AsyncAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_18__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.isChannelItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_asyncapi_2__WEBPACK_IMPORTED_MODULE_10__.isChannelItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new AsyncAPI2DereferenceVisitor({
@@ -92782,10 +92814,12 @@ class AsyncAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -92904,12 +92938,16 @@ class OpenAPI2DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IMPO
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]({
       reference: reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -92996,6 +93034,7 @@ class OpenAPI2DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -93008,13 +93047,15 @@ class OpenAPI2DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_19__.AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.refractCache = refractCache;
     this.ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_19__.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -93263,7 +93304,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_20__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.isReferenceElement)(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI2DereferenceVisitor({
@@ -93271,10 +93316,12 @@ class OpenAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -93399,7 +93446,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_20__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_14__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI2DereferenceVisitor({
@@ -93407,10 +93458,12 @@ class OpenAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -93554,7 +93607,11 @@ class OpenAPI2DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_20__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_11__.isJSONReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_2__WEBPACK_IMPORTED_MODULE_11__.isJSONReferenceElement)(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI2DereferenceVisitor({
@@ -93562,10 +93619,12 @@ class OpenAPI2DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_7__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -93677,12 +93736,16 @@ class OpenAPI3_0DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IM
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]({
       reference: reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -93766,6 +93829,7 @@ class OpenAPI3_0DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -93778,13 +93842,15 @@ class OpenAPI3_0DereferenceVisitor {
     options,
     indirections = [],
     ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_20__.AncestorLineage(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_20__.AncestorLineage(...ancestors);
     this.refractCache = refractCache;
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -94033,7 +94099,11 @@ class OpenAPI3_0DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_17__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isReferenceElement)(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_0DereferenceVisitor({
@@ -94041,10 +94111,12 @@ class OpenAPI3_0DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -94171,7 +94243,11 @@ class OpenAPI3_0DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_17__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
+
         // append referencing reference to ancestors lineage
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_0DereferenceVisitor({
@@ -94179,10 +94255,12 @@ class OpenAPI3_0DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
 
         // remove referencing reference from ancestors lineage
@@ -94441,12 +94519,16 @@ class OpenAPI3_1DereferenceStrategy extends _DereferenceStrategy_mjs__WEBPACK_IM
       reference = mutableRefSet.find(ref => ref.uri === file.uri);
       refSet = mutableRefSet;
     }
+    const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]({
       reference: reference,
       options
     });
     const dereferencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_2__.traverseAsync)(refSet.rootRef.value, visitor, {
-      mutable: true
+      mutable: true,
+      ...(shouldDetectCircular && {
+        skipVisited: true
+      })
     });
 
     /**
@@ -94767,6 +94849,7 @@ class OpenAPI3_1DereferenceVisitor {
   reference;
   options;
   refractCache;
+  visited;
 
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
@@ -94779,13 +94862,15 @@ class OpenAPI3_1DereferenceVisitor {
     options,
     indirections = [],
     refractCache = new WeakMap(),
-    ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_28__.AncestorLineage()
+    ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_28__.AncestorLineage(),
+    visited = new WeakSet()
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.refractCache = refractCache;
     this.ancestors = new _util_mjs__WEBPACK_IMPORTED_MODULE_28__.AncestorLineage(...ancestors);
+    this.visited = visited;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -95034,17 +95119,22 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_23__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isReferenceElement)(referencedElement) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -95187,17 +95277,22 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_23__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isPathItemElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -95544,17 +95639,22 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = _util_url_mjs__WEBPACK_IMPORTED_MODULE_23__.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+      if ((isExternalReference || isNonEntryDocument || (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isSchemaElement)(referencedElement) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+        if (shouldDetectCircular) {
+          this.visited.add(referencedElement);
+        }
         directAncestors.add(referencingElement);
         const visitor = new OpenAPI3_1DereferenceVisitor({
           reference,
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          visited: this.visited,
           ancestors: ancestorsLineage
         });
         referencedElement = await (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.traverseAsync)(referencedElement, visitor, {
-          mutable: true
+          mutable: true,
+          skipVisited: true
         });
         directAncestors.delete(referencingElement);
       }
@@ -100170,10 +100270,12 @@ function* traverseGenerator(root, visitor, options) {
     nodePredicate,
     nodeCloneFn,
     detectCycles,
+    skipVisited,
     mutable,
     mutationFn
   } = options;
   const keyMapIsFunction = typeof keyMap === 'function';
+  const visitedNodes = skipVisited ? new WeakSet() : null;
   let stack;
   let inArray = Array.isArray(root);
   let keys = [root];
@@ -100259,6 +100361,14 @@ function* traverseGenerator(root, visitor, options) {
         continue;
       }
 
+      // Skip already-visited nodes (handles DAG structures from cloneShallow)
+      if (skipVisited && !isLeaving) {
+        if (visitedNodes.has(node)) {
+          continue;
+        }
+        visitedNodes.add(node);
+      }
+
       // Always create Path for the current node (needed for parentPath chain)
       currentPath = new _Path_mjs__WEBPACK_IMPORTED_MODULE_2__.Path(node, parent, parentPath, key, inArray);
       const visitFn = (0,_visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.getVisitFn)(visitor, nodeTypeGetter(node), isLeaving);
@@ -100402,6 +100512,7 @@ const traverse = (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.cloneNode,
     detectCycles: options.detectCycles ?? true,
+    skipVisited: options.skipVisited ?? false,
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.mutateNode
   };
@@ -100433,6 +100544,7 @@ const traverseAsync = async (root, visitor, options = {}) => {
     nodePredicate: options.nodePredicate ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.isNode,
     nodeCloneFn: options.nodeCloneFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.cloneNode,
     detectCycles: options.detectCycles ?? true,
+    skipVisited: options.skipVisited ?? false,
     mutable: options.mutable ?? false,
     mutationFn: options.mutationFn ?? _visitors_mjs__WEBPACK_IMPORTED_MODULE_3__.mutateNode
   };