@scalar/mock-server 0.14.4 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @scalar/mock-server
 
+## 0.15.0
+
+### Minor Changes
+
+- [#10290](https://github.com/scalar/scalar/pull/10290): Update Hono and its Node.js server, WebSocket, and OpenAPI integration dependencies.
+
+  Replace the deprecated `@hono/node-ws` adapter with Node server v2 WebSocket support. `createAsyncApiMockServer()` now returns `websocket` instead of `injectWebSocket`. Start the server with `serve({ fetch: app.fetch, websocket })` instead of calling `injectWebSocket(server)`.
+
+  AsyncAPI callers must upgrade to `@hono/node-server` v2. Node server v1 ignores the `websocket` option, so WebSocket channels will silently stop accepting connections if the server dependency is not upgraded.
+
+- [#10286](https://github.com/scalar/scalar/pull/10286): Fix JSON and YAML exports for file and URL inputs. Add an origin option to resolve relative references in already loaded documents without fetching the root document again.
+- [#10288](https://github.com/scalar/scalar/pull/10288): Upgrade documents to OpenAPI 3.2 when preparing mock responses, and use OpenAPI 3.2 for the empty-document default.
+- [#10176](https://github.com/scalar/scalar/pull/10176): Generate finite SSE, JSON Lines, NDJSON, and JSON Sequence mock responses from OpenAPI 3.2 itemSchema definitions, including custom handler responses.
+
+  Honor named examples in custom stream handlers and keep media-type recognition consistent with stream serialization.
+
+  Use the same stream serializer as documentation examples. SSE objects without valid fields are omitted with a console warning per serialization call; other records still stream normally. The mock serializes each item separately to retain individual chunk writes.
+
+- [#10191](https://github.com/scalar/scalar/pull/10191): Support OpenAPI 3.2 OAuth device authorization with verification codes, cancellable token polling, stored credentials, and OAuth metadata discovery. Add mock device authorization and approval endpoints with pending, denial, expiry, and polling backoff responses.
+
+  Use consistent form-encoded Basic credentials and environment substitution across OAuth token and refresh flows. Allow HTTP metadata and verification links on local development hosts and reserved test domains, coerce discovery fields consistently, and report device-code expiry clearly.
+
+### Patch Changes
+
+- [#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.
+
+- [#10203](https://github.com/scalar/scalar/pull/10203): Add a picker for generated response examples with anyOf or oneOf schema variants.
+
+  Apply union selections to primitive and array examples in the shared generator without reusing the selection for nested unions.
+
+  The shared generator change also affects request examples, snippets, mock responses, and AsyncAPI payloads: root primitive/array unions now generate their chosen branch before type inference from sibling properties or items. For example, a string schema with `oneOf: [{ const: "first" }, { const: "second" }]` now generates `"first"` by default, and selecting the second branch generates `"second"`. Keywords for unrelated types do not force object/array generation. Root selections are consumed once; nested unions retain their own default or path-specific choice.
+
+  Do not show a response variant picker for an empty enum, which permits no valid alternatives.
+
+  Preserve the generated branch shape in mock HTTP responses instead of re-wrapping selected primitive values as arrays based on root sibling `items`. Explicit authored examples retain the existing array normalization.
+
+- [#10206](https://github.com/scalar/scalar/pull/10206): Add generic document identity hooks for bundling and an explicit root URI option for reference proxies. Honor OpenAPI 3.2 `$self` through an OpenAPI plugin in workspace-store, including external documents and partial bundles, and enable it in OpenAPI bundling callers.
+
+  URI resolution now honors root-relative and protocol-relative URLs, query/fragment references, and trailing-slash directory bases for all bundler consumers. Absolute non-HTTP identifiers remain unchanged instead of becoming filesystem paths; loader support is unchanged. Relative HTTP references retain query strings and fragments and are emitted only when they round-trip to the original URL.
+
+  Preserve authored reference spellings through serialized partial bundles and editable exports, while keeping older OpenAPI resolution and configured loader restrictions unchanged.
+
+  Keep references matching authored root schema identifiers intact so schema labels and anchors retain their existing behavior.
+
 ## 0.14.4
 
 ### Patch Changes

package/dist/create-asyncapi-mock-server.d.ts

@@ -1,4 +1,4 @@
-import { createNodeWebSocket } from '@hono/node-ws';
+import { type WebSocketServerLike } from '@hono/node-server';
 import { Hono } from 'hono';
 import type { MessageDirection, MockTransport } from './transports/types.js';
 import type { MockServerLogger } from './types.js';
@@ -33,11 +33,10 @@ export type AsyncApiMockServerOptions = {
 export type AsyncApiMockServer = {
     /** The Hono app serving SSE channels and WebSocket upgrade routes. */
     app: Hono;
-    /**
-     * Attaches WebSocket handling to the running Node HTTP server returned by `@hono/node-server`'s
-     * `serve()`. Must be called for WebSocket channels to accept connections.
-     */
-    injectWebSocket: ReturnType<typeof createNodeWebSocket>['injectWebSocket'];
+    /** Pass this option to `@hono/node-server`'s `serve()` to enable WebSocket channels. */
+    websocket: {
+        server: WebSocketServerLike;
+    };
 };
 /**
  * Create a mock server for an AsyncAPI 3.1 document — the event-driven counterpart of
@@ -45,12 +44,11 @@ export type AsyncApiMockServer = {
  * default) that emits realistic mock messages generated from the channel's message payload
  * schemas, the same way the REST mocker generates HTTP response bodies.
  *
- * WebSocket support requires attaching to the HTTP server after `serve()`:
+ * Pass the returned WebSocket option to `serve()`:
  *
  * ```ts
- * const { app, injectWebSocket } = await createAsyncApiMockServer({ document })
- * const server = serve({ fetch: app.fetch, port: 3000 })
- * injectWebSocket(server)
+ * const { app, websocket } = await createAsyncApiMockServer({ document })
+ * serve({ fetch: app.fetch, port: 3000, websocket })
  * ```
  */
 export declare function createAsyncApiMockServer(options: AsyncApiMockServerOptions): Promise<AsyncApiMockServer>;

package/dist/create-asyncapi-mock-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-asyncapi-mock-server.d.ts","sourceRoot":"","sources":["../src/create-asyncapi-mock-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAM/C,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAE5B,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sEAAsE;IACtE,GAAG,EAAE,IAAI,CAAA;IACT;;;OAGG;IACH,eAAe,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,iBAAiB,CAAC,CAAA;CAC3E,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0C9G"}
+{"version":3,"file":"create-asyncapi-mock-server.d.ts","sourceRoot":"","sources":["../src/create-asyncapi-mock-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,mBAAmB,CAAA;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAK3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAM/C,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAE5B,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sEAAsE;IACtE,GAAG,EAAE,IAAI,CAAA;IACT,wFAAwF;IACxF,SAAS,EAAE;QAAE,MAAM,EAAE,mBAAmB,CAAA;KAAE,CAAA;CAC3C,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqC9G"}

package/dist/create-asyncapi-mock-server.js

@@ -1,6 +1,7 @@
-import { createNodeWebSocket } from '@hono/node-ws';
+import { upgradeWebSocket } from '@hono/node-server';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
+import { WebSocketServer } from 'ws';
 import { defaultTransports } from './transports/index.js';
 import { generateMessage } from './utils/generate-message.js';
 import { processAsyncApiDocument } from './utils/process-asyncapi-document.js';
@@ -12,20 +13,15 @@ import { resolveLogger } from './utils/resolve-logger.js';
  * default) that emits realistic mock messages generated from the channel's message payload
  * schemas, the same way the REST mocker generates HTTP response bodies.
  *
- * WebSocket support requires attaching to the HTTP server after `serve()`:
+ * Pass the returned WebSocket option to `serve()`:
  *
  * ```ts
- * const { app, injectWebSocket } = await createAsyncApiMockServer({ document })
- * const server = serve({ fetch: app.fetch, port: 3000 })
- * injectWebSocket(server)
+ * const { app, websocket } = await createAsyncApiMockServer({ document })
+ * serve({ fetch: app.fetch, port: 3000, websocket })
  * ```
  */
 export async function createAsyncApiMockServer(options) {
     const app = new Hono();
-    // The Node WebSocket adapter must be created against the app before routes are registered so the
-    // `upgradeWebSocket` helper shares this app's lifecycle. `injectWebSocket` is wired to the
-    // HTTP server by the caller after `serve()`.
-    const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
     const document = await processAsyncApiDocument(options.document);
     const channels = resolveChannels(document);
     const transports = [...defaultTransports, ...(options.transports ?? [])];
@@ -50,5 +46,5 @@ export async function createAsyncApiMockServer(options) {
         transport.register(channel, context);
         log(`[asyncapi] ${transport.name} -> ${channel.route} (channel "${channel.id}")`);
     }
-    return { app, injectWebSocket };
+    return { app, websocket: { server: new WebSocketServer({ noServer: true }) } };
 }

package/dist/create-mock-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,IAAI,EAA0B,MAAM,MAAM,CAAA;AAIjE,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAwD5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2NtF"}
+{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,IAAI,EAA0B,MAAM,MAAM,CAAA;AAIjE,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAwD5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8NtF"}

package/dist/create-mock-server.js

@@ -1,3 +1,5 @@
+import { normalize } from '@scalar/json-magic/helpers/normalize';
+import { getRaw } from '@scalar/json-magic/magic-proxy';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { Hono } from 'hono';
 import { every } from 'hono/combine';
@@ -66,8 +68,14 @@ export async function createMockServer(configuration) {
             ...(operation ? { operation } : {}),
         }, 500);
     });
-    /** Dereferenced OpenAPI document */
-    const schema = await processOpenApiDocument(configuration?.document ?? configuration?.specification);
+    const input = configuration?.document ?? configuration?.specification;
+    const schema = await processOpenApiDocument(input, configuration?.origin);
+    const sourceDocument = typeof input === 'string' ? normalize(input) : input;
+    // Source locations need a bundled export so relative references remain usable outside the server.
+    const exportDocument = configuration?.origin ||
+        (typeof input === 'string' && (sourceDocument === null || typeof sourceDocument !== 'object'))
+        ? getRaw(schema)
+        : input;
     // Seed data from schemas with x-seed extension
     // This happens before routes are set up so data is available immediately
     const schemas = schema?.components?.schemas;
@@ -203,8 +211,8 @@ export async function createMockServer(configuration) {
         });
     });
     // OpenAPI JSON file
-    app.get('/openapi.json', (c) => respondWithOpenApiDocument(c, configuration?.document ?? configuration?.specification, 'json'));
+    app.get('/openapi.json', (c) => respondWithOpenApiDocument(c, exportDocument, 'json'));
     // OpenAPI YAML file
-    app.get('/openapi.yaml', (c) => respondWithOpenApiDocument(c, configuration?.document ?? configuration?.specification, 'yaml'));
+    app.get('/openapi.yaml', (c) => respondWithOpenApiDocument(c, exportDocument, 'yaml'));
     return app;
 }

package/dist/routes/mock-any-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAcnC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,YA4HjF"}
+{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAenC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,YA6IjF"}

package/dist/routes/mock-any-response.js

@@ -1,16 +1,17 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
 import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
-import { accepts } from 'hono/accepts';
 import { streamSSE } from 'hono/streaming';
 import { collectSseEvents, isEventStreamContentType } from '../utils/collect-sse-events.js';
 import { findPreferredResponseKey } from '../utils/find-preferred-response-key.js';
 import { generateResponseExample } from '../utils/generate-response-example.js';
+import { negotiateContentType } from '../utils/negotiate-content-type.js';
 import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { pathParameters } from '../utils/path-parameters.js';
 import { selectResponseExample } from '../utils/select-response-example.js';
 import { serializeResponseBody } from '../utils/serialize-response-body.js';
+import { getStreamingResponse, sendStreamingResponse } from '../utils/streaming-response.js';
 /**
  * Mock any response
  */
@@ -61,15 +62,17 @@ export function mockAnyResponse(c, operation) {
         return c.body(null);
     }
     // Content-Type
-    const acceptedContentType = accepts(c, {
-        header: 'Accept',
-        supports: supportedContentTypes,
-        default: supportedContentTypes.includes('application/json')
-            ? 'application/json'
-            : (supportedContentTypes[0] ?? 'text/plain;charset=UTF-8'),
-    });
+    const acceptedContentType = negotiateContentType(c, selectedResponse.content);
     c.header('Content-Type', acceptedContentType);
     const acceptedResponse = selectedResponse?.content?.[acceptedContentType];
+    const streamingResponse = getStreamingResponse(acceptedResponse, acceptedContentType, {
+        exampleName: prefer.example,
+        variables: pathParameters(c),
+    });
+    if (streamingResponse) {
+        c.status(statusCode);
+        return sendStreamingResponse(c, streamingResponse);
+    }
     const responseSchema = acceptedResponse?.schema ? getResolvedRefDeep(acceptedResponse.schema) : undefined;
     /** Generates the response body from the schema, or returns `undefined` when there is no schema. */
     const generateFromSchema = () => responseSchema ? generateResponseExample(responseSchema, pathParameters(c)) : undefined;
@@ -99,11 +102,23 @@ export function mockAnyResponse(c, operation) {
     // Body: a named/singular/first example if one is defined, otherwise generate
     // a value from the schema. `Prefer: example=<name>` picks a named example.
     const selectedExample = selectResponseExample(acceptedResponse, prefer.example);
-    const body = selectedExample
-        ? normalizeResponseBody(selectedExample.value, responseSchema)
-        : responseSchema
-            ? normalizeResponseBody(generateFromSchema(), responseSchema)
-            : null;
+    const body = (() => {
+        if (selectedExample) {
+            return normalizeResponseBody(selectedExample.value, responseSchema);
+        }
+        if (!responseSchema) {
+            return null;
+        }
+        const generated = generateFromSchema();
+        // Schema-level examples are authored values too, so retain their array normalization.
+        if (responseSchema.example !== undefined ||
+            (Array.isArray(responseSchema.examples) && responseSchema.examples.length)) {
+            return normalizeResponseBody(generated, responseSchema);
+        }
+        // The generator already chooses the value shape, including root union branches.
+        // Re-inferring it from sibling items would wrap a selected primitive in an array.
+        return generated;
+    })();
     c.status(statusCode);
     const serializedBody = serializeResponseBody(body, acceptedContentType, responseSchema);
     // `JSON.stringify` returns `undefined` for an `undefined` body, which is an empty response.

package/dist/routes/mock-handler-response.d.ts

@@ -1,9 +1,8 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 import type { Context } from 'hono';
-import type { StatusCode } from 'hono/utils/http-status';
 /**
  * Mock response using x-handler code.
  * Executes the handler and returns its result as the response.
  */
-export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject): Promise<(Response & import("hono").TypedResponse<null, StatusCode, "body">) | (Response & import("hono").TypedResponse<any, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject): Promise<Response>;
 //# sourceMappingURL=mock-handler-response.d.ts.map

package/dist/routes/mock-handler-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AA+HxD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,gMAyD3F"}
+{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AA4HnC;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,qBAoE3F"}

package/dist/routes/mock-handler-response.js

@@ -1,12 +1,13 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
-import { accepts } from 'hono/accepts';
 import { buildHandlerContext } from '../utils/build-handler-context.js';
 import { executeHandler } from '../utils/execute-handler.js';
 import { generateResponseExample } from '../utils/generate-response-example.js';
+import { negotiateContentType } from '../utils/negotiate-content-type.js';
 import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { pathParameters } from '../utils/path-parameters.js';
 import { selectResponseExample } from '../utils/select-response-example.js';
+import { getStreamingResponse, sendStreamingResponse } from '../utils/streaming-response.js';
 /**
  * Get example response from OpenAPI spec for a given status code.
  * Returns the example value if found, or null if not available.
@@ -30,13 +31,7 @@ function getExampleFromResponse(c, statusCode, responses, exampleName) {
         return null;
     }
     // Content-Type negotiation
-    const acceptedContentType = accepts(c, {
-        header: 'Accept',
-        supports: supportedContentTypes,
-        default: supportedContentTypes.includes('application/json')
-            ? 'application/json'
-            : (supportedContentTypes[0] ?? 'text/plain;charset=UTF-8'),
-    });
+    const acceptedContentType = negotiateContentType(c, response.content);
     const acceptedResponse = response.content?.[acceptedContentType];
     if (!acceptedResponse) {
         return null;
@@ -125,6 +120,16 @@ export async function mockHandlerResponse(c, operation) {
         if (statusCode === 204) {
             return c.body(null);
         }
+        const response = getResolvedRef(operation.responses?.[String(statusCode)] ?? operation.responses?.default);
+        const contentType = negotiateContentType(c, response?.content);
+        const streamingResponse = getStreamingResponse(response?.content?.[contentType], contentType, {
+            body: result ?? undefined,
+            exampleName: parsePreferHeader(c.req.header('Prefer')).example,
+            variables: pathParameters(c),
+        });
+        if (streamingResponse) {
+            return sendStreamingResponse(c, streamingResponse);
+        }
         // Set Content-Type header for other responses
         c.header('Content-Type', 'application/json');
         // Return the handler result as JSON

package/dist/types.d.ts

@@ -13,6 +13,8 @@ type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyo
 /** A sink for the informational log lines the mock servers print while starting up. */
 export type MockServerLogger = (line: string) => void;
 type BaseMockServerOptions = {
+    /** Source file path or URL used to resolve relative references in an already loaded document. */
+    origin?: string;
     /**
      * The OpenAPI document to use for mocking.
      * Can be a string (URL or file path) or an object.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,WAAW,+DAAgE,CAAA;AAExF,wBAAwB;AACxB,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,GACzF;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAA;AAET,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAErD,KAAK,qBAAqB,GAAG;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,WAAW,CAAC,eAAe,CAAA;KAAE,KAAK,IAAI,CAAA;IAExF;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,eAAe,GAAG,UAAU,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,WAAW,+DAAgE,CAAA;AAExF,wBAAwB;AACxB,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,GACzF;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAA;AAET,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAErD,KAAK,qBAAqB,GAAG;IAC3B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,WAAW,CAAC,eAAe,CAAA;KAAE,KAAK,IAAI,CAAA;IAExF;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,eAAe,GAAG,UAAU,CAAC,CAAA"}

package/dist/utils/build-handler-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAOnC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,GAAG,EAAE;QACH,IAAI,EAAE,GAAG,CAAA;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,sBAAsB,CAAA;CACjC,CAAA;AAqDD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CA4C/B"}
+{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAQnC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAGjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,GAAG,EAAE;QACH,IAAI,EAAE,GAAG,CAAA;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,sBAAsB,CAAA;CACjC,CAAA;AA6DD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CA4C/B"}

package/dist/utils/build-handler-context.js

@@ -4,8 +4,10 @@ import { accepts } from 'hono/accepts';
 import { store } from '../libs/store.js';
 import { generateResponseExample } from './generate-response-example.js';
 import { normalizeResponseBody } from './normalize-response-body.js';
+import { parsePreferHeader } from './parse-prefer-header.js';
 import { pathParameters } from './path-parameters.js';
 import { createStoreWrapper } from './store-wrapper.js';
+import { getStreamingResponse } from './streaming-response.js';
 /**
  * Get example response from OpenAPI spec for a given status code.
  * Returns the example value if found, or null if not available.
@@ -35,6 +37,13 @@ function getExampleFromResponse(c, statusCode, responses) {
     if (!acceptedResponse) {
         return null;
     }
+    const streamingResponse = getStreamingResponse(acceptedResponse, acceptedContentType, {
+        exampleName: parsePreferHeader(c.req.header('Prefer')).example,
+        variables: pathParameters(c),
+    });
+    if (streamingResponse) {
+        return streamingResponse.body;
+    }
     const responseSchema = acceptedResponse.schema ? getResolvedRefDeep(acceptedResponse.schema) : undefined;
     // Extract example from example property or generate from schema
     return acceptedResponse.example !== undefined

package/dist/utils/get-oauth2-metadata.d.ts

@@ -3,6 +3,7 @@ import type { OpenAPIV3_2 } from '@scalar/openapi-types';
 type OAuth2Metadata = {
     issuer: string;
     authorization_endpoint?: string;
+    device_authorization_endpoint?: string;
     token_endpoint?: string;
     response_types_supported: string[];
     grant_types_supported: string[];

package/dist/utils/get-oauth2-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-oauth2-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/get-oauth2-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,mEAAmE;AACnE,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wBAAwB,EAAE,MAAM,EAAE,CAAA;IAClC,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,QAAQ,MAAM,KAAG,cAqBpG,CAAA"}
+{"version":3,"file":"get-oauth2-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/get-oauth2-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,mEAAmE;AACnE,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,6BAA6B,CAAC,EAAE,MAAM,CAAA;IACtC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wBAAwB,EAAE,MAAM,EAAE,CAAA;IAClC,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,QAAQ,MAAM,KAAG,cA0BpG,CAAA"}

package/dist/utils/get-oauth2-metadata.js

@@ -2,16 +2,20 @@ import { getPathFromUrl } from './get-open-auth-token-urls.js';
 /** Advertises local mock endpoints instead of sending clients to the real authorization server. */
 export const getOAuth2Metadata = (flows, origin) => {
     const authorizationFlow = flows?.authorizationCode ?? flows?.implicit;
-    const tokenFlow = flows?.authorizationCode ?? flows?.clientCredentials ?? flows?.password;
+    const tokenFlow = flows?.authorizationCode ?? flows?.clientCredentials ?? flows?.password ?? flows?.deviceAuthorization;
     const localUrl = (url) => new URL(getPathFromUrl(url), origin).href;
     const supportedFlows = [
         { flow: flows?.authorizationCode, grant: 'authorization_code', response: 'code' },
         { flow: flows?.implicit, grant: 'implicit', response: 'token' },
         { flow: flows?.clientCredentials, grant: 'client_credentials' },
         { flow: flows?.password, grant: 'password' },
+        { flow: flows?.deviceAuthorization, grant: 'urn:ietf:params:oauth:grant-type:device_code' },
     ].filter(({ flow }) => flow);
     return {
         issuer: origin,
+        ...(flows?.deviceAuthorization
+            ? { device_authorization_endpoint: localUrl(flows.deviceAuthorization.deviceAuthorizationUrl || '/oauth/device') }
+            : {}),
         ...(authorizationFlow
             ? { authorization_endpoint: localUrl(authorizationFlow.authorizationUrl ?? '/oauth/authorize') }
             : {}),

package/dist/utils/get-open-auth-token-urls.d.ts

@@ -1,7 +1,7 @@
 import type { OpenAPI } from '@scalar/openapi-types';
 /**
- * Extract path from URL. Metadata is fetched at its exact declared URL, so its routes
- * preserve trailing slashes instead of using the token-route normalization.
+ * Extract path from URL. Metadata routes preserve trailing slashes because discovery
+ * fetches the exact declared URL, unlike normalized token routes.
  */
 export declare function getPathFromUrl(url: string, { preserveTrailingSlash }?: {
     preserveTrailingSlash?: boolean;

package/dist/utils/get-open-auth-token-urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAG5E;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,EAAE,qBAA6B,EAAE,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1E,MAAM,CAYR;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAuCxE"}
+{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAuC,MAAM,uBAAuB,CAAA;AAGzF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,EAAE,qBAA6B,EAAE,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1E,MAAM,CAYR;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAyCxE"}

package/dist/utils/get-open-auth-token-urls.js

@@ -1,7 +1,7 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 /**
- * Extract path from URL. Metadata is fetched at its exact declared URL, so its routes
- * preserve trailing slashes instead of using the token-route normalization.
+ * Extract path from URL. Metadata routes preserve trailing slashes because discovery
+ * fetches the exact declared URL, unlike normalized token routes.
  */
 export function getPathFromUrl(url, { preserveTrailingSlash = false } = {}) {
     try {
@@ -41,13 +41,15 @@ export function getOpenAuthTokenUrls(schema) {
         if (!scheme || !isOAuth2Scheme(scheme)) {
             continue;
         }
-        const flows = scheme.flows; // Type assertion no longer needed
+        const flows = scheme.flows;
         // Helper to safely add valid OAuth URLs
         const addOAuthUrl = (url) => {
             if (url && isValidOAuthUrl(url)) {
                 oauthUrls.add(getPathFromUrl(url));
             }
         };
+        addOAuthUrl(flows?.deviceAuthorization?.tokenUrl);
+        addOAuthUrl(flows?.deviceAuthorization?.refreshUrl);
         addOAuthUrl(flows?.password?.tokenUrl);
         addOAuthUrl(flows?.password?.refreshUrl);
         addOAuthUrl(flows?.clientCredentials?.tokenUrl);

package/dist/utils/handle-authentication.d.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { OpenAPIV3_1, OpenAPIV3_2 } from '@scalar/openapi-types';
 import type { Context } from 'hono';
 /**
  * Handles authentication for incoming requests based on the OpenAPI document.
@@ -8,5 +8,5 @@ import type { Context } from 'hono';
  * only when *every* scheme it lists is satisfied. An empty requirement object (`{}`)
  * means authentication is optional and always passes.
  */
-export declare function handleAuthentication(schema?: OpenAPIV3_1.Document, operation?: OpenAPIV3_1.OperationObject): (c: Context, next: () => Promise<void>) => Promise<Response | void>;
+export declare function handleAuthentication(schema?: OpenAPIV3_1.Document | OpenAPIV3_2.Document, operation?: OpenAPIV3_2.OperationObject): (c: Context, next: () => Promise<void>) => Promise<Response | void>;
 //# sourceMappingURL=handle-authentication.d.ts.map

package/dist/utils/handle-authentication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAEnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAiInC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAC3F,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA4D/E"}
+{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,WAAW,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAEhF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAiInC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,EACpD,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAEzB,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA4D/E"}

package/dist/utils/log-authentication-instructions.d.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
 import type { MockServerLogger } from '../types.js';
 /**
  * Log authentication instructions for different security schemes.
@@ -7,5 +7,5 @@ import type { MockServerLogger } from '../types.js';
  * security schemes the mock server cannot handle are printed unconditionally, so a silenced startup
  * still surfaces schemes that will not work.
  */
-export declare function logAuthenticationInstructions(securitySchemes: Record<string, OpenAPIV3_1.SecuritySchemeObject>, log?: MockServerLogger): void;
+export declare function logAuthenticationInstructions(securitySchemes: Record<string, OpenAPIV3_2.SecuritySchemeObject>, log?: MockServerLogger): void;
 //# sourceMappingURL=log-authentication-instructions.d.ts.map

package/dist/utils/log-authentication-instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QAiIpD"}
+{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QA4IpD"}

package/dist/utils/log-authentication-instructions.js

@@ -76,6 +76,13 @@ export function logAuthenticationInstructions(securitySchemes, log = (line) => c
                 if (scheme.flows) {
                     Object.keys(scheme.flows).forEach((flow) => {
                         switch (flow) {
+                            case 'deviceAuthorization':
+                                log('✅ OAuth 2.0 Device Authorization Flow');
+                                log(`   POST ${getPathFromUrl(scheme.flows?.deviceAuthorization?.deviceAuthorizationUrl || '/oauth/device')}`);
+                                log('   Send client_id and scope as form data, open verification_uri, and enter user_code.');
+                                log(`   Poll ${getPathFromUrl(scheme.flows?.deviceAuthorization?.tokenUrl || '/oauth/token')} with grant_type=urn:ietf:params:oauth:grant-type:device_code and device_code.`);
+                                log('');
+                                break;
                             case 'implicit':
                                 log('✅ OAuth 2.0 Implicit Flow');
                                 log('   Use the following URL to initiate the OAuth 2.0 Implicit Flow:');

package/dist/utils/negotiate-content-type.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from 'hono';
+/** Use the same response media-type preference for generated and custom-handler responses. */
+export declare const negotiateContentType: (c: Context, content: Record<string, unknown> | undefined) => string;
+//# sourceMappingURL=negotiate-content-type.d.ts.map

package/dist/utils/negotiate-content-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate-content-type.d.ts","sourceRoot":"","sources":["../../src/utils/negotiate-content-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAGnC,8FAA8F;AAC9F,eAAO,MAAM,oBAAoB,GAAI,GAAG,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,MAS/F,CAAA"}

package/dist/utils/negotiate-content-type.js

@@ -0,0 +1,12 @@
+import { accepts } from 'hono/accepts';
+/** Use the same response media-type preference for generated and custom-handler responses. */
+export const negotiateContentType = (c, content) => {
+    const supportedContentTypes = Object.keys(content ?? {});
+    return accepts(c, {
+        header: 'Accept',
+        supports: supportedContentTypes,
+        default: supportedContentTypes.includes('application/json')
+            ? 'application/json'
+            : (supportedContentTypes[0] ?? 'text/plain;charset=UTF-8'),
+    });
+};

package/dist/utils/process-openapi-document.d.ts

@@ -1,6 +1,6 @@
-import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { OpenAPIV3_1, OpenAPIV3_2 } from '@scalar/openapi-types';
 /**
- * Processes an OpenAPI document by bundling external references, upgrading to OpenAPI 3.1,
+ * Processes an OpenAPI document by bundling external references, upgrading compatible input to OpenAPI 3.2,
  * and wrapping it so internal references stay intact but resolve lazily.
  *
  * Unlike a full dereference, the returned document keeps `$ref` nodes in place. Consumers
@@ -8,9 +8,12 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
  * `$ref-value` exposed by the magic proxy. This avoids eagerly flattening (and duplicating)
  * the whole document up front.
  *
+ * Compatibility failures retain the OpenAPI 3.1 document and its version, without applying partial migrations.
+ *
  * @param document - The OpenAPI document to process. Can be a string (URL/path) or an object.
- * @returns A promise that resolves to the OpenAPI 3.1 document with lazily resolvable references.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
+ * @returns A promise that resolves to the document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export declare function processOpenApiDocument(document: string | Record<string, any> | undefined): Promise<OpenAPIV3_1.Document>;
+export declare function processOpenApiDocument(document: string | Record<string, any> | undefined, origin?: string): Promise<OpenAPIV3_1.Document | OpenAPIV3_2.Document>;
 //# sourceMappingURL=process-openapi-document.d.ts.map

package/dist/utils/process-openapi-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAsD/B"}
+{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIrE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAClD,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAkEtD"}

package/dist/utils/process-openapi-document.js

@@ -3,10 +3,12 @@ import { cwd } from 'node:process';
 import { bundle } from '@scalar/json-magic/bundle';
 import { fetchUrls, parseJson, parseYaml, readFiles } from '@scalar/json-magic/bundle/plugins/node';
 import { isFilePath } from '@scalar/json-magic/helpers/is-file-path';
+import { isHttpUrl } from '@scalar/json-magic/helpers/is-http-url';
 import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
 import { upgrade } from '@scalar/openapi-upgrader';
+import { openApiDocument, resolveOpenApiDocument } from '@scalar/workspace-store/plugins/bundler';
 /**
- * Processes an OpenAPI document by bundling external references, upgrading to OpenAPI 3.1,
+ * Processes an OpenAPI document by bundling external references, upgrading compatible input to OpenAPI 3.2,
  * and wrapping it so internal references stay intact but resolve lazily.
  *
  * Unlike a full dereference, the returned document keeps `$ref` nodes in place. Consumers
@@ -14,16 +16,19 @@ import { upgrade } from '@scalar/openapi-upgrader';
  * `$ref-value` exposed by the magic proxy. This avoids eagerly flattening (and duplicating)
  * the whole document up front.
  *
+ * Compatibility failures retain the OpenAPI 3.1 document and its version, without applying partial migrations.
+ *
  * @param document - The OpenAPI document to process. Can be a string (URL/path) or an object.
- * @returns A promise that resolves to the OpenAPI 3.1 document with lazily resolvable references.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
+ * @returns A promise that resolves to the document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export async function processOpenApiDocument(document) {
+export async function processOpenApiDocument(document, origin) {
     // Handle empty/undefined input gracefully
     if (!document || (typeof document === 'object' && Object.keys(document).length === 0)) {
-        // Return a minimal valid OpenAPI 3.1 document
+        // Return a minimal valid OpenAPI 3.2 document
         return {
-            openapi: '3.1.0',
+            openapi: '3.2.0',
             info: {
                 title: 'Mock API',
                 version: '1.0.0',
@@ -35,12 +40,20 @@ export async function processOpenApiDocument(document) {
     // Confine local file `$ref`s to the document's own directory (or the working directory when the
     // document is an object or inline string), and refuse to fetch private or internal addresses.
     // Without these guards a `$ref` could read arbitrary local files or reach internal services.
-    const basePath = typeof document === 'string' && isFilePath(document) ? path.dirname(path.resolve(document)) : cwd();
+    const source = origin ?? document;
+    const basePath = typeof source === 'string' && isFilePath(source) ? path.dirname(path.resolve(source)) : cwd();
     try {
         // Bundle external references with Node.js plugins
         // Include parseJson and parseYaml to handle string inputs
         bundled = await bundle(document, {
-            plugins: [parseJson(), parseYaml(), readFiles({ basePath }), fetchUrls({ blockPrivateNetworks: true })],
+            origin,
+            plugins: [
+                openApiDocument(),
+                parseJson(),
+                parseYaml(),
+                readFiles({ basePath }),
+                fetchUrls({ blockPrivateNetworks: true }),
+            ],
             treeShake: false,
         });
     }
@@ -50,18 +63,20 @@ export async function processOpenApiDocument(document) {
     if (!bundled || typeof bundled !== 'object') {
         throw new Error('Bundled document is invalid: expected an object');
     }
+    // Upgrading must not activate a $self field authored in an older OpenAPI version.
+    const retrievalUri = origin ?? (typeof document === 'string' && (isFilePath(document) || isHttpUrl(document)) ? document : '/');
+    const documentUri = resolveOpenApiDocument(bundled, retrievalUri)?.baseUri;
     let upgraded;
     try {
-        // Upgrade to OpenAPI 3.1
-        upgraded = upgrade(bundled, '3.1');
+        upgraded = upgrade(bundled, '3.2', { onIncompatible: 'collect' }).document;
     }
     catch (error) {
-        throw new Error(`Failed to upgrade OpenAPI document to 3.1: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Failed to upgrade OpenAPI document to 3.2: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (!upgraded) {
         throw new Error('Upgraded document is invalid: upgrade returned null or undefined');
     }
     // Wrap the document in a magic proxy so internal references resolve lazily via `$ref-value`.
     // External references were already pulled inline by `bundle` above, so only local `$ref`s remain.
-    return createMagicProxy(upgraded);
+    return createMagicProxy(upgraded, { documentUri });
 }

package/dist/utils/select-response-example.d.ts

@@ -16,7 +16,9 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
  * caller still gets a schema-generated body. An unknown `exampleName` simply
  * falls through to the later steps.
  */
-export declare const selectResponseExample: (mediaType: OpenAPIV3_1.MediaTypeObject | undefined, exampleName?: string) => {
+export declare const selectResponseExample: <T extends Pick<OpenAPIV3_1.MediaTypeObject, "example" | "examples"> & {
+    schema?: unknown;
+}>(mediaType: T | undefined, exampleName?: string) => {
     value: unknown;
 } | undefined;
 //# sourceMappingURL=select-response-example.d.ts.map

package/dist/utils/select-response-example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/select-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,WAAW,CAAC,eAAe,GAAG,SAAS,EAClD,cAAc,MAAM,KACnB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAoCvB,CAAA"}
+{"version":3,"file":"select-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/select-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,SAAS,GAAG,UAAU,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAE1F,WAAW,CAAC,GAAG,SAAS,EACxB,cAAc,MAAM,KACnB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAoCvB,CAAA"}

package/dist/utils/set-up-authentication-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QA+G7E"}
+{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAShC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QAiH7E"}

package/dist/utils/set-up-authentication-routes.js

@@ -3,11 +3,13 @@ import { respondWithAuthorizePage } from '../routes/respond-with-authorize-page.
 import { respondWithToken } from '../routes/respond-with-token.js';
 import { getOAuth2Metadata } from './get-oauth2-metadata.js';
 import { getOpenAuthTokenUrls, getPathFromUrl } from './get-open-auth-token-urls.js';
+import { setUpDeviceAuthorization } from './set-up-device-authorization.js';
 /**
  * Helper function to set up authentication routes for OAuth 2.0 flows
  */
 export function setUpAuthenticationRoutes(app, schema) {
     const securitySchemes = schema?.components?.securitySchemes || {};
+    setUpDeviceAuthorization(app, schema);
     // Set up authentication routes for OAuth 2.0 flows
     getOpenAuthTokenUrls(schema).forEach((tokenUrl) => {
         app.post(tokenUrl, (c) => {

package/dist/utils/set-up-device-authorization.d.ts

@@ -0,0 +1,5 @@
+import type { OpenAPI } from '@scalar/openapi-types';
+import type { Hono } from 'hono';
+/** Registers a local RFC8628 approval flow before the permissive mock token handlers. */
+export declare const setUpDeviceAuthorization: (app: Hono, document?: OpenAPI.Document) => void;
+//# sourceMappingURL=set-up-device-authorization.d.ts.map

package/dist/utils/set-up-device-authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-up-device-authorization.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-device-authorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,uBAAuB,CAAA;AAEjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AA0FhC,yFAAyF;AACzF,eAAO,MAAM,wBAAwB,GAAI,KAAK,IAAI,EAAE,WAAW,OAAO,CAAC,QAAQ,KAAG,IAsJjF,CAAA"}

package/dist/utils/set-up-device-authorization.js

@@ -0,0 +1,192 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { html } from 'hono/html';
+import { getPathFromUrl } from './get-open-auth-token-urls.js';
+/** Both endpoints compare the decoded client ID, regardless of credential location. */
+const getClientId = (clientId, authorization) => {
+    if (typeof clientId === 'string') {
+        return clientId;
+    }
+    if (!authorization?.startsWith('Basic ')) {
+        return '';
+    }
+    const credentials = Buffer.from(authorization.slice(6), 'base64').toString();
+    const separator = credentials.indexOf(':');
+    if (separator === -1) {
+        return '';
+    }
+    try {
+        return decodeURIComponent(credentials.slice(0, separator).replace(/\+/g, ' '));
+    }
+    catch {
+        return '';
+    }
+};
+/** Keeps the device form and its outcomes consistent with the mock OAuth authorization page. */
+const renderDevicePage = (title, heading, content) => html `
+  <!doctype html>
+  <html lang="en">
+    <head>
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width, initial-scale=1">
+      <title>${heading}</title>
+      <style>
+        * { box-sizing: border-box; }
+        body { margin: 0; min-height: 100svh; display: grid; place-items: center; padding: 32px 16px; background: #f3f4f6; color: #4b5563; font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; line-height: 1.5; }
+        main { width: 100%; max-width: 448px; }
+        .brand { display: flex; align-items: center; justify-content: center; gap: 8px; margin-bottom: 20px; color: #111827; font-size: 18px; font-weight: 500; }
+        .brand img { width: 24px; }
+        .brand span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+        .card { padding: 4px; border-radius: 8px; background: #f9fafb; box-shadow: 0 1px 3px #0000001a, 0 1px 2px #0000001a; }
+        h1 { margin: 0; padding: 8px 24px 12px; color: #1f2937; font-size: 16px; font-weight: 500; }
+        .content { padding: 24px; border-radius: 4px; background: white; }
+        p { margin: 0 0 20px; }
+        .content > p:last-child { margin-bottom: 0; }
+        label { display: block; margin-bottom: 8px; color: #374151; font-weight: 500; }
+        input { width: 100%; min-width: 0; padding: 12px; border: 1px solid #d1d5db; border-radius: 4px; background: #f9fafb; color: #111827; font: 18px ui-monospace, monospace; letter-spacing: .15em; }
+        .actions { display: flex; flex-direction: row-reverse; justify-content: space-between; gap: 12px; margin-top: 24px; }
+        button { padding: 8px 24px; border: 1px solid #e5e7eb; border-radius: 4px; background: white; color: #4b5563; font: inherit; cursor: pointer; }
+        button:hover { background: #f3f4f6; }
+        button[value="approve"] { border-color: black; background: black; color: white; }
+        button[value="approve"]:hover { background: #1f2937; }
+        :focus-visible { outline: 2px solid #2563eb; outline-offset: 3px; }
+        footer { margin-top: 20px; color: #6b7280; text-align: center; font-size: 12px; }
+        a { color: #4b5563; text-underline-offset: 2px; }
+      </style>
+    </head>
+    <body>
+      <main>
+        <div class="brand">
+          <img src="https://cdn.scalar.com/images/logo-dark.svg" alt="Scalar">
+          <span>${title}</span>
+        </div>
+        <section class="card" aria-labelledby="page-title">
+          <h1 id="page-title">${heading}</h1>
+          <div class="content">${content}</div>
+        </section>
+        <footer>
+          This authorization page is provided by the
+          <a href="https://scalar.com/tools/mock-server/getting-started" target="_blank" rel="noopener noreferrer">Scalar Mock Server</a>.
+        </footer>
+      </main>
+    </body>
+  </html>
+`;
+/** Registers a local RFC8628 approval flow before the permissive mock token handlers. */
+export const setUpDeviceAuthorization = (app, document) => {
+    const title = document?.info?.title ?? '';
+    const grants = new Map();
+    const devicePaths = new Map();
+    const securitySchemes = document?.components?.securitySchemes ?? {};
+    for (const rawScheme of Object.values(securitySchemes)) {
+        const scheme = getResolvedRef(rawScheme);
+        if (scheme?.type === 'oauth2' && scheme.flows?.deviceAuthorization) {
+            const flow = scheme.flows.deviceAuthorization;
+            devicePaths.set(getPathFromUrl(flow.deviceAuthorizationUrl || '/oauth/device'), getPathFromUrl(flow.tokenUrl || '/oauth/token'));
+        }
+    }
+    const tokenPaths = new Set(devicePaths.values());
+    const removeExpired = () => {
+        for (const [code, grant] of grants) {
+            if (grant.expiresAt <= Date.now()) {
+                grants.delete(code);
+            }
+        }
+    };
+    for (const [devicePath, tokenPath] of devicePaths) {
+        const verificationPath = `${devicePath.replace(/\/$/, '')}/verify`;
+        app.post(devicePath, async (c) => {
+            const body = await c.req.parseBody();
+            const clientId = getClientId(body.client_id, c.req.header('Authorization'));
+            c.header('Cache-Control', 'no-store');
+            c.header('Pragma', 'no-cache');
+            if (!clientId) {
+                return c.json({ error: 'invalid_request', error_description: 'Missing client_id' }, 400);
+            }
+            removeExpired();
+            const deviceCode = crypto.randomUUID();
+            const userCode = crypto.randomUUID().slice(0, 8).toUpperCase();
+            grants.set(deviceCode, {
+                clientId,
+                userCode,
+                tokenPath,
+                expiresAt: Date.now() + 600000,
+                nextPoll: 0,
+                interval: 5000,
+                status: 'pending',
+            });
+            const verificationUri = new URL(verificationPath, c.req.url).href;
+            return c.json({
+                device_code: deviceCode,
+                user_code: userCode,
+                verification_uri: verificationUri,
+                verification_uri_complete: `${verificationUri}?user_code=${userCode}`,
+                expires_in: 600,
+                interval: 5,
+            });
+        });
+        app.get(verificationPath, (c) => c.html(renderDevicePage(title, 'Authorize device', html `
+          <p>Enter the code shown in your API client to approve this mock authorization request.</p>
+          <form method="post">
+            <label for="user-code">Device code</label>
+            <input id="user-code" name="user_code" required value="${c.req.query('user_code') ?? ''}" autocomplete="one-time-code" spellcheck="false" autocapitalize="characters">
+            <div class="actions">
+              <button name="decision" value="approve">Approve</button>
+              <button name="decision" value="deny">Deny</button>
+            </div>
+          </form>
+        `)));
+        app.post(verificationPath, async (c) => {
+            const body = await c.req.parseBody();
+            const grant = [...grants.values()].find((entry) => entry.userCode === String(body.user_code).trim().toUpperCase() && entry.tokenPath === tokenPath);
+            if (!grant || grant.expiresAt <= Date.now() || grant.status !== 'pending') {
+                return c.html(renderDevicePage(title, 'Invalid or expired device code', html `<p>Start a new authorization request in your API client and enter the new device code.</p>`), 400);
+            }
+            if (body.decision !== 'approve' && body.decision !== 'deny') {
+                return c.html(renderDevicePage(title, 'Choose Approve or Deny', html `<p>Return to the device authorization form and choose whether to approve or deny the request.</p>`), 400);
+            }
+            grant.status = body.decision === 'approve' ? 'approved' : 'denied';
+            return c.html(renderDevicePage(title, grant.status === 'approved' ? 'Device authorized' : 'Device authorization denied', grant.status === 'approved'
+                ? html `<p>Device authorized. You can return to your API client.</p>`
+                : html `<p>Device authorization denied. You can return to your API client to start a new request.</p>`));
+        });
+    }
+    for (const tokenPath of tokenPaths) {
+        app.post(tokenPath, async (c, next) => {
+            const body = await c.req.parseBody();
+            if (body.grant_type !== 'urn:ietf:params:oauth:grant-type:device_code') {
+                return next();
+            }
+            c.header('Cache-Control', 'no-store');
+            c.header('Pragma', 'no-cache');
+            const clientId = getClientId(body.client_id, c.req.header('Authorization'));
+            const code = String(body.device_code ?? '');
+            const grant = grants.get(code);
+            if (!grant || grant.tokenPath !== tokenPath || grant.clientId !== clientId) {
+                return c.json({ error: 'invalid_grant' }, 400);
+            }
+            if (grant.expiresAt <= Date.now()) {
+                grants.delete(code);
+                return c.json({ error: 'expired_token' }, 400);
+            }
+            if (Date.now() < grant.nextPoll) {
+                grant.interval += 5000;
+                grant.nextPoll = Date.now() + grant.interval;
+                return c.json({ error: 'slow_down' }, 400);
+            }
+            grant.nextPoll = Date.now() + grant.interval;
+            if (grant.status === 'pending') {
+                return c.json({ error: 'authorization_pending' }, 400);
+            }
+            grants.delete(code);
+            if (grant.status === 'denied') {
+                return c.json({ error: 'access_denied' }, 400);
+            }
+            return c.json({
+                access_token: 'super-secret-access-token',
+                token_type: 'Bearer',
+                expires_in: 3600,
+                refresh_token: 'example-refresh-token',
+            });
+        });
+    }
+};

package/dist/utils/streaming-response.d.ts

@@ -0,0 +1,24 @@
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
+import type { Context } from 'hono';
+/** A finite mock stream, with its data-model value available to custom handlers. */
+type StreamingResponse = {
+    body: unknown;
+    chunks: string[];
+    contentType: string;
+};
+/**
+ * Build a finite response for media types with an OpenAPI 3.2 itemSchema.
+ * Explicit examples describe the whole response. Generated item-only streams contain three items,
+ * keeping array-valued items intact. A complete schema controls the sequence when also present.
+ */
+export declare const getStreamingResponse: (mediaType: (Omit<OpenAPIV3_2.MediaTypeObject, "itemSchema"> & {
+    itemSchema?: OpenAPIV3_2.MediaTypeObject["itemSchema"] | boolean;
+}) | undefined, contentType: string, options?: {
+    exampleName?: string;
+    variables?: Record<string, unknown>;
+    body?: unknown;
+}) => StreamingResponse | undefined;
+/** Write each mocked item separately and close the stream when the finite sequence is exhausted. */
+export declare const sendStreamingResponse: (c: Context, response: StreamingResponse) => Response;
+export {};
+//# sourceMappingURL=streaming-response.d.ts.map

package/dist/utils/streaming-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-response.d.ts","sourceRoot":"","sources":["../../src/utils/streaming-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAMnC,oFAAoF;AACpF,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,WACI,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,YAAY,CAAC,GAAG;IACjD,UAAU,CAAC,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,GAAG,OAAO,CAAA;CACjE,CAAC,GACF,SAAS,EACb,aAAa,MAAM,EACnB,UAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,KAC1F,iBAAiB,GAAG,SA8CtB,CAAA;AAED,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,GAAI,GAAG,OAAO,EAAE,UAAU,iBAAiB,KAAG,QAY/E,CAAA"}

package/dist/utils/streaming-response.js

@@ -0,0 +1,65 @@
+import { getStreamFormat } from '@scalar/helpers/http/is-streaming-content-type';
+import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
+import { serializeStreamExample } from '@scalar/workspace-store/helpers/serialize-stream-example';
+import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
+import { SchemaObjectSchema } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { stream } from 'hono/streaming';
+import { generateResponseExample } from './generate-response-example.js';
+import { selectResponseExample } from './select-response-example.js';
+/**
+ * Build a finite response for media types with an OpenAPI 3.2 itemSchema.
+ * Explicit examples describe the whole response. Generated item-only streams contain three items,
+ * keeping array-valued items intact. A complete schema controls the sequence when also present.
+ */
+export const getStreamingResponse = (mediaType, contentType, options = {}) => {
+    if (mediaType?.itemSchema === undefined) {
+        return undefined;
+    }
+    const format = getStreamFormat(contentType);
+    if (format === undefined || format === 'multipart') {
+        return undefined;
+    }
+    const example = options.body !== undefined ? { value: options.body } : selectResponseExample(mediaType, options.exampleName);
+    if (example && typeof example.value === 'string') {
+        return { body: example.value, chunks: [example.value], contentType };
+    }
+    const itemSchema = typeof mediaType.itemSchema === 'boolean' ? mediaType.itemSchema : getResolvedRefDeep(mediaType.itemSchema);
+    const completeSchema = typeof mediaType.schema === 'boolean' ? mediaType.schema : getResolvedRefDeep(mediaType.schema);
+    const generateBody = () => {
+        if (itemSchema === false || completeSchema === false) {
+            return [];
+        }
+        if (completeSchema === undefined) {
+            return Array.from({ length: 3 }, () => itemSchema === true
+                ? null
+                : generateResponseExample(coerceValue(SchemaObjectSchema, itemSchema), options.variables));
+        }
+        if (typeof completeSchema === 'object' && 'type' in completeSchema && completeSchema.type === 'array') {
+            return generateResponseExample(coerceValue(SchemaObjectSchema, {
+                ...completeSchema,
+                items: ('items' in completeSchema ? completeSchema.items : undefined) ?? itemSchema,
+            }), options.variables);
+        }
+        return generateResponseExample(coerceValue(SchemaObjectSchema, completeSchema), options.variables);
+    };
+    const body = example ? example.value : generateBody();
+    const items = body === undefined ? [] : Array.isArray(body) ? body : [body];
+    const chunks = items
+        .filter((item) => item !== undefined)
+        .map((item) => serializeStreamExample(item, contentType, true) ?? '');
+    return { body, chunks, contentType };
+};
+/** Write each mocked item separately and close the stream when the finite sequence is exhausted. */
+export const sendStreamingResponse = (c, response) => {
+    c.header('Content-Type', response.contentType);
+    c.header('Cache-Control', 'no-cache');
+    c.header('X-Accel-Buffering', 'no');
+    return stream(c, async (writer) => {
+        for (const chunk of response.chunks) {
+            if (writer.aborted) {
+                break;
+            }
+            await writer.write(chunk);
+        }
+    });
+};

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.14.4",
+  "version": "0.15.0",
   "engines": {
     "node": ">=22"
   },
@@ -52,21 +52,24 @@
   },
   "dependencies": {
     "@faker-js/faker": "10.6.0",
-    "@hono/node-ws": "^1.2.0",
-    "@scalar/helpers": "0.12.0",
-    "@scalar/json-magic": "0.14.0",
-    "@scalar/openapi-types": "0.9.6",
-    "@scalar/openapi-upgrader": "0.2.17",
-    "@scalar/types": "0.20.1",
-    "@scalar/workspace-store": "0.64.0",
+    "@hono/node-server": "^2.1.1",
+    "@scalar/helpers": "0.13.0",
+    "@scalar/json-magic": "0.15.0",
+    "@scalar/openapi-types": "0.9.7",
+    "@scalar/openapi-upgrader": "0.3.0",
+    "@scalar/types": "0.21.0",
+    "@scalar/workspace-store": "0.65.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "hono": "^4.13.7",
+    "hono": "^4.13.8",
     "quickjs-emscripten": "0.32.0",
+    "ws": "8.21.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",
+    "@types/ws": "8.18.1",
+    "undici": "7.24.4",
     "vite": "8.1.5"
   },
   "scripts": {