@scalar/workspace-store 0.64.0 → 0.65.0

package/dist/helpers/get-example-value.js

@@ -0,0 +1,28 @@
+import { parseMimeType } from '@scalar/helpers/http/mime-type';
+import { getResolvedRef } from '../helpers/get-resolved-ref.js';
+/** Select an explicit example without confusing false, zero, null, or empty text with absence. */
+export const getExampleValue = (input) => {
+    const example = getResolvedRef(input);
+    if (example?.serializedValue !== undefined) {
+        return { source: 'serialized', value: example.serializedValue };
+    }
+    if (example?.dataValue !== undefined) {
+        return { source: 'data', value: example.dataValue };
+    }
+    if (example?.value !== undefined) {
+        return { source: 'value', value: example.value };
+    }
+    // externalValue is fetched by the bundler; until then it is not an inline payload.
+    return undefined;
+};
+/** Preserve explicit wire text for any media type, or serialize structured JSON data. */
+export const getExplicitExampleText = (example, contentType, indent) => {
+    if (example?.source === 'serialized') {
+        return example.value;
+    }
+    const { essence, subtype } = parseMimeType(contentType);
+    if (example?.source === 'data' && (essence === 'application/json' || subtype.endsWith('+json'))) {
+        return JSON.stringify(example.value, null, indent);
+    }
+    return undefined;
+};

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

