@scalar/workspace-store 0.63.0 → 0.64.0

package/dist/helpers/chunk-index.js

@@ -0,0 +1,139 @@
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { escapeJsonPointer } from '@scalar/json-magic/helpers/escape-json-pointer';
+import { encodeChunkName } from '../helpers/encode-chunk-name.js';
+/**
+ * The extension key a compact sparse document carries its chunk index under.
+ *
+ * It exists on the wire only: the client expands the index back into per-node references while the
+ * document is ingested and removes the key, so nothing downstream ever sees it.
+ */
+export const CHUNK_INDEX_KEY = 'x-scalar-chunk-index';
+/** Stands in for an externalized operation on a compact path item. */
+const OPERATION_PLACEHOLDER = 0;
+/** Matches a `{slot}` in a template, or a doubled brace standing for a literal one. */
+const TEMPLATE_SLOT = /\{\{|\}\}|\{(\w+)\}/g;
+/**
+ * Fills the `{slot}`s of a chunk-reference template.
+ *
+ * `{{` and `}}` stand for literal braces, so text the writer inlined into a template — a document
+ * name, a base URL — may contain braces without being read back as a slot. An unknown slot is left
+ * alone rather than blanked, so a template from a newer writer fails visibly instead of resolving
+ * to the wrong chunk.
+ */
+export const fillChunkRef = (template, values = {}) => template.replace(TEMPLATE_SLOT, (match, slot) => slot === undefined ? match.charAt(0) : (values[slot] ?? match));
+/** Escapes text inlined into a template verbatim, so its braces are not read back as slots. */
+const escapeTemplateLiteral = (text) => text.replaceAll('{', '{{').replaceAll('}', '}}');
+const identity = (value) => value;
+/**
+ * How each template slot is spelled, per mode.
+ *
+ * Static references name files, so their variable segments go through `encodeChunkName` — the same
+ * call `generateWorkspaceChunks` makes when it writes those files. SSR references name pointers
+ * into the store's in-memory assets, which `get()` looks up with JSON Pointer segments, so only the
+ * path is escaped. A method is never encoded in either mode: it is written as it was read, and
+ * `isHttpMethod` keeps it to letters.
+ *
+ * Both sides read the table from here. A reader that encoded a segment differently would build a
+ * reference to a chunk that does not exist.
+ */
+const SLOT_ENCODERS = {
+    static: { type: encodeChunkName, name: encodeChunkName, path: encodeChunkName, method: identity },
+    ssr: { type: identity, name: identity, path: escapeJsonPointer, method: identity },
+};
+/**
+ * Builds the reference templates for one document.
+ *
+ * Filled, these produce exactly the references `externalizeComponentReferences` and
+ * `externalizePathReferences` write, so a client that expands the index lands on the same chunk.
+ */
+export const chunkRefTemplates = (meta) => {
+    if (meta.mode === 'ssr') {
+        const base = `${escapeTemplateLiteral(meta.baseUrl)}/${escapeTemplateLiteral(meta.name)}`;
+        return {
+            components: `${base}/components/{type}/{name}#`,
+            operations: `${base}/operations/{path}/{method}#`,
+            navigation: `${base}/navigation#`,
+        };
+    }
+    const base = `./chunks/${escapeTemplateLiteral(encodeChunkName(meta.name))}`;
+    return {
+        components: `${base}/components/{type}/{name}.json#`,
+        operations: `${base}/operations/{path}/{method}.json#`,
+        navigation: `${base}/navigation.json#`,
+    };
+};
+/** The reference a lazily loaded chunk is reached through. */
+export const chunkReference = (ref) => ({ '$ref': ref, $global: true });
+/**
+ * Compacts a sparse document's `components` and `paths` into an index.
+ *
+ * Takes the sections the externalizers produced rather than the document itself, so the index is
+ * built from the very references it replaces and the two cannot come to describe different sets of
+ * chunks.
+ */
+export const buildChunkIndex = ({ mode, refs, components, paths, }) => ({
+    mode,
+    refs,
+    components: Object.fromEntries(Object.entries(components).map(([type, names]) => [type, Object.keys(names)])),
+    paths: Object.fromEntries(Object.entries(paths).map(([path, pathItem]) => [
+        path,
+        Object.fromEntries(Object.entries(pathItem).map(([key, value]) => [key, isHttpMethod(key) ? OPERATION_PLACEHOLDER : value])),
+    ])),
+});
+/** Whether a value is shaped like an index this build knows how to expand. */
+const isChunkIndex = (value) => isObject(value) &&
+    (value['mode'] === 'static' || value['mode'] === 'ssr') &&
+    isObject(value['refs']) &&
+    isObject(value['components']) &&
+    isObject(value['paths']);
+/**
+ * Expands a compact sparse document into the one a non-compact server store would have sent.
+ *
+ * Mutates the document in place and drops the index key, so what the rest of the store sees is an
+ * ordinary sparse document: `resolve()`, the bundler and anything enumerating `paths` or
+ * `components` are looking at the shape they always have.
+ *
+ * A document without an index is left alone, which is every document a non-compact server store or
+ * an author produces.
+ *
+ * @param document - The document to expand, mutated in place
+ * @returns Whether an index was found and expanded
+ */
+export const expandChunkIndex = (document) => {
+    if (!isObject(document) || document[CHUNK_INDEX_KEY] === undefined) {
+        return false;
+    }
+    const index = document[CHUNK_INDEX_KEY];
+    if (!isChunkIndex(index)) {
+        // The key is dropped rather than passed on: it is not part of any document a consumer should
+        // see, and the sections it stands for are missing either way, so there is nothing a partial
+        // expansion could recover.
+        delete document[CHUNK_INDEX_KEY];
+        console.warn(`Ignoring an unreadable "${CHUNK_INDEX_KEY}"; this document's chunks cannot be resolved.`);
+        return false;
+    }
+    const encoders = SLOT_ENCODERS[index.mode];
+    // Define own properties so document keys such as `__proto__` remain data, without invoking
+    // inherited setters or changing the prototype of any expanded object.
+    const components = Object.fromEntries(Object.entries(index.components).map(([type, names]) => [
+        type,
+        Object.fromEntries(names.map((name) => [
+            name,
+            chunkReference(fillChunkRef(index.refs.components, { type: encoders.type(type), name: encoders.name(name) })),
+        ])),
+    ]));
+    const paths = Object.fromEntries(Object.entries(index.paths).map(([path, pathItem]) => [
+        path,
+        Object.fromEntries(Object.entries(pathItem).map(([key, value]) => [
+            key,
+            isHttpMethod(key)
+                ? chunkReference(fillChunkRef(index.refs.operations, { path: encoders.path(path), method: encoders.method(key) }))
+                : value,
+        ])),
+    ]));
+    document['components'] = components;
+    document['paths'] = paths;
+    delete document[CHUNK_INDEX_KEY];
+    return true;
+};

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

