@scalar/openapi-to-markdown 1.0.2 → 1.2.0

package/dist/render-operation.js

@@ -1,15 +1,19 @@
+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';
+import { renderEncoding, renderHeaders, renderResponseLinks } from './render-operation-details.js';
 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)
         metadata.push(field('Tags', text(operation.tags.join(', '))));
     if (stability)
@@ -52,23 +56,28 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         if ('allowReserved' in parameter && parameter.allowReserved)
             fields.push(field('Allow Reserved', text('true')));
         nodes.push(list(fields), ...(await description(parameter.description)));
-        if ('schema' in parameter && parameter.schema)
+        if ('schema' in parameter && parameter.schema !== undefined)
             nodes.push(...schemas.render(parameter.schema));
+        if ('example' in parameter || 'examples' in parameter)
+            nodes.push(...(await renderExamples({ example: parameter.example, examples: parameter.examples }, description, 'application/json', 'write', openapiVersion)));
         for (const [mediaType, content] of Object.entries('content' in parameter ? (parameter.content ?? {}) : {})) {
             nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
-            if (content.schema)
+            if (content.schema !== undefined)
                 nodes.push(...schemas.render(content.schema));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion)));
         }
     }
     const body = getResolvedRef(operation.requestBody, mergeSiblingReferences);
-    if (body?.content) {
+    if (body) {
         nodes.push(heading(4, text('Request Body')), ...(await description(body.description)));
-        if (body.required)
-            nodes.push(paragraph(strong(text('Required:')), text(' true')));
-        for (const [mediaType, content] of Object.entries(body.content)) {
+        if (typeof body.required === 'boolean')
+            nodes.push(paragraph(strong(text('Required:')), text(' '), inlineCode(body.required)));
+        for (const [mediaType, content] of Object.entries(body.content ?? {})) {
             nodes.push(heading(5, text(`Content-Type: ${mediaType}`)));
-            if (content.schema)
-                nodes.push(...schemas.render(content.schema), paragraph(strong(text('Example:'))), schemas.example(content.schema, mediaType.includes('xml')));
+            if (content.schema !== undefined)
+                nodes.push(...schemas.render(content.schema));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion)));
+            nodes.push(...(await renderEncoding(content.encoding, mediaType, description, schemas, openapiVersion)));
         }
     }
     const responses = Object.entries(operation.responses ?? {}).flatMap(([status, reference]) => {
@@ -79,10 +88,12 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         nodes.push(heading(4, text('Responses')));
     for (const { status, response } of responses) {
         nodes.push(heading(5, text(`Status: ${status}${response.description ? ` ${response.description}` : ''}`)));
+        nodes.push(...(await renderHeaders(response.headers, description, schemas, openapiVersion)), ...(await renderResponseLinks(response.links, description)));
         for (const [mediaType, content] of Object.entries(response.content ?? {})) {
             nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
-            if (content.schema)
-                nodes.push(...schemas.render(content.schema), paragraph(strong(text('Example:'))), schemas.example(content.schema, mediaType.includes('xml')));
+            if (content.schema !== undefined)
+                nodes.push(...schemas.render(content.schema));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'read', openapiVersion)));
         }
     }
     return nodes;

package/dist/render-schema.d.ts

@@ -1,31 +1,73 @@
 import type { MaybeRefSchemaObject, SchemaObject } from '@scalar/workspace-store/schemas/v3.2/strict/schema';
-import type { Code, RootContent } from 'mdast';
+import type { RootContent } from 'mdast';
+/** Boolean schemas must survive rendering without being coerced into empty objects. */
+type MarkdownSchema = MaybeRefSchemaObject | boolean;
 type SchemaView = {
-    schema: SchemaObject;
+    schema: SchemaObject | boolean;
     title?: string;
     description?: string;
     type?: string | string[];
     format?: string;
     enum?: unknown[];
+    const?: unknown;
     default?: unknown;
-    allOf?: MaybeRefSchemaObject[];
-    anyOf?: MaybeRefSchemaObject[];
-    oneOf?: MaybeRefSchemaObject[];
-    not?: MaybeRefSchemaObject;
-    properties: [string, MaybeRefSchemaObject][];
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    allOf?: MarkdownSchema[];
+    anyOf?: MarkdownSchema[];
+    oneOf?: MarkdownSchema[];
+    not?: MarkdownSchema;
+    properties: [string, MarkdownSchema][];
     required: ReadonlySet<string>;
-    items?: MaybeRefSchemaObject;
+    items?: MarkdownSchema;
     minItems?: number;
     maxItems?: number;
     uniqueItems?: boolean;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minProperties?: number;
+    maxProperties?: number;
+    additionalProperties?: MarkdownSchema;
+    discriminator?: {
+        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;
 };
-/** Schema normalization is cached separately from ancestry-dependent expansion. */
+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.
+ *
+ * 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: MaybeRefSchemaObject) => SchemaView;
-    render: (schema: MaybeRefSchemaObject, depth?: number, ancestors?: readonly unknown[]) => RootContent[];
-    example: (schema: MaybeRefSchemaObject, xml?: boolean) => Code;
+    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":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,oDAAoD,CAAA;AAC5G,OAAO,KAAK,EAAE,IAAI,EAA6B,WAAW,EAAE,MAAM,OAAO,CAAA;AAIzE,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,YAAY,CAAA;IACpB,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,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC9B,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC9B,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC9B,GAAG,CAAC,EAAE,oBAAoB,CAAA;IAC1B,UAAU,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAAE,CAAA;IAC5C,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC7B,KAAK,CAAC,EAAE,oBAAoB,CAAA;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,UAAU,CAAA;IAClD,MAAM,EAAE,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,WAAW,EAAE,CAAA;IACvG,OAAO,EAAE,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAC/D,CAAA;AAED,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,QAAO,cA0FvC,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,98 +1,256 @@
-import { json2xml } from '@scalar/helpers/file/json2xml';
-import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
-import { resolve } from '@scalar/workspace-store/resolve';
+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);
+    const merged = getResolvedRef(input, mergeSiblingReferences);
+    if (typeof target !== 'boolean')
+        return merged;
+    if (!isObject(merged) ||
+        !Object.keys(merged).some((key) => !['$ref', '$ref-value', '$global', '$status'].includes(key)))
+        return target;
+    if (target)
+        return merged;
+    // A false target remains impossible, even when siblings describe a type or annotations.
+    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 = views.get(input);
+        const cached = typeof input === 'object' ? views.get(input) : undefined;
         if (cached)
             return cached;
