@scalar/openapi-to-markdown 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @scalar/openapi-to-markdown
 
+## 1.1.0
+
+### Minor Changes
+
+- [#10251](https://github.com/scalar/scalar/pull/10251): Preserve chained path-item references with non-enumerable links.
+
+  Remove the HTML output APIs `createHtmlFromOpenApi` and `renderer.renderHtml` from `@scalar/openapi-to-markdown`. Use `createMarkdownFromOpenApi` or `renderer.render` and convert the resulting Markdown with an application-provided renderer when HTML is needed.
+
+- [#10222](https://github.com/scalar/scalar/pull/10222): Add a Copy as Markdown button to operations and webhooks in both API Reference layouts. Add a browser entry point for converting resolved OpenAPI documents to Markdown.
+
+### Patch Changes
+
+- [#10275](https://github.com/scalar/scalar/pull/10275): Preserve operation and schema details, supplied and named examples, response headers and links, and request encoding metadata in Markdown output. Render composition siblings and schema annotations, respect readOnly/writeOnly when generating examples, and distinguish recursive references from deep schemas.
+- [#10211](https://github.com/scalar/scalar/pull/10211): Preserve literal data and tag groups when upgrading to OpenAPI 3.2, migrate XML metadata only in schemas, and remove incompatible legacy XML flags. Make 3.2 upgrades leave the input unchanged, match the complete source version, prevent previously inactive parameter settings from changing serialization, and report path-specific errors for detected compatibility issues that require an author's decision.
+
+  Tag `kind` values may change: navigation groups are classified from actual operation-tag usage instead of name substrings. Malformed 3.1 versions now report explicit errors, and successful 3.2 upgrades clone the input only once.
+
+  Expose `UpgradeIncompatibilityError` so Markdown generation can retain OpenAPI 3.1 for descriptions requiring author decisions instead of failing or silently changing semantics. Clone safety and malformed-version errors still propagate.
+
+  The mock server also retains OpenAPI 3.1 when the strict 3.2 migration reports compatibility diagnostics. Existing inline XML descriptions continue loading without inventing element names.
+
+  Read only own data properties during migration so inherited parameter lists, XML metadata, and reference targets cannot modify prototype-owned objects.
+
+  Add `upgrade(input, '3.2', { onIncompatible: 'collect' })` to return a complete document and compatibility diagnostics. Compatible descriptions upgrade to 3.2; incompatible descriptions retain 3.1 without partial transformations. Strict mode remains the default, and malformed-version and clone-safety errors still propagate. The Markdown converter and mock server now use the shared collect mode.
+
 ## 1.0.2
 
 ## 1.0.1

package/README.md

@@ -134,10 +134,8 @@ Schema normalization and description parsing are cached within each renderer. Re
 schema expansion still tracks ancestors and stops at a depth of ten. Output may use tighter
 list spacing and normalized Markdown escaping compared with earlier versions.
 
-### HTML output
-
-`createHtmlFromOpenApi` and `renderer.renderHtml` remain available. They convert the
-Markdown output to HTML on demand, without loading a Vue renderer.
+The package only generates Markdown. To produce HTML, pass the Markdown output to a
+Markdown renderer in your application.
 
 ## Community
 
@@ -178,3 +176,21 @@ Omitting options, or passing `{}`, renders the whole document. OpenAPI 2.0 input
 Invalid, combined, or missing selectors reject the returned promise with an error. Duplicate operation IDs are ambiguous and list matching paths and methods; use a path/method selector instead. Duplicate tag declarations are also rejected. Names are case sensitive. Operation JSON pointers must target `/paths/{path}/{method}`, with an optional leading `#` and standard `~0`/`~1` escaping.
 
 Selection does not add support for every OpenAPI or JSON Schema keyword. Callbacks are not selectable pages. External references follow the existing workspace loader behavior. Recursive schema expansion stops on a repeated ancestor, with a depth limit of ten as a fallback. Shared dependencies have one component section, but may also appear inline where used. Authentication lists alternatives separately; schemes within one requirement must be used together.
+
+### Copying Markdown in the browser
+
+Use the browser entry point with an OpenAPI document already resolved by
+`@scalar/workspace-store`. It supports the same page selectors as the default
+entry point, without file loading or HTML minification.
+
+```ts
+const { createMarkdownFromOpenApi } =
+  await import('@scalar/openapi-to-markdown/browser')
+
+const markdown = await createMarkdownFromOpenApi(document, {
+  operation: { path: '/users/{id}', method: 'get' },
+})
+```
+
+Use the default entry point for raw JSON, YAML, URLs, or file paths that still need
+loading, migration, and reference resolution.

package/dist/browser.d.ts

@@ -0,0 +1,9 @@
+import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { type OpenApiRenderOptions } from './select-document.js';
+/**
+ * Convert an OpenAPI document from the workspace store to Markdown in the browser.
+ * References must already be resolved by the store. This entry point does not load
+ * files, fetch URLs, or migrate raw API descriptions.
+ */
+export declare const createMarkdownFromOpenApi: (document: OpenApiDocument, options?: OpenApiRenderOptions) => Promise<string>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAGnG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,eAAe,EACzB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAAsE,CAAA"}

package/dist/browser.js

@@ -0,0 +1,8 @@
+import { createDocumentRenderer } from './render-document.js';
+import { selectDocument } from './select-document.js';
+/**
+ * Convert an OpenAPI document from the workspace store to Markdown in the browser.
+ * References must already be resolved by the store. This entry point does not load
+ * files, fetch URLs, or migrate raw API descriptions.
+ */
+export const createMarkdownFromOpenApi = async (document, options) => await createDocumentRenderer()(selectDocument(document, options));

package/dist/create-markdown-from-openapi.d.ts

@@ -4,7 +4,6 @@ type AnyDocument = OpenApiDocument | Record<string, unknown> | string;
 /** A resolved API description that can render multiple pages without loading it again. */
 export type OpenApiMarkdownRenderer = {
     render: (options?: OpenApiRenderOptions) => Promise<string>;
-    renderHtml: (options?: OpenApiRenderOptions) => Promise<string>;
 };
 /**
  * Load and resolve an API description once, then render any number of selections.
@@ -13,7 +12,5 @@ export type OpenApiMarkdownRenderer = {
 export declare const createOpenApiMarkdownRenderer: (input: AnyDocument) => Promise<OpenApiMarkdownRenderer>;
 /** Generate Markdown from an API description, optionally scoped to a single page. */
 export declare const createMarkdownFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions) => Promise<string>;
-/** Generate HTML through the optional Markdown conversion path. */
-export declare const createHtmlFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions) => Promise<string>;
 export {};
 //# sourceMappingURL=create-markdown-from-openapi.d.ts.map

package/dist/create-markdown-from-openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAInG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3D,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAChE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GAAU,OAAO,WAAW,KAAG,OAAO,CAAC,uBAAuB,CAoBvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,GAAU,OAAO,WAAW,EAAE,UAAU,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAG9G,CAAA"}
+{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAInG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GAAU,OAAO,WAAW,KAAG,OAAO,CAAC,uBAAuB,CAOvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,CAAA"}

package/dist/create-markdown-from-openapi.js

@@ -9,27 +9,10 @@ export const createOpenApiMarkdownRenderer = async (input) => {
     const content = await loadDocument(input);
     const renderDocument = createDocumentRenderer();
     const render = async (options) => await renderDocument(selectDocument(content, options));
-    return {
-        render,
-        renderHtml: async (options) => {
-            const [{ unified }, { default: remarkParse }, { default: remarkRehype }, { default: rehypeStringify }] = await Promise.all([
-                import('unified'),
-                import('remark-parse'),
-                import('remark-rehype'),
-                import('rehype-stringify'),
-            ]);
-            const processor = unified().use(remarkParse).use(remarkRehype).use(rehypeStringify);
-            return processor.processSync(await render(options)).toString();
-        },
-    };
+    return { render };
 };
 /** Generate Markdown from an API description, optionally scoped to a single page. */
 export const createMarkdownFromOpenApi = async (input, options) => {
     const renderer = await createOpenApiMarkdownRenderer(input);
     return renderer.render(options);
 };
-/** Generate HTML through the optional Markdown conversion path. */
-export const createHtmlFromOpenApi = async (input, options) => {
-    const renderer = await createOpenApiMarkdownRenderer(input);
-    return renderer.renderHtml(options);
-};

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

@@ -0,0 +1,22 @@
+/** Example-bearing media types, parameters, and headers share the same precedence rules. */
+export type ExampleSource = {
+    schema?: unknown;
+    example?: unknown;
+    examples?: Record<string, unknown>;
+};
+/** Named examples can contain a literal value or point to an external value. */
+type MarkdownExample = {
+    name?: string;
+    summary?: string;
+    description?: string;
+} & ({
+    value: unknown;
+} | {
+    externalValue: string;
+} | {
+    serializedValue: string;
+});
+/** 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 {};
+//# sourceMappingURL=get-markdown-examples.d.ts.map

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

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

package/dist/get-markdown-examples.js

@@ -0,0 +1,37 @@
+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';
+/** 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)
+        return [{ value: source.example }];
+    if (source.examples && Object.keys(source.examples).length) {
+        return Object.entries(source.examples).flatMap(([name, reference]) => {
+            const example = getResolvedRef(reference);
+            if (!isObject(example))
+                return [];
+            const metadata = {
+                name,
+                summary: typeof example.summary === 'string' ? example.summary : undefined,
+                description: typeof example.description === 'string' ? example.description : undefined,
+            };
+            if (example.value !== undefined)
+                return [{ ...metadata, value: example.value }];
+            if (/^3\.2\./.test(openapiVersion) && typeof example.serializedValue === 'string')
+                return [{ ...metadata, serializedValue: example.serializedValue }];
+            if (typeof example.externalValue === 'string')
+                return [{ ...metadata, externalValue: example.externalValue }];
+            if (/^3\.2\./.test(openapiVersion) && example.dataValue !== undefined)
+                return [{ ...metadata, value: example.dataValue }];
+            return [];
+        });
+    }
+    const schema = getResolvedRef(source.schema);
+    if (!isObject(schema))
+        return [];
+    const value = getExampleFromSchema(getResolvedRef(source.schema, mergeSiblingReferences), {
+        xml: mediaType.includes('xml'),
+        mode,
+    });
+    return value === undefined ? [] : [{ value }];
+};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { HttpMethod } from '@scalar/helpers/http/http-methods';
 export type { OpenApiMarkdownRenderer } from './create-markdown-from-openapi.js';
-export { createHtmlFromOpenApi, createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
+export { createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
 export type { OpenApiRenderOptions, OperationSelector } from './select-document.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { createHtmlFromOpenApi, createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
+export { createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';

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

@@ -1 +1 @@
-{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,8DAA8D,CAAA;AAyErE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CAoFzB,CAAA"}
+{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,8DAA8D,CAAA;AA2ErE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CA0FzB,CAAA"}

package/dist/load-document.js

@@ -10,6 +10,7 @@ import { upgrade } from '@scalar/openapi-upgrader';
 import { deepClone } from '@scalar/workspace-store/helpers/deep-clone';
 import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
 import { OpenAPIDocumentSchema, } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { restoreBooleanSchemas } from './restore-boolean-schemas.js';
 /**
  * Link references in a private, bundled document without proxies or expanded copies.
  * JSON Magic owns `$id` and anchor indexing, which keeps local-reference behavior
@@ -104,7 +105,8 @@ export const loadDocument = async (input) => {
         throw new Error('Failed to load OpenAPI document');
     }
     // Upgrade before indexing so reference resolution sees one consistent dialect.
-    const upgraded = upgrade(raw, '3.2');
+    const declaredOpenapiVersion = typeof raw.openapi === 'string' ? raw.openapi : '2.0';
+    const { document: upgraded } = upgrade(raw, '3.2', { onIncompatible: 'collect' });
     const upgradedSchemas = getSchemas(upgraded);
     const hasExternalReferences = attachRefValues(upgraded, false, upgradedSchemas);
     let document = upgraded;
@@ -134,6 +136,11 @@ export const loadDocument = async (input) => {
     // Restore non-enumerable shared links afterward so rendering never expands the graph.
     attachRefValues(document, true, schemas);
     const coerced = coerceValue(OpenAPIDocumentSchema, document);
+    // Rendering must use the declared version for features added after OpenAPI 3.1.
+    coerced['x-original-oas-version'] = declaredOpenapiVersion;
+    // Boolean schemas were introduced in OpenAPI 3.1; older descriptions retain their existing coercion.
+    if (/^3\.[12]\./.test(declaredOpenapiVersion))
+        restoreBooleanSchemas(document, coerced);
     // Keep extension resources that local and bundled references can target.
     for (const [key, value] of Object.entries(document)) {
         if (key.startsWith('x-') && !(key in coerced)) {

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;AAcpH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAgIxF,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,CAyIxF,CAAA"}

package/dist/render-document.js

@@ -5,6 +5,7 @@ import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
 import { field, heading, inlineCode, item, link, list, paragraph, strong, text } from './markdown-nodes.js';
 import { createDescriptionParser } from './parse-description.js';
+import { renderExamples } from './render-examples.js';
 import { renderOperation } from './render-operation.js';
 import { createSchemaRenderer } from './render-schema.js';
 import { renderSecurity } from './render-security.js';
@@ -101,9 +102,9 @@ export const createDocumentRenderer = () => {
                 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));
+            ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true }));
             if (view.type === 'object')
-                nodes.push(paragraph(strong(text('Example:'))), schemas.example(schema));
+                nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi)));
             flush();
         }
         flush();

package/dist/render-examples.d.ts

@@ -0,0 +1,6 @@
+import type { RootContent } from 'mdast';
+import { type ExampleSource } from './get-markdown-examples.js';
+import type { DescriptionParser } from './parse-description.js';
+/** Render supplied examples before considering a schema-generated fallback. */
+export declare const renderExamples: (source: ExampleSource, description: DescriptionParser, mediaType?: string, mode?: "read" | "write", openapiVersion?: string) => Promise<RootContent[]>;
+//# sourceMappingURL=render-examples.d.ts.map

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

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

package/dist/render-examples.js

@@ -0,0 +1,37 @@
+import { json2xml } from '@scalar/helpers/file/json2xml';
+import { getMarkdownExamples } from './get-markdown-examples.js';
+import { link, paragraph, strong, text } from './markdown-nodes.js';
+/** Render supplied examples before considering a schema-generated fallback. */
+export const renderExamples = async (source, description, mediaType = 'application/json', mode, openapiVersion = '3.2.0') => {
+    const nodes = [];
+    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion)) {
+        nodes.push(paragraph(strong(text(example.name ? `Example: ${example.name}` : 'Example:'))));
+        if (example.summary)
+            nodes.push(paragraph(text(example.summary)));
+        nodes.push(...(await description(example.description)));
+        if ('externalValue' in example) {
+            nodes.push(paragraph(strong(text('External value:')), text(' '), link(example.externalValue, example.externalValue)));
+            continue;
+        }
+        if ('serializedValue' in example) {
+            nodes.push({
+                type: 'code',
+                lang: mediaType.includes('xml') ? 'xml' : mediaType.includes('json') ? 'json' : 'text',
+                value: example.serializedValue,
+            });
+            continue;
+        }
+        const xml = mediaType.includes('xml');
+        nodes.push({
+            type: 'code',
+            lang: xml ? 'xml' : 'json',
+            // XML strings are already serialized; primitives must not become object keys.
+            value: xml
+                ? example.value !== null && typeof example.value === 'object'
+                    ? json2xml(example.value)
+                    : String(example.value)
+                : (JSON.stringify(example.value, null, 2) ?? ''),
+        });
+    }
+    return nodes;
+};

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

@@ -0,0 +1,11 @@
+import type { EncodingObject, ResponseObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import type { RootContent } from 'mdast';
+import type { DescriptionParser } from './parse-description.js';
+import type { SchemaRenderer } from './render-schema.js';
+/** Render response or multipart headers, whose names come from their containing map. */
+export declare const renderHeaders: (headers: ResponseObject["headers"], description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string) => Promise<RootContent[]>;
+/** Preserve explicit encoding settings, including false flags and part headers. */
+export declare const renderEncoding: (encoding: Record<string, EncodingObject> | undefined, mediaType: string, description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string) => Promise<RootContent[]>;
+/** Render response link expressions as literal values, without evaluating them. */
+export declare const renderResponseLinks: (links: ResponseObject["links"], description: DescriptionParser) => Promise<RootContent[]>;
+//# sourceMappingURL=render-operation-details.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-operation-details.d.ts","sourceRoot":"","sources":["../src/render-operation-details.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAA;AAClH,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,wFAAwF;AACxF,eAAO,MAAM,aAAa,GACxB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,KACrB,OAAO,CAAC,WAAW,EAAE,CAkCvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EACpD,WAAW,MAAM,EACjB,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,KACrB,OAAO,CAAC,WAAW,EAAE,CAuBvB,CAAA;AAID,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,EAC9B,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA2BvB,CAAA"}

package/dist/render-operation-details.js

@@ -0,0 +1,85 @@
+import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
+import { renderExamples } from './render-examples.js';
+/** Render response or multipart headers, whose names come from their containing map. */
+export const renderHeaders = async (headers, description, schemas, openapiVersion) => {
+    const entries = [];
+    for (const [name, reference] of Object.entries(headers ?? {})) {
+        // OpenAPI reserves Content-Type for the media type map / encoding field.
+        if (name.toLowerCase() === 'content-type')
+            continue;
+        if (!getResolvedRef(reference))
+            continue;
+        const header = getResolvedRef(reference, mergeSiblingReferences);
+        const blocks = [
+            paragraph(strong(inlineCode(name)), text(header.required ? ' (required)' : '')),
+            ...(await description(header.description)),
+        ];
+        if ('schema' in header && header.schema !== undefined)
+            blocks.push(...schemas.render(header.schema));
+        if ('example' in header || 'examples' in header) {
+            blocks.push(...(await renderExamples({ example: header.example, examples: header.examples }, description, 'application/json', undefined, openapiVersion)));
+        }
+        for (const [mediaType, content] of Object.entries('content' in header ? (header.content ?? {}) : {})) {
+            blocks.push(paragraph(strong(text('Content-Type:')), text(` ${mediaType}`)));
+            if (content.schema !== undefined)
+                blocks.push(...schemas.render(content.schema));
+            blocks.push(...(await renderExamples(content, description, mediaType, undefined, openapiVersion)));
+        }
+        entries.push(item(...blocks));
+    }
+    return entries.length ? [paragraph(strong(text('Headers:'))), list(entries)] : [];
+};
+/** Preserve explicit encoding settings, including false flags and part headers. */
+export const renderEncoding = async (encoding, mediaType, description, schemas, openapiVersion) => {
+    const multipart = mediaType.startsWith('multipart/');
+    if (!multipart && mediaType !== 'application/x-www-form-urlencoded')
+        return [];
+    const entries = [];
+    for (const [name, entry] of Object.entries(encoding ?? {})) {
+        const fields = [];
+        for (const [key, label] of [
+            ['contentType', 'Content-Type'],
+            ['style', 'Style'],
+            ['explode', 'Explode'],
+            ['allowReserved', 'Allow reserved'],
+        ]) {
+            if (entry[key] !== undefined)
+                fields.push(item(paragraph(text(`${label}: `), inlineCode(entry[key]))));
+        }
+        const blocks = [paragraph(strong(inlineCode(name)))];
+        if (fields.length)
+            blocks.push(list(fields));
+        if (multipart)
+            blocks.push(...(await renderHeaders(entry.headers, description, schemas, openapiVersion)));
+        entries.push(item(...blocks));
+    }
+    return entries.length ? [paragraph(strong(text('Encoding:'))), list(entries)] : [];
+};
+const formatValue = (value) => (typeof value === 'string' ? value : (JSON.stringify(value) ?? ''));
+/** Render response link expressions as literal values, without evaluating them. */
+export const renderResponseLinks = async (links, description) => {
+    const entries = [];
+    for (const [name, reference] of Object.entries(links ?? {})) {
+        if (!getResolvedRef(reference))
+            continue;
+        const link = getResolvedRef(reference, mergeSiblingReferences);
+        const blocks = [
+            paragraph(strong(text(name))),
+            ...(await description(link.description)),
+        ];
+        if (link.operationId)
+            blocks.push(paragraph(strong(text('Operation ID:')), text(' '), inlineCode(link.operationId)));
+        if (link.operationRef)
+            blocks.push(paragraph(strong(text('Operation reference:')), text(' '), inlineCode(link.operationRef)));
+        const parameters = Object.entries(link.parameters ?? {});
+        if (parameters.length)
+            blocks.push(list(parameters.map(([name, value]) => item(paragraph(strong(text(`${name}:`)), text(' '), inlineCode(formatValue(value)))))));
+        if (link.requestBody !== undefined)
+            blocks.push(paragraph(strong(text('Request body:')), text(' '), inlineCode(formatValue(link.requestBody))));
+        if (link.server)
+            blocks.push(paragraph(strong(text('Server:')), text(' '), inlineCode(link.server.url)));
+        entries.push(item(...blocks));
+    }
+    return entries.length ? [paragraph(strong(text('Links:'))), list(entries)] : [];
+};

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;AAC5D,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,CAgGvB,CAAA"}
+{"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"}

package/dist/render-operation.js

@@ -1,8 +1,11 @@
 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 openapiVersion = document['x-original-oas-version'] ?? document.openapi;
     const stability = operation['x-scalar-stability'];
     const title = (operation.summary || `${method.toUpperCase()} ${path}`) +
         (stability ? ` (${stability})` : operation.deprecated ? ' ⚠️ Deprecated' : '');
@@ -10,6 +13,8 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         field('Method', inlineCode(method.toUpperCase())),
         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 +57,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 +89,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,29 +1,53 @@
 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>;
+    };
+};
+type RenderOptions = {
+    hideDescription?: boolean;
+    hideDetails?: boolean;
+    property?: boolean;
 };
 /** Schema normalization is cached separately from ancestry-dependent expansion. */
 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[];
 };
 /** Keep merged reference siblings and sorted properties stable throughout an export. */
 export declare const createSchemaRenderer: () => SchemaRenderer;

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

