@scalar/workspace-store 0.68.1 → 0.68.2

package/dist/helpers/resolve-security-requirements.js

@@ -0,0 +1,222 @@
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { isPollutionKey } from '@scalar/helpers/object/prevent-pollution';
+import { isSchemaPath } from '@scalar/helpers/openapi/is-schema-path';
+import { bundle, resolveReferencePath } from '@scalar/json-magic/bundle';
+import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
+import { Value } from '@scalar/typebox/value';
+import { generateUniqueValue } from '../helpers/generate-unique-value.js';
+import { getResolvedRef } from '../helpers/get-resolved-ref.js';
+import { normalizeAuthSchemes } from '../plugins/bundler/index.js';
+import { resolveOpenApiDocument } from '../plugins/bundler/openapi-document.js';
+import { SecuritySchemeObjectSchema } from '../schemas/v3.2/strict/openapi-document.js';
+const ALIASES = 'x-scalar-security-uri-aliases';
+const ORIGINAL_KEYS = 'x-scalar-original-security-keys';
+/** Resolve the URI portion separately so filesystem origins do not interpret fragments as filenames. */
+const absoluteReference = (reference, base) => {
+    const separator = reference.indexOf('#');
+    const resource = separator === -1 ? reference : reference.slice(0, separator);
+    const fragment = separator === -1 ? '' : reference.slice(separator);
+    return `${resource ? resolveReferencePath(base, resource) : base}${fragment}`;
+};
+/**
+ * Makes URI requirements available to the existing name-based auth consumers.
+ * Aliases live only in the working document; export removes them and restores authored keys.
+ * Relative keys in referenced documents become absolute to keep distinct document bases apart.
+ */
+export const resolveSecurityRequirements = async (document, { origin = '/', loaders }) => {
+    if (typeof document.openapi !== 'string' || !/^3\.2\.\d+$/.test(document.openapi))
+        return;
+    const originalKeys = isObject(document[ORIGINAL_KEYS]) ? document[ORIGINAL_KEYS] : {};
+    const components = isObject(document.components) ? document.components : {};
+    const schemes = isObject(components.securitySchemes) ? components.securitySchemes : {};
+    const metadata = isObject(document[ALIASES])
+        ? document[ALIASES]
+        : {
+            hadComponents: isObject(document.components),
+            hadSecuritySchemes: isObject(components.securitySchemes),
+            schemes: {},
+        };
+    const aliases = isObject(metadata.schemes) ? metadata.schemes : {};
+    metadata.schemes = aliases;
+    const namedSchemes = new Set(Object.keys(schemes).filter((name) => !Object.hasOwn(aliases, name)));
+    const visited = new WeakSet();
+    const processedDocuments = new Set();
+    const cache = new Map();
+    const visit = async (node, path, base, external) => {
+        if (node === null || typeof node !== 'object' || visited.has(node) || isSchemaPath(path))
+            return;
+        visited.add(node);
+        // Security is a fixed field on document and operation objects, not arbitrary example payloads.
+        const operationKey = path.at(-1) ?? '';
+        const isOperation = isHttpMethod(operationKey) || path.at(-2) === 'additionalOperations';
+        const isDocument = path.length === 0 || (path[0] === 'x-ext' && path.length === 2);
+        if (isObject(node) && (isDocument || isOperation) && Array.isArray(node.security)) {
+            for (const [index, requirement] of node.security.entries()) {
+                if (!isObject(requirement))
+                    continue;
+                for (const [name, scopes] of Object.entries(requirement)) {
+                    if (namedSchemes.has(name) || !Array.isArray(scopes))
+                        continue;
+                    const uri = (() => {
+                        try {
+                            return Object.hasOwn(aliases, name) && typeof aliases[name] === 'string'
+                                ? aliases[name]
+                                : absoluteReference(name, base);
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    })();
+                    if (uri === undefined)
+                        continue;
+                    const key = await generateUniqueValue({
+                        defaultValue: external ? uri : name,
+                        validation: (candidate) => !namedSchemes.has(candidate) &&
+                            (!Object.hasOwn(aliases, candidate) || aliases[candidate] === uri) &&
+                            (!external || candidate === name || !Object.hasOwn(requirement, candidate)),
+                        maxRetries: Object.keys(schemes).length + 1,
+                    });
+                    if (key === undefined)
+                        continue;
+                    if (!Object.hasOwn(aliases, key)) {
+                        const reference = { $ref: uri };
+                        await bundle({ components: { securitySchemes: { target: reference } } }, {
+                            root: document,
+                            origin,
+                            treeShake: false,
+                            urlMap: true,
+                            cache,
+                            plugins: [...loaders, normalizeAuthSchemes()],
+                            hooks: { resolveDocument: resolveOpenApiDocument },
+                        });
+                        // Validate the target before exposing an auth option; missing pointers and non-schemes
+                        // keep their original requirement and never acquire a misleading working alias.
+                        const proxy = createMagicProxy({ ...document, 'x-scalar-security-uri-target': reference }, {
+                            documentUri: resolveOpenApiDocument(document, origin)?.baseUri,
+                        });
+                        const target = getResolvedRef(proxy['x-scalar-security-uri-target']);
+                        // The strict runtime schema requires refreshUrl, while authored OAuth flows may omit it.
+                        const validationTarget = isObject(target) && target.type === 'oauth2' && isObject(target.flows)
+                            ? {
+                                ...target,
+                                flows: Object.fromEntries(Object.entries(target.flows).map(([flow, value]) => [
+                                    flow,
+                                    isObject(value) ? { refreshUrl: '', ...value } : value,
+                                ])),
+                            }
+                            : target;
+                        if (!Value.Check(SecuritySchemeObjectSchema, validationTarget))
+                            continue;
+                        Object.defineProperty(schemes, key, {
+                            value: reference,
+                            enumerable: true,
+                            writable: true,
+                            configurable: true,
+                        });
+                        Object.defineProperty(aliases, key, { value: uri, enumerable: true, writable: true, configurable: true });
+                        components.securitySchemes = schemes;
+                        document.components = components;
+                        document[ALIASES] = metadata;
+                    }
+                    if (external) {
+                        const location = JSON.stringify([...path, 'security', String(index)]);
+                        const mapping = isObject(originalKeys[location]) ? originalKeys[location] : {};
+                        Object.defineProperty(mapping, name, { value: key, enumerable: true, writable: true, configurable: true });
+                        originalKeys[location] = mapping;
+                        document[ORIGINAL_KEYS] = originalKeys;
+                        if (key === name)
+                            continue;
+                        const previous = Object.hasOwn(requirement, key) ? requirement[key] : [];
+                        Object.defineProperty(requirement, key, {
+                            value: [...new Set([...(Array.isArray(previous) ? previous : []), ...scopes])],
+                            enumerable: true,
+                            writable: true,
+                            configurable: true,
+                        });
+                        delete requirement[name];
+                    }
+                }
+            }
+        }
+        for (const [key, child] of Object.entries(node)) {
+            if (key.startsWith('x-') || key === 'example' || key === 'examples' || key === 'security')
+                continue;
+            await visit(child, [...path, key], base, external);
+        }
+    };
+    const entryBase = resolveOpenApiDocument(document, origin)?.baseUri ?? origin;
+    await visit(document, [], entryBase, false);
+    // URI-only dependencies can load further documents, so process newly embedded documents too.
+    while (isObject(document['x-ext'])) {
+        const next = Object.entries(document['x-ext']).find(([key]) => !processedDocuments.has(key));
+        if (!next)
+            break;
+        const [key, external] = next;
+        processedDocuments.add(key);
+        if (!isObject(external))
+            continue;
+        if (typeof external.openapi === 'string' && !/^3\.2\.\d+$/.test(external.openapi))
+            continue;
+        const mappings = document['x-ext-urls'];
+        const retrieval = isObject(mappings) && typeof mappings[key] === 'string' ? mappings[key] : key;
+        const retrievalUri = resolveReferencePath(entryBase, retrieval);
+        await visit(external, ['x-ext', key], resolveOpenApiDocument(external, retrievalUri)?.baseUri ?? retrievalUri, true);
+    }
+};
+/** Remove runtime URI aliases while keeping edited scopes and authored requirement spellings. */
+export const restoreSecurityRequirements = (document) => {
+    const originalKeys = Object.hasOwn(document, ORIGINAL_KEYS) ? document[ORIGINAL_KEYS] : undefined;
+    if (isObject(originalKeys)) {
+        for (const [location, mapping] of Object.entries(originalKeys)) {
+            const path = (() => {
+                try {
+                    return JSON.parse(location);
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            if (!Array.isArray(path) ||
+                !path.every((segment) => typeof segment === 'string' && !isPollutionKey(segment)) ||
+                !isObject(mapping))
+                continue;
+            const requirement = path.reduce((parent, segment) => {
+                if (parent === null || typeof parent !== 'object' || !Object.hasOwn(parent, segment))
+                    return undefined;
+                return Reflect.get(parent, segment);
+            }, document);
+            if (!isObject(requirement))
+                continue;
+            const entries = Object.entries(mapping).flatMap(([original, rewritten]) => typeof rewritten === 'string' && Object.hasOwn(requirement, rewritten)
+                ? [{ original, rewritten, scopes: requirement[rewritten] }]
+                : []);
+            for (const { rewritten } of entries)
+                delete requirement[rewritten];
+            for (const { original, scopes } of entries) {
+                Object.defineProperty(requirement, original, {
+                    value: scopes,
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            }
+        }
+    }
+    const metadata = Object.hasOwn(document, ALIASES) ? document[ALIASES] : undefined;
+    const components = Object.hasOwn(document, 'components') ? document.components : undefined;
+    if (isObject(metadata) &&
+        isObject(metadata.schemes) &&
+        isObject(components) &&
+        Object.hasOwn(components, 'securitySchemes') &&
+        isObject(components.securitySchemes)) {
+        for (const key of Object.keys(metadata.schemes))
+            delete components.securitySchemes[key];
+        if (!metadata.hadSecuritySchemes && Object.keys(components.securitySchemes).length === 0)
+            delete components.securitySchemes;
+        if (!metadata.hadComponents && Object.keys(components).length === 0)
+            delete document.components;
+    }
+    delete document[ALIASES];
+    delete document[ORIGINAL_KEYS];
+};

package/dist/navigation/helpers/get-navigation-tag-names.d.ts

@@ -0,0 +1,5 @@
+import type { TagsMap } from '../../navigation/types.js';
+import type { OpenApiDocument } from '../../schemas/v3.2/strict/openapi-document.js';
+/** Label tags must not create operation groups, but undeclared tags still do. */
+export declare const getNavigationTagNames: (document: OpenApiDocument, names: string[] | undefined, tagsMap: TagsMap) => string[];
+//# sourceMappingURL=get-navigation-tag-names.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-navigation-tag-names.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/get-navigation-tag-names.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAE7E,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,GAChC,UAAU,eAAe,EACzB,OAAO,MAAM,EAAE,GAAG,SAAS,EAC3B,SAAS,OAAO,KACf,MAAM,EAA2F,CAAA"}

package/dist/navigation/helpers/get-navigation-tag-names.js

@@ -0,0 +1,3 @@
+import { getTagKind } from '../../helpers/get-tag-kind.js';
+/** Label tags must not create operation groups, but undeclared tags still do. */
+export const getNavigationTagNames = (document, names, tagsMap) => names?.filter((name) => getTagKind(document, tagsMap.get(name)?.tag) === 'nav') ?? [];

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

@@ -1 +1 @@
-{"version":3,"file":"traverse-paths.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-paths.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAE5F,OAAO,KAAK,EAA+B,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAI9F,eAAO,MAAM,qBAAqB,GAAI,WAAW,eAAe,YAE/D,CAAA;AAsED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GAAI,sEAM3B;IACD,QAAQ,EAAE,eAAe,CAAA;IACzB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,0DAA0D;IAC1D,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAC7C,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;CAC5C,KAAG;IAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAA;CA0D7C,CAAA"}
+{"version":3,"file":"traverse-paths.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-paths.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAE5F,OAAO,KAAK,EAA+B,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAK9F,eAAO,MAAM,qBAAqB,GAAI,WAAW,eAAe,YAE/D,CAAA;AAsED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GAAI,sEAM3B;IACD,QAAQ,EAAE,eAAe,CAAA;IACzB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,0DAA0D;IAC1D,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAC7C,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;CAC5C,KAAG;IAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAA;CA2D7C,CAAA"}

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

@@ -4,6 +4,7 @@ import { getResolvedRef, mergeSiblingReferences } from '../../helpers/get-resolv
 import { isHidden } from '../../helpers/is-hidden.js';
 import { traverseOperationExamples } from '../../navigation/helpers/traverse-examples.js';
 import { XScalarStabilityValues } from '../../schemas/extensions/operation/index.js';
+import { getNavigationTagNames } from './get-navigation-tag-names.js';
 import { getTag } from './get-tag.js';
 export const isDeprecatedOperation = (operation) => {
     return operation.deprecated || operation['x-scalar-stability'] === XScalarStabilityValues.Deprecated;
@@ -85,8 +86,9 @@ export const traversePaths = ({ document, tagsMap, generateId, documentId, opera
             }
             const ref = `#/paths/${escapeJsonPointer(path)}/${getPathItemOperationKey(method)}`;
             // Traverse tags
-            if (operation.tags?.length) {
-                operation.tags.forEach((tagName) => {
+            const navigationTags = getNavigationTagNames(document, operation.tags, tagsMap);
+            if (navigationTags.length) {
+                navigationTags.forEach((tagName) => {
                     const { tag, id: tagId } = getTag({
                         tagsMap,
                         name: tagName,

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

@@ -1 +1 @@
-{"version":3,"file":"traverse-schemas.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-schemas.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAa,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,wCAAwC,CAAA;AA2C3F;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,gDAK7B;IACD,QAAQ,EAAE,eAAe,CAAA;IACzB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAC7C,UAAU,EAAE,MAAM,CAAA;CACnB,KAAG,eAAe,EAkDlB,CAAA"}
+{"version":3,"file":"traverse-schemas.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-schemas.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAa,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,wCAAwC,CAAA;AA2C3F;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,gDAK7B;IACD,QAAQ,EAAE,eAAe,CAAA;IACzB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAC7C,UAAU,EAAE,MAAM,CAAA;CACnB,KAAG,eAAe,EAmDlB,CAAA"}

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

@@ -1,5 +1,6 @@
 import { getResolvedRef, mergeSiblingReferences } from '../../helpers/get-resolved-ref.js';
 import { isHidden } from '../../helpers/is-hidden.js';
+import { getNavigationTagNames } from '../../navigation/helpers/get-navigation-tag-names.js';
 import { getTag } from '../../navigation/helpers/get-tag.js';
 /** Creates a traversed schema entry from an OpenAPI schema object.
  *
@@ -46,8 +47,9 @@ export const traverseSchemas = ({ document, tagsMap, generateId, documentId, })
         }
         const ref = `#/components/schemas/${name}`;
         // Add to tags
-        if (schema?.['x-tags']) {
-            schema['x-tags'].forEach((tagName) => {
+        const navigationTags = getNavigationTagNames(document, schema?.['x-tags'], tagsMap);
+        if (navigationTags.length) {
+            navigationTags.forEach((tagName) => {
                 const { tag, id: tagId } = getTag({ tagsMap, name: tagName, documentId, generateId });
                 tagsMap.get(tagName)?.entries.push(createSchemaEntry({
                     ref,

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":"AAKA,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;AAiS1F;;;;;;;;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,EAoEjB,CAAA"}
+{"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"}

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

@@ -1,4 +1,5 @@
 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 { getXKeysFromObject } from '../../navigation/helpers/get-x-keys.js';
@@ -57,7 +58,7 @@ const createTagEntry = ({ tag, generateId, children, isGroup = false, isTagGroup
  * @returns Array of processed and sorted tag entries
  */
 /** Sorts tags and returns entries */
-const getSortedTagEntries = ({ _keys, tagsMap, options: { tagsSorter, operationsSorter, generateId }, documentId, sortOrder, }) => {
+const getSortedTagEntries = ({ _keys, document, tagsMap, options: { tagsSorter, operationsSorter, generateId }, documentId, sortOrder, }) => {
     /**
      * Process each tag and its entries:
      * - Skip internal and ignored tags
@@ -67,7 +68,7 @@ const getSortedTagEntries = ({ _keys, tagsMap, options: { tagsSorter, operations
     const entries = _keys.flatMap((key) => {
         const { tag, entries } = getTag({ tagsMap, name: key, documentId, generateId });
         // Skip if the tag is internal or scalar-ignore
-        if (isHidden(tag)) {
+        if (isHidden(tag) || getTagKind(document, tag) !== 'nav') {
             return [];
         }
         const sortOrder = tag['x-scalar-order'];
@@ -167,7 +168,7 @@ const nestTagsByParent = ({ flatEntries, document, originalOrders, }) => {
             hadOwnOperations.set(entry.name, (entry.children?.length ?? 0) > 0);
         }
     }
-    const parentOf = getParentMap(document.tags ?? []);
+    const parentOf = getParentMap((document.tags ?? []).filter((tag) => getTagKind(document, tag) === 'nav'));
     // Re-parent entries by reference, tracking which ones leave the top level.
     const nested = new Set();
     const gainedNestedTags = new Set();
@@ -232,7 +233,7 @@ export const traverseTags = ({ document, tagsMap, documentId, options: { generat
     // Native OpenAPI 3.2 tag nesting via `parent` takes precedence over x-tagGroups, but only
     // when at least one `parent` resolves to another declared tag outside a circular reference.
     // A stray or misspelled `parent` value must not disable the legacy `x-tagGroups` handling.
-    const parentOf = getParentMap(document.tags ?? []);
+    const parentOf = getParentMap((document.tags ?? []).filter((tag) => getTagKind(document, tag) === 'nav'));
     const hasNestedTags = Array.from(parentOf.keys()).some((name) => !isCyclic(parentOf, name));
     if (hasNestedTags) {
         // The flat traversal rewrites tag-level `x-scalar-order`, so capture the original values
@@ -244,6 +245,7 @@ export const traverseTags = ({ document, tagsMap, documentId, options: { generat
             }
         }
         const flatEntries = getSortedTagEntries({
+            document,
             _keys: Array.from(tagsMap.keys()),
             tagsMap,
             options: { generateId, tagsSorter, operationsSorter },
@@ -257,6 +259,7 @@ export const traverseTags = ({ document, tagsMap, documentId, options: { generat
         const tagGroups = document['x-tagGroups'];
         return tagGroups.flatMap((tagGroup) => {
             const entries = getSortedTagEntries({
+                document,
                 _keys: tagGroup.tags,
                 tagsMap,
                 options: { tagsSorter, operationsSorter, generateId },
@@ -280,6 +283,7 @@ export const traverseTags = ({ document, tagsMap, documentId, options: { generat
     // Ungrouped regular tags
     const keys = Array.from(tagsMap.keys());
     const tags = getSortedTagEntries({
+        document,
         _keys: keys,
         tagsMap,
         options: { generateId, tagsSorter, operationsSorter },

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

@@ -1 +1 @@
-{"version":3,"file":"traverse-webhooks.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-webhooks.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAa,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,wCAAwC,CAAA;AA2DzG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAAI,0EAM9B;IACD,uBAAuB;IACvB,QAAQ,EAAE,eAAe,CAAA;IACzB,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAC7C,wBAAwB,EAAE,MAAM,CAAA;IAChC,UAAU,EAAE,MAAM,CAAA;CACnB,KAAG,gBAAgB,EAuDnB,CAAA"}
+{"version":3,"file":"traverse-webhooks.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/traverse-webhooks.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAa,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,wCAAwC,CAAA;AA4DzG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAAI,0EAM9B;IACD,uBAAuB;IACvB,QAAQ,EAAE,eAAe,CAAA;IACzB,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAC7C,wBAAwB,EAAE,MAAM,CAAA;IAChC,UAAU,EAAE,MAAM,CAAA;CACnB,KAAG,gBAAgB,EAwDnB,CAAA"}

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

@@ -2,6 +2,7 @@ import { forEachPathItemOperation, getPathItemOperationKey } from '../../helpers
 import { getResolvedRef, mergeSiblingReferences } from '../../helpers/get-resolved-ref.js';
 import { isHidden } from '../../helpers/is-hidden.js';
 import { isDeprecatedOperation } from '../../navigation/helpers/traverse-paths.js';
+import { getNavigationTagNames } from './get-navigation-tag-names.js';
 import { getTag } from './get-tag.js';
 /** Creates a traversed webhook entry from an OpenAPI webhook object.
  *
@@ -63,8 +64,9 @@ export const traverseWebhooks = ({ document, tagsMap, generateId, untaggedWebhoo
                 return;
             }
             const ref = `#/webhooks/${name}/${getPathItemOperationKey(method)}`;
-            if (operation.tags?.length) {
-                operation.tags.forEach((tagName) => {
+            const navigationTags = getNavigationTagNames(document, operation.tags, tagsMap);
+            if (navigationTags.length) {
+                navigationTags.forEach((tagName) => {
                     const { tag, id: tagId } = getTag({ tagsMap, name: tagName, documentId, generateId });
                     tagsMap.get(tagName)?.entries.push(createWebhookEntry({
                         ref,

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

@@ -1 +1 @@
-{"version":3,"file":"build-request-body.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/build-request-body.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0DAA0D,CAAA;AAKjG,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,mBAAmB,CAAA;AAO1B,KAAK,QAAQ,GAAG;IACd,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,CACH;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CACJ,EAAE,CAAA;CACJ,CAAA;AAwBD,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,YAAY,CAAA;IAClB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;KACd,EAAE,CAAA;CACJ,CAAA;AAED,KAAK,GAAG,GAAG;IACT,IAAI,EAAE,KAAK,CAAA;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,UAAU,GACV,GAAG,GACH;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAAA;AA2CtE;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,iBAAiB,GAAG,SAAS;AAC1C,qCAAqC;AACrC,oBAAuB;AACvB,sEAAsE;AACtE,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxD,iBAAiB,MAAM,KACtB,WAAW,GAAG,IAoXhB,CAAA"}
+{"version":3,"file":"build-request-body.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/build-request-body.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0DAA0D,CAAA;AAMjG,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,mBAAmB,CAAA;AAO1B,KAAK,QAAQ,GAAG;IACd,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,CACH;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,GACD;QACE,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,IAAI,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CACJ,EAAE,CAAA;CACJ,CAAA;AAwBD,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,YAAY,CAAA;IAClB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;KACd,EAAE,CAAA;CACJ,CAAA;AAED,KAAK,GAAG,GAAG;IACT,IAAI,EAAE,KAAK,CAAA;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,UAAU,GACV,GAAG,GACH;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAAA;AA2CtE;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,iBAAiB,GAAG,SAAS;AAC1C,qCAAqC;AACrC,oBAAuB;AACvB,sEAAsE;AACtE,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxD,iBAAiB,MAAM,KACtB,WAAW,GAAG,IAiXhB,CAAA"}

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

@@ -2,10 +2,10 @@
 import { parseMimeType } from '@scalar/helpers/http/mime-type';
 import { isObject } from '@scalar/helpers/object/is-object';
 import { setValueAtPath } from '@scalar/helpers/object/set-value-at-path';
-import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { unpackProxyObject } from '@scalar/workspace-store/helpers/unpack-proxy';
 import { isObjectSchema } from '@scalar/workspace-store/schemas/v3.2/strict/type-guards';
 import { getExampleValue, getExplicitExampleText } from '../../../helpers/get-example-value.js';
+import { resolveFormSchema } from '../../../helpers/resolve-form-schema.js';
 import { buildMultipart, getMultipartItemSchema, isPositionalMultipart, needsMultipartEncoding, } from './build-multipart.js';
 import { getExampleFromBody } from './get-request-body-example.js';
 import { getSelectedBodyContentType } from './get-selected-body-content-type.js';
@@ -90,7 +90,7 @@ requestBodyCompositionSelection, openapiVersion) => {
     // object schema that declares it outside `required`, so undeclared and required keys are
     // always kept. This mirrors the unchecked-by-default checkbox in the Test Request panel.
     // The array (edited) form path is unaffected: it carries its own per-row `isDisabled`.
-    const resolvedBodySchema = getResolvedRef(requestBody.content[bodyContentType]?.schema, mergeSiblingReferences);
+    const resolvedBodySchema = resolveFormSchema(requestBody.content[bodyContentType]?.schema, requestBodyCompositionSelection);
     const objectBodySchema = resolvedBodySchema && isObjectSchema(resolvedBodySchema) ? resolvedBodySchema : undefined;
     // Composition (allOf/oneOf/anyOf) can mark a property required inside a subschema we do not
     // merge here, so skip dropping entirely for composed schemas rather than risk removing an
@@ -171,9 +171,7 @@ requestBodyCompositionSelection, openapiVersion) => {
         // lazily allocate the regrouped object for its top-level key and push it into
         // `entries` at the position of the *first* matching row, then keep folding leaves
         // into the same live object reference so interleaved flat rows keep their order.
-        const multipartSchema = result.mode === 'formdata'
-            ? getResolvedRef(requestBody.content[bodyContentType]?.schema, mergeSiblingReferences)
-            : undefined;
+        const multipartSchema = result.mode === 'formdata' ? resolvedBodySchema : undefined;
         const entries = result.mode === 'formdata' ? regroupMultipartRows(exampleValue, multipartSchema) : exampleValue;
         // Loop over all entries and add them to the form
         entries.forEach(({ name, value }) => {

package/dist/request-example/builder/body/schema-value-coercion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-value-coercion.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/schema-value-coercion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8DAA8D,CAAA;AAShG;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,YAAY,GAAG,SAAS,EAAE,UAAU,MAAM,EAAE,KAAG,YAAY,GAAG,SASvG,CAAA;AA2BD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,OAAO,EAAE,QAAQ,YAAY,GAAG,SAAS,KAAG,OAe9F,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,OAUnD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GAAI,QAAQ,OAAO,aAG1C,MAAM,UAAU,OAAO,YAkBzC,CAAA"}
+{"version":3,"file":"schema-value-coercion.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/schema-value-coercion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8DAA8D,CAAA;AAShG;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,YAAY,GAAG,SAAS,EAAE,UAAU,MAAM,EAAE,KAAG,YAAY,GAAG,SASvG,CAAA;AA2BD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,OAAO,EAAE,QAAQ,YAAY,GAAG,SAAS,KAAG,OAe9F,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,OAUnD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GAAI,QAAQ,OAAO,aAG1C,MAAM,UAAU,OAAO,YAgBzC,CAAA"}

package/dist/request-example/builder/body/schema-value-coercion.js

@@ -1,4 +1,4 @@
-import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { resolveSchemaWithAnnotations } from '@scalar/workspace-store/helpers/resolve-schema-with-annotations';
 import { isObjectSchema } from '@scalar/workspace-store/schemas/v3.2/strict/type-guards';
 /** Normalize a schema's `type` (string | string[] | absent) into a plain string array. */
 const normalizeSchemaTypes = (schema) => {
@@ -10,12 +10,12 @@ const normalizeSchemaTypes = (schema) => {
  * or undefined when any segment is not a declared object property.
  */
 export const resolveLeafSchema = (schema, segments) => {
-    let current = schema;
+    let current = resolveSchemaWithAnnotations(schema);
     for (const segment of segments) {
         if (!current || !isObjectSchema(current) || !current.properties) {
             return undefined;
         }
-        current = getResolvedRef(current.properties[segment], mergeSiblingReferences);
+        current = resolveSchemaWithAnnotations(current.properties[segment]);
     }
     return current;
 };
@@ -97,15 +97,13 @@ export const coerceUntypedValue = (value) => {
  * back into nested objects.
  */
 export const buildDottedNestedRowPredicate = (schema) => {
-    const resolved = schema ? getResolvedRef(schema, mergeSiblingReferences) : undefined;
+    const resolved = schema ? resolveSchemaWithAnnotations(schema) : undefined;
     if (!resolved || !isObjectSchema(resolved) || !resolved.properties) {
         return (_name, _value) => false;
     }
     const nestedTopKeys = new Set();
     for (const [key, child] of Object.entries(resolved.properties)) {
-        const childResolved = child
-            ? getResolvedRef(child, mergeSiblingReferences)
-            : undefined;
+        const childResolved = child ? resolveSchemaWithAnnotations(child) : undefined;
         if (childResolved && isObjectSchema(childResolved) && childResolved.properties) {
             nestedTopKeys.add(key);
         }

package/dist/request-example/builder/build-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-request.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/build-request.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,8BAA8B,CAAA;AAQnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAA;AAC/E,OAAO,EACL,KAAK,6BAA6B,EAEnC,MAAM,uDAAuD,CAAA;AAK9D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAwClD;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,cAAc,EACvB,cAAc,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,iBAAiB;IAAE,6BAA6B,CAAC,EAAE,OAAO,CAAA;CAAE,KAC3D,MAyBF,CAAA;AAED;;;;;KAKK;AACL,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kGAAkG;IAClG,cAAc,EAAE,cAAc,CAAA;IAC9B,2BAA2B;IAC3B,UAAU,EAAE,eAAe,CAAA;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAA;AAEnE,MAAM,MAAM,uBAAuB,GAAG,6BAA6B,GAAG,OAAO,oBAAoB,CAAA;AAEjG,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAAA;AAElF,eAAO,MAAM,YAAY,GACvB,SAAS,cAAc,EACvB,SAAS;IACP,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC;;;OAGG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAA;CACxC,KACA,kBAMF,CAAA"}
+{"version":3,"file":"build-request.d.ts","sourceRoot":"","sources":["../../../src/request-example/builder/build-request.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,8BAA8B,CAAA;AAQnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAA;AAC/E,OAAO,EACL,KAAK,6BAA6B,EAEnC,MAAM,uDAAuD,CAAA;AAK9D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAwClD;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,cAAc,EACvB,cAAc,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,iBAAiB;IAAE,6BAA6B,CAAC,EAAE,OAAO,CAAA;CAAE,KAC3D,MAyBF,CAAA;AAED;;;;;KAKK;AACL,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kGAAkG;IAClG,cAAc,EAAE,cAAc,CAAA;IAC9B,2BAA2B;IAC3B,UAAU,EAAE,eAAe,CAAA;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAA;AAEnE,MAAM,MAAM,uBAAuB,GAAG,6BAA6B,GAAG,OAAO,oBAAoB,CAAA;AAEjG,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAAA;AAElF,eAAO,MAAM,YAAY,GACvB,SAAS,cAAc,EACvB,SAAS;IACP,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC;;;OAGG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAA;CACxC,KACA,kBASF,CAAA"}

package/dist/request-example/builder/build-request.js

@@ -68,6 +68,9 @@ export const resolveExecutableRequestUrl = (request, envVariables, resolveOption
 /** Catch-all code when an unexpected synchronous error escapes a helper during request construction. */
 export const BUILD_REQUEST_FAILED = 'BUILD_REQUEST_FAILED';
 export const buildRequest = (request, options) => {
+    if (request.cookieErrors?.length) {
+        return err(BUILD_REQUEST_FAILED, request.cookieErrors[0]);
+    }
     const guarded = safeRun(() => buildRequestInner(request, options));
     if (!guarded.ok) {
         return err(BUILD_REQUEST_FAILED, guarded.error);

package/dist/request-example/builder/header/build-request-parameters.d.ts

@@ -1,5 +1,6 @@
 import { type XScalarCookie } from '@scalar/workspace-store/schemas/extensions/general/x-scalar-cookies';
 import type { ParameterObject, ReferenceType } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import type { ReservedPathParameter } from '../../../helpers/encode-path-parameter.js';
 /**
  * Converts the parameters into a set of headers, cookies and url params while
  * replacing environment variables and extracting example values. Also builds up a record of the path
@@ -14,10 +15,15 @@ export declare const buildRequestParameters: (
 /** All parameters */
 parameters?: ReferenceType<ParameterObject>[], 
 /** The key of the current example */
-exampleName?: string) => {
+exampleName?: string, 
+/** Reserved path expansion was introduced in OpenAPI 3.2. */
+openapiVersion?: string) => {
     cookies: XScalarCookie[];
+    /** Invalid active cookie parameters that prevent sending this request. */
+    cookieErrors?: string[];
     headers: Record<string, string>;
     pathVariables: Record<string, string>;
+    reservedPathParameters?: Record<string, ReservedPathParameter>;
     allowReservedQueryParameters: Set<string>;
     urlParams: URLSearchParams;
     serializedQuery?: string[];

package/dist/request-example/builder/header/build-request-parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-request-parameters.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/build-request-parameters.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,qEAAqE,CAAA;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAA;AAqBlH;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB;AACjC,qBAAqB;AACrB,aAAY,aAAa,CAAC,eAAe,CAAC,EAAO;AACjD,qCAAqC;AACrC,cAAa,MAAkB,KAC9B;IACD,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,4BAA4B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzC,SAAS,EAAE,eAAe,CAAA;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,wBAAwB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CA8IvC,CAAA"}
+{"version":3,"file":"build-request-parameters.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/build-request-parameters.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,qEAAqE,CAAA;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAA;AAElH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAoB5E;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB;AACjC,qBAAqB;AACrB,aAAY,aAAa,CAAC,eAAe,CAAC,EAAO;AACjD,qCAAqC;AACrC,cAAa,MAAkB;AAC/B,6DAA6D;AAC7D,iBAAiB,MAAM,KACtB;IACD,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAA;IAC9D,4BAA4B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzC,SAAS,EAAE,eAAe,CAAA;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,wBAAwB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CA+JvC,CAAA"}

package/dist/request-example/builder/header/build-request-parameters.js

@@ -1,4 +1,5 @@
 import { isDefined } from '@scalar/helpers/array/is-defined';
+import { getCookieSerializationError } from '@scalar/helpers/http/get-cookie-serialization-error';
 import { isObject } from '@scalar/helpers/object/is-object';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { xScalarCookieSchema, } from '@scalar/workspace-store/schemas/extensions/general/x-scalar-cookies';
@@ -23,7 +24,9 @@ export const buildRequestParameters = (
 /** All parameters */
 parameters = [], 
 /** The key of the current example */
-exampleName = 'default') => {
+exampleName = 'default', 
+/** Reserved path expansion was introduced in OpenAPI 3.2. */
+openapiVersion) => {
     const result = {
         cookies: [],
         headers: {},
@@ -123,6 +126,15 @@ exampleName = 'default') => {
                 // Path parameters use simple style by default
                 const serialized = serializeSimpleStyle(deSerializedValue, getExplode(param, false));
                 result.pathVariables[paramName] = String(serialized);
+                if (openapiVersion?.startsWith('3.2.') && 'schema' in param && param.allowReserved === true) {
+                    ;
+                    (result.reservedPathParameters ??= {})[paramName] = {
+                        value: deSerializedValue,
+                        originalValue: String(serialized),
+                        style: param.style ?? 'simple',
+                        explode: getExplode(param, false),
+                    };
+                }
                 break;
             }
             case 'query': {
@@ -130,6 +142,15 @@ exampleName = 'default') => {
                 break;
             }
             case 'cookie': {
+                const [major, minor] = (openapiVersion ?? '').split('.');
+                const error = major === '3' && minor === '2' && !('content' in param)
+                    ? getCookieSerializationError(param, deSerializedValue)
+                    : undefined;
+                if (error) {
+                    ;
+                    (result.cookieErrors ??= []).push(error);
+                    break;
+                }
                 if ('style' in param && param.style === 'cookie') {
                     result.cookies.push(...serializeCookieStyle(paramName, deSerializedValue, getExplode(param, true)).map((cookie) => coerceValue(xScalarCookieSchema, { ...cookie, path: '/' })));
                     break;

package/dist/request-example/builder/request-factory.d.ts

@@ -2,6 +2,7 @@ import type { XScalarEnvironment } from '@scalar/workspace-store/schemas/extensi
 import type { XScalarCookie } from '@scalar/workspace-store/schemas/extensions/general/x-scalar-cookies';
 import type { ServerObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 import type { OperationObject } from '@scalar/workspace-store/schemas/v3.2/strict/operation';
+import type { ReservedPathParameter } from '../../helpers/encode-path-parameter.js';
 import { type QuerystringParameter } from '../../helpers/querystring-parameter.js';
 import { type BuildRequestSecurityResult } from '../../request-example/builder/security/build-request-security.js';
 import type { SecuritySchemeObjectSecret } from '../../request-example/builder/security/secret-types.js';
@@ -74,6 +75,8 @@ import { type RequestBody } from './body/build-request-body.js';
  * ```
  */
 export type RequestFactory = {
+    /** Invalid active cookie declarations, retained for previews and reported before sending. */
+    cookieErrors?: string[];
     /**
      * The base API server URL prior to environment or server variable substitution.
      * May still contain placeholders such as `{version}` or `{region}`.
@@ -94,6 +97,8 @@ export type RequestFactory = {
         variables: Record<string, string>;
         /** Names whose example is already URI-encoded. */
         serializedParameters?: Set<string>;
+        /** Schema-based values using OpenAPI 3.2 reserved expansion. */
+        reservedParameters?: Record<string, ReservedPathParameter>;
         /**
          * The raw request path string, as entered by the user or read from the OpenAPI schema.
          * Placeholders are not yet substituted.
@@ -198,7 +203,7 @@ export declare const requestFactory: ({ exampleName, globalCookies, method, oper
     /** The selected security schemes for the current operation */
     selectedSecuritySchemes: SecuritySchemeObjectSecret[];
     /** Selected anyOf/oneOf request-body variants keyed by schema path */
-    /** Originating OpenAPI version, used for XML mapping rules. */
+    /** Originating OpenAPI version, used for version-specific serialization. */
     openapiVersion?: string;
     requestBodyCompositionSelection?: Record<string, number>;
 }) => {