-        const schema = resolve.schema(input);
-        const value = schema;
+        // Keep the linked document's nested identities and boolean schemas. Coercing a
+        // second time here would discard boolean children and copy recursive targets.
+        const schema = resolveMarkdownSchema(input);
+        const value = (typeof schema === 'object' ? schema : {});
         const required = new Set(value.required ?? []);
         const properties = Object.entries(value.properties ?? {})
-            .filter((entry) => entry[1] && typeof entry[1] === 'object')
+            .filter(([, child]) => typeof child === 'boolean' || (child !== null && typeof child === 'object'))
             .sort(([a], [b]) => Number(required.has(b)) - Number(required.has(a)) || a.localeCompare(b));
-        const result = { ...value, schema, required, properties };
-        views.set(input, result);
+        const result = {
+            ...value,
+            type: typeof schema === 'boolean' ? (schema ? 'any' : 'never') : value.type,
+            schema: schema,
+            required,
+            properties,
+        };
+        result.name = getSharedName(input, result);
+        if (typeof input === 'object')
+            views.set(input, result);
         return result;
     };
-    const details = (value, property = false) => {
+    const details = (value, property = false, hideDescription = false, showType = true) => {
+        if (typeof value.schema === 'boolean')
+            return [text(value.schema ? 'any (true schema)' : 'never (false schema)')];
         const type = Array.isArray(value.type) ? value.type.join(' | ') : value.type;
-        const nodes = type || property ? [inlineCode(type || 'object')] : [];
-        if (value.format)
-            nodes.push(text(', format: '), inlineCode(value.format));
+        const nodes = showType && (type || property) ? [inlineCode(type || 'object')] : [];
+        const add = (label, entry) => {
+            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)
-            nodes.push(text(', possible values: '), inlineCode(value.enum.map((entry) => JSON.stringify(entry)).join(', ')));
+            add('possible values', value.enum.map((entry) => JSON.stringify(entry)).join(', '));
+        if (value.const !== undefined)
+            add('const', JSON.stringify(value.const));
         if (value.default !== undefined)
-            nodes.push(text(', default: '), inlineCode(JSON.stringify(value.default)));
-        if (value.description)
-            nodes.push(text(` — ${value.description}`));
-        return nodes;
-    };
-    const render = (input, depth = 0, ancestors = []) => {
-        // The previous renderer expanded a resolved root before tracking child reference strings.
-        const identity = depth > 0 && '$ref' in input ? input.$ref : input;
-        if (depth >= 10 || ancestors.includes(identity)) {
-            return [paragraph({ type: 'emphasis', children: [text('[Circular Reference]')] })];
-        }
-        const value = view(input);
-        const childAncestors = [...ancestors, identity];
-        for (const [key, label] of [
-            ['allOf', 'All of:'],
-            ['anyOf', 'Any of:'],
-            ['oneOf', 'One of:'],
-        ]) {
+            add('default', JSON.stringify(value.default));
+        for (const key of [
+            'minimum',
+            'maximum',
+            'exclusiveMinimum',
+            'exclusiveMaximum',
+            'multipleOf',
+            'minLength',
+            'maxLength',
+            'pattern',
+            'minProperties',
+            'maxProperties',
+        ])
+            add(key, value[key]);
+        for (const key of ['readOnly', 'writeOnly']) {
             if (value[key])
-                return [
-                    paragraph(strong(text(label))),
-                    ...value[key].flatMap((child) => render(child, depth + 1, childAncestors)),
-                ];
+                nodes.push(text(`${nodes.length ? ', ' : ''}${key}`));
         }
-        if (value.not)
-            return [paragraph(strong(text('Not:'))), ...render(value.not, depth + 1, childAncestors)];
-        if (value.type === 'object' || 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))];
-                if (child.type === 'object' || child.properties.length) {
-                    blocks.push(...render(schema, depth + 1, childAncestors));
-                }
-                if (child.type === 'array' && child.items) {
-                    blocks.push(paragraph(strong(text('Items:'))), ...render(child.items, depth + 1, childAncestors));
+        if (!hideDescription && value.description)
+            nodes.push(text(`${nodes.length ? ' — ' : ''}${value.description}`));
+        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');
                 }
-                return item(...blocks);
-            });
-            return properties.length ? [list(properties)] : [];
-        }
-        if (value.type === 'array' && value.items) {
-            const nodes = [paragraph(strong(text('Array of:'))), ...render(value.items, depth + 1, childAncestors)];
+                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)
-                constraints.push(item(paragraph(text('Unique items: '), inlineCode(true))));
+            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 nodes = details(value);
-        return nodes.length ? [paragraph(...nodes)] : [];
-    };
-    const example = (input, xml = false) => {
-        const value = getExampleFromSchema(view(input).schema, { xml });
+        };
         return {
-            type: 'code',
-            lang: xml ? 'xml' : 'json',
-            value: xml ? json2xml(value) : (JSON.stringify(value, null, 2) ?? ''),
+            view,
+            render,
+            beginSection: () => {
+                nodeCount = 0;
+            },
+            forDocument,
         };
     };
