@scalar/workspace-store 0.63.0 → 0.65.0

package/dist/helpers/chunk-index.js

@@ -0,0 +1,152 @@
+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 });
+/**
+ * The navigation a compact document carries inline: the document entry without its children.
+ *
+ * Navigation is store metadata rather than part of the description, and every reader takes it by
+ * plain property access — `name` keys the auth and history stores, `title` and `icon` render the
+ * document header — so it is never a reference in any mode. Only the children are externalized,
+ * since they are what makes a navigation tree large. They start as an empty array, so a reader
+ * iterating them before they are loaded sees an empty sidebar rather than an error.
+ */
+export const navigationHeader = ({ children: _children, ...header }) => ({
+    ...header,
+    children: [],
+});
+/**
+ * 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: refs.components, operations: refs.operations },
+    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,19 @@
+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;
+    /** Preserve wire text when a 3.2 example also supplies structured data. */
+    serializedValue?: string;
+    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,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,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,uBAwCF,CAAA"}

package/dist/helpers/external-examples.js

@@ -0,0 +1,51 @@
+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.serializedValue = typeof result.raw === 'string' ? result.raw : undefined;
+                            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/for-each-path-item-operation.js

@@ -11,10 +11,10 @@ const MAX_REF_HOPS = 10;
 /**
  * Whether a merged path item still carries an unfollowed hop.
  *
- * `mergeSiblingReferences` spreads the resolved target over the siblings. When that target is itself
- * a reference, the spread carries its `$ref-value` across as a real key, which is the signal that
- * one more hop is waiting. A fully resolved path item never has one: the `$ref` sibling is kept (it
- * is what the author wrote) but nothing resolves through it any more.
+ * `mergeSiblingReferences` preserves the resolved target's `$ref-value`, including non-enumerable
+ * links in plain documents. That link signals that one more hop is waiting. A fully resolved path
+ * item never has one: the `$ref` sibling is kept (it is what the author wrote) but nothing resolves
+ * through it any more.
  */
 const hasUnfollowedRef = (pathItem) => isObjectLike(pathItem) && Object.hasOwn(pathItem, '$ref-value');
 /**

package/dist/helpers/get-example-value.d.ts

@@ -0,0 +1,15 @@
+import type { ExampleObject } from '../schemas/v3.2/strict/example.js';
+import type { ReferenceType } from '../schemas/v3.2/strict/reference.js';
+/** Preserve the source so consumers do not serialize wire text a second time. */
+export type ExampleValue = {
+    source: 'serialized';
+    value: string;
+} | {
+    source: 'data' | 'value';
+    value: unknown;
+};
+/** Select an explicit example without confusing false, zero, null, or empty text with absence. */
+export declare const getExampleValue: (input: ReferenceType<ExampleObject> | undefined) => ExampleValue | undefined;
+/** Preserve explicit wire text for any media type, or serialize structured JSON data. */
+export declare const getExplicitExampleText: (example: ExampleValue | undefined, contentType: string, indent?: number) => string | undefined;
+//# sourceMappingURL=get-example-value.d.ts.map

package/dist/helpers/get-example-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-example-value.d.ts","sourceRoot":"","sources":["../../src/helpers/get-example-value.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAEpE,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEjH,kGAAkG;AAClG,eAAO,MAAM,eAAe,GAAI,OAAO,aAAa,CAAC,aAAa,CAAC,GAAG,SAAS,KAAG,YAAY,GAAG,SAahG,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,GACjC,SAAS,YAAY,GAAG,SAAS,EACjC,aAAa,MAAM,EACnB,SAAS,MAAM,KACd,MAAM,GAAG,SASX,CAAA"}

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

@@ -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,eAgCF,CAAA"}

package/dist/helpers/operation-examples.js

@@ -0,0 +1,48 @@
+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]) {
+                const media = mapMedia(content[mediaType]);
+                return media === content[mediaType] ? parameter : { ...resolved, content: { ...content, [mediaType]: media } };
+            }
+            // 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"}