@@ -0,0 +1,17 @@
+import { type LoaderPlugin } from '@scalar/json-magic/bundle';
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser';
+import type { ExampleObject } from '../schemas/v3.2/strict/openapi-document.js';
+/** Download state lives outside the document so reading an example never creates an edit. */
+export type ExternalExampleState = {
+    status: 'idle' | 'loading' | 'loaded' | 'error';
+    value?: unknown;
+    load: () => Promise<void>;
+};
+/** A resolver belongs to one document revision and its configured transport. */
+export type ExternalExampleResolver = (example: ExampleObject) => ExternalExampleState;
+/** Cache external payloads and in-flight requests without changing authored examples. */
+export declare const createExternalExampleResolver: (options?: Parameters<typeof fetchUrls>[0] & {
+    origin?: string;
+    fileLoader?: LoaderPlugin;
+}) => ExternalExampleResolver;
+//# sourceMappingURL=external-examples.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"external-examples.d.ts","sourceRoot":"","sources":["../../src/helpers/external-examples.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAA;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,2CAA2C,CAAA;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,6FAA6F;AAC7F,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B,CAAA;AAED,gFAAgF;AAChF,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,oBAAoB,CAAA;AAEtF,yFAAyF;AACzF,eAAO,MAAM,6BAA6B,GACxC,UAAS,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,YAAY,CAAA;CAAO,KAC7F,uBAuCF,CAAA"}

package/dist/helpers/external-examples.js

