@scalar/workspace-store 0.63.0 → 0.65.0

package/dist/helpers/serialize-stream-example.js

@@ -0,0 +1,52 @@
+import { getStreamFormat } from '@scalar/helpers/http/is-streaming-content-type';
+import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * Frame generated values and authored structured examples as sequential content.
+ * Callers bypass this helper for authored strings that already contain wire framing.
+ * SSE objects with no valid fields are omitted with one warning per call; an empty
+ * input sequence is valid and does not produce a warning.
+ */
+export const serializeStreamExample = (value, contentType, singleItem) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const format = getStreamFormat(contentType);
+    const items = singleItem ? [value] : Array.isArray(value) ? value : [value];
+    if (format === 'json-lines') {
+        return items.map((item) => `${JSON.stringify(item)}\n`).join('');
+    }
+    if (format === 'json-seq') {
+        return items.map((item) => `\u001e${JSON.stringify(item)}\n`).join('');
+    }
+    if (format === 'sse') {
+        const frames = items.map((item) => {
+            if (!isObject(item)) {
+                return `data: ${JSON.stringify(item)}\n\n`;
+            }
+            const fields = ['event', 'id', 'retry', 'data'].flatMap((field) => {
+                const fieldValue = item[field];
+                if (field === 'retry') {
+                    return typeof fieldValue === 'number' && Number.isInteger(fieldValue) && fieldValue >= 0
+                        ? [`retry: ${fieldValue}`]
+                        : [];
+                }
+                if (field === 'data' && fieldValue !== undefined) {
+                    const data = typeof fieldValue === 'string' ? fieldValue : JSON.stringify(fieldValue);
+                    return data.split(/\r\n|\r|\n/).map((line) => `data: ${line}`);
+                }
+                if (typeof fieldValue !== 'string' || (field === 'id' && fieldValue.includes('\0'))) {
+                    return [];
+                }
+                const lines = fieldValue.split(/\r\n|\r|\n/);
+                return lines.length === 1 ? [`${field}: ${fieldValue}`] : [];
+            });
+            return fields.length ? `${fields.join('\n')}\n\n` : '';
+        });
+        const omitted = frames.filter((frame) => frame === '').length;
+        if (omitted > 0) {
+            console.warn(`Skipped ${omitted} SSE example item(s) with no valid event, id, retry, or data fields.`);
+        }
+        return frames.join('');
+    }
+    return undefined;
+};

package/dist/helpers/use-external-examples.d.ts

@@ -0,0 +1,15 @@
+import { type ComponentPublicInstance, type ComputedRef, type InjectionKey, type Ref } from 'vue';
+import { type ExternalExampleResolver } from '../helpers/external-examples.js';
+import type { ExampleObject } from '../schemas/v3.2/strict/openapi-document.js';
+/** Supply the current document's resolver so consumers share downloads and invalidation. */
+export declare const EXTERNAL_EXAMPLES: InjectionKey<() => ExternalExampleResolver>;
+/** Observe current visibility, rather than mounting, to avoid fetching every operation on a long page. */
+export declare const useExampleVisibility: (target: Ref<Element | ComponentPublicInstance | null>) => Ref<boolean>;
+/** Resolve only the selected examples and expose immutable views of their downloaded values. */
+export declare const useExternalExamples: (examples: () => (ExampleObject | undefined)[], enabled?: () => boolean, resolver?: () => ExternalExampleResolver) => {
+    pending: ComputedRef<boolean>;
+    failed: ComputedRef<boolean>;
+    resolve: (example: ExampleObject | undefined) => ExampleObject | undefined;
+    retry: () => Promise<void>;
+};
+//# sourceMappingURL=use-external-examples.d.ts.map

package/dist/helpers/use-external-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-external-examples.d.ts","sourceRoot":"","sources":["../../src/helpers/use-external-examples.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,GAAG,EAOT,MAAM,KAAK,CAAA;AAEZ,OAAO,EAAE,KAAK,uBAAuB,EAAiC,MAAM,6BAA6B,CAAA;AACzG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,4FAA4F;AAC5F,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAAC,MAAM,uBAAuB,CAA+B,CAAA;AAEzG,0GAA0G;AAC1G,eAAO,MAAM,oBAAoB,GAAI,QAAQ,GAAG,CAAC,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAAC,KAAG,GAAG,CAAC,OAAO,CAuBvG,CAAA;AAED,gGAAgG;AAChG,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,CAAC,aAAa,GAAG,SAAS,CAAC,EAAE,EAC7C,UAAS,MAAM,OAAoB,EACnC,WAAW,MAAM,uBAAuB,KACvC;IACD,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IAC7B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IAC5B,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,KAAK,aAAa,GAAG,SAAS,CAAA;IAC1E,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAsC3B,CAAA"}

