@scalar/openapi-to-markdown 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/openapi-to-markdown
 
+## 1.2.0
+
+### Minor Changes
+
+- [#10186](https://github.com/scalar/scalar/pull/10186): Support document-defined additional operations in Markdown operation, webhook, and tag selections. Preserve custom method spelling and inherited parameters, servers, and security when copying an operation as Markdown.
+
+### Patch Changes
+
+- [#10329](https://github.com/scalar/scalar/pull/10329): Render each shared schema once per page. The first reference to a structured schema expands it and labels it with its name (for example `schema: Account`). Later references print "Schema `Account` is shown above." instead of expanding it again. Model sections for schemas already expanded on the page refer back to them too. True cycles still print `[Circular Reference]`. This keeps Markdown output proportional to the schema graph, rather than to the number of paths through it. Before this change, densely linked descriptions such as Stripe's ran out of memory when rendering a single operation.
+
+  A node budget per operation and model section adds a visible `[Schema output truncated]` marker as a last resort. Generated examples that would exceed 10,000 values are omitted with a note. References past the depth limit now point to the model's own section instead of being cut off.
+
 ## 1.1.0
 
 ### Minor Changes

package/dist/get-markdown-examples.d.ts

@@ -15,7 +15,14 @@ type MarkdownExample = {
     externalValue: string;
 } | {
     serializedValue: string;
+} | {
+    omitted: true;
 });
+/**
+ * Estimate how many values an example generated from this schema contains, stopping just past the limit.
+ * Counts are cached per schema and level, so this is linear in the size of the schema graph.
+ */
+export declare const countGeneratedExampleValues: (root: unknown, limit?: number) => number;
 /** Preserve supplied values; generate a fallback only when examples are not supplied. */
 export declare const getMarkdownExamples: (source: ExampleSource, mediaType: string, mode?: "read" | "write", openapiVersion?: string) => MarkdownExample[];
 export {};

package/dist/get-markdown-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAKA,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,gFAAgF;AAChF,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAElF,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,WAAW,MAAM,EACjB,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,eAAe,EA2BjB,CAAA"}
+{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAKA,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,gFAAgF;AAChF,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAYtG;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,OAAO,EAAE,cAAoC,KAAG,MA2CjG,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,WAAW,MAAM,EACjB,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,eAAe,EA4BjB,CAAA"}

package/dist/get-markdown-examples.js

@@ -1,6 +1,72 @@
 import { isObject } from '@scalar/helpers/object/is-object';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+/** Mirrors the depth at which `getExampleFromSchema` stops following nested schemas. */
+const EXAMPLE_DEPTH = 10;
+/**
+ * Generated examples repeat every shared schema at each place it is used, up to ten levels deep.
+ * A densely shared schema graph therefore produces billions of values, so larger examples are skipped.
+ * The largest generated examples in the Stripe, GitHub, and Cloudflare descriptions have about 7,600 values.
+ */
+const MAX_GENERATED_EXAMPLE_VALUES = 10_000;
+/**
+ * Estimate how many values an example generated from this schema contains, stopping just past the limit.
+ * Counts are cached per schema and level, so this is linear in the size of the schema graph.
+ */
+export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_VALUES) => {
+    const counts = new WeakMap();
+    const count = (input, level) => {
+        if (level > EXAMPLE_DEPTH || !isObject(input))
+            return 1;
+        const cached = counts.get(input)?.get(level);
+        if (cached !== undefined)
+            return cached;
+        const schema = getResolvedRef(input, mergeSiblingReferences);
+        if (!isObject(schema))
+            return 1;
+        // Supplied examples bypass schema expansion in the generator too.
+        if (schema.example !== undefined || (Array.isArray(schema.examples) && schema.examples.length > 0))
+            return 1;
+        let total = 1;
+        const add = (child) => {
+            if (total <= limit)
+                total += count(child, level + 1);
+        };
+        if (isObject(schema.properties))
+            Object.values(schema.properties).forEach(add);
+        if (isObject(schema.patternProperties))
+            Object.values(schema.patternProperties).forEach(add);
+        if (isObject(schema.additionalProperties))
+            add(schema.additionalProperties);
+        if (schema.items !== undefined)
+            add(schema.items);
+        if (Array.isArray(schema.prefixItems))
+            schema.prefixItems.forEach(add);
+        if (Array.isArray(schema.allOf))
+            schema.allOf.forEach(add);
+        const variants = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : [];
+        // Object and array generation can use the first variant, while other unions skip null.
+        // A discriminator can choose any variant, so bound the largest candidate in that case.
+        const nonNull = variants.find((variant) => {
+            const resolved = getResolvedRef(variant, mergeSiblingReferences);
+            return isObject(resolved) && resolved.type !== 'null';
+        });
+        const candidates = isObject(schema.discriminator) && schema.discriminator.defaultMapping !== undefined
+            ? variants
+            : [variants[0], nonNull];
+        let variantCount = 0;
+        for (const candidate of candidates) {
+            if (candidate !== undefined && total <= limit && variantCount <= limit)
+                variantCount = Math.max(variantCount, count(candidate, level + 1));
+        }
+        total += variantCount;
+        const levels = counts.get(input) ?? new Map();
+        levels.set(level, total);
+        counts.set(input, levels);
+        return total;
+    };
+    return count(root, 0);
+};
 /** Preserve supplied values; generate a fallback only when examples are not supplied. */
 export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3.2.0') => {
     if (source.example !== undefined)
@@ -29,6 +95,8 @@ export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3
     const schema = getResolvedRef(source.schema);
     if (!isObject(schema))
         return [];
+    if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES)
+        return [{ omitted: true }];
     const value = getExampleFromSchema(getResolvedRef(source.schema, mergeSiblingReferences), {
         xml: mediaType.includes('xml'),
         mode,

package/dist/render-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAepH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAyIxF,CAAA"}
+{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAepH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CA6IxF,CAAA"}

package/dist/render-document.js

@@ -13,9 +13,11 @@ const serializer = unified().use(remarkGfm).use(remarkStringify, { bullet: '-' }
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
 export const createDocumentRenderer = () => {
     const descriptions = createDescriptionParser();
-    const schemas = createSchemaRenderer();
+    const schemaRenderer = createSchemaRenderer();
     return async (document) => {
         const description = descriptions();
+        // Each page expands a shared schema once, then refers back to it.
+        const schemas = schemaRenderer.forDocument(document.components?.schemas);
         const { info } = document;
         const metadata = [
             field('OpenAPI Version', inlineCode(document.openapi)),
@@ -85,6 +87,7 @@ export const createDocumentRenderer = () => {
                         nodes.push(heading(2, text(group.title)));
                         hasOperations = true;
                     }
+                    schemas.beginSection();
                     nodes.push(...(await renderOperation(document, path, method, pathItem, operation, group.webhook, {
                         description,
                         schemas,
@@ -97,12 +100,13 @@ export const createDocumentRenderer = () => {
         if (models.length)
             nodes.push(heading(2, text('Schemas')));
         for (const [name, schema] of models) {
+            schemas.beginSection();
             const view = schemas.view(schema);
             nodes.push(heading(3, text(view.title ?? name)), list([
                 view.type
                     ? field('Type', inlineCode(Array.isArray(view.type) ? view.type.join(' | ') : view.type))
                     : item(paragraph(strong(text('Type:')))),
-            ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true }));
+            ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true, name }));
             if (view.type === 'object')
                 nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi)));
             flush();

package/dist/render-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAExC,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,OAAO,CAAC,WAAW,EAAE,CAiCvB,CAAA"}
+{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAExC,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,OAAO,CAAC,WAAW,EAAE,CAqCvB,CAAA"}

package/dist/render-examples.js

@@ -6,6 +6,10 @@ export const renderExamples = async (source, description, mediaType = 'applicati
     const nodes = [];
     for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion)) {
         nodes.push(paragraph(strong(text(example.name ? `Example: ${example.name}` : 'Example:'))));
+        if ('omitted' in example) {
+            nodes.push(paragraph(text('[Generated example omitted because it is too large]')));
+            continue;
+        }
         if (example.summary)
             nodes.push(paragraph(text(example.summary)));
         nodes.push(...(await description(example.description)));

package/dist/render-operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CA2GvB,CAAA"}
+{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CAyGvB,CAAA"}

package/dist/render-operation.js

@@ -1,3 +1,4 @@
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { field, heading, inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
 import { renderExamples } from './render-examples.js';
@@ -5,14 +6,12 @@ import { renderEncoding, renderHeaders, renderResponseLinks } from './render-ope
 import { renderSecurity } from './render-security.js';
 /** Render effective operation context without mutating the prepared document. */
 export const renderOperation = async (document, path, method, pathItem, operation, webhook, { description, schemas }) => {
+    const displayMethod = method === method.toLowerCase() && isHttpMethod(method) ? method.toUpperCase() : method;
     const openapiVersion = document['x-original-oas-version'] ?? document.openapi;
     const stability = operation['x-scalar-stability'];
-    const title = (operation.summary || `${method.toUpperCase()} ${path}`) +
+    const title = (operation.summary || `${displayMethod} ${path}`) +
         (stability ? ` (${stability})` : operation.deprecated ? ' ⚠️ Deprecated' : '');
-    const metadata = [
-        field('Method', inlineCode(method.toUpperCase())),
-        field(webhook ? 'Webhook' : 'Path', inlineCode(path)),
-    ];
+    const metadata = [field('Method', inlineCode(displayMethod)), field(webhook ? 'Webhook' : 'Path', inlineCode(path))];
     if (operation.operationId)
         metadata.push(field('Operation ID', inlineCode(operation.operationId)));
     if (operation.tags)

package/dist/render-schema.d.ts

@@ -38,18 +38,36 @@ type SchemaView = {
         propertyName: string;
         mapping?: Record<string, string>;
     };
+    /** Set for references to a structured schema that is rendered once per document and referred to afterwards. */
+    name?: string;
 };
 type RenderOptions = {
     hideDescription?: boolean;
     hideDetails?: boolean;
     property?: boolean;
+    /** Record this root under the given name, for example in its own model section, even if it is not a reference. */
+    name?: string;
 };
-/** Schema normalization is cached separately from ancestry-dependent expansion. */
+/**
+ * Schema normalization is cached separately from ancestry-dependent expansion.
+ *
+ * A renderer also tracks which shared schemas one output document already shows, so each one is
+ * expanded once and referred to afterwards. Use `forDocument` for every document: renders can
+ * run concurrently, and each needs its own record.
+ */
 export type SchemaRenderer = {
     view: (schema: MarkdownSchema) => SchemaView;
     render: (schema: MarkdownSchema, depth?: number, ancestors?: readonly unknown[], options?: RenderOptions) => RootContent[];
+    /** Restore the node budget, for example for each operation or model section. */
+    beginSection: () => void;
+    /** Start a document that shares normalized views, given the models it renders in its own sections. */
+    forDocument: (models?: Record<string, MarkdownSchema>) => SchemaRenderer;
+};
+type SchemaRendererOptions = {
+    /** Upper bound on expanded schema nodes per section, so no description can make a page unbounded. */
+    maxNodes?: number;
 };
 /** Keep merged reference siblings and sorted properties stable throughout an export. */
-export declare const createSchemaRenderer: () => SchemaRenderer;
+export declare const createSchemaRenderer: ({ maxNodes }?: SchemaRendererOptions) => SchemaRenderer;
 export {};
 //# sourceMappingURL=render-schema.d.ts.map

package/dist/render-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,oDAAoD,CAAA;AAC5G,OAAO,KAAK,EAA6B,WAAW,EAAE,MAAM,OAAO,CAAA;AAInE,uFAAuF;AACvF,KAAK,cAAc,GAAG,oBAAoB,GAAG,OAAO,CAAA;AAEpD,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,YAAY,GAAG,OAAO,CAAA;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;IACxB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;IACxB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;IACxB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,UAAU,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAAA;IACtC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC7B,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oBAAoB,CAAC,EAAE,cAAc,CAAA;IACrC,aAAa,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAC3E,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,UAAU,CAAA;IAC5C,MAAM,EAAE,CACN,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,CAAC,EAAE,aAAa,KACpB,WAAW,EAAE,CAAA;CACnB,CAAA;AAiBD,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,QAAO,cA0IvC,CAAA"}
+{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"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"}

package/dist/render-schema.js

@@ -1,6 +1,58 @@
+import { unescapeJsonPointer } from '@scalar/helpers/json/unescape-json-pointer';
 import { isObject } from '@scalar/helpers/object/is-object';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
+/** Guards against stack exhaustion. Past it, references to models point to their own section instead. */
+const MAX_DEPTH = 64;
+/**
+ * Deduplicated output is proportional to the schema graph, so only a pathological description
+ * (for example a YAML alias graph without references) reaches this.
+ */
+const MAX_NODES = 100_000;
+/** Keywords that `render` expands, as opposed to annotations that `details` prints on one line. */
+const structuralKeywords = new Set([
+    'allOf',
+    'anyOf',
+    'oneOf',
+    'not',
+    'properties',
+    'required',
+    'items',
+    'additionalProperties',
+    'discriminator',
+    'minItems',
+    'maxItems',
+    'uniqueItems',
+]);
+/** Link bookkeeping that is not a sibling keyword of a reference. */
+const referenceKeys = new Set(['$ref', '$ref-value', '$global', '$status']);
+const emphasis = (...children) => ({ type: 'emphasis', children });
+/** Prefer the component name, which is how model sections and other references identify the schema. */
+const getReferenceName = (ref) => {
+    const match = /^#\/components\/schemas\/([^/]+)$/.exec(ref);
+    if (!match)
+        return ref;
+    try {
+        return unescapeJsonPointer(match[1]);
+    }
+    catch {
+        return ref;
+    }
+};
+/** Only references that add nothing structural can be replaced by the schema they point to. */
+const getSharedName = (input, view) => {
+    const ref = isObject(input) ? input.$ref : undefined;
+    if (typeof ref !== 'string' || typeof view.schema !== 'object')
+        return undefined;
+    if (Object.keys(input).some((key) => structuralKeywords.has(key)))
+        return undefined;
+    const structured = Boolean(view.allOf?.length || view.anyOf?.length || view.oneOf?.length || view.properties.length) ||
+        view.not !== undefined ||
+        view.items !== undefined ||
+        view.additionalProperties !== undefined;
+    // Leaf schemas are as short as a reference to them, so they stay in place.
+    return structured ? getReferenceName(ref) : undefined;
+};
 /** Boolean targets still combine with adjacent schema keywords. */
 const resolveMarkdownSchema = (input) => {
     const target = getResolvedRef(input);
@@ -16,7 +68,7 @@ const resolveMarkdownSchema = (input) => {
     return { ...merged, allOf: [false, ...(Array.isArray(merged.allOf) ? merged.allOf : [])] };
 };
 /** Keep merged reference siblings and sorted properties stable throughout an export. */
-export const createSchemaRenderer = () => {
+export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
     const views = new WeakMap();
     const view = (input) => {
         const cached = typeof input === 'object' ? views.get(input) : undefined;
@@ -37,6 +89,7 @@ export const createSchemaRenderer = () => {
             required,
             properties,
         };
+        result.name = getSharedName(input, result);
         if (typeof input === 'object')
             views.set(input, result);
         return result;
@@ -50,6 +103,8 @@ export const createSchemaRenderer = () => {
             if (entry !== undefined)
                 nodes.push(text(`${nodes.length ? ', ' : ''}${label}: `), inlineCode(entry));
         };
+        // Later references to a shared schema point back to this name.
+        add('schema', value.name);
         add('format', value.format);
         if (value.enum)
             add('possible values', value.enum.map((entry) => JSON.stringify(entry)).join(', '));
@@ -78,71 +133,124 @@ export const createSchemaRenderer = () => {
             nodes.push(text(`${nodes.length ? ' — ' : ''}${value.description}`));
         return nodes;
     };
-    const render = (input, depth = 0, ancestors = [], options = {}) => {
-        // Follow the original target: merging reference siblings creates fresh objects.
-        const identity = getResolvedRef(input) ?? input;
-        if (typeof identity === 'object' && ancestors.includes(identity)) {
-            return [paragraph({ type: 'emphasis', children: [text('[Circular Reference]')] })];
-        }
-        if (depth >= 64)
-            return [paragraph(text('[Maximum schema depth reached]'))];
-        const value = view(input);
-        if (typeof value.schema === 'boolean')
-            return options.hideDetails ? [] : [paragraph(...details(value))];
-        const childAncestors = [...ancestors, identity];
-        const nodes = [];
-        for (const [key, label] of [
-            ['allOf', 'All of:'],
-            ['anyOf', 'Any of:'],
-            ['oneOf', 'One of:'],
-        ]) {
-            if (value[key]?.length)
-                nodes.push(paragraph(strong(text(label))), ...value[key].flatMap((child) => render(child, depth + 1, childAncestors)));
-        }
-        if (value.not !== undefined)
-            nodes.push(paragraph(strong(text('Not:'))), ...render(value.not, depth + 1, childAncestors));
-        const array = value.type === 'array' || value.items !== undefined;
-        if (!options.hideDetails) {
-            // Child sections imply a single container type, but never its nullable alternatives.
-            const impliedType = (value.type === 'object' && value.properties.length > 0) ||
-                (value.type === 'array' && value.items !== undefined);
-            const annotations = details(value, false, options.hideDescription, !impliedType);
-            if (annotations.length)
-                nodes.push(paragraph(...annotations));
-        }
-        if (value.properties.length) {
-            const properties = value.properties.map(([name, schema]) => {
-                const child = view(schema);
-                const label = [inlineCode(name)];
-                if (value.required.has(name))
-                    label.push(text(' (required)'));
-                const blocks = [paragraph(strong(...label)), paragraph(...details(child, true))];
-                blocks.push(...render(schema, depth + 1, childAncestors, { hideDetails: true, property: true }));
-                return item(...blocks);
-            });
-            nodes.push(list(properties));
-        }
-        if (array && value.items !== undefined) {
-            nodes.push(paragraph(strong(text(options.property ? 'Items:' : 'Array of:'))), ...render(value.items, depth + 1, childAncestors));
-        }
-        const constraints = [];
-        if (value.minItems !== undefined)
-            constraints.push(item(paragraph(text('Min items: '), inlineCode(value.minItems))));
-        if (value.maxItems !== undefined)
-            constraints.push(item(paragraph(text('Max items: '), inlineCode(value.maxItems))));
-        if (value.uniqueItems !== undefined)
-            constraints.push(item(paragraph(text('Unique items: '), inlineCode(value.uniqueItems))));
-        if (constraints.length)
-            nodes.push(list(constraints));
-        if (value.additionalProperties !== undefined)
-            nodes.push(paragraph(strong(text('Additional properties:'))), ...render(value.additionalProperties, depth + 1, childAncestors));
-        if (value.discriminator) {
-            nodes.push(paragraph(strong(text('Discriminator:')), text(' '), inlineCode(value.discriminator.propertyName)));
-            const mappings = Object.entries(value.discriminator.mapping ?? {});
-            if (mappings.length)
-                nodes.push(list(mappings.map(([name, target]) => item(paragraph(inlineCode(name), text(': '), inlineCode(target))))));
-        }
-        return nodes;
+    const forDocument = (models = {}) => {
+        /** Shared schemas this document already expanded, with the name later references use. */
+        const shown = new Map();
+        /** Models that the document renders in their own sections after the operations. */
+        const sections = new Set(Object.values(models).map((model) => getResolvedRef(model) ?? model));
+        let nodeCount = 0;
+        /** Refer to a schema expanded elsewhere, keeping annotations the reference itself adds. */
+        const reference = (input, value, options, name, location) => {
+            const nodes = [];
+            const siblings = isObject(input) && Object.keys(input).some((key) => !referenceKeys.has(key));
+            if (siblings && !options.hideDetails) {
+                const annotations = details({ ...value, name: undefined }, false, options.hideDescription);
+                if (annotations.length)
+                    nodes.push(paragraph(...annotations));
+            }
+            nodes.push(paragraph(emphasis(text('Schema '), inlineCode(name), text(` is shown ${location}.`))));
+            return nodes;
+        };
+        const render = (input, depth = 0, ancestors = [], options = {}) => {
+            // Follow the original target: merging reference siblings creates fresh objects.
+            const identity = getResolvedRef(input) ?? input;
+            if (typeof identity === 'object' && ancestors.includes(identity)) {
+                return [paragraph(emphasis(text('[Circular Reference]')))];
+            }
+            const value = view(input);
+            // A named model with structural reference siblings is its own schema, not another
+            // occurrence of its target. Otherwise either rendering order can hide properties.
+            const sharedIdentity = isObject(input) && '$ref' in input && Object.keys(input).some((key) => structuralKeywords.has(key))
+                ? input
+                : identity;
+            const shared = typeof sharedIdentity === 'object' && sharedIdentity !== null ? sharedIdentity : undefined;
+            const name = options.name ?? value.name;
+            if (shared && name !== undefined) {
+                // Expanding every path through a shared schema grows exponentially, so expand it once.
+                const previous = shown.get(shared);
+                if (previous !== undefined) {
+                    // A model section already prints its own annotations above the schema.
+                    const referenceOptions = options.name === undefined ? options : { ...options, hideDetails: true };
+                    return reference(input, value, referenceOptions, previous, 'above');
+                }
+                if (value.name !== undefined && options.name === undefined && depth >= MAX_DEPTH && sections.has(shared))
+                    return reference(input, value, options, value.name, 'below under Schemas');
+            }
+            if (depth >= MAX_DEPTH)
+                return [paragraph(text('[Maximum schema depth reached]'))];
+            if (nodeCount >= maxNodes)
+                return [paragraph(emphasis(text('[Schema output truncated]')))];
+            nodeCount++;
+            if (shared && name !== undefined && !shown.has(shared))
+                shown.set(shared, name);
+            if (typeof value.schema === 'boolean')
+                return options.hideDetails ? [] : [paragraph(...details(value))];
+            const childAncestors = [...ancestors, identity];
+            const nodes = [];
+            for (const [key, label] of [
+                ['allOf', 'All of:'],
+                ['anyOf', 'Any of:'],
+                ['oneOf', 'One of:'],
+            ]) {
+                if (value[key]?.length)
+                    nodes.push(paragraph(strong(text(label))), ...value[key].flatMap((child) => render(child, depth + 1, childAncestors)));
+            }
+            if (value.not !== undefined)
+                nodes.push(paragraph(strong(text('Not:'))), ...render(value.not, depth + 1, childAncestors));
+            const array = value.type === 'array' || value.items !== undefined;
+            if (!options.hideDetails) {
+                // Child sections imply a single container type, but never its nullable alternatives.
+                const impliedType = (value.type === 'object' && value.properties.length > 0) ||
+                    (value.type === 'array' && value.items !== undefined);
+                const annotations = details(value, false, options.hideDescription, !impliedType);
+                if (annotations.length)
+                    nodes.push(paragraph(...annotations));
+            }
+            if (value.properties.length) {
+                const properties = value.properties.map(([name, schema]) => {
+                    const child = view(schema);
+                    const label = [inlineCode(name)];
+                    if (value.required.has(name))
+                        label.push(text(' (required)'));
+                    const blocks = [paragraph(strong(...label)), paragraph(...details(child, true))];
+                    blocks.push(...render(schema, depth + 1, childAncestors, {
+                        hideDetails: true,
+                        property: true,
+                    }));
+                    return item(...blocks);
+                });
+                nodes.push(list(properties));
+            }
+            if (array && value.items !== undefined) {
+                nodes.push(paragraph(strong(text(options.property ? 'Items:' : 'Array of:'))), ...render(value.items, depth + 1, childAncestors));
+            }
+            const constraints = [];
+            if (value.minItems !== undefined)
+                constraints.push(item(paragraph(text('Min items: '), inlineCode(value.minItems))));
+            if (value.maxItems !== undefined)
+                constraints.push(item(paragraph(text('Max items: '), inlineCode(value.maxItems))));
+            if (value.uniqueItems !== undefined)
+                constraints.push(item(paragraph(text('Unique items: '), inlineCode(value.uniqueItems))));
+            if (constraints.length)
+                nodes.push(list(constraints));
+            if (value.additionalProperties !== undefined)
+                nodes.push(paragraph(strong(text('Additional properties:'))), ...render(value.additionalProperties, depth + 1, childAncestors));
+            if (value.discriminator) {
+                nodes.push(paragraph(strong(text('Discriminator:')), text(' '), inlineCode(value.discriminator.propertyName)));
+                const mappings = Object.entries(value.discriminator.mapping ?? {});
+                if (mappings.length)
+                    nodes.push(list(mappings.map(([name, target]) => item(paragraph(inlineCode(name), text(': '), inlineCode(target))))));
+            }
+            return nodes;
+        };
+        return {
+            view,
+            render,
+            beginSection: () => {
+                nodeCount = 0;
+            },
+            forDocument,
+        };
     };
-    return { view, render };
+    return forDocument();
 };

package/dist/select-document.d.ts

@@ -1,9 +1,9 @@
-import { type HttpMethod } from '@scalar/helpers/http/http-methods';
+import type { OperationMethod } from '@scalar/workspace-store/schemas/navigation';
 import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 /** Identify one operation by path and method, operation ID, or JSON pointer. */
 export type OperationSelector = {
     path: string;
-    method: HttpMethod | Uppercase<HttpMethod>;
+    method: OperationMethod;
 } | {
     operationId: string;
 } | {
@@ -19,7 +19,7 @@ type PageSelectors = {
     model: string;
     webhook: {
         name: string;
-        method: HttpMethod | Uppercase<HttpMethod>;
+        method: OperationMethod;
     };
     introduction: true;
 };

package/dist/select-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAIjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;CAC3C,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CACnH,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/C,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;KAAE,CAAA;IACrE,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAkKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eA+M9F,CAAA"}
+{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CACnH,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/C,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eAuN9F,CAAA"}

package/dist/select-document.js

@@ -1,6 +1,6 @@
 import { HTTP_METHODS } from '@scalar/helpers/http/http-methods';
 import { isObject } from '@scalar/helpers/object/is-object';
-import { getPathItemOperation, getResolvedPathItem } from '@scalar/workspace-store/helpers/for-each-path-item-operation';
+import { forEachPathItemOperation, getPathItemOperation, getResolvedPathItem, setPathItemOperation, } from '@scalar/workspace-store/helpers/for-each-path-item-operation';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 const HTTP_METHOD_SET = new Set(HTTP_METHODS);
 const normalizeHttpMethod = (method) => {
@@ -28,17 +28,18 @@ const parseJsonPointer = (pointer) => normalizeJsonPointer(pointer)
     .map((segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~'));
 const getOperationSelectorFromPointer = (pointer) => {
     const segments = parseJsonPointer(pointer);
-    if (segments.length !== 3 || segments[0] !== 'paths') {
+    if (segments[0] !== 'paths' ||
+        !(segments.length === 3 || (segments.length === 4 && segments[2] === 'additionalOperations'))) {
         throw new Error(`JSON pointer "${pointer}" must target an operation object under "/paths/{path}/{method}"`);
     }
     const path = segments[1];
-    const method = segments[2];
-    if (!path || !method) {
+    const method = segments.length === 4 ? segments[3] : segments[2];
+    if (!path || !method || (segments.length === 3 ? !HTTP_METHOD_SET.has(method) : HTTP_METHOD_SET.has(method))) {
         throw new Error(`JSON pointer "${pointer}" must target an operation object under "/paths/{path}/{method}"`);
     }
     return {
         path,
-        method: method,
+        method,
     };
 };
 const getPathEntries = (document) => {
@@ -51,12 +52,20 @@ const getPathEntries = (document) => {
         return pathItem ? [[path, pathItem]] : [];
     });
 };
-const filterPathItemToSingleOperation = (pathItem, selectedMethod) => Object.fromEntries(Object.entries(pathItem).filter(([key]) => {
-    const method = normalizeHttpMethod(key);
-    return !method || method === selectedMethod;
-}));
+/** Keep path metadata while excluding every unselected fixed or additional operation. */
+const filterPathItemOperations = (pathItem, methods) => {
+    const selected = Object.fromEntries(Object.entries(pathItem).filter(([key]) => !HTTP_METHOD_SET.has(key) && key !== 'additionalOperations'));
+    forEachPathItemOperation(pathItem, (method, operation) => {
+        if (methods.includes(method)) {
+            setPathItemOperation(selected, method, operation);
+        }
+    });
+    return selected;
+};
+/** Exact authored methods take precedence over the legacy uppercase fixed-method aliases. */
+const resolveMethod = (pathItem, method) => getPathItemOperation(pathItem, method) ? method : normalizeHttpMethod(method);
 const findOperationByPathAndMethod = (document, selector) => {
-    const method = normalizeHttpMethod(selector.method);
+    const method = resolveMethod(getResolvedPathItem(document.paths?.[selector.path]), selector.method);
     if (!method) {
         throw new Error(`Invalid HTTP method "${selector.method}". Supported methods: ${HTTP_METHODS.join(', ')}`);
     }
@@ -69,20 +78,22 @@ const findOperationByPathAndMethod = (document, selector) => {
         method,
     };
 };
-const findOperationsByOperationId = (document, operationId) => getPathEntries(document).flatMap(([path, pathItem]) => Object.entries(pathItem).flatMap(([methodKey, operation]) => {
-    const method = normalizeHttpMethod(methodKey);
-    if (!method || !isObject(operation)) {
-        return [];
-    }
-    const candidateOperationId = 'operationId' in operation && typeof operation.operationId === 'string' ? operation.operationId : undefined;
-    if (candidateOperationId !== operationId) {
-        return [];
-    }
-    return [{ path, method }];
-}));
+const findOperationsByOperationId = (document, operationId) => getPathEntries(document).flatMap(([path, pathItem]) => {
+    const matches = [];
+    forEachPathItemOperation(pathItem, (method, operation) => {
+        if (getResolvedRef(operation)?.operationId === operationId) {
+            matches.push({ path, method });
+        }
+    });
+    return matches;
+});
 const resolveOperationMatch = (document, selector) => {
     if ('pointer' in selector) {
-        return findOperationByPathAndMethod(document, getOperationSelectorFromPointer(selector.pointer));
+        const match = getOperationSelectorFromPointer(selector.pointer);
+        if (!getPathItemOperation(document.paths?.[match.path], match.method)) {
+            throw new Error(`Operation not found at JSON pointer "${selector.pointer}"`);
+        }
+        return match;
     }
     if ('operationId' in selector) {
         const matches = findOperationsByOperationId(document, selector.operationId);
@@ -106,7 +117,7 @@ const filterDocumentByOperation = (document, selector) => {
     return {
         ...document,
         paths: {
-            [match.path]: filterPathItemToSingleOperation(pathItem, match.method),
+            [match.path]: filterPathItemOperations(pathItem, [match.method]),
         },
     };
 };
@@ -157,9 +168,14 @@ export const selectDocument = (document, options = {}) => {
         }
         selected.tags = metadata.length ? metadata : [{ name: options.tag }];
         for (const [path, item] of getPathEntries(document)) {
-            const methods = HTTP_METHODS.filter((method) => getPathItemOperation(item, method)?.tags?.includes(options.tag));
+            const methods = [];
+            forEachPathItemOperation(item, (method, operation) => {
+                if (getResolvedRef(operation)?.tags?.includes(options.tag)) {
+                    methods.push(method);
+                }
+            });
             if (methods.length) {
-                selected.paths[path] = Object.fromEntries(Object.entries(item).filter(([key]) => !HTTP_METHOD_SET.has(key) || methods.includes(key)));
+                selected.paths[path] = filterPathItemOperations(item, methods);
             }
         }
         if (!metadata.length && !Object.keys(selected.paths ?? {}).length) {
@@ -182,26 +198,31 @@ export const selectDocument = (document, options = {}) => {
             Object.keys(selector).length !== 2) {
             throw new Error('Invalid webhook selector. Use { name, method }');
         }
-        const method = normalizeHttpMethod(selector.method);
+        const item = getResolvedPathItem(document.webhooks?.[selector.name]);
+        const method = resolveMethod(item, selector.method);
         if (!method) {
             throw new Error(`Invalid HTTP method "${selector.method}"`);
         }
-        const item = getResolvedPathItem(document.webhooks?.[selector.name]);
         if (!item || !getPathItemOperation(item, method)) {
             throw new Error(`Webhook "${selector.name}" with method "${method.toUpperCase()}" was not found`);
         }
-        selected.webhooks = { [selector.name]: filterPathItemToSingleOperation(item, method) };
+        selected.webhooks = { [selector.name]: filterPathItemOperations(item, [method]) };
     }
     const securityNames = new Set();
     const tagNames = new Set();
     for (const items of [selected.paths, selected.webhooks]) {
         for (const [path, itemRef] of Object.entries(items ?? {})) {
             const item = getResolvedPathItem(itemRef);
-            const scoped = { ...item, parameters: undefined, servers: undefined };
-            for (const method of HTTP_METHODS) {
-                const operation = getPathItemOperation(item, method);
+            const scoped = {
+                ...item,
+                additionalOperations: item.additionalOperations ? { ...item.additionalOperations } : undefined,
+                parameters: undefined,
+                servers: undefined,
+            };
+            forEachPathItemOperation(item, (method, operationRef) => {
+                const operation = getResolvedRef(operationRef);
                 if (!operation) {
-                    continue;
+                    return;
                 }
                 const parameters = new Map();
                 for (const ref of [...(item.parameters ?? []), ...(operation.parameters ?? [])]) {
@@ -219,14 +240,14 @@ export const selectDocument = (document, options = {}) => {
                 for (const name of operation.tags ?? []) {
                     tagNames.add(name);
                 }
-                scoped[method] = {
+                setPathItemOperation(scoped, method, {
                     ...operation,
                     parameters: [...parameters.values()],
                     servers: operation.servers ?? item.servers ?? document.servers,
                     security,
                     tags: options.tag !== undefined ? [options.tag] : operation.tags,
-                };
-            }
+                });
+            });
             items[path] = scoped;
         }
     }

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.1.0",
+  "version": "1.2.0",
   "engines": {
     "node": ">=22"
   },
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "@scalar/code-highlight": "0.4.7",
-    "@scalar/helpers": "0.13.0",
-    "@scalar/json-magic": "0.15.0",
-    "@scalar/openapi-upgrader": "0.3.0",
-    "@scalar/workspace-store": "0.65.0",
+    "@scalar/helpers": "0.14.0",
+    "@scalar/json-magic": "0.15.1",
+    "@scalar/openapi-upgrader": "0.3.1",
+    "@scalar/workspace-store": "0.66.0",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",