@usearazzo/resolver 1.0.1-alpha.17 → 1.0.1-alpha.19

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.0.1-alpha.19](https://github.com/usearazzo/arazzo-toolkit/compare/v1.0.1-alpha.18...v1.0.1-alpha.19) (2026-10-31)
+
+### Bug Fixes
+
+- **validator:** accept in: querystring in Arazzo 1.1.0 documents ([#299](https://github.com/usearazzo/arazzo-toolkit/issues/299)) ([4d26bbb](https://github.com/usearazzo/arazzo-toolkit/commit/4d26bbb3fd9c08c1345c51d4d6aae99f4e359f28)), closes [speclynx/api-languageservice#97](https://github.com/speclynx/api-languageservice/issues/97) [#281](https://github.com/usearazzo/arazzo-toolkit/issues/281)
+
+## [1.0.1-alpha.18](https://github.com/usearazzo/arazzo-toolkit/compare/v1.0.1-alpha.17...v1.0.1-alpha.18) (2026-10-30)
+
+**Note:** Version bump only for package @usearazzo/resolver
+
 ## [1.0.1-alpha.17](https://github.com/usearazzo/arazzo-toolkit/compare/v1.0.1-alpha.16...v1.0.1-alpha.17) (2026-10-29)
 
 **Note:** Version bump only for package @usearazzo/resolver

package/dist/arazzo-resolver.browser.js

@@ -2893,11 +2893,8 @@ const serializer = (element, replacer, space, options) => {
 __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(62823);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(74918);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(25035);
-/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(69236);
+/* harmony import */ var _util_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(69236);
 
- // 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.
@@ -2907,7 +2904,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)) {
@@ -2925,8 +2921,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;
     }
@@ -2941,7 +2937,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);
@@ -3309,9 +3304,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(' ');
@@ -3350,7 +3346,10 @@ const toYAMLNode = (element, context) => {
     }
   }
   if ((style.scalarStyle === 'Literal' || style.scalarStyle === 'Folded') && typeof style.rawContent === 'string' && typeof scalar.value === 'string') {
-    const text = style.rawContent.replace(/\r\n/g, '\n').replace(/\n$/, '');
+    const raw = style.rawContent.replace(/\r\n/g, '\n');
+    // the empty lines after a clip or strip block aren't part of its value, but separate it from
+    // what follows in its source, so they're dropped; a keep block's are part of its value
+    const text = raw.replace(/^[|>][1-9]?\+/.test(raw) ? /\n$/ : /\n+$/, '');
     scalar.value = new RawBlockScalar(scalar.value, text);
   }
   if (style.styleGroup === 'Flow' && typeof style.rawContent === 'string' && typeof scalar.value === 'string' && scalar.value !== '') {
@@ -37278,15 +37277,19 @@ const transformCstToYamlAst = (cursor, ctx) => {
 __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(81669);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(62823);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(23560);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(67533);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(32420);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(84149);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(77093);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(52728);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(6361);
-/* harmony import */ var _ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(7775);
-/* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(2995);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(61614);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(27682);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(25035);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(23560);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(67533);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(32420);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(84149);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(77093);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(52728);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(6361);
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(41821);
+/* harmony import */ var _ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(7775);
+/* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_14__ = __webpack_require__(2995);
 
 
  // Transform context passed through transformation
@@ -37296,7 +37299,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
@@ -37314,7 +37317,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;
@@ -37446,7 +37449,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
@@ -37560,17 +37563,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);
     }
   }
@@ -37583,7 +37586,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);
@@ -37643,7 +37646,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);
@@ -37662,7 +37665,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);
@@ -37673,7 +37676,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);
@@ -37686,14 +37689,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,
@@ -37704,15 +37707,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
@@ -37732,19 +37745,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');
@@ -37772,7 +37784,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;
   }
@@ -37783,7 +37795,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);
@@ -37794,7 +37806,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);
@@ -37803,7 +37815,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);
@@ -37813,10 +37825,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;
 };
@@ -37843,7 +37855,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)
@@ -37853,12 +37865,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));
@@ -40880,6 +40892,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;
@@ -41588,6 +41604,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;
@@ -41723,98 +41744,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;
+  PathItemElement = {
+    leave: async 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}`;
-
-    // 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
@@ -42474,6 +42505,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;
@@ -44792,6 +44828,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();
@@ -45095,6 +45136,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();
@@ -45588,6 +45634,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();
@@ -46772,6 +46823,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();
@@ -63396,7 +63452,7 @@ const Ast = function fnast() {
     xml += `<root nodes="${records.length / 2}" characters="${chars.length}">\n`;
     xml += `<!-- input string -->\n`;
     xml += indent(depth + 2);
-    xml += utils.charsToString(chars);
+    xml += utils.charsToXmlString(chars);
     xml += '\n';
     records.forEach((rec) => {
       if (rec.state === id.SEM_PRE) {
@@ -63404,7 +63460,7 @@ const Ast = function fnast() {
         xml += indent(depth);
         xml += `<node name="${rec.name}" index="${rec.phraseIndex}" length="${rec.phraseLength}">\n`;
         xml += indent(depth + 2);
-        xml += utils.charsToString(chars, rec.phraseIndex, rec.phraseLength);
+        xml += utils.charsToXmlString(chars, rec.phraseIndex, rec.phraseLength);
         xml += '\n';
       } else {
         xml += indent(depth);
@@ -63786,6 +63842,14 @@ const utilities = {
     }
     return String.fromCodePoint(...subChars);
   },
+  charsToXmlString: (chars, beg, len) =>
+    utilities
+      .charsToString(chars, beg, len)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/'/g, '&apos;')
+      .replace(/"/g, '&quot;'),
 };
 
 const identifiers = {