package/dist/helpers/use-external-examples.js

@@ -0,0 +1,62 @@
+import { computed, inject, onScopeDispose, ref, watch, watchEffect, } from 'vue';
+import { createExternalExampleResolver } from '../helpers/external-examples.js';
+/** Supply the current document's resolver so consumers share downloads and invalidation. */
+export const EXTERNAL_EXAMPLES = Symbol('external-examples');
+/** Observe current visibility, rather than mounting, to avoid fetching every operation on a long page. */
+export const useExampleVisibility = (target) => {
+    const visible = ref(false);
+    let observer;
+    watch(target, (element) => {
+        observer?.disconnect();
+        visible.value = false;
+        const node = element && ('$el' in element ? element.$el : element);
+        if (typeof Element === 'undefined' || !(node instanceof Element))
+            return;
+        if (typeof IntersectionObserver === 'undefined') {
+            visible.value = true;
+            return;
+        }
+        observer = new IntersectionObserver(([entry]) => {
+            visible.value = entry?.isIntersecting ?? false;
+        });
+        observer.observe(node);
+    }, { flush: 'post' });
+    onScopeDispose(() => observer?.disconnect());
+    return visible;
+};
+/** Resolve only the selected examples and expose immutable views of their downloaded values. */
+export const useExternalExamples = (examples, enabled = () => true, resolver) => {
+    const fallback = createExternalExampleResolver();
+    const getResolver = resolver ?? inject(EXTERNAL_EXAMPLES, () => fallback);
+    const states = computed(() => examples()
+        .filter((example) => example !== undefined && example.value === undefined && !!example.externalValue)
+        .map((example) => getResolver()(example)));
+    watchEffect(() => {
+        if (!enabled())
+            return;
+        for (const state of states.value) {
+            if (state.status === 'idle')
+                void state.load();
+        }
+    });
+    return {
+        pending: computed(() => states.value.some((state) => state.status !== 'loaded')),
+        failed: computed(() => states.value.some((state) => state.status === 'error')),
+        resolve: (example) => {
+            if (!example || example.value !== undefined || !example.externalValue)
+                return example;
+            const state = getResolver()(example);
+            if (state.status !== 'loaded')
+                return example;
+            // A 3.2 example can pair structured data with external wire text. Keep both in the
+            // resolved view so raw consumers display the download and form editors retain the data.
+            if (example.dataValue !== undefined && state.serializedValue !== undefined) {
+                return { ...example, serializedValue: state.serializedValue };
+            }
+            return { ...example, value: state.value };
+        },
+        retry: async () => {
+            await Promise.all(states.value.map((state) => state.load()));
+        },
+    };
+};

package/dist/mutators/index.d.ts