@@ -0,0 +1,50 @@
+import { resolveReferencePath } from '@scalar/json-magic/bundle';
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser';
+import { shallowReactive } from 'vue';
+/** Cache external payloads and in-flight requests without changing authored examples. */
+export const createExternalExampleResolver = (options = {}) => {
+    const loader = fetchUrls({ ...options, limit: 10 });
+    const cache = new Map();
+    return (example) => {
+        if (example.value !== undefined || !example.externalValue) {
+            return { status: 'loaded', value: example.value, load: () => Promise.resolve() };
+        }
+        const url = resolveReferencePath(options.origin ?? '', example.externalValue) ?? example.externalValue;
+        const cached = cache.get(url);
+        if (cached)
+            return cached;
+        let pending;
+        const state = shallowReactive({
+            status: 'idle',
+            load: () => {
+                if (pending)
+                    return pending;
+                if (state.status === 'loaded')
+                    return Promise.resolve();
+                state.status = 'loading';
+                pending = (async () => {
+                    try {
+                        const selectedLoader = [loader, options.fileLoader].find((candidate) => candidate?.validate(url));
+                        const result = await selectedLoader?.exec(url);
+                        if (result?.ok) {
+                            state.value = result.data === undefined ? result.raw : result.data;
+                            state.status = 'loaded';
+                        }
+                        else {
+                            state.status = 'error';
+                        }
+                    }
+                    catch {
+                        state.status = 'error';
+                    }
+                    finally {
+                        pending = undefined;
+                    }
+                })();
+                return pending;
+            },
+        });
+        cache.set(url, state);
+        return state;
+    };
+};

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

@@ -0,0 +1,6 @@
+import type { ExampleObject, OperationObject } from '../schemas/v3.2/strict/openapi-document.js';
+/** The request body and parameter examples needed by a single request, never its responses. */
+export declare const getOperationExamples: (operation: OperationObject, key: string, contentType?: string) => (ExampleObject | undefined)[];
+/** Overlay fetched values for request consumers without persisting them as document edits. */
+export declare const resolveOperationExamples: (operation: OperationObject, key: string, contentType: string | undefined, resolve: (example: ExampleObject | undefined) => ExampleObject | undefined) => OperationObject;
+//# sourceMappingURL=operation-examples.d.ts.map

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

@@ -0,0 +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"}

package/dist/helpers/operation-examples.js

@@ -0,0 +1,45 @@
+import { getResolvedRef } from '../helpers/get-resolved-ref.js';
+import { getExample } from '../request-example/builder/helpers/get-example.js';
+/** The request body and parameter examples needed by a single request, never its responses. */
+export const getOperationExamples = (operation, key, contentType) => {
+    const body = getResolvedRef(operation.requestBody);
+    return [
+        body ? getExample(body, key, contentType) : undefined,
+        ...(operation.parameters ?? []).map((parameter) => {
+            const resolved = getResolvedRef(parameter);
+            return resolved ? getExample(resolved, key, undefined) : undefined;
+        }),
+    ];
+};
+/** Overlay fetched values for request consumers without persisting them as document edits. */
+export const resolveOperationExamples = (operation, key, contentType, resolve) => {
+    const mapMedia = (media) => {
+        const selected = key || Object.keys(media.examples ?? {})[0];
+        const example = selected ? getResolvedRef(media.examples?.[selected]) : undefined;
+        const resolved = resolve(example);
+        return selected && resolved && resolved !== example
+            ? { ...media, examples: { ...media.examples, [selected]: resolved } }
+            : media;
+    };
+    const body = getResolvedRef(operation.requestBody);
+    const type = contentType ?? Object.keys(body?.content ?? {})[0];
+    return {
+        ...operation,
+        ...(body && type && body.content[type]
+            ? {
+                requestBody: { ...body, content: { ...body.content, [type]: mapMedia(body.content[type]) } },
+            }
+            : {}),
+        parameters: operation.parameters?.map((parameter) => {
+            const resolved = getResolvedRef(parameter);
+            if (!resolved)
+                return parameter;
+            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]) } };
+            }
+            return { ...resolved, ...mapMedia(resolved) };
+        }),
+    };
+};

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;CAgC3B,CAAA"}

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