package/dist/render-schema.js

@@ -1,98 +1,148 @@
-import { json2xml } from '@scalar/helpers/file/json2xml';
-import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
-import { resolve } from '@scalar/workspace-store/resolve';
+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';
+/** 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 = () => {
     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,
+        };
+        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));
+        };
+        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}`));
+            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])
+                nodes.push(text(`${nodes.length ? ', ' : ''}${key}`));
+        }
+        if (!hideDescription && value.description)
+            nodes.push(text(`${nodes.length ? ' — ' : ''}${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)) {
+    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])
-                return [
-                    paragraph(strong(text(label))),
-                    ...value[key].flatMap((child) => render(child, depth + 1, childAncestors)),
-                ];
+            if (value[key]?.length)
+                nodes.push(paragraph(strong(text(label))), ...value[key].flatMap((child) => render(child, depth + 1, childAncestors)));
         }
-        if (value.not)
-            return [paragraph(strong(text('Not:'))), ...render(value.not, depth + 1, childAncestors)];
-        if (value.type === 'object' || value.properties.length) {
+        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))];
-                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));
-                }
+                blocks.push(...render(schema, depth + 1, childAncestors, { hideDetails: true, property: true }));
                 return item(...blocks);
             });
-            return properties.length ? [list(properties)] : [];
+            nodes.push(list(properties));
         }
-        if (value.type === 'array' && value.items) {
-            const nodes = [paragraph(strong(text('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 (constraints.length)
-                nodes.push(list(constraints));
-            return nodes;
+        if (array && value.items !== undefined) {
+            nodes.push(paragraph(strong(text(options.property ? 'Items:' : 'Array of:'))), ...render(value.items, depth + 1, childAncestors));
         }
-        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) ?? ''),
-        };
+        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, example };
+    return { view, render };
 };

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,4 +1,4 @@
-import type { HttpMethod } from '@scalar/helpers/http/http-methods';
+import { type HttpMethod } from '@scalar/helpers/http/http-methods';
 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 = {

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

package/dist/select-document.js

@@ -1,7 +1,7 @@
+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 { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
-const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
 const HTTP_METHOD_SET = new Set(HTTP_METHODS);
 const normalizeHttpMethod = (method) => {
     const normalized = method.toLowerCase();

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.0.2",
+  "version": "1.1.0",
   "engines": {
     "node": ">=22"
   },
@@ -28,6 +28,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./browser": {
+      "import": "./dist/browser.js",
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
     }
   },
   "files": [
@@ -35,26 +40,24 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/code-highlight": "0.4.6",
-    "@scalar/helpers": "0.12.0",
-    "@scalar/json-magic": "0.14.0",
-    "@scalar/openapi-upgrader": "0.2.17",
-    "@scalar/workspace-store": "0.64.0",
+    "@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",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",
-    "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
-    "remark-rehype": "^11.1.2",
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@hono/node-server": "^1.19.10",
+    "@hono/node-server": "^2.1.1",
     "@scalar/galaxy": "0.7.1",
     "@types/mdast": "^4.0.4",
-    "hono": "^4.13.7",
+    "hono": "^4.13.8",
     "vitest": "4.1.10"
   },
   "scripts": {