@@ -12,8 +12,8 @@ export declare function generateClientMutators(store: WorkspaceStore | null): {
     workspace: () => {
         cookie: {
             upsertCookie: (payload: {
-                payload: Partial<import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie>;
                 index?: number | undefined;
+                payload: Partial<import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie>;
             }) => import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie | undefined;
             deleteCookie: (payload: {
                 index: number;
@@ -77,8 +77,8 @@ export declare function generateClientMutators(store: WorkspaceStore | null): {
         };
         cookie: {
             upsertCookie: (payload: {
-                payload: Partial<import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie>;
                 index?: number | undefined;
+                payload: Partial<import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie>;
             }) => import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie | undefined;
             deleteCookie: (payload: {
                 index: number;
@@ -168,8 +168,8 @@ export declare function generateClientMutators(store: WorkspaceStore | null): {
         };
         cookie: {
             upsertCookie: (payload: {
-                payload: Partial<import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie>;
                 index?: number | undefined;
+                payload: Partial<import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie>;
             }) => import("../schemas/extensions/general/x-scalar-cookies.js").XScalarCookie | undefined;
             deleteCookie: (payload: {
                 index: number;

package/dist/mutators/operation/body.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../../../src/mutators/operation/body.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAIrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAoClD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qCAAqC,GAChD,UAAU,iBAAiB,GAAG,IAAI,EAClC,mBAAmB,eAAe,CAAC,0CAA0C,CAAC,SAwB/E,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,GAC5C,UAAU,iBAAiB,GAAG,IAAI,EAClC,gCAAgC,eAAe,CAAC,oCAAoC,CAAC,SAStF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,GAC9C,UAAU,iBAAiB,GAAG,IAAI,EAClC,gCAAgC,eAAe,CAAC,wCAAwC,CAAC,SAS1F,CAAA"}
+{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../../../src/mutators/operation/body.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAIrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AA4ClD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qCAAqC,GAChD,UAAU,iBAAiB,GAAG,IAAI,EAClC,mBAAmB,eAAe,CAAC,0CAA0C,CAAC,SAwB/E,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,GAC5C,UAAU,iBAAiB,GAAG,IAAI,EAClC,gCAAgC,eAAe,CAAC,oCAAoC,CAAC,SAStF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,GAC9C,UAAU,iBAAiB,GAAG,IAAI,EAClC,gCAAgC,eAAe,CAAC,wCAAwC,CAAC,SAS1F,CAAA"}

package/dist/mutators/operation/body.js

@@ -2,6 +2,13 @@ import { getPathItemOperation } from '../../helpers/for-each-path-item-operation
 import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
 import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
 import { isOpenApiDocument } from '../../schemas/type-guards.js';
+/** An edit replaces the authored source so the old serialized/data value cannot win. */
+const replaceExampleValue = (example, value) => {
+    delete example.serializedValue;
+    delete example.dataValue;
+    delete example.externalValue;
+    example.value = value;
+};
 /** Ensure the json that we need exists up to the example object in the request body */
 const findOrCreateRequestBodyExample = (document, contentType, meta) => {
     if (!isOpenApiDocument(document)) {
@@ -81,7 +88,7 @@ export const updateOperationRequestBodyExample = (document, { meta, payload, con
         console.error('Example not found', meta.exampleKey);
         return;
     }
-    example.value = payload;
+    replaceExampleValue(example, payload);
 };
 /**
  * Stores the form data for the request body example
@@ -94,5 +101,5 @@ export const updateOperationRequestBodyFormValue = (document, { meta, payload, c
         console.error('Example not found', meta.exampleKey);
         return;
     }
-    example.value = unpackProxyObject(payload, { depth: 3 });
+    replaceExampleValue(example, unpackProxyObject(payload, { depth: 3 }));
 };

package/dist/mutators/operation/parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../../src/mutators/operation/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAIrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAmClD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,iBAAiB,GAAG,IAAI,EAClC,4CAA4C,eAAe,CAAC,4BAA4B,CAAC,SAuD1F,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8BAA8B,GACzC,UAAU,iBAAiB,GAAG,IAAI,EAClC,uCAAuC,eAAe,CAAC,mCAAmC,CAAC,SA8C5F,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,iBAAiB,GAAG,IAAI,EAClC,6BAA6B,eAAe,CAAC,4BAA4B,CAAC,SAkC3E,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,GACvC,UAAU,iBAAiB,GAAG,IAAI,EAClC,gBAAgB,eAAe,CAAC,iCAAiC,CAAC,SAanE,CAAA"}
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../../src/mutators/operation/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAIrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAmClD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,iBAAiB,GAAG,IAAI,EAClC,4CAA4C,eAAe,CAAC,4BAA4B,CAAC,SAuE1F,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8BAA8B,GACzC,UAAU,iBAAiB,GAAG,IAAI,EAClC,uCAAuC,eAAe,CAAC,mCAAmC,CAAC,SA8C5F,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,iBAAiB,GAAG,IAAI,EAClC,6BAA6B,eAAe,CAAC,4BAA4B,CAAC,SAkC3E,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,GACvC,UAAU,iBAAiB,GAAG,IAAI,EAClC,gBAAgB,eAAe,CAAC,iCAAiC,CAAC,SAanE,CAAA"}

package/dist/mutators/operation/parameters.js

@@ -2,6 +2,7 @@ import { getPathItemOperation } from '../../helpers/for-each-path-item-operation
 import { getResolvedRef } from '../../helpers/get-resolved-ref.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';
 const getPathItemsForParameterMutation = (pathItemRef) => {
     if (!pathItemRef || typeof pathItemRef !== 'object') {
         return [];
@@ -40,23 +41,41 @@ const getPathItemsForParameterMutation = (pathItemRef) => {
 export const upsertOperationParameter = (document, { meta, type, payload, originalParameter }) => {
     // We are editing an existing parameter
     if (originalParameter) {
-        // To support content-type parameters in the API client, we just assume an
-        // examples property can be set.
         const param = originalParameter;
+        const target = isContentTypeParameterObject(param) ? Object.values(param.content ?? {})[0] : param;
+        if (!target) {
+            return;
+        }
+        if (target !== param) {
+            // Keep authored examples and migrate edits saved by older clients. Those edits
+            // already take precedence when reading, so they must also win during migration.
+            target.examples = {
+                ...(target.example !== undefined ? { default: { value: target.example } } : {}),
+                ...target.examples,
+                ...('example' in param && param.example !== undefined ? { default: { value: param.example } } : {}),
+                ...('examples' in param ? param.examples : {}),
+            };
+            // A media type cannot carry both the singular example and the examples map.
+            delete target.example;
+            if ('examples' in param) {
+                delete param.examples;
+            }
+            if ('example' in param) {
+                delete param.example;
+            }
+        }
         // Only update the name when the payload carries a non-empty value — an
         // empty name in the payload means the key input blurred before rendering
         // its initial value and should not overwrite the existing parameter name.
         if (payload.name || !param.name) {
             param.name = payload.name;
         }
-        if (!param.examples) {
-            param.examples = {};
-        }
-        // Create the example if it doesn't exist
-        if (!param.examples[meta.exampleKey]) {
-            param.examples[meta.exampleKey] = {};
+        target.examples ??= {};
+        target.examples[meta.exampleKey] ??= {};
+        const example = getResolvedRef(target.examples[meta.exampleKey]);
+        if (!example) {
+            return;
         }
-        const example = getResolvedRef(param.examples[meta.exampleKey]);
         // Update the example value and disabled state
         example.value = payload.value;
         example['x-disabled'] = payload.isDisabled;

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

@@ -20,9 +20,12 @@ export declare const loadingStatus: () => LifecyclePlugin;
  *
  * This is useful for inlining external content (like examples or schemas) into the OpenAPI document during bundling.
  *
- * @param node - The node being processed, which may contain an 'externalValue' property.
+ * In lazy mode, preserve the absolute URL for on-demand client resolution without fetching a payload.
+ * The default eager mode remains available to existing bundler consumers.
  */
-export declare const externalValueResolver: () => LifecyclePlugin;
+export declare const externalValueResolver: (options?: {
+    lazy?: boolean;
+}) => LifecyclePlugin;
 /**
  * Lifecycle plugin to resolve $ref on any object, including non-standard locations like the info object.
  *
@@ -114,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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAAO,eAmCxC,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,eAkFrC,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

@@ -39,21 +39,30 @@ export const loadingStatus = () => {
  *
  * This is useful for inlining external content (like examples or schemas) into the OpenAPI document during bundling.
  *
- * @param node - The node being processed, which may contain an 'externalValue' property.
+ * In lazy mode, preserve the absolute URL for on-demand client resolution without fetching a payload.
+ * The default eager mode remains available to existing bundler consumers.
  */
-export const externalValueResolver = () => {
+export const externalValueResolver = (options) => {
     return {
         type: 'lifecycle',
         onAfterNodeProcess: async (node, context) => {
             const externalValue = node['externalValue'];
             const cache = context.resolutionCache;
             // Only process if 'externalValue' is a string
-            if (typeof externalValue !== 'string') {
+            if (typeof externalValue !== 'string' || node['value'] !== undefined) {
                 return;
             }
             // `externalValue` may be relative (for example `/examples/pet.json`). Resolve it against the
             // origin of the document it lives in so it becomes an absolute URL a loader can fetch.
             const resolvedValue = resolveReferencePath(context.origin, externalValue);
+            if (options?.lazy) {
+                const path = context.path.at(-2) === 'examples' ? context.path : (context.referencedFromPath ?? context.path);
+                if (path.at(-2) !== 'examples' || isSchemaPath(path))
+                    return;
+                // Preserve the referenced document origin before bundling loses that context.
+                node['externalValue'] = resolvedValue;
+                return;
+            }
             const loader = context.loaders.find((it) => it.validate(resolvedValue));
             // We can not process the external value
             if (!loader) {
@@ -140,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)) {
@@ -325,3 +340,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"}