@scalar/workspace-store 0.68.3 → 0.68.5

package/dist/helpers/get-async-api-schema-view.js

@@ -0,0 +1,82 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+import { getResolvedAsyncApiRef } from './get-resolved-async-api-ref.js';
+const schemaMaps = new Set(['properties', 'patternProperties', 'definitions', '$defs', 'dependentSchemas']);
+const schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const schemaFields = new Set([
+    'items',
+    'additionalItems',
+    'additionalProperties',
+    'contains',
+    'propertyNames',
+    'not',
+    'if',
+    'then',
+    'else',
+    'unevaluatedItems',
+    'unevaluatedProperties',
+]);
+/**
+ * Give shared schema renderers and example generation an AsyncAPI view without authored
+ * reference siblings. Keep reference wrappers for model links and traverse only schema
+ * positions: examples, defaults, extensions, and property names can contain literal `$ref`s.
+ * The snapshot is local to a read so subsequent reactive edits are not hidden by a cache.
+ */
+export const getAsyncApiSchemaView = (source, schemaFormat) => {
+    // Foreign schema formats own their reference semantics. AsyncAPI's native schemas and
+    // its required JSON Schema draft-07 format both ignore reference siblings.
+    if (schemaFormat &&
+        !/^application\/(?:vnd\.aai\.asyncapi(?:\+json|\+yaml)?(?:;|$)|schema\+(?:json|yaml)(?:;version=draft-07)?$)/i.test(schemaFormat)) {
+        return source;
+    }
+    const seen = new WeakMap();
+    const visit = (value) => {
+        if (!isObject(value)) {
+            return value;
+        }
+        const existing = seen.get(value);
+        if (existing) {
+            return existing;
+        }
+        const result = {};
+        seen.set(value, result);
+        if (typeof value.$ref === 'string') {
+            result.$ref = value.$ref;
+            // Bookkeeping belongs to the store, not the authored Reference Object.
+            for (const key of ['$global', '$status']) {
+                if (Object.hasOwn(value, key)) {
+                    result[key] = value[key];
+                }
+            }
+            Object.defineProperty(result, '$ref-value', {
+                value: visit(getResolvedAsyncApiRef(value)),
+                enumerable: true,
+            });
+            return result;
+        }
+        for (const [key, child] of Object.entries(value)) {
+            Object.defineProperty(result, key, {
+                value: visitChild(key, child),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return result;
+    };
+    const visitChild = (key, child) => {
+        if (schemaMaps.has(key) && isObject(child)) {
+            return Object.fromEntries(Object.entries(child).map(([name, schema]) => [name, visit(schema)]));
+        }
+        if (key === 'dependencies' && isObject(child)) {
+            return Object.fromEntries(Object.entries(child).map(([name, dependency]) => [
+                name,
+                Array.isArray(dependency) ? dependency : visit(dependency),
+            ]));
+        }
+        if ((schemaArrays.has(key) || key === 'items') && Array.isArray(child)) {
+            return child.map(visit);
+        }
+        return schemaFields.has(key) ? visit(child) : child;
+    };
+    return visit(source);
+};

package/dist/helpers/get-resolved-async-api-ref.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AsyncAPI Reference Objects have no authored siblings. Follow every hop, including
+ * references with ignored siblings, and leave missing or circular aliases unresolved.
+ * Keep the shared OpenAPI resolver unchanged: its schema resources have different rules.
+ */
+export declare const getResolvedAsyncApiRef: <Node>(node: Node | {
+    $ref: string;
+    "$ref-value"?: Node;
+}) => Node | undefined;
+//# sourceMappingURL=get-resolved-async-api-ref.d.ts.map

package/dist/helpers/get-resolved-async-api-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-resolved-async-api-ref.d.ts","sourceRoot":"","sources":["../../src/helpers/get-resolved-async-api-ref.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,EAAE,MAAM,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,KAAG,IAAI,GAAG,SAWxG,CAAA"}

package/dist/helpers/get-resolved-async-api-ref.js

@@ -0,0 +1,18 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * AsyncAPI Reference Objects have no authored siblings. Follow every hop, including
+ * references with ignored siblings, and leave missing or circular aliases unresolved.
+ * Keep the shared OpenAPI resolver unchanged: its schema resources have different rules.
+ */
+export const getResolvedAsyncApiRef = (node) => {
+    const seen = new Set();
+    let current = node;
+    while (isObject(current) && typeof current.$ref === 'string') {
+        if (seen.has(current)) {
+            return undefined;
+        }
+        seen.add(current);
+        current = current['$ref-value'];
+    }
+    return current;
+};

package/dist/helpers/resolve-traits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-traits.d.ts","sourceRoot":"","sources":["../../src/helpers/resolve-traits.ts"],"names":[],"mappings":"AAoEA,uFAAuF;AACvF,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,SAAS,MAAM,EAAE,KAAG,CAetF,CAAA"}
+{"version":3,"file":"resolve-traits.d.ts","sourceRoot":"","sources":["../../src/helpers/resolve-traits.ts"],"names":[],"mappings":"AA4EA,uFAAuF;AACvF,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,SAAS,MAAM,EAAE,KAAG,CAetF,CAAA"}

package/dist/helpers/resolve-traits.js

@@ -1,7 +1,23 @@
 import { isObject } from '@scalar/helpers/object/is-object';
-import { getResolvedRef } from './get-resolved-ref.js';
+import { getResolvedAsyncApiRef } from './get-resolved-async-api-ref.js';
 const schemaMaps = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
 const dataFields = new Set(['example', 'examples', 'default', 'enum', 'const', 'value', 'dataValue']);
+/** Select how the next trait field treats schema references and literal data. */
+const getChildContext = (context, key) => {
+    if (context === 'data') {
+        return 'data';
+    }
+    if (context === 'map') {
+        return 'object';
+    }
+    if (key === 'channel') {
+        return 'reference';
+    }
+    if (dataFields.has(key) || key.startsWith('x-')) {
+        return 'data';
+    }
+    return schemaMaps.has(key) ? 'map' : 'object';
+};
 /**
  * Apply JSON Merge Patch to resolved trait fields. Unlike mergeObjects, null removes a key.
  * Resolve schema references before merging so a message can extend referenced trait headers.
@@ -11,7 +27,7 @@ const mergeTraitFields = (target, patch, context = 'object', ancestors = new Wea
     if (context === 'reference') {
         return patch;
     }
-    const resolvedPatch = context === 'object' && isObject(patch) && typeof patch.$ref === 'string' ? getResolvedRef(patch) : patch;
+    const resolvedPatch = context === 'object' && isObject(patch) && typeof patch.$ref === 'string' ? getResolvedAsyncApiRef(patch) : patch;
     if (!isObject(resolvedPatch)) {
         return resolvedPatch;
     }
@@ -19,7 +35,9 @@ const mergeTraitFields = (target, patch, context = 'object', ancestors = new Wea
     if (ancestors.has(resolvedPatch)) {
         return ancestors.get(resolvedPatch);
     }
-    const resolvedTarget = context === 'object' && isObject(target) && typeof target.$ref === 'string' ? getResolvedRef(target) : target;
+    const resolvedTarget = context === 'object' && isObject(target) && typeof target.$ref === 'string'
+        ? getResolvedAsyncApiRef(target)
+        : target;
     const result = isObject(resolvedTarget) ? { ...resolvedTarget } : {};
     ancestors.set(resolvedPatch, result);
     for (const [key, value] of Object.entries(resolvedPatch)) {
@@ -28,17 +46,7 @@ const mergeTraitFields = (target, patch, context = 'object', ancestors = new Wea
         }
         else if (value !== undefined) {
             // Schema names and example data can contain literal $ref keys without being references.
-            const childContext = context === 'data'
-                ? 'data'
-                : context === 'map'
-                    ? 'object'
-                    : key === 'channel'
-                        ? 'reference'
-                        : dataFields.has(key) || key.startsWith('x-')
-                            ? 'data'
-                            : schemaMaps.has(key)
-                                ? 'map'
-                                : 'object';
+            const childContext = getChildContext(context, key);
             // Define an own property even for schema properties named __proto__.
             Object.defineProperty(result, key, {
                 value: mergeTraitFields(Object.hasOwn(result, key) ? result[key] : undefined, value, childContext, ancestors),
@@ -57,7 +65,7 @@ export const resolveTraits = (target, traits) => {
         return target;
     }
     const inherited = traits.reduce((fields, trait) => {
-        const resolved = getResolvedRef(trait);
+        const resolved = getResolvedAsyncApiRef(trait);
         return resolved ? mergeTraitFields(fields, resolved) : fields;
     }, {});
     // Only overlay fields supplied by traits. Unrelated fields keep their references and identity.

package/dist/helpers/snapshot-schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Snapshot each schema object once, retaining shared and recursive references.
+ * Unpacking is shallow: use the raw object only for identity and ownership, then
+ * read through the proxy so reactive edits remain tracked and references resolve.
+ * Synthetic reference targets stay accessible to the generator but are omitted
+ * when literal example data is serialized.
+ */
+export declare const snapshotSchema: <T>(source: T, seen?: WeakMap<object, object>) => T;
+//# sourceMappingURL=snapshot-schema.d.ts.map

package/dist/helpers/snapshot-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-schema.d.ts","sourceRoot":"","sources":["../../src/helpers/snapshot-schema.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,8BAAoC,KAAG,CA+BnF,CAAA"}

package/dist/helpers/snapshot-schema.js

@@ -0,0 +1,38 @@
+import { unpackProxyShallow } from '../helpers/unpack-proxy.js';
+/**
+ * Snapshot each schema object once, retaining shared and recursive references.
+ * Unpacking is shallow: use the raw object only for identity and ownership, then
+ * read through the proxy so reactive edits remain tracked and references resolve.
+ * Synthetic reference targets stay accessible to the generator but are omitted
+ * when literal example data is serialized.
+ */
+export const snapshotSchema = (source, seen = new WeakMap()) => {
+    if (typeof source !== 'object' || source === null) {
+        return source;
+    }
+    const raw = unpackProxyShallow(source);
+    const existing = seen.get(raw);
+    if (existing) {
+        return existing;
+    }
+    const snapshot = Array.isArray(source) ? [] : {};
+    seen.set(raw, snapshot);
+    for (const key of Object.keys(source)) {
+        // Data descriptors also preserve literal __proto__ and inherited accessor names.
+        Object.defineProperty(snapshot, key, {
+            value: snapshotSchema(Reflect.get(source, key), seen),
+            enumerable: key !== '$ref-value' || Object.hasOwn(raw, key),
+            configurable: true,
+            writable: true,
+        });
+    }
+    // Static document loaders can keep reference targets non-enumerable.
+    if ('$ref' in source && '$ref-value' in source && !Object.hasOwn(snapshot, '$ref-value')) {
+        Object.defineProperty(snapshot, '$ref-value', {
+            value: snapshotSchema(Reflect.get(source, '$ref-value'), seen),
+            configurable: true,
+            writable: true,
+        });
+    }
+    return snapshot;
+};

package/dist/mutators/auth.d.ts

@@ -1,3 +1,4 @@
+import type { AuthenticationConfiguration } from '@scalar/types/api-reference';
 import type { WorkspaceStore } from '../client.js';
 import type { AuthEvents } from '../events/definitions/auth.js';
 import type { WorkspaceDocument } from '../schemas.js';
@@ -155,7 +156,7 @@ export declare const authMutatorsFactory: ({ document, store, }: {
 }) => {
     updateSelectedSecuritySchemes: (payload: AuthEvents["auth:update:selected-security-schemes"]) => Promise<void>;
     clearSelectedSecuritySchemes: (payload: AuthEvents["auth:clear:selected-security-schemes"]) => void;
-    updateSecurityScheme: (payload: AuthEvents["auth:update:security-scheme"]) => SecuritySchemeObject | undefined;
+    updateSecurityScheme: (data: AuthEvents["auth:update:security-scheme"], configuredSchemes?: AuthenticationConfiguration["securitySchemes"]) => SecuritySchemeObject | undefined;
     updateSecuritySchemeSecrets: (payload: AuthEvents["auth:update:security-scheme-secrets"]) => void;
     resetSecuritySchemeSecret: (payload: AuthEvents["auth:reset:security-scheme-secret"]) => void;
     clearSecuritySchemeSecrets: (payload: AuthEvents["auth:clear:security-scheme-secrets"]) => void;

package/dist/mutators/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mutators/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAU3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAGlD,OAAO,KAAK,EAAgB,oBAAoB,EAAE,MAAM,uCAAuC,CAAA;AAuC/F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B,GACxC,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,4CAA4C,UAAU,CAAC,uCAAuC,CAAC,kBAgFhG,CAAA;AAwBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,iBAAiB,GAAG,IAAI,EAClC,mBAAmB,UAAU,CAAC,6BAA6B,CAAC,qCAwB7D,CAAA;AAqED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,iBAAiB,UAAU,CAAC,0BAA0B,CAAC,SAgDxD,CAAA;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,6CAA6C,UAAU,CAAC,6BAA6B,CAAC,SA0EvF,CAAA;AAqED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,0DAA0D,UAAU,CAAC,oBAAoB,CAAC,SA2D3F,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,2BAA2B,UAAU,CAAC,oBAAoB,CAAC,SAwB5D,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,WAAW,UAAU,CAAC,6BAA6B,CAAC,SAsFrD,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,sBAGjC;IACD,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAClC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;CAC7B;6CAE4C,UAAU,CAAC,uCAAuC,CAAC;4CAEpD,UAAU,CAAC,sCAAsC,CAAC;oCAE1D,UAAU,CAAC,6BAA6B,CAAC;2CAElC,UAAU,CAAC,qCAAqC,CAAC;yCAEnD,UAAU,CAAC,mCAAmC,CAAC;0CAE9C,UAAU,CAAC,oCAAoC,CAAC;qCAErD,UAAU,CAAC,0BAA0B,CAAC;oCAEvC,UAAU,CAAC,6BAA6B,CAAC;2BAElD,UAAU,CAAC,oBAAoB,CAAC;2BAChC,UAAU,CAAC,oBAAoB,CAAC;oCACvB,UAAU,CAAC,6BAA6B,CAAC;CAG5E,CAAA"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mutators/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAE9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAW3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAGlD,OAAO,KAAK,EAAgB,oBAAoB,EAAE,MAAM,uCAAuC,CAAA;AAuC/F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6BAA6B,GACxC,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,4CAA4C,UAAU,CAAC,uCAAuC,CAAC,kBAgFhG,CAAA;AAwBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,iBAAiB,GAAG,IAAI,EAClC,mBAAmB,UAAU,CAAC,6BAA6B,CAAC,qCAwB7D,CAAA;AAqED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,iBAAiB,UAAU,CAAC,0BAA0B,CAAC,SAgDxD,CAAA;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,6CAA6C,UAAU,CAAC,6BAA6B,CAAC,SA0EvF,CAAA;AAqED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,0DAA0D,UAAU,CAAC,oBAAoB,CAAC,SA2D3F,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,2BAA2B,UAAU,CAAC,oBAAoB,CAAC,SAwB5D,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,cAAc,GAAG,IAAI,EAC5B,UAAU,iBAAiB,GAAG,IAAI,EAClC,WAAW,UAAU,CAAC,6BAA6B,CAAC,SAsFrD,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,sBAGjC;IACD,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAClC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;CAC7B;6CAE4C,UAAU,CAAC,uCAAuC,CAAC;4CAEpD,UAAU,CAAC,sCAAsC,CAAC;iCAGlF,UAAU,CAAC,6BAA6B,CAAC,sBAC5B,2BAA2B,CAAC,iBAAiB,CAAC,KAChE,oBAAoB,GAAG,SAAS;2CAgCI,UAAU,CAAC,qCAAqC,CAAC;yCAEnD,UAAU,CAAC,mCAAmC,CAAC;0CAE9C,UAAU,CAAC,oCAAoC,CAAC;qCAErD,UAAU,CAAC,0BAA0B,CAAC;oCAEvC,UAAU,CAAC,6BAA6B,CAAC;2BAElD,UAAU,CAAC,oBAAoB,CAAC;2BAChC,UAAU,CAAC,oBAAoB,CAAC;oCACvB,UAAU,CAAC,6BAA6B,CAAC;CAG5E,CAAA"}

package/dist/mutators/auth.js

@@ -7,6 +7,7 @@ import { isNonOptionalSecurityRequirement } from '../helpers/is-non-optional-sec
 import { mergeObjects } from '../helpers/merge-object.js';
 import { unpackProxyObject } from '../helpers/unpack-proxy.js';
 import { getSelectedSecurity } from '../request-example/context/security/get-selected-security.js';
+import { usesApiKeyNameOverride } from '../request-example/context/security/uses-api-key-name-override.js';
 import { isAsyncApiDocument, isOpenApiDocument } from '../schemas/type-guards.js';
 /**
  * The auth-store key for a document's selection and secret state.
@@ -617,7 +618,35 @@ export const authMutatorsFactory = ({ document, store, }) => {
     return {
         updateSelectedSecuritySchemes: (payload) => updateSelectedSecuritySchemes(store, document, payload),
         clearSelectedSecuritySchemes: (payload) => clearSelectedSecuritySchemes(store, document, payload),
-        updateSecurityScheme: (payload) => updateSecurityScheme(document, payload),
+        updateSecurityScheme: (data, configuredSchemes = {}) => {
+            const { payload, name } = data;
+            if (payload.type !== 'apiKey' || payload.name === undefined) {
+                return updateSecurityScheme(document, data);
+            }
+            const configured = Object.hasOwn(configuredSchemes, name) ? configuredSchemes[name] : undefined;
+            const documentScheme = getResolvedRef(getDocumentSecuritySchemes(document)[name]);
+            if (!configured || !usesApiKeyNameOverride(configured, documentScheme)) {
+                // Document-backed names must remain available to export and synchronization.
+                const updated = updateSecurityScheme(document, data);
+                const documentName = getAuthDocumentName(document);
+                const secrets = documentName ? store?.auth.getAuthSecrets(documentName, name) : undefined;
+                // Only release an existing override, so typing a name does not write secrets on every keystroke.
+                if (updated && secrets?.type === 'apiKey' && secrets.name !== undefined) {
+                    updateSecuritySchemeSecrets(store, document, { name, payload: { type: 'apiKey', name: undefined } });
+                }
+                return updated;
+            }
+            const defaultName = ('name' in configured ? configured.name : undefined) ??
+                (documentScheme && typeof documentScheme === 'object' && 'name' in documentScheme
+                    ? documentScheme.name
+                    : undefined);
+            // Restoring the default releases the override without clearing the API key token.
+            updateSecuritySchemeSecrets(store, document, {
+                name,
+                payload: { type: 'apiKey', name: payload.name === defaultName ? undefined : payload.name },
+            });
+            return undefined;
+        },
         updateSecuritySchemeSecrets: (payload) => updateSecuritySchemeSecrets(store, document, payload),
         resetSecuritySchemeSecret: (payload) => resetSecuritySchemeSecret(store, document, payload),
         clearSecuritySchemeSecrets: (payload) => clearSecuritySchemeSecrets(store, document, payload),

package/dist/mutators/index.d.ts

@@ -66,7 +66,7 @@ export declare function generateClientMutators(store: WorkspaceStore | null): {
         auth: {
             updateSelectedSecuritySchemes: (payload: import("../events/definitions/auth.js").AuthEvents["auth:update:selected-security-schemes"]) => Promise<void>;
             clearSelectedSecuritySchemes: (payload: import("../events/definitions/auth.js").AuthEvents["auth:clear:selected-security-schemes"]) => void;
-            updateSecurityScheme: (payload: import("../events/definitions/auth.js").AuthEvents["auth:update:security-scheme"]) => import("../schemas/v3.2/strict/security-scheme.js").SecuritySchemeObject | undefined;
+            updateSecurityScheme: (data: import("../events/definitions/auth.js").AuthEvents["auth:update:security-scheme"], configuredSchemes?: import("@scalar/types/api-reference").AuthenticationConfiguration["securitySchemes"]) => import("../schemas/v3.2/strict/security-scheme.js").SecuritySchemeObject | undefined;
             updateSecuritySchemeSecrets: (payload: import("../events/definitions/auth.js").AuthEvents["auth:update:security-scheme-secrets"]) => void;
             resetSecuritySchemeSecret: (payload: import("../events/definitions/auth.js").AuthEvents["auth:reset:security-scheme-secret"]) => void;
             clearSecuritySchemeSecrets: (payload: import("../events/definitions/auth.js").AuthEvents["auth:clear:security-scheme-secrets"]) => void;
@@ -158,7 +158,7 @@ export declare function generateClientMutators(store: WorkspaceStore | null): {
         auth: {
             updateSelectedSecuritySchemes: (payload: import("../events/definitions/auth.js").AuthEvents["auth:update:selected-security-schemes"]) => Promise<void>;
             clearSelectedSecuritySchemes: (payload: import("../events/definitions/auth.js").AuthEvents["auth:clear:selected-security-schemes"]) => void;
-            updateSecurityScheme: (payload: import("../events/definitions/auth.js").AuthEvents["auth:update:security-scheme"]) => import("../schemas/v3.2/strict/security-scheme.js").SecuritySchemeObject | undefined;
+            updateSecurityScheme: (data: import("../events/definitions/auth.js").AuthEvents["auth:update:security-scheme"], configuredSchemes?: import("@scalar/types/api-reference").AuthenticationConfiguration["securitySchemes"]) => import("../schemas/v3.2/strict/security-scheme.js").SecuritySchemeObject | undefined;
             updateSecuritySchemeSecrets: (payload: import("../events/definitions/auth.js").AuthEvents["auth:update:security-scheme-secrets"]) => void;
             resetSecuritySchemeSecret: (payload: import("../events/definitions/auth.js").AuthEvents["auth:reset:security-scheme-secret"]) => void;
             clearSecuritySchemeSecrets: (payload: import("../events/definitions/auth.js").AuthEvents["auth:clear:security-scheme-secrets"]) => void;

package/dist/navigation/get-navigation-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-navigation-options.d.ts","sourceRoot":"","sources":["../../src/navigation/get-navigation-options.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,4BAA4B,EAAgC,MAAM,6BAA6B,CAAA;AAE7G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAe7D,MAAM,MAAM,iBAAiB,GACzB,OAAO,CACL,IAAI,CACF,4BAA4B,EAC1B,qBAAqB,GACrB,iBAAiB,GACjB,uBAAuB,GACvB,qBAAqB,GACrB,mBAAmB,GACnB,kBAAkB,GAClB,YAAY,GACZ,YAAY,GACZ,oBAAoB,GACpB,sBAAsB,CACzB,CACF,GACD,SAAS,CAAA;AAEb;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,cAAc,MAAM,EAAE,UAAU,iBAAiB,KAAG,mBAyJxF,CAAA"}
+{"version":3,"file":"get-navigation-options.d.ts","sourceRoot":"","sources":["../../src/navigation/get-navigation-options.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,4BAA4B,EAAgC,MAAM,6BAA6B,CAAA;AAE7G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAe7D,MAAM,MAAM,iBAAiB,GACzB,OAAO,CACL,IAAI,CACF,4BAA4B,EAC1B,qBAAqB,GACrB,iBAAiB,GACjB,uBAAuB,GACvB,qBAAqB,GACrB,mBAAmB,GACnB,kBAAkB,GAClB,YAAY,GACZ,YAAY,GACZ,oBAAoB,GACpB,sBAAsB,CACzB,CACF,GACD,SAAS,CAAA;AAEb;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,cAAc,MAAM,EAAE,UAAU,iBAAiB,KAAG,mBA6JxF,CAAA"}

package/dist/navigation/get-navigation-options.js

@@ -87,6 +87,9 @@ export const getNavigationOptions = (documentName, options) => {
         }
         // -------- Default webhook id generation logic --------
         if (props.type === 'webhook') {
+            if (!props.name && props.method === undefined) {
+                return `${documentId}/webhooks`;
+            }
             const prefixTag = props.parentTag
                 ? `${generateId({
                     type: 'tag',

package/dist/navigation/helpers/get-tag-external-docs.d.ts

@@ -0,0 +1,4 @@
+import type { ExternalDocumentationObject, TagObject } from '../../schemas/v3.2/strict/openapi-document.js';
+/** Navigation is cloned and persisted, so keep documentation as plain display metadata. */
+export declare const getTagExternalDocs: (tag: TagObject) => ExternalDocumentationObject | undefined;
+//# sourceMappingURL=get-tag-external-docs.d.ts.map

package/dist/navigation/helpers/get-tag-external-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-tag-external-docs.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/get-tag-external-docs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,2BAA2B,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAA;AAEpG,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,GAAI,KAAK,SAAS,KAAG,2BAA2B,GAAG,SAGjF,CAAA"}

package/dist/navigation/helpers/get-tag-external-docs.js

@@ -0,0 +1,6 @@
+import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+/** Navigation is cloned and persisted, so keep documentation as plain display metadata. */
+export const getTagExternalDocs = (tag) => {
+    const documentation = getResolvedRef(tag.externalDocs);
+    return documentation ? { url: documentation.url, description: documentation.description } : undefined;
+};

package/dist/navigation/helpers/traverse-asyncapi-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traverse-asyncapi-document.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-asyncapi-document.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,gBAAgB,EAA2B,MAAM,4BAA4B,CAAA;AAOlH,OAAO,EAAE,KAAK,iBAAiB,EAAwB,MAAM,qCAAqC,CAAA;AAOlG,OAAO,KAAK,EAKV,iBAAiB,EAGlB,MAAM,sBAAsB,CAAA;AAM7B,oFAAoF;AACpF,KAAK,wCAAwC,GAAG,gBAAgB,GAAG;IACjE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AA0iBD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACnC,cAAc,MAAM,EACpB,UAAU,wCAAwC,EAClD,UAAU,iBAAiB,KAC1B,iBA+HF,CAAA"}
+{"version":3,"file":"traverse-asyncapi-document.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-asyncapi-document.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,gBAAgB,EAA2B,MAAM,4BAA4B,CAAA;AAOlH,OAAO,EAAE,KAAK,iBAAiB,EAAwB,MAAM,qCAAqC,CAAA;AAQlG,OAAO,KAAK,EAKV,iBAAiB,EAGlB,MAAM,sBAAsB,CAAA;AAM7B,oFAAoF;AACpF,KAAK,wCAAwC,GAAG,gBAAgB,GAAG;IACjE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAqjBD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACnC,cAAc,MAAM,EACpB,UAAU,wCAAwC,EAClD,UAAU,iBAAiB,KAC1B,iBAsJF,CAAA"}

package/dist/navigation/helpers/traverse-asyncapi-document.js

@@ -2,11 +2,12 @@ import { sortByOrder } from '@scalar/helpers/array/sort-by-order';
 import { objectKeys } from '@scalar/helpers/object/object-keys';
 import { resolveOperationWithTraits } from '../../channel-example/resolve-operation-with-traits.js';
 import { getNameFromRef } from '../../helpers/get-name-from-ref.js';
-import { getResolvedRef, mergeSiblingReferences } from '../../helpers/get-resolved-ref.js';
+import { getResolvedAsyncApiRef } from '../../helpers/get-resolved-async-api-ref.js';
 import { isHidden } from '../../helpers/is-hidden.js';
 import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
 import { getNavigationOptions } from '../../navigation/get-navigation-options.js';
 import { getTag } from '../../navigation/helpers/get-tag.js';
+import { getTagExternalDocs } from '../../navigation/helpers/get-tag-external-docs.js';
 import { traverseDescription } from '../../navigation/helpers/traverse-description.js';
 import { traverseSchemas } from '../../navigation/helpers/traverse-schemas.js';
 /**
@@ -63,10 +64,8 @@ const resolveOperationChannel = (document, operation) => {
     if (!channelEntry) {
         return undefined;
     }
-    return {
-        channelName,
-        channel: getResolvedRef(channelEntry, mergeSiblingReferences),
-    };
+    const channel = getResolvedAsyncApiRef(channelEntry);
+    return channel ? { channelName, channel } : undefined;
 };
 /**
  * Resolves which channel message names an operation references.
@@ -108,11 +107,18 @@ const resolveOperationMessageNames = (operation, channel, channelName) => {
  * used by the shared tag navigation helpers.
  */
 const toTagObject = (tag) => {
-    const resolved = getResolvedRef(tag, mergeSiblingReferences);
-    return {
-        name: resolved.name,
-        description: resolved.description,
-    };
+    const resolved = getResolvedAsyncApiRef(tag);
+    if (!resolved) {
+        return [];
+    }
+    const externalDocs = getResolvedAsyncApiRef(resolved.externalDocs);
+    return [
+        {
+            name: resolved.name,
+            ...(resolved.description !== undefined ? { description: resolved.description } : {}),
+            ...(externalDocs ? { externalDocs } : {}),
+        },
+    ];
 };
 /**
  * Sorts operation navigation entries in place using the workspace `operationsSorter` option.
@@ -145,8 +151,8 @@ const createMessageEntries = ({ channelName, channel, parentId, messageNames, ge
         if (!messageNode) {
             return [];
         }
-        const message = getResolvedRef(messageNode, mergeSiblingReferences);
-        if (isHidden(message)) {
+        const message = getResolvedAsyncApiRef(messageNode);
+        if (!message || isHidden(message)) {
             return [];
         }
         return [
@@ -269,6 +275,7 @@ const createTagEntry = ({ tag, generateId, children, parentId, }) => {
         parentId,
         isGroup: false,
     });
+    const externalDocs = getTagExternalDocs(tag);
     const title = tag['x-displayName'] ?? tag.name ?? 'Untitled Tag';
     tag['x-scalar-order'] = children.map((child) => child.id);
     return {
@@ -277,6 +284,7 @@ const createTagEntry = ({ tag, generateId, children, parentId, }) => {
         title,
         name: tag.name || title,
         description: tag.description,
+        ...(externalDocs ? { externalDocs } : {}),
         children,
         isGroup: false,
         isWebhooks: false,
@@ -325,7 +333,7 @@ const getOrCreateChannelBucket = (channelBuckets, channelName, channel) => {
         channelName,
         channel,
         channelAddress: getChannelAddress(channelName, channel),
-        channelTags: channel.tags?.map(toTagObject) ?? [],
+        channelTags: channel.tags?.flatMap(toTagObject) ?? [],
         operations: [],
     };
     channelBuckets.set(channelName, bucket);
@@ -344,8 +352,8 @@ const collectChannelBuckets = (document) => {
         if (!channelNode) {
             continue;
         }
-        const channel = getResolvedRef(channelNode, mergeSiblingReferences);
-        if (isHidden(channel)) {
+        const channel = getResolvedAsyncApiRef(channelNode);
+        if (!channel || isHidden(channel)) {
             continue;
         }
         getOrCreateChannelBucket(channelBuckets, channelName, channel);
@@ -354,7 +362,11 @@ const collectChannelBuckets = (document) => {
         if (!operationNode) {
             continue;
         }
-        const operation = resolveOperationWithTraits(getResolvedRef(operationNode, mergeSiblingReferences));
+        const resolvedOperation = getResolvedAsyncApiRef(operationNode);
+        if (!resolvedOperation) {
+            continue;
+        }
+        const operation = resolveOperationWithTraits(resolvedOperation);
         const resolved = resolveOperationChannel(document, operation);
         if (!resolved) {
             continue;
@@ -391,6 +403,14 @@ export const traverseAsyncApiDocument = (documentName, document, options) => {
     const channelBuckets = collectChannelBuckets(document);
     const tagsMap = new Map();
     const untaggedChannels = [];
+    // Info-level tags own their metadata and links, rather than contributing introduction links.
+    for (const tag of (document.info.tags ?? []).flatMap(toTagObject)) {
+        if (!tag.name) {
+            continue;
+        }
+        const entry = getTag({ tagsMap, name: tag.name, documentId, generateId });
+        entry.tag = tag;
+    }
     for (const bucket of channelBuckets.values()) {
         // Operation-level tags are intentionally skipped for now: every operation is rendered
         // under its channel, and only the channel's own tags drive tag grouping below.
@@ -410,7 +430,9 @@ export const traverseAsyncApiDocument = (documentName, document, options) => {
         // Channels can declare their own tags independently of any operation tags.
         for (const tag of bucket.channelTags) {
             const tagName = tag.name ?? 'Untitled Tag';
-            const { id: tagId, entries } = getTag({ tagsMap, name: tagName, documentId, generateId });
+            const tagEntry = getTag({ tagsMap, name: tagName, documentId, generateId });
+            tagEntry.tag = { ...tagEntry.tag, ...tag };
+            const { id: tagId, entries } = tagEntry;
             const alreadyRegistered = entries.some((entry) => entry.type === 'asyncapi-channel' && entry.channelName === bucket.channelName);
             if (alreadyRegistered) {
                 continue;
@@ -438,9 +460,19 @@ export const traverseAsyncApiDocument = (documentName, document, options) => {
     // typed against the OpenAPI document. We hand it the resolved `components` (so a `$ref`-only
     // wrapper still exposes its schemas) wrapped in a minimal document; the cast bridges the single
     // overlapping field, since AsyncAPI and OpenAPI documents are otherwise distinct types.
-    const components = document.components ? getResolvedRef(document.components, mergeSiblingReferences) : undefined;
+    const components = document.components ? getResolvedAsyncApiRef(document.components) : undefined;
     const untaggedModels = !hideModels && components?.schemas
-        ? traverseSchemas({ documentId, document: { components }, generateId, tagsMap })
+        ? traverseSchemas({
+            documentId,
+            document: {
+                components: {
+                    ...components,
+                    schemas: Object.fromEntries(Object.entries(components.schemas).map(([name, schema]) => [name, getResolvedAsyncApiRef(schema)])),
+                },
+            },
+            generateId,
+            tagsMap,
+        })
         : [];
     // Surface the Introduction entry plus any headings extracted from `info.description`
     // before the channel/tag entries, mirroring how OpenAPI documents are traversed.

package/dist/navigation/helpers/traverse-tags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traverse-tags.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-tags.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,sBAAsB,CAAA;AACxE,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,wCAAwC,CAAA;AAIxF,KAAK,OAAO,GAAG,IAAI,CAAC,mBAAmB,EAAE,YAAY,GAAG,kBAAkB,GAAG,YAAY,CAAC,CAAA;AAmS1F;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,2FAK1B;IACD,QAAQ,EAAE,eAAe,CAAA;IACzB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB,KAAG,cAAc,EAuEjB,CAAA"}
+{"version":3,"file":"traverse-tags.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-tags.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,sBAAsB,CAAA;AACxE,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,wCAAwC,CAAA;AAIxF,KAAK,OAAO,GAAG,IAAI,CAAC,mBAAmB,EAAE,YAAY,GAAG,kBAAkB,GAAG,YAAY,CAAC,CAAA;AAqS1F;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,2FAK1B;IACD,QAAQ,EAAE,eAAe,CAAA;IACzB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB,KAAG,cAAc,EAuEjB,CAAA"}

package/dist/navigation/helpers/traverse-tags.js

@@ -2,6 +2,7 @@ import { sortByOrder } from '@scalar/helpers/array/sort-by-order';
 import { getTagKind } from '../../helpers/get-tag-kind.js';
 import { isHidden } from '../../helpers/is-hidden.js';
 import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
+import { getTagExternalDocs } from '../../navigation/helpers/get-tag-external-docs.js';
 import { getXKeysFromObject } from '../../navigation/helpers/get-x-keys.js';
 import { getTag } from './get-tag.js';
 /** Creates a traversed tag entry from an OpenAPI tag object.
@@ -22,6 +23,7 @@ const createTagEntry = ({ tag, generateId, children, isGroup = false, isTagGroup
         isTagGroup,
     });
     // `summary` is the OpenAPI 3.2 display label; `x-displayName` keeps precedence for backwards compatibility.
+    const externalDocs = getTagExternalDocs(tag);
     const title = tag['x-displayName'] ?? tag.summary ?? tag.name ?? 'Untitled Tag';
     // Update the order of the children based on the items
     // This will ensure that the sort order is always in sync with the items
@@ -31,6 +33,7 @@ const createTagEntry = ({ tag, generateId, children, isGroup = false, isTagGroup
         title,
         name: tag.name || title,
         description: tag.description,
+        ...(externalDocs ? { externalDocs } : {}),
         children,
         isGroup,
         // Only tag on legacy `x-tagGroups` wrappers so the renderer can flatten them without a header.

package/dist/request-example/builder/body/get-request-body-example.d.ts

@@ -5,8 +5,8 @@ import type { ExampleObject, RequestBodyObject } from '@scalar/workspace-store/s
  * This is the schema-generation half of {@link getExampleFromBody}. It is exposed on its own so
  * callers that need to regenerate a body for a freshly selected composition branch (rather than the
  * edited example that would otherwise shadow it) produce the exact same value the initial example
- * does. Data generation deep-resolves nested `$ref` members. XML retains reference sites so node
- * naming and version-specific wrappers survive serialization.
+ * does. Keep reference sites intact so the generator can detect cycles without losing the schema
+ * at the recursion point. XML also needs them for node naming and version-specific wrappers.
  *
  * Returns `undefined` when there is no schema for the content type.
  */

package/dist/request-example/builder/body/get-request-body-example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-request-body-example.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/get-request-body-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EAElB,MAAM,8DAA8D,CAAA;AASrE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GACnC,aAAa,iBAAiB,EAC9B,aAAa,MAAM,EACnB,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxD,iBAAiB,MAAM,KACtB,OAgCF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,iBAAiB,EAC9B,aAAa,MAAM,EACnB,aAAa,MAAM,EACnB,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxD,iBAAiB,MAAM,KACtB,aAAa,GAAG,IA4ClB,CAAA"}
+{"version":3,"file":"get-request-body-example.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/get-request-body-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EAElB,MAAM,8DAA8D,CAAA;AAUrE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GACnC,aAAa,iBAAiB,EAC9B,aAAa,MAAM,EACnB,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxD,iBAAiB,MAAM,KACtB,OA8BF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,iBAAiB,EAC9B,aAAa,MAAM,EACnB,aAAa,MAAM,EACnB,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxD,iBAAiB,MAAM,KACtB,aAAa,GAAG,IA4ClB,CAAA"}

package/dist/request-example/builder/body/get-request-body-example.js

@@ -1,8 +1,9 @@
 import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { parseMimeType } from '@scalar/helpers/http/mime-type';
 import { getExampleValue } from '../../../helpers/get-example-value.js';
-import { getResolvedRefDeep } from '../../../helpers/get-resolved-ref-deep.js';
+import { getResolvedRef } from '../../../helpers/get-resolved-ref.js';
 import { serializeStreamExample } from '../../../helpers/serialize-stream-example.js';
+import { snapshotSchema } from '../../../helpers/snapshot-schema.js';
 import { getExample } from '../../../request-example/builder/helpers/get-example.js';
 import { getExampleFromSchema } from '../../../request-example/builder/helpers/get-example-from-schema.js';
 import { getXmlBodyExample } from '../../../request-example/xml/get-xml-body-example.js';
@@ -12,8 +13,8 @@ import { getXmlBodyExample } from '../../../request-example/xml/get-xml-body-exa
  * This is the schema-generation half of {@link getExampleFromBody}. It is exposed on its own so
  * callers that need to regenerate a body for a freshly selected composition branch (rather than the
  * edited example that would otherwise shadow it) produce the exact same value the initial example
- * does. Data generation deep-resolves nested `$ref` members. XML retains reference sites so node
- * naming and version-specific wrappers survive serialization.
+ * does. Keep reference sites intact so the generator can detect cycles without losing the schema
+ * at the recursion point. XML also needs them for node naming and version-specific wrappers.
  *
  * Returns `undefined` when there is no schema for the content type.
  */
@@ -31,11 +32,10 @@ export const getSchemaExampleFromBody = (requestBody, contentType, requestBodyCo
             schemaPath: ['requestBody'],
         }).xml;
     }
-    if (!schema) {
+    if (!schema || getResolvedRef(schema) === undefined) {
         return undefined;
     }
-    const resolvedSchema = getResolvedRefDeep(schema);
-    const value = getExampleFromSchema(resolvedSchema, {
+    const value = getExampleFromSchema(snapshotSchema(schema), {
         mode: 'write',
         compositionSelection: requestBodyCompositionSelection,
     }, {