@@ -1 +1 @@
-{"version":3,"file":"get-resolved-ref.d.ts","sourceRoot":"","sources":["../../src/helpers/get-resolved-ref.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AACjF,MAAM,MAAM,SAAS,CAAC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AA0ElD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,IAclE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EACzC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EACrB,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,MAAM,GACzC,IAAI,GAAG,MAAM,CAAA;AAChB,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAAA;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;AAW7E;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"get-resolved-ref.d.ts","sourceRoot":"","sources":["../../src/helpers/get-resolved-ref.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AACjF,MAAM,MAAM,SAAS,CAAC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AA0ElD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,IA2BlE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EACzC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EACrB,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,MAAM,GACzC,IAAI,GAAG,MAAM,CAAA;AAChB,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAAA;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;AAW7E;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA"}

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

@@ -76,7 +76,18 @@ export const mergeSiblingReferences = (node) => {
     if (!isObject(target)) {
         return rest;
     }
-    return { ...target, ...rest };
+    const merged = { ...target, ...rest };
+    // Plain document loaders hide reference links from serialization. Preserve the
+    // next hop explicitly so chain resolution does not depend on object spread.
+    if (Object.hasOwn(target, '$ref-value') && !Object.hasOwn(merged, '$ref-value')) {
+        Object.defineProperty(merged, '$ref-value', {
+            value: target['$ref-value'],
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return merged;
 };
 export function getResolvedRef(node, transform = defaultTransform) {
     if (typeof node === 'object' && node !== null && '$ref' in node) {

package/dist/helpers/normalize-boolean-schemas.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize boolean schemas without mutating caller-owned data.
+ * Only changed schema containers and their ancestors are copied. Unchanged bundled
+ * documents and opaque example/extension payloads retain their identity. Iterative
+ * discovery and copy propagation preserve cycles without recursive cloning.
+ * The marker represents an untyped schema; false is its negation. additionalProperties
+ * already accepts booleans and therefore retains its authored representation.
+ */
+export declare const normalizeBooleanSchemas: <T extends Record<string, unknown>>(document: T) => T;
+//# sourceMappingURL=normalize-boolean-schemas.d.ts.map

package/dist/helpers/normalize-boolean-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-boolean-schemas.d.ts","sourceRoot":"","sources":["../../src/helpers/normalize-boolean-schemas.ts"],"names":[],"mappings":"AAgDA;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,KAAG,CAkJxF,CAAA"}

package/dist/helpers/normalize-boolean-schemas.js

@@ -0,0 +1,193 @@
+import { parseJsonPointerSegments } from '@scalar/helpers/json/parse-json-pointer-segments';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { isSchemaPath } from '@scalar/helpers/openapi/is-schema-path';
+const schemaMaps = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
+const schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const childSchemas = new Set([
+    'items',
+    'not',
+    'if',
+    'then',
+    'else',
+    'contains',
+    'propertyNames',
+    'contentSchema',
+    '$ref-value',
+]);
+const openApiMaps = new Set([
+    'paths',
+    'webhooks',
+    'responses',
+    'content',
+    'headers',
+    'examples',
+    'links',
+    'encoding',
+    'variables',
+    'parameters',
+    'requestBodies',
+    'securitySchemes',
+    'pathItems',
+    'mediaTypes',
+    'additionalOperations',
+    'callbacks',
+    'x-ext',
+]);
+const opaqueValues = new Set(['example', 'examples', 'default', 'enum', 'const', 'value', 'dataValue']);
+/**
+ * Normalize boolean schemas without mutating caller-owned data.
+ * Only changed schema containers and their ancestors are copied. Unchanged bundled
+ * documents and opaque example/extension payloads retain their identity. Iterative
+ * discovery and copy propagation preserve cycles without recursive cloning.
+ * The marker represents an untyped schema; false is its negation. additionalProperties
+ * already accepts booleans and therefore retains its authored representation.
+ */
+export const normalizeBooleanSchemas = (document) => {
+    const nodes = new WeakMap();
+    const changed = new Set();
+    const schemas = new WeakSet();
+    const documents = new WeakSet();
+    const tasks = [];
+    const getNode = (source) => {
+        const existing = nodes.get(source);
+        if (existing) {
+            return existing;
+        }
+        const node = { source };
+        nodes.set(source, node);
+        return node;
+    };
+    const root = getNode(document);
+    const link = (parent, key, child) => {
+        const node = getNode(child);
+        if (!node.parent) {
+            node.parent = { node: parent, key };
+        }
+        else if (node.parent.node !== parent || node.parent.key !== key) {
+            const parents = (node.otherParents ??= []);
+            if (!parents.some((edge) => edge.node === parent && edge.key === key)) {
+                parents.push({ node: parent, key });
+            }
+        }
+        return node;
+    };
+    const schema = (parent, key, value) => {
+        if (typeof value === 'boolean') {
+            ;
+            (parent.replacements ??= new Map()).set(key, value ? { __scalar_: '' } : { __scalar_: '', not: { __scalar_: '' } });
+            changed.add(parent);
+        }
+        else if (isObject(value)) {
+            tasks.push({ node: link(parent, key, value), kind: 'schema' });
+        }
+    };
+    const reference = (pointer) => {
+        const segments = parseJsonPointerSegments(pointer);
+        let parent = root;
+        for (const [index, key] of segments.entries()) {
+            // A local reference cannot reach inherited properties or prototype setters.
+            if (!Object.hasOwn(parent.source, key)) {
+                return;
+            }
+            const value = Reflect.get(parent.source, key);
+            if (index === segments.length - 1) {
+                schema(parent, key, value);
+            }
+            else if (value !== null && typeof value === 'object') {
+                parent = link(parent, key, value);
+            }
+            else {
+                return;
+            }
+        }
+    };
+    tasks.push({ node: root, kind: 'document', path: [], mapDepth: 0 });
+    while (tasks.length > 0) {
+        const task = tasks.pop();
+        if (!task) {
+            break;
+        }
+        const { node } = task;
+        const visited = task.kind === 'schema' ? schemas : documents;
+        if (visited.has(node.source)) {
+            continue;
+        }
+        visited.add(node.source);
+        if (task.kind === 'schema') {
+            const value = node.source;
+            if (typeof value.$ref === 'string' && value.$ref.startsWith('#/')) {
+                reference(value.$ref.slice(1));
+            }
+            for (const [key, child] of Object.entries(value)) {
+                if ((schemaMaps.has(key) && isObject(child)) || (schemaArrays.has(key) && Array.isArray(child))) {
+                    const container = link(node, key, child);
+                    for (const [name, nested] of Object.entries(child)) {
+                        schema(container, name, nested);
+                    }
+                }
+                else if (childSchemas.has(key)) {
+                    schema(node, key, child);
+                }
+                else if (['additionalProperties', 'unevaluatedProperties', 'unevaluatedItems'].includes(key) &&
+                    isObject(child)) {
+                    schema(node, key, child);
+                }
+            }
+            continue;
+        }
+        const { path } = task;
+        for (const [key, child] of Object.entries(node.source)) {
+            const childPath = [...path, key];
+            const isMapEntry = task.mapDepth > 0;
+            if (key === 'schemas' && path.at(-1) === 'components' && isObject(child)) {
+                const container = link(node, key, child);
+                for (const [name, nested] of Object.entries(child)) {
+                    schema(container, name, nested);
+                }
+            }
+            else if ((key === 'schema' || key === 'itemSchema') && !isMapEntry && isSchemaPath(childPath)) {
+                schema(node, key, child);
+            }
+            else if (isMapEntry || (!opaqueValues.has(key) && (!key.startsWith('x-') || key === 'x-ext'))) {
+                // Vendor extensions are opaque. x-ext additionally contains bundled documents
+                // and schema targets whose context can be supplied by a local reference.
+                if (child !== null && typeof child === 'object') {
+                    tasks.push({
+                        node: link(node, key, child),
+                        kind: 'document',
+                        path: childPath,
+                        mapDepth: isMapEntry ? task.mapDepth - 1 : key === 'callbacks' ? 2 : openApiMaps.has(key) ? 1 : 0,
+                    });
+                }
+            }
+        }
+    }
+    const forEachParent = (node, callback) => {
+        if (node.parent) {
+            callback(node.parent);
+        }
+        node.otherParents?.forEach(callback);
+    };
+    // Set iteration also visits newly added ancestors, including shared/cyclic parents.
+    for (const node of changed) {
+        forEachParent(node, (parent) => changed.add(parent.node));
+    }
+    for (const node of changed) {
+        node.copy = Array.isArray(node.source) ? [] : {};
+    }
+    for (const node of changed) {
+        forEachParent(node, (parent) => (parent.node.replacements ??= new Map()).set(parent.key, node.copy));
+    }
+    for (const node of changed) {
+        for (const [key, value] of Object.entries(node.source)) {
+            // Define an own data property so authored keys such as __proto__ remain data.
+            Object.defineProperty(node.copy, key, {
+                value: node.replacements?.has(key) ? node.replacements.get(key) : value,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+    }
+    return (root.copy ?? document);
+};

package/dist/helpers/operation-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation-examples.d.ts","sourceRoot":"","sources":["../../src/helpers/operation-examples.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAmB,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAE7G,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB,GAC/B,WAAW,eAAe,EAC1B,KAAK,MAAM,EACX,cAAc,MAAM,KACnB,CAAC,aAAa,GAAG,SAAS,CAAC,EAS7B,CAAA;AAED,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GACnC,WAAW,eAAe,EAC1B,KAAK,MAAM,EACX,aAAa,MAAM,GAAG,SAAS,EAC/B,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,KAAK,aAAa,GAAG,SAAS,KACzE,eA6BF,CAAA"}
+{"version":3,"file":"operation-examples.d.ts","sourceRoot":"","sources":["../../src/helpers/operation-examples.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAmB,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAE7G,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB,GAC/B,WAAW,eAAe,EAC1B,KAAK,MAAM,EACX,cAAc,MAAM,KACnB,CAAC,aAAa,GAAG,SAAS,CAAC,EAS7B,CAAA;AAED,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GACnC,WAAW,eAAe,EAC1B,KAAK,MAAM,EACX,aAAa,MAAM,GAAG,SAAS,EAC/B,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,KAAK,aAAa,GAAG,SAAS,KACzE,eAgCF,CAAA"}

package/dist/helpers/operation-examples.js

@@ -37,9 +37,12 @@ export const resolveOperationExamples = (operation, key, contentType, resolve) =
             const content = 'content' in resolved ? resolved.content : undefined;
             const mediaType = Object.keys(content ?? {})[0];
             if (mediaType && content?.[mediaType]) {
-                return { ...resolved, content: { ...content, [mediaType]: mapMedia(content[mediaType]) } };
+                const media = mapMedia(content[mediaType]);
+                return media === content[mediaType] ? parameter : { ...resolved, content: { ...content, [mediaType]: media } };
             }
-            return { ...resolved, ...mapMedia(resolved) };
+            // Keep editable source objects when there is no downloaded example to overlay.
+            const media = mapMedia(resolved);
+            return media === resolved ? parameter : { ...resolved, ...media };
         }),
     };
 };

package/dist/helpers/serialize-stream-example.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare const serializeStreamExample: (value: unknown, contentType: string, singleItem: boolean) => string | undefined;
+//# sourceMappingURL=serialize-stream-example.d.ts.map

package/dist/helpers/serialize-stream-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-stream-example.d.ts","sourceRoot":"","sources":["../../src/helpers/serialize-stream-example.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,OAAO,EACd,aAAa,MAAM,EACnB,YAAY,OAAO,KAClB,MAAM,GAAG,SA2CX,CAAA"}

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.map

@@ -1 +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;CAgC3B,CAAA"}
+{"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

@@ -46,7 +46,14 @@ export const useExternalExamples = (examples, enabled = () => true, resolver) =>
             if (!example || example.value !== undefined || !example.externalValue)
                 return example;
             const state = getResolver()(example);
-            return state.status === 'loaded' ? { ...example, value: state.value } : 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/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,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

@@ -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)) {
@@ -334,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"}