@scalar/workspace-store 0.64.0 → 0.66.0

package/dist/mutators/operation/parameters.js

@@ -1,5 +1,7 @@
 import { getPathItemOperation } from '../../helpers/for-each-path-item-operation.js';
+import { getParameterExample } from '../../helpers/get-parameter-example.js';
 import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+import { getQuerystringParameter, serializeQuerystringParameter } from '../../helpers/querystring-parameter.js';
 import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
 import { isOpenApiDocument } from '../../schemas/type-guards.js';
 import { isContentTypeParameterObject } from '../../schemas/v3.2/strict/type-guards.js';
@@ -41,8 +43,13 @@ const getPathItemsForParameterMutation = (pathItemRef) => {
 export const upsertOperationParameter = (document, { meta, type, payload, originalParameter }) => {
     // We are editing an existing parameter
     if (originalParameter) {
+        const querystring = getQuerystringParameter(originalParameter, meta.exampleKey, { includeDisabled: true });
+        const preserveQuerystringValue = querystring && payload.value === serializeQuerystringParameter(querystring);
         const param = originalParameter;
-        const target = isContentTypeParameterObject(param) ? Object.values(param.content ?? {})[0] : param;
+        const selected = getParameterExample(param, meta.exampleKey);
+        const target = param.in !== 'querystring' && !selected.serialized && isContentTypeParameterObject(param)
+            ? Object.values(param.content ?? {})[0]
+            : param;
         if (!target) {
             return;
         }
@@ -77,7 +84,39 @@ export const upsertOperationParameter = (document, { meta, type, payload, origin
             return;
         }
         // Update the example value and disabled state
-        example.value = payload.value;
+        if (param.in === 'querystring') {
+            // The whole-query editor displays the URI-ready value, including percent encoding.
+            delete example.value;
+            delete example.dataValue;
+            // Inline edits replace the external example source as well as its cached representation.
+            delete example.externalValue;
+            delete example.serializedValue;
+            // Toggling an unchanged preview must preserve data and environment placeholders
+            // so future environment changes still happen before serialization.
+            if (preserveQuerystringValue && querystring.kind !== 'uri-ready') {
+                if (querystring.kind === 'serialized') {
+                    example.value = querystring.value;
+                }
+                else {
+                    example.dataValue = querystring.value;
+                }
+            }
+            else {
+                example.serializedValue = String(payload.value);
+            }
+        }
+        else {
+            delete example.dataValue;
+            delete example.serializedValue;
+            delete example.externalValue;
+            if (selected.serialized || selected.mediaSerialized) {
+                delete example.value;
+                example.serializedValue = String(payload.value);
+            }
+            else {
+                example.value = payload.value;
+            }
+        }
         example['x-disabled'] = payload.isDisabled;
         return;
     }
@@ -212,5 +251,6 @@ export const deleteAllOperationParameters = (document, { meta, type }) => {
         return;
     }
     // Filter out parameters of the specified type
-    operation.parameters = operation.parameters?.filter((it) => getResolvedRef(it)?.in !== type) ?? [];
+    operation.parameters =
+        operation.parameters?.filter((it) => getResolvedRef(it)?.in !== type && !(type === 'query' && getResolvedRef(it)?.in === 'querystring')) ?? [];
 };

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":"AACA,OAAO,EAAE,KAAK,4BAA4B,EAAgC,MAAM,6BAA6B,CAAA;AAE7G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAG7D,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,mBAmJxF,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,mBAyJxF,CAAA"}

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

@@ -1,5 +1,16 @@
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
 import { slugify } from '@scalar/helpers/string/slugify';
 import { DEFAULT_MODELS_SECTION_LABEL } from '@scalar/types/api-reference';
+/**
+ * Fixed fields retain their existing links; authored variants need a distinct namespace.
+ * Extension methods retain exact case because HTTP method tokens are case-sensitive.
+ * Normalizing COPY and copy would collapse distinct operations onto the same anchor.
+ */
+const getMethodId = (method) => isHttpMethod(method)
+    ? method === method.toLowerCase()
+        ? method.toUpperCase()
+        : `additionalOperations/${method}`
+    : method;
 /**
  * Returns options for traversing an OpenAPI document, allowing customization of
  * how IDs and slugs are generated for tags, headings, models, operations, and webhooks.
@@ -65,11 +76,13 @@ export const getNavigationOptions = (documentName, options) => {
                 return `${prefixTag}${options.generateOperationSlug({
                     path: props.path,
                     operationId: props.operation.operationId,
-                    method: props.method.toUpperCase(),
+                    method: isHttpMethod(props.method) && props.method === props.method.toLowerCase()
+                        ? props.method.toUpperCase()
+                        : props.method,
                     summary: props.operation.summary,
                 })}`;
             }
-            return `${prefixTag}${props.method.toUpperCase()}${props.path}`;
+            return `${prefixTag}${getMethodId(props.method)}${props.path}`;
         }
         // -------- Default webhook id generation logic --------
         if (props.type === 'webhook') {
@@ -83,13 +96,15 @@ export const getNavigationOptions = (documentName, options) => {
             if (options?.generateWebhookSlug) {
                 return `${prefixTag}webhook/${options.generateWebhookSlug({
                     name: props.name,
-                    method: props.method?.toUpperCase(),
+                    method: isHttpMethod(props.method) && props.method === props.method.toLowerCase()
+                        ? props.method.toUpperCase()
+                        : props.method,
                 })}`;
             }
             // Webhook events are commonly named with dots (e.g. "account_holder.created").
             // Keep the dot so the deep link stays close to the event name, instead of
             // dropping it and joining adjacent words ("account-holdercreated").
-            return `${prefixTag}webhook/${props.method?.toUpperCase()}/${slugify(props.name, { allowedSpecialChars: '.' })}`;
+            return `${prefixTag}webhook/${getMethodId(props.method)}/${slugify(props.name, { allowedSpecialChars: '.' })}`;
         }
         // -------- Default model id generation logic --------
         if (props.type === 'model') {

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":"AAOA,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;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"}

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

@@ -1,5 +1,5 @@
 import { escapeJsonPointer } from '@scalar/json-magic/helpers/escape-json-pointer';
-import { forEachPathItemOperation } from '../../helpers/for-each-path-item-operation.js';
+import { forEachPathItemOperation, getPathItemOperationKey } from '../../helpers/for-each-path-item-operation.js';
 import { getResolvedRef, mergeSiblingReferences } from '../../helpers/get-resolved-ref.js';
 import { isHidden } from '../../helpers/is-hidden.js';
 import { traverseOperationExamples } from '../../navigation/helpers/traverse-examples.js';
@@ -83,7 +83,7 @@ export const traversePaths = ({ document, tagsMap, generateId, documentId, opera
             if (isHidden(operation)) {
                 return;
             }
-            const ref = `#/paths/${escapeJsonPointer(path)}/${method}`;
+            const ref = `#/paths/${escapeJsonPointer(path)}/${getPathItemOperationKey(method)}`;
             // Traverse tags
             if (operation.tags?.length) {
                 operation.tags.forEach((tagName) => {

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":"AAMA,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;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"}

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

@@ -1,4 +1,4 @@
-import { forEachPathItemOperation } from '../../helpers/for-each-path-item-operation.js';
+import { forEachPathItemOperation, getPathItemOperationKey } from '../../helpers/for-each-path-item-operation.js';
 import { getResolvedRef, mergeSiblingReferences } from '../../helpers/get-resolved-ref.js';
 import { isHidden } from '../../helpers/is-hidden.js';
 import { isDeprecatedOperation } from '../../navigation/helpers/traverse-paths.js';
@@ -62,7 +62,7 @@ export const traverseWebhooks = ({ document, tagsMap, generateId, untaggedWebhoo
             if (isHidden(operation)) {
                 return;
             }
-            const ref = `#/webhooks/${name}/${method}`;
+            const ref = `#/webhooks/${name}/${getPathItemOperationKey(method)}`;
             if (operation.tags?.length) {
                 operation.tags.forEach((tagName) => {
                     const { tag, id: tagId } = getTag({ tagsMap, name: tagName, documentId, generateId });

package/dist/navigation/helpers/update-order-ids.d.ts

@@ -1,4 +1,3 @@
-import type { HttpMethod } from '@scalar/helpers/http/http-methods';
 import type { WorkspaceStore } from '../../client.js';
 import type { IdGenerator, TraversedOperation, TraversedTag, TraversedWebhook, WithParent } from '../../schemas/navigation.js';
 import type { TagObject } from '../../schemas/v3.2/strict/openapi-document.js';
@@ -10,7 +9,7 @@ type UpdateOrderIdParams = {
     /** Operation or webhook entries to update the order ID for */
     entries: (WithParent<TraversedOperation> | WithParent<TraversedWebhook>)[];
     operation: OperationObject;
-    method: HttpMethod;
+    method: string;
     path: string;
 } | {
     /** Tag entries to update the order ID for */

package/dist/navigation/helpers/update-order-ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-order-ids.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/update-order-ids.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEvH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAEtE,KAAK,mBAAmB,GAAG;IACzB,KAAK,EAAE,cAAc,CAAA;IACrB,UAAU,EAAE,WAAW,CAAA;CACxB,GAAG,CACA;IACE,8DAA8D;IAC9D,OAAO,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAA;IAC1E,SAAS,EAAE,eAAe,CAAA;IAC1B,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;CACb,GACD;IACE,6CAA6C;IAC7C,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,CAAA;IACnC,GAAG,EAAE,SAAS,CAAA;CACf,CACJ,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,gCAAgC,mBAAmB,SAiEjF,CAAA"}
+{"version":3,"file":"update-order-ids.d.ts","sourceRoot":"","sources":["../../../src/navigation/helpers/update-order-ids.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEvH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAEtE,KAAK,mBAAmB,GAAG;IACzB,KAAK,EAAE,cAAc,CAAA;IACrB,UAAU,EAAE,WAAW,CAAA;CACxB,GAAG,CACA;IACE,8DAA8D;IAC9D,OAAO,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAA;IAC1E,SAAS,EAAE,eAAe,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,GACD;IACE,6CAA6C;IAC7C,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,CAAA;IACnC,GAAG,EAAE,SAAS,CAAA;CACf,CACJ,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,gCAAgC,mBAAmB,SAiEjF,CAAA"}

package/dist/plugins/bundler/index.d.ts

@@ -117,4 +117,5 @@ export declare const syncPathParameters: () => LifecyclePlugin;
  * These keys are used for internal purposes and are not needed in the final bundled document.
  */
 export declare const removeExtraScalarKeys: () => LifecyclePlugin;
+export { openApiDocument, resolveOpenApiDocument } from './openapi-document.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/plugins/bundler/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/bundler/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,2BAA2B,CAAA;AAStF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAO,eAahC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KAAG,eA2CpE,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,QAAO,eAwCjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,QAAO,eAuBtC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,QAAO,eAuBvC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAAO,eAyBhC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,QAAO,eAkFrC,CAAA;AAKD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAO,eAaxC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/bundler/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,2BAA2B,CAAA;AAStF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAO,eAahC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KAAG,eA2CpE,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,QAAO,eAwCjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,QAAO,eA6BtC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,QAAO,eAuBvC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAAO,eAyBhC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,QAAO,eAmFrC,CAAA;AAKD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAO,eAaxC,CAAA;AAED,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/plugins/bundler/index.js

@@ -149,9 +149,15 @@ export const refsEverywhere = () => {
 export const restoreOriginalRefs = () => {
     return {
         type: 'lifecycle',
-        onBeforeNodeProcess: (node, context) => {
+        onAfterNodeProcess: (node, context) => {
             const ref = node['$ref'];
             const root = context.rootNode;
+            const authoredRefs = root['x-scalar-original-refs'];
+            const authored = isObject(authoredRefs) ? authoredRefs[JSON.stringify(context.path)] : undefined;
+            if (isObject(authored) && typeof authored.original === 'string' && authored.rewritten === ref) {
+                node['$ref'] = authored.original;
+                return;
+            }
             const extUrls = root['x-ext-urls'];
             // Only process if $ref is a string and x-ext-urls is a valid object
             if (typeof ref !== 'string' || typeof extUrls !== 'object' || extUrls === null || !isLocalRef(ref)) {
@@ -267,8 +273,9 @@ export const syncPathParameters = () => {
             }
             const pathString = path[1];
             // Sync parameters for each operation method
-            for (const method of HTTP_METHODS) {
-                const operation = getResolvedRef(node[method], context);
+            const additionalOperations = isObject(node.additionalOperations) ? Object.values(node.additionalOperations) : [];
+            for (const operationNode of [...HTTP_METHODS.map((method) => node[method]), ...additionalOperations]) {
+                const operation = getResolvedRef(operationNode, context);
                 if (!isObject(operation)) {
                     continue;
                 }
@@ -334,3 +341,4 @@ export const removeExtraScalarKeys = () => {
         },
     };
 };
+export { openApiDocument, resolveOpenApiDocument } from './openapi-document.js';

package/dist/plugins/bundler/openapi-document.d.ts

@@ -0,0 +1,6 @@
+import { type DocumentResolver, type LifecyclePlugin } from '@scalar/json-magic/bundle';
+/** Resolves an OpenAPI document's declared identity against its retrieval location. */
+export declare const resolveOpenApiDocument: DocumentResolver;
+/** Honors `$self` for complete OpenAPI documents, including external and cached documents. */
+export declare const openApiDocument: () => LifecyclePlugin;
+//# sourceMappingURL=openapi-document.d.ts.map

package/dist/plugins/bundler/openapi-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-document.d.ts","sourceRoot":"","sources":["../../../src/plugins/bundler/openapi-document.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAwB,MAAM,2BAA2B,CAAA;AAE7G,uFAAuF;AACvF,eAAO,MAAM,sBAAsB,EAAE,gBAcpC,CAAA;AAED,8FAA8F;AAC9F,eAAO,MAAM,eAAe,QAAO,eAsClC,CAAA"}

package/dist/plugins/bundler/openapi-document.js

@@ -0,0 +1,57 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+import { resolveReferencePath } from '@scalar/json-magic/bundle';
+/** Resolves an OpenAPI document's declared identity against its retrieval location. */
+export const resolveOpenApiDocument = (document, retrievalUri) => {
+    if (!isObject(document) ||
+        typeof document.openapi !== 'string' ||
+        !/^3\.2\.\d+$/.test(document.openapi) ||
+        typeof document.$self !== 'string') {
+        return undefined;
+    }
+    const self = resolveReferencePath(retrievalUri, document.$self);
+    // RFC 3986 requires a fragment-free base, while the declared identity can retain its fragment.
+    const fragmentIndex = self.indexOf('#');
+    const baseUri = fragmentIndex === -1 ? self : self.slice(0, fragmentIndex);
+    return { baseUri, metadata: { openapi: document.openapi, $self: self } };
+};
+/** Honors `$self` for complete OpenAPI documents, including external and cached documents. */
+export const openApiDocument = () => {
+    const authoredRefs = new WeakMap();
+    const paths = new WeakMap();
+    const indexPaths = (value, path) => {
+        if (value === null || typeof value !== 'object' || paths.has(value))
+            return;
+        paths.set(value, path);
+        for (const [key, child] of Object.entries(value)) {
+            indexPaths(child, [...path, key]);
+        }
+    };
+    return {
+        type: 'lifecycle',
+        resolveDocument: resolveOpenApiDocument,
+        onBeforeNodeProcess: (node, context) => {
+            if (typeof node.$ref === 'string' && resolveOpenApiDocument(context.rootNode, context.origin)) {
+                // Partial bundles report paths relative to the selected subtree. Index the supplied root
+                // so the saved references can also be restored when exporting the entire document.
+                indexPaths(context.rootNode, []);
+                authoredRefs.set(node, node.$ref);
+            }
+        },
+        onAfterNodeProcess: (node, context) => {
+            const authored = authoredRefs.get(node);
+            if (authored === undefined || authored === node.$ref) {
+                return;
+            }
+            // A path-based map survives serialization and partial bundles without changing Reference Objects.
+            // Keep the first spelling, including fragments and ./, when a later pass rewrites it again.
+            const root = context.rootNode;
+            const existing = root['x-scalar-original-refs'];
+            const mapping = isObject(existing) ? existing : {};
+            const key = JSON.stringify(paths.get(node) ?? context.path);
+            const previous = mapping[key];
+            const original = isObject(previous) && previous.rewritten === authored ? previous.original : authored;
+            mapping[key] = { original, rewritten: node.$ref };
+            root['x-scalar-original-refs'] = mapping;
+        },
+    };
+};

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

@@ -0,0 +1,29 @@
+import type { MediaTypeObject, SchemaObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+/** Multipart parts stay structured until sending so nested text can resolve environment variables. */
+export type MultipartPart = {
+    key?: string;
+    contentType?: string;
+    headers?: Record<string, string>;
+} & ({
+    type: 'text';
+    value: string;
+} | {
+    type: 'file';
+    value: File;
+} | {
+    type: 'blob';
+    value: Blob;
+} | {
+    type: 'multipart';
+    value: MultipartPart[];
+    contentType: string;
+});
+/** Identify ordered multipart independently of the editor's row representation. */
+export declare const isPositionalMultipart: (contentType: string, media: MediaTypeObject) => boolean;
+/** Whether a media type needs ordered or nested multipart serialization. */
+export declare const needsMultipartEncoding: (contentType: string, media: MediaTypeObject) => boolean;
+/** Resolve a positional item's schema independently of the encoding prefix length. */
+export declare const getMultipartItemSchema: (schema: SchemaObject | undefined, index: number, itemSchema?: MediaTypeObject["itemSchema"]) => SchemaObject | undefined;
+/** Build ordered parts, applying prefix encodings independently of schema prefix lengths. */
+export declare const buildMultipart: (value: unknown, contentType: string, encoding?: Pick<MediaTypeObject, "encoding" | "prefixEncoding" | "itemEncoding" | "itemSchema">, schema?: SchemaObject, nesting?: number) => MultipartPart[];
+//# sourceMappingURL=build-multipart.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-multipart.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/body/build-multipart.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACb,MAAM,8DAA8D,CAAA;AAQrE,sGAAsG;AACtG,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC,GAAG,CACA;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CACrE,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,GAAI,aAAa,MAAM,EAAE,OAAO,eAAe,KAAG,OASnF,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,GAAI,aAAa,MAAM,EAAE,OAAO,eAAe,KAAG,OASpF,CAAA;AA4CD,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,GACjC,QAAQ,YAAY,GAAG,SAAS,EAChC,OAAO,MAAM,EACb,aAAa,eAAe,CAAC,YAAY,CAAC,KACzC,YAAY,GAAG,SAMa,CAAA;AAc/B,6FAA6F;AAC7F,eAAO,MAAM,cAAc,GACzB,OAAO,OAAO,EACd,aAAa,MAAM,EACnB,WAAU,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,gBAAgB,GAAG,cAAc,GAAG,YAAY,CAAM,EACnG,SAAS,YAAY,EACrB,gBAAW,KACV,aAAa,EAkIf,CAAA"}

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

@@ -0,0 +1,191 @@
+import { parseMimeType } from '@scalar/helpers/http/mime-type';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { unpackProxyObject } from '@scalar/workspace-store/helpers/unpack-proxy';
+import { isArraySchema } from '@scalar/workspace-store/schemas/v3.2/strict/type-guards';
+import { serializeXmlPart } from '../../xml/serialize-xml-part.js';
+import { MAX_MULTIPART_NESTING } from './multipart-limits.js';
+import { resolveLeafSchema } from './schema-value-coercion.js';
+import { hasEncodingStyle, serializeFormPropertyWithEncoding } from './serialize-form-property.js';
+/** Identify ordered multipart independently of the editor's row representation. */
+export const isPositionalMultipart = (contentType, media) => {
+    const schema = getResolvedRef(media.schema);
+    return (parseMimeType(contentType).essence !== 'multipart/form-data' ||
+        media.prefixEncoding !== undefined ||
+        media.itemEncoding !== undefined ||
+        (schema !== undefined && isArraySchema(schema)) ||
+        media.itemSchema !== undefined);
+};
+/** Whether a media type needs ordered or nested multipart serialization. */
+export const needsMultipartEncoding = (contentType, media) => {
+    const mime = parseMimeType(contentType);
+    return (mime.type === 'multipart' &&
+        (isPositionalMultipart(contentType, media) ||
+            Object.values(media.encoding ?? {}).some((encoding) => parseMimeType(encoding.contentType).type === 'multipart' || encoding.encoding !== undefined)));
+};
+const defaultContentType = (schema, value) => {
+    if (value instanceof Blob) {
+        return value.type || 'application/octet-stream';
+    }
+    // OpenAPI 3.2.1 Encoding Object defaults explicitly treat absent type as binary.
+    // With no schema at all, infer from the example so existing editor values remain usable.
+    if (schema && (!('type' in schema) || !schema.type || (schema.type === 'string' && schema.contentEncoding))) {
+        return 'application/octet-stream';
+    }
+    return typeof value === 'object' && value !== null ? 'application/json' : 'text/plain';
+};
+/** Encoding accepts ranges, but each wire header needs a single concrete media type. */
+const selectContentType = (encoding, schema, value) => {
+    const fallback = defaultContentType(schema, value);
+    if (!encoding) {
+        return fallback;
+    }
+    if (/[\r\n\0]/.test(encoding)) {
+        throw new Error('Invalid multipart content type');
+    }
+    const choices = encoding.split(',').map((choice) => choice.trim());
+    const preferred = parseMimeType(fallback);
+    const match = choices.find((choice) => {
+        const mime = parseMimeType(choice);
+        return ((mime.type === '*' || mime.type === preferred.type) &&
+            (mime.subtype === '*' || mime.subtype === preferred.subtype));
+    });
+    if (match) {
+        const mime = parseMimeType(match);
+        if (!mime.essence.includes('*')) {
+            return match;
+        }
+        // Keep parameters from the range while replacing only its wildcard essence.
+        return match.replace(/^[^;]+/, preferred.essence);
+    }
+    // A nonmatching range cannot supply a concrete wire type; keep the inferred fallback.
+    return choices.find((choice) => !parseMimeType(choice).essence.includes('*')) ?? fallback;
+};
+/** Resolve a positional item's schema independently of the encoding prefix length. */
+export const getMultipartItemSchema = (schema, index, itemSchema) => getResolvedRef((schema && 'prefixItems' in schema ? schema.prefixItems?.[index] : undefined) ??
+    (schema && 'items' in schema ? schema.items : undefined) ??
+    itemSchema, mergeSiblingReferences);
+/** Serialize structured values to the selected part format; strings already containing XML stay intact. */
+const serializePartValue = (value, contentType, schema) => {
+    const subtype = contentType ? parseMimeType(contentType).subtype : undefined;
+    if ((subtype === 'xml' || subtype?.endsWith('+xml')) && isObject(value)) {
+        return serializeXmlPart(value, schema);
+    }
+    const json = subtype === 'json' || subtype?.endsWith('+json');
+    return json || (value !== null && typeof value === 'object')
+        ? JSON.stringify(unpackProxyObject(value))
+        : String(value ?? '');
+};
+/** Build ordered parts, applying prefix encodings independently of schema prefix lengths. */
+export const buildMultipart = (value, contentType, encoding = {}, schema, nesting = 0) => {
+    if (nesting >= MAX_MULTIPART_NESTING) {
+        throw new Error('Maximum multipart nesting exceeded');
+    }
+    const named = parseMimeType(contentType).essence === 'multipart/form-data';
+    const positional = Array.isArray(value);
+    const entries = positional
+        ? value.map((item, index) => {
+            const itemEncoding = index < (encoding.prefixEncoding?.length ?? 0) ? encoding.prefixEncoding?.[index] : encoding.itemEncoding;
+            const itemSchema = getMultipartItemSchema(schema, index, encoding.itemSchema);
+            if (named && item !== null && typeof item === 'object' && !Array.isArray(item)) {
+                // Each position describes one named part; accepting more keys would silently discard data.
+                const entries = Object.entries(item);
+                const entry = entries[0];
+                if (entries.length !== 1 || !entry) {
+                    throw new Error('Named positional multipart items must contain exactly one property');
+                }
+                return [entry[0], entry[1], itemEncoding, resolveLeafSchema(itemSchema, [entry[0]])];
+            }
+            return [undefined, item, itemEncoding, itemSchema];
+        })
+        : value !== null && typeof value === 'object'
+            ? Object.entries(value).flatMap(([key, item]) => {
+                const propertySchema = resolveLeafSchema(schema, [key]);
+                return (Array.isArray(item) ? item : [item]).map((part) => [
+                    key,
+                    part,
+                    encoding.encoding?.[key],
+                    Array.isArray(item)
+                        ? getResolvedRef(propertySchema && isArraySchema(propertySchema) ? propertySchema.items : undefined, mergeSiblingReferences)
+                        : propertySchema,
+                ]);
+            })
+            : [];
+    return entries.flatMap(([key, item, partEncoding, partSchema]) => {
+        const style = named && hasEncodingStyle(partEncoding);
+        const styleParts = style ? serializeFormPropertyWithEncoding(key ?? '', item, partEncoding) : null;
+        const partContentType = style ? undefined : selectContentType(partEncoding?.contentType, partSchema, item);
+        const headers = Object.fromEntries(Object.entries(partEncoding?.headers ?? {}).flatMap(([name, ref]) => {
+            if (name.toLowerCase() === 'content-type') {
+                return [];
+            }
+            const header = getResolvedRef(ref);
+            if (!header || !('schema' in header)) {
+                return [];
+            }
+            const headerSchema = getResolvedRef(header.schema);
+            const example = header?.example ??
+                getResolvedRef(Object.values(header?.examples ?? {})[0])?.value ??
+                headerSchema?.const ??
+                headerSchema?.default;
+            return example === undefined ? [] : [[name, String(example)]];
+        }));
+        if (partSchema?.contentEncoding &&
+            !Object.keys(headers).some((name) => name.toLowerCase() === 'content-transfer-encoding')) {
+            headers['Content-Transfer-Encoding'] = partSchema.contentEncoding;
+        }
+        const metadata = {
+            ...(key === undefined ? {} : { key }),
+            ...(partContentType ? { contentType: partContentType } : {}),
+            ...(Object.keys(headers).length ? { headers } : {}),
+        };
+        if (styleParts) {
+            return styleParts.map((part) => ({ ...metadata, type: 'text', ...part }));
+        }
+        if (partContentType &&
+            parseMimeType(partContentType).type === 'multipart' &&
+            typeof item !== 'string' &&
+            !(item instanceof Blob)) {
+            return [
+                {
+                    ...metadata,
+                    type: 'multipart',
+                    contentType: partContentType,
+                    value: buildMultipart(item, partContentType, partEncoding, partSchema, nesting + 1),
+                },
+            ];
+        }
+        if (partContentType &&
+            parseMimeType(partContentType).essence === 'application/x-www-form-urlencoded' &&
+            item !== null &&
+            typeof item === 'object') {
+            const params = Object.entries(item).flatMap(([name, fieldValue]) => (Array.isArray(fieldValue) ? fieldValue : [fieldValue]).flatMap((field) => {
+                const fieldEncoding = partEncoding?.encoding?.[name];
+                const styled = serializeFormPropertyWithEncoding(name, field, fieldEncoding);
+                if (styled) {
+                    return styled;
+                }
+                return [
+                    {
+                        key: name,
+                        value: serializePartValue(field, hasEncodingStyle(fieldEncoding) ? undefined : fieldEncoding?.contentType),
+                    },
+                ];
+            }));
+            return [
+                {
+                    ...metadata,
+                    type: 'text',
+                    value: new URLSearchParams(params.map((part) => [part.key, part.value])).toString(),
+                },
+            ];
+        }
+        if (item instanceof File) {
+            return [{ ...metadata, type: 'file', value: unpackProxyObject(item) }];
+        }
+        if (item instanceof Blob) {
+            return [{ ...metadata, type: 'blob', value: unpackProxyObject(item) }];
+        }
+        return [{ ...metadata, type: 'text', value: serializePartValue(item, partContentType, partSchema) }];
+    });
+};

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

@@ -1,4 +1,5 @@
 import type { RequestBodyObject } from '@scalar/workspace-store/schemas/v3.2/strict/request-body';
+import { type MultipartPart } from './build-multipart.js';
 type FormData = {
     mode: 'formdata';
     value: ({
@@ -30,7 +31,11 @@ type Raw = {
     value: string | File | Blob;
     contentType?: string;
 };
-export type RequestBody = FormData | UrlEncoded | Raw;
+export type RequestBody = FormData | UrlEncoded | Raw | {
+    mode: 'multipart';
+    contentType: string;
+    value: MultipartPart[];
+};
 /**
  * Create the fetch request body
  */

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":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0DAA0D,CAAA;AASjG,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,GAAG,QAAQ,GAAG,UAAU,GAAG,GAAG,CAAA;AAKrD;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,iBAAiB,GAAG,SAAS;AAC1C,qCAAqC;AACrC,oBAAuB;AACvB,sEAAsE;AACtE,kCAAkC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KACvD,WAAW,GAAG,IAuUhB,CAAA"}
+{"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,KACvD,WAAW,GAAG,IA8WhB,CAAA"}