-    return { view, render, example };
+    return forDocument();
 };

package/dist/restore-boolean-schemas.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The workspace schema currently casts boolean JSON Schemas into empty objects.
+ * Restore them only in schema positions, never in example payloads or metadata.
+ * TODO: Remove this bridge when the shared schema accepts boolean JSON Schemas.
+ */
+export declare const restoreBooleanSchemas: (source: unknown, target: unknown) => void;
+//# sourceMappingURL=restore-boolean-schemas.d.ts.map

package/dist/restore-boolean-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-boolean-schemas.d.ts","sourceRoot":"","sources":["../src/restore-boolean-schemas.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,OAAO,EAAE,QAAQ,OAAO,KAAG,IA0DxE,CAAA"}

package/dist/restore-boolean-schemas.js

@@ -0,0 +1,73 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * The workspace schema currently casts boolean JSON Schemas into empty objects.
+ * Restore them only in schema positions, never in example payloads or metadata.
+ * TODO: Remove this bridge when the shared schema accepts boolean JSON Schemas.
+ */
+export const restoreBooleanSchemas = (source, target) => {
+    const seen = new WeakSet();
+    const schemaMaps = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
+    const schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+    const schemaFields = new Set([
+        'items',
+        'not',
+        'additionalProperties',
+        'additionalItems',
+        'contains',
+        'propertyNames',
+        'if',
+        'then',
+        'else',
+        'unevaluatedProperties',
+        'unevaluatedItems',
+        '$ref-value',
+    ]);
+    const getChildContext = (context, key) => {
+        if (context === 'map')
+            return 'schema';
+        if (context === 'schema') {
+            if (schemaMaps.has(key))
+                return 'map';
+            if (schemaArrays.has(key) || schemaFields.has(key))
+                return 'schema';
+            return undefined;
+        }
+        if (key === 'schema' || key === 'itemSchema')
+            return 'schema';
+        if (key === 'schemas')
+            return 'map';
+        if (['example', 'examples', 'default', 'const', 'enum'].includes(key))
+            return undefined;
+        return 'document';
+    };
+    const visit = (original, coerced, context = 'document') => {
+        if (context === 'schema' && typeof original === 'boolean')
+            return original;
+        if (!original || typeof original !== 'object' || !coerced || typeof coerced !== 'object' || seen.has(coerced))
+            return coerced;
+        seen.add(coerced);
+        if (Array.isArray(original) && Array.isArray(coerced)) {
+            for (const [index, value] of original.entries()) {
+                const property = Object.getOwnPropertyDescriptor(coerced, index);
+                if (!property || !('value' in property))
+                    continue;
+                Object.defineProperty(coerced, index, { ...property, value: visit(value, property.value, context) });
+            }
+        }
+        else if (isObject(original) && isObject(coerced)) {
+            for (const [key, value] of Object.entries(original)) {
+                // Never follow inherited values or invoke setters, including __proto__.
+                // Defining an own data property still preserves those names in schema maps.
+                const property = Object.getOwnPropertyDescriptor(coerced, key);
+                if (!property || !('value' in property))
+                    continue;
+                const childContext = getChildContext(context, key);
+                if (childContext === undefined)
+                    continue;
+                Object.defineProperty(coerced, key, { ...property, value: visit(value, property.value, childContext) });
+            }
+        }
+        return coerced;
+    };
+    visit(source, target);
+};

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,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAInE,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;AAmKD,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"}