@@ -0,0 +1,55 @@
+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);
+            return state.status === 'loaded' ? { ...example, value: state.value } : example;
+        },
+        retry: async () => {
+            await Promise.all(states.value.map((state) => state.load()));
+        },
+    };
+};

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

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,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"}

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) {

package/dist/request-example/builder/header/is-param-disabled.d.ts

@@ -3,11 +3,11 @@ import type { ExampleObject, ParameterObject } from '@scalar/workspace-store/sch
  * Determines if a parameter is disabled
  *
  * First we explicitly check if its been disabled via the `x-disabled` extension.
- * Then we check if its an optional parameter and not a path parameter.
+ * Populated examples are enabled unless explicitly disabled. Empty optional parameters stay disabled.
  *
  * @param param - The parameter to check.
  * @param example - The example to check.
- * @param defaultDisabled - When true (default), optional parameters are treated as disabled unless explicitly enabled. When false, only parameters explicitly marked `x-disabled: true` are disabled.
+ * @param defaultDisabled - When true (default), empty optional parameters are treated as disabled unless explicitly enabled. When false, only parameters explicitly marked `x-disabled: true` are disabled.
  * @returns true if the parameter is disabled, false otherwise.
  */
 export declare const isParamDisabled: (param: ParameterObject, example: ExampleObject | undefined, defaultDisabled?: boolean) => boolean;

package/dist/request-example/builder/header/is-param-disabled.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-param-disabled.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/is-param-disabled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAElH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,eAAe,EACtB,SAAS,aAAa,GAAG,SAAS,EAClC,kBAAiB,OAAc,YAgBhC,CAAA"}
+{"version":3,"file":"is-param-disabled.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/header/is-param-disabled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAElH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,eAAe,EACtB,SAAS,aAAa,GAAG,SAAS,EAClC,kBAAiB,OAAc,KAC9B,OAgBF,CAAA"}

package/dist/request-example/builder/header/is-param-disabled.js

@@ -2,11 +2,11 @@
  * Determines if a parameter is disabled
  *
  * First we explicitly check if its been disabled via the `x-disabled` extension.
- * Then we check if its an optional parameter and not a path parameter.
+ * Populated examples are enabled unless explicitly disabled. Empty optional parameters stay disabled.
  *
  * @param param - The parameter to check.
  * @param example - The example to check.
- * @param defaultDisabled - When true (default), optional parameters are treated as disabled unless explicitly enabled. When false, only parameters explicitly marked `x-disabled: true` are disabled.
+ * @param defaultDisabled - When true (default), empty optional parameters are treated as disabled unless explicitly enabled. When false, only parameters explicitly marked `x-disabled: true` are disabled.
  * @returns true if the parameter is disabled, false otherwise.
  */
 export const isParamDisabled = (param, example, defaultDisabled = true) => {
@@ -15,8 +15,9 @@ export const isParamDisabled = (param, example, defaultDisabled = true) => {
     if (typeof xDisabled === 'boolean') {
         return xDisabled;
     }
-    // If the parameter is not disabled by default, return false
-    if (!defaultDisabled) {
+    // Keep the editor, generated snippets, and outgoing requests aligned for pre-populated values.
+    const hasValue = example?.value !== undefined && example.value !== '' && example.value !== null;
+    if (!defaultDisabled || hasValue) {
         return false;
     }
     // Otherwise, disable optional parameters (except path parameters which are always required)

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

@@ -4,6 +4,8 @@ import type { ExampleObject, MediaTypeObject, ParameterObject, RequestBodyObject
  * Or the [deprecated] `example` field.
  * If no exampleKey is provided it will fallback to the first example in the examples object then the [deprecated]
  * `example` field.
+ * When the parameter carries both its own `examples`/`example` and a `content` object, the parameter-level value
+ * takes priority to preserve edits saved by older clients before they are migrated into the media type.
  * Used both for send-request and generating code snippets.
  */
 export declare const getExample: (param: ParameterObject | RequestBodyObject | MediaTypeObject, exampleName: string | undefined, contentType: string | undefined) => ExampleObject | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"get-example.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/helpers/get-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,iBAAiB,EAClB,MAAM,8DAA8D,CAAA;AAgCrE;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,eAAe,GAAG,iBAAiB,GAAG,eAAe,EAC5D,aAAa,MAAM,GAAG,SAAS,EAC/B,aAAa,MAAM,GAAG,SAAS,KAC9B,aAAa,GAAG,SA6ClB,CAAA"}
+{"version":3,"file":"get-example.d.ts","sourceRoot":"","sources":["../../../../src/request-example/builder/helpers/get-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,iBAAiB,EAClB,MAAM,8DAA8D,CAAA;AAgCrE;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,eAAe,GAAG,iBAAiB,GAAG,eAAe,EAC5D,aAAa,MAAM,GAAG,SAAS,EAC/B,aAAa,MAAM,GAAG,SAAS,KAC9B,aAAa,GAAG,SA6ClB,CAAA"}

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

@@ -23,20 +23,22 @@ const getExampleFromExamples = (examples, exampleField, exampleName) => {
  * Or the [deprecated] `example` field.
  * If no exampleKey is provided it will fallback to the first example in the examples object then the [deprecated]
  * `example` field.
+ * When the parameter carries both its own `examples`/`example` and a `content` object, the parameter-level value
+ * takes priority to preserve edits saved by older clients before they are migrated into the media type.
  * Used both for send-request and generating code snippets.
  */
 export const getExample = (param, exampleName, contentType) => {
-    // Content based parameters
-    if ('content' in param) {
-        const content = param.content?.[contentType ?? Object.keys(param.content)[0] ?? ''];
-        const result = getExampleFromExamples(content?.examples, content?.example, exampleName);
+    // Schema-based parameters and content-based parameter edits saved by older clients.
+    if ('examples' in param || 'example' in param) {
+        const result = getExampleFromExamples(param.examples, param.example, exampleName);
         if (result !== undefined) {
             return result;
         }
     }
-    // Schema based parameters
-    if ('examples' in param || 'example' in param) {
-        const result = getExampleFromExamples(param.examples, param.example, exampleName);
+    // Content based parameters
+    if ('content' in param) {
+        const content = param.content?.[contentType ?? Object.keys(param.content)[0] ?? ''];
+        const result = getExampleFromExamples(content?.examples, content?.example, exampleName);
         if (result !== undefined) {
             return result;
         }

package/dist/request-example/context/headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/headers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAanG;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAI,YAAY,MAAM,KAAG,MACQ,CAAA;AAE3E;;GAEG;AACH,eAAO,MAAM,qCAAqC,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CACK,CAAA;AAkDlH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACvC,WAAW,eAAe,EAC1B,aAAa,MAAM,EACnB,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAIpB,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,0FAU/B;IACD,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,eAAe,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,OAAO,CAAC,EAAE;QACR,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,OAAO,CAAA;KACpB,CAAA;CACF,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAuCxB,CAAA"}
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../src/request-example/context/headers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAcnG;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAI,YAAY,MAAM,KAAG,MACQ,CAAA;AAE3E;;GAEG;AACH,eAAO,MAAM,qCAAqC,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CACK,CAAA;AAgDlH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACvC,WAAW,eAAe,EAC1B,aAAa,MAAM,EACnB,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAIpB,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,0FAU/B;IACD,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,eAAe,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,OAAO,CAAC,EAAE;QACR,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,OAAO,CAAA;KACpB,CAAA;CACF,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAuCxB,CAAA"}

package/dist/request-example/context/headers.js

@@ -1,6 +1,7 @@
 import { canMethodHaveBody } from '@scalar/helpers/http/can-method-have-body';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { isParamDisabled } from '../../request-example/builder/header/is-param-disabled.js';
+import { getExample } from '../../request-example/builder/helpers/get-example.js';
 /** Default Accept header value to accept all response types. */
 const DEFAULT_ACCEPT = '*/*';
 const CONVENTIONAL_DEFAULT_HEADER_NAMES = {
@@ -21,8 +22,7 @@ export const restoreConventionalHeaderName = (headerName) => CONVENTIONAL_DEFAUL
 export const restoreConventionalDefaultHeaderNames = (headers) => Object.fromEntries(Object.entries(headers).map(([name, value]) => [restoreConventionalHeaderName(name), value]));
 /**
  * Lowercase names of **enabled** operation parameters with `in: header` for the given example.
- * Uses the same rules as the request builder (`isParamDisabled`): optional parameters are treated
- * as disabled unless `examples[exampleName]['x-disabled']` is explicitly `false`.
+ * Uses the same example selection and enablement rules as the request builder, including schema defaults.
  */
 const getEnabledOperationHeaderParameterNames = (operation, exampleName) => {
     const names = new Set();
@@ -31,8 +31,7 @@ const getEnabledOperationHeaderParameterNames = (operation, exampleName) => {
         if (!param || param.in !== 'header') {
             continue;
         }
-        const rawExample = 'examples' in param && param.examples?.[exampleName] ? param.examples[exampleName] : undefined;
-        const example = rawExample ? getResolvedRef(rawExample) : undefined;
+        const example = getExample(param, exampleName, undefined);
         if (!isParamDisabled(param, example)) {
             names.add(param.name.toLowerCase());
         }