schema-components 1.19.0 → 1.21.0

package/dist/openapi/ApiCallbacks.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
+import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
 import { CallbackInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiLinks.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
+import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
 import { LinkInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiResponseHeaders.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
+import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
 import { HeaderInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiSecurity.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
+import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
 import { SecurityRequirement, SecurityScheme } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiSecurity.mjs

@@ -1,5 +1,46 @@
+import { isObject } from "../core/guards.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/openapi/ApiSecurity.tsx
+/**
+* The four OAuth 2 flow keys defined by OpenAPI 3.x. Listed in the
+* canonical specification order so renders are deterministic.
+*/
+const OAUTH_FLOW_KEYS = [
+	"implicit",
+	"password",
+	"clientCredentials",
+	"authorizationCode"
+];
+function readString(source, key) {
+	const value = source[key];
+	return typeof value === "string" ? value : void 0;
+}
+function readScopes(source) {
+	const scopes = source.scopes;
+	const result = /* @__PURE__ */ new Map();
+	if (!isObject(scopes)) return result;
+	for (const [name, description] of Object.entries(scopes)) {
+		if (typeof description !== "string") continue;
+		result.set(name, description);
+	}
+	return result;
+}
+function extractFlows(flows) {
+	if (flows === void 0) return [];
+	const result = [];
+	for (const name of OAUTH_FLOW_KEYS) {
+		const flow = flows[name];
+		if (!isObject(flow)) continue;
+		result.push({
+			name,
+			authorizationUrl: readString(flow, "authorizationUrl"),
+			tokenUrl: readString(flow, "tokenUrl"),
+			refreshUrl: readString(flow, "refreshUrl"),
+			scopes: readScopes(flow)
+		});
+	}
+	return result;
+}
 function ApiSecurity({ requirements, schemes }) {
 	if (requirements.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
@@ -13,13 +54,7 @@ function ApiSecurity({ requirements, schemes }) {
 						"data-security-name": true,
 						children: req.name
 					}),
-					scheme !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [scheme.type !== void 0 && /* @__PURE__ */ jsx("span", {
-						"data-security-type": true,
-						children: scheme.type
-					}), scheme.description && /* @__PURE__ */ jsx("span", {
-						"data-security-description": true,
-						children: scheme.description
-					})] }),
+					scheme !== void 0 && /* @__PURE__ */ jsx(SchemeDetails, { scheme }),
 					req.scopes.length > 0 && /* @__PURE__ */ jsx("span", {
 						"data-security-scopes": true,
 						children: req.scopes.join(", ")
@@ -29,5 +64,76 @@ function ApiSecurity({ requirements, schemes }) {
 		})]
 	});
 }
+function SchemeDetails({ scheme }) {
+	const flows = extractFlows(scheme.flows);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		scheme.type !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-type": true,
+			children: scheme.type
+		}),
+		scheme.description !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-description": true,
+			children: scheme.description
+		}),
+		scheme.scheme !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-http-scheme": true,
+			children: scheme.scheme
+		}),
+		scheme.bearerFormat !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-bearer-format": true,
+			children: scheme.bearerFormat
+		}),
+		scheme.name !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-apikey-name": true,
+			children: scheme.name
+		}),
+		scheme.location !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-apikey-in": true,
+			children: scheme.location
+		}),
+		scheme.openIdConnectUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+			"data-security-openid-url": true,
+			href: scheme.openIdConnectUrl,
+			children: scheme.openIdConnectUrl
+		}),
+		flows.length > 0 && /* @__PURE__ */ jsx("section", {
+			"data-security-flows": true,
+			children: flows.map((flow) => /* @__PURE__ */ jsx(FlowDetails, { flow }, flow.name))
+		})
+	] });
+}
+function FlowDetails({ flow }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-security-flow": flow.name,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-security-flow-name": true,
+				children: flow.name
+			}),
+			flow.authorizationUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+				"data-security-flow-authorization-url": true,
+				href: flow.authorizationUrl,
+				children: flow.authorizationUrl
+			}),
+			flow.tokenUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+				"data-security-flow-token-url": true,
+				href: flow.tokenUrl,
+				children: flow.tokenUrl
+			}),
+			flow.refreshUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+				"data-security-flow-refresh-url": true,
+				href: flow.refreshUrl,
+				children: flow.refreshUrl
+			}),
+			flow.scopes.size > 0 && /* @__PURE__ */ jsx("dl", {
+				"data-security-flow-scopes": true,
+				children: [...flow.scopes.entries()].map(([name, description]) => /* @__PURE__ */ jsxs("div", {
+					"data-security-flow-scope": name,
+					children: [/* @__PURE__ */ jsx("dt", { children: name }), /* @__PURE__ */ jsx("dd", { children: description })]
+				}, name))
+			})
+		]
+	});
+}
 //#endregion
 export { ApiSecurity };

package/dist/openapi/bundle.mjs

@@ -1,4 +1,5 @@
 import { isObject } from "../core/guards.mjs";
+import { isPrototypePollutingKey } from "../core/uri.mjs";
 //#region src/openapi/bundle.ts
 /**
 * OpenAPI document bundler — inlines external $ref files.
@@ -104,6 +105,7 @@ function resolveFragment(doc, fragment) {
 	for (const part of parts) {
 		if (!isObject(current)) return void 0;
 		const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
+		if (isPrototypePollutingKey(decoded)) return void 0;
 		current = current[decoded];
 	}
 	return isObject(current) ? current : void 0;

package/dist/openapi/components.d.mts

@@ -1,10 +1,24 @@
-import { T as SchemaMeta, u as FieldOverride } from "../types-D_5ST7SS.mjs";
-import { a as InferResponseFields, d as UnsafeFields, i as InferRequestBodyFields, r as InferParameterOverrides } from "../typeInference-5JiqIZ8t.mjs";
+import { T as SchemaMeta, u as FieldOverride } from "../types-BnxPEElk.mjs";
+import { r as DiagnosticSink } from "../diagnostics-CbBPsxSt.mjs";
+import { a as InferResponseFields, i as InferRequestBodyFields, m as UnsafeFields, r as InferParameterOverrides } from "../typeInference-Bxw3NOG1.mjs";
 import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/components.d.ts
-interface ApiOperationProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+/**
+ * Diagnostics props accepted by every top-level OpenAPI component.
+ *
+ * `onDiagnostic` is the sink invoked for each event surfaced by the
+ * normalisation pipeline (duplicate body parameter, dropped Swagger
+ * feature, divisible-by conflict, unknown JSON Schema dialect,
+ * relative-ref resolved, etc.). `strict` converts every emitted
+ * diagnostic into a thrown `SchemaNormalisationError`.
+ */
+interface ApiDiagnosticsProps {
+  onDiagnostic?: DiagnosticSink;
+  strict?: boolean;
+}
+interface ApiOperationProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
@@ -30,9 +44,11 @@ declare function ApiOperation<Doc = unknown, Path extends string = string, Metho
   responseValue,
   meta,
   requestBodyFields,
-  widgets
+  widgets,
+  onDiagnostic,
+  strict
 }: ApiOperationProps<Doc, Path, Method>): ReactNode;
-interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
@@ -47,9 +63,11 @@ declare function ApiParameters<Doc = unknown, Path extends string = string, Meth
   method,
   meta,
   overrides,
-  widgets
+  widgets,
+  onDiagnostic,
+  strict
 }: ApiParametersProps<Doc, Path, Method>): ReactNode;
-interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
@@ -68,9 +86,11 @@ declare function ApiRequestBody<Doc = unknown, Path extends string = string, Met
   onChange,
   meta,
   fields,
-  widgets
+  widgets,
+  onDiagnostic,
+  strict
 }: ApiRequestBodyProps<Doc, Path, Method>): ReactNode;
-interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> {
+interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
@@ -89,7 +109,9 @@ declare function ApiResponse<Doc = unknown, Path extends string = string, Method
   value,
   meta,
   fields,
-  widgets
+  widgets,
+  onDiagnostic,
+  strict
 }: ApiResponseProps<Doc, Path, Method, Status>): ReactNode;
 //#endregion
 export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps };

package/dist/openapi/components.mjs

@@ -6,7 +6,7 @@ import { ApiResponseHeaders } from "./ApiResponseHeaders.mjs";
 import { ApiSecurity } from "./ApiSecurity.mjs";
 import { getLinks, getSecurityRequirements, getSecuritySchemes, listCallbacks } from "./parser.mjs";
 import { joinPath, renderField, sanitisePrefix } from "../react/SchemaComponent.mjs";
-import { getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, toDoc } from "./resolve.mjs";
+import { getParsed, resolveOperationFromParsed, resolveParametersFromParsed, resolveRequestBodyFromParsed, resolveResponseFromParsed, toDoc } from "./resolve.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 //#region src/openapi/components.tsx
@@ -23,6 +23,13 @@ import { useId } from "react";
 * rendered via the walker + headless resolver directly, bypassing
 * SchemaComponent to avoid deferred-conditional-type compatibility issues.
 */
+function buildDiagnostics(onDiagnostic, strict) {
+	if (onDiagnostic === void 0 && strict !== true) return void 0;
+	const opts = {};
+	if (onDiagnostic !== void 0) opts.diagnostics = onDiagnostic;
+	if (strict === true) opts.strict = true;
+	return opts;
+}
 function noop() {}
 function renderSchema(schema, rootDocument, options) {
 	if (!isObject(schema)) throw new Error("renderSchema received a non-object schema from the resolver.");
@@ -42,10 +49,10 @@ function renderSchema(schema, rootDocument, options) {
 	};
 	return renderField(tree, options.value, options.onChange ?? noop, void 0, makeRenderChild(options.rootPath), options.rootPath, options.widgets);
 }
-function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets }) {
+function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets, onDiagnostic, strict }) {
 	const rootDoc = toDoc(doc);
-	const resolved = resolveOperation(rootDoc, path, method);
-	const parsed = getParsed(rootDoc);
+	const parsed = getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict));
+	const resolved = resolveOperationFromParsed(parsed, path, method);
 	const securityReqs = getSecurityRequirements(parsed, path, method);
 	const securitySchemes = getSecuritySchemes(parsed);
 	const callbacks = listCallbacks(parsed, path, method);
@@ -53,7 +60,10 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 	return /* @__PURE__ */ jsxs("section", {
 		"data-operation": `${method.toUpperCase()} ${path}`,
 		children: [
-			/* @__PURE__ */ jsx(OperationHeader, { operation: resolved.operation }),
+			/* @__PURE__ */ jsx(OperationHeader, {
+				operation: resolved.operation,
+				pathItem: resolved.pathItem
+			}),
 			/* @__PURE__ */ jsx(ApiSecurity, {
 				requirements: securityReqs,
 				schemes: securitySchemes
@@ -96,6 +106,7 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 				children: [/* @__PURE__ */ jsx("h4", { children: "Responses" }), resolved.responses.map((response) => /* @__PURE__ */ jsx(ResponseCard, {
 					response,
 					rootDoc,
+					parsed,
 					value: responseValue,
 					meta,
 					widgets,
@@ -107,9 +118,9 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 		]
 	});
 }
-function ApiParameters({ schema: doc, path, method, meta, overrides, widgets }) {
+function ApiParameters({ schema: doc, path, method, meta, overrides, widgets, onDiagnostic, strict }) {
 	const rootDoc = toDoc(doc);
-	const params = resolveParameters(rootDoc, path, method);
+	const params = resolveParametersFromParsed(getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict)), path, method);
 	const instancePrefix = sanitisePrefix(useId());
 	if (params.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
@@ -124,9 +135,9 @@ function ApiParameters({ schema: doc, path, method, meta, overrides, widgets })
 		})]
 	});
 }
-function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets }) {
+function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets, onDiagnostic, strict }) {
 	const rootDoc = toDoc(doc);
-	const requestBody = resolveRequestBody(rootDoc, path, method);
+	const requestBody = resolveRequestBodyFromParsed(getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict)), path, method);
 	const instancePrefix = sanitisePrefix(useId());
 	if (requestBody?.schema === void 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
@@ -152,9 +163,10 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 		]
 	});
 }
-function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets }) {
+function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets, onDiagnostic, strict }) {
 	const rootDoc = toDoc(doc);
-	const response = resolveResponse(rootDoc, path, method, status);
+	const parsed = getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict));
+	const response = resolveResponseFromParsed(parsed, path, method, status);
 	const instancePrefix = sanitisePrefix(useId());
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": status,
@@ -167,6 +179,7 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 	return /* @__PURE__ */ jsx(ResponseCard, {
 		response,
 		rootDoc,
+		parsed,
 		value,
 		fields,
 		meta,
@@ -176,8 +189,18 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 		idPrefix: instancePrefix
 	});
 }
-function OperationHeader({ operation }) {
+function OperationHeader({ operation, pathItem }) {
 	return /* @__PURE__ */ jsxs("header", { children: [
+		(pathItem.summary !== void 0 || pathItem.description !== void 0) && /* @__PURE__ */ jsxs("div", {
+			"data-path-info": true,
+			children: [pathItem.summary !== void 0 && /* @__PURE__ */ jsx("p", {
+				"data-path-summary": true,
+				children: pathItem.summary
+			}), pathItem.description !== void 0 && /* @__PURE__ */ jsx("p", {
+				"data-path-description": true,
+				children: pathItem.description
+			})]
+		}),
 		/* @__PURE__ */ jsxs("h3", { children: [
 			operation.method.toUpperCase(),
 			" ",
@@ -214,7 +237,7 @@ function ParameterList({ parameters, rootDoc, overrides, meta, widgets, idPrefix
 		]
 	}, param.name)) });
 }
-function ResponseCard({ response, rootDoc, value, fields, meta, widgets, path, method, idPrefix }) {
+function ResponseCard({ response, rootDoc, parsed, value, fields, meta, widgets, path, method, idPrefix }) {
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": response.statusCode,
 		children: [
@@ -224,9 +247,7 @@ function ResponseCard({ response, rootDoc, value, fields, meta, widgets, path, m
 		]
 	});
 	let links = [];
-	if (path !== void 0 && method !== void 0) try {
-		links = getLinks(getParsed(rootDoc), path, method, response.statusCode);
-	} catch {}
+	if (path !== void 0 && method !== void 0) links = getLinks(parsed, path, method, response.statusCode);
 	return /* @__PURE__ */ jsxs("div", {
 		"data-status": response.statusCode,
 		children: [

package/dist/openapi/parser.d.mts

@@ -1,4 +1,4 @@
-import { m as JsonObject } from "../types-D_5ST7SS.mjs";
+import { m as JsonObject } from "../types-BnxPEElk.mjs";
 
 //#region src/openapi/parser.d.ts
 interface OpenApiDocument {

package/dist/openapi/parser.mjs

@@ -1,4 +1,5 @@
 import { getProperty, isObject } from "../core/guards.mjs";
+import { isPrototypePollutingKey } from "../core/uri.mjs";
 //#region src/openapi/parser.ts
 function getString(value, key) {
 	const result = isObject(value) ? value[key] : void 0;
@@ -119,8 +120,10 @@ function resolveParam(doc, param) {
 	return param;
 }
 function getRequestBody(parsed, path, method) {
-	const requestBody = getProperty(getProperty(lookupPathItem(parsed, path), method), "requestBody");
-	if (!isObject(requestBody)) return void 0;
+	const requestBodyRaw = getProperty(getProperty(lookupPathItem(parsed, path), method), "requestBody");
+	if (!isObject(requestBodyRaw)) return void 0;
+	const requestBody = resolveWrapperRef(parsed.doc, requestBodyRaw);
+	if (requestBody === void 0) return void 0;
 	const content = getProperty(requestBody, "content");
 	if (!isObject(content)) return {
 		required: getProperty(requestBody, "required") === true,
@@ -141,8 +144,10 @@ function getResponses(parsed, path, method) {
 	const responses = getProperty(getProperty(lookupPathItem(parsed, path), method), "responses");
 	if (!isObject(responses)) return [];
 	const result = [];
-	for (const [statusCode, response] of Object.entries(responses)) {
-		if (!isObject(response)) continue;
+	for (const [statusCode, responseRaw] of Object.entries(responses)) {
+		if (!isObject(responseRaw)) continue;
+		const response = resolveWrapperRef(parsed.doc, responseRaw);
+		if (response === void 0) continue;
 		const content = getProperty(response, "content");
 		const contentTypes = isObject(content) ? Object.keys(content) : [];
 		const schema = isObject(content) ? extractSchemaFromContent(content) : void 0;
@@ -157,15 +162,46 @@ function getResponses(parsed, path, method) {
 	}
 	return result;
 }
+/**
+* Resolve a single-hop `$ref` on a wrapper object — Response Object,
+* Request Body Object, etc. — against the document root. Returns the
+* referenced node when the wrapper is a `$ref`, the wrapper itself when
+* it has no `$ref`, or `undefined` when the `$ref` is malformed or
+* cannot be resolved (so the caller skips the entry rather than reading
+* stale fields from the bare `{ $ref }` envelope).
+*/
+function resolveWrapperRef(doc, wrapper) {
+	const ref = getString(wrapper, "$ref");
+	if (ref === void 0) return wrapper;
+	return resolveRefInDoc(doc, ref);
+}
 function extractSchemaFromContent(content) {
 	const jsonSchema = getProperty(getProperty(content, "application/json"), "schema");
 	if (isObject(jsonSchema)) return jsonSchema;
+	for (const [mediaType, mediaObj] of Object.entries(content)) {
+		if (!isJsonSuffixMediaType(mediaType)) continue;
+		if (!isObject(mediaObj)) continue;
+		const schema = getProperty(mediaObj, "schema");
+		if (isObject(schema)) return schema;
+	}
 	for (const mediaType of Object.values(content)) {
 		if (!isObject(mediaType)) continue;
 		const schema = getProperty(mediaType, "schema");
 		if (isObject(schema)) return schema;
 	}
 }
+/**
+* Detect RFC 6839 structured-syntax-suffix media types that encode JSON.
+* Matches `application/<anything>+json`, optionally with parameters
+* (`; charset=utf-8`). Excludes the literal `application/json`, which
+* the caller checks separately to preserve preference order.
+*/
+function isJsonSuffixMediaType(mediaType) {
+	const lower = mediaType.toLowerCase();
+	if (lower === "application/json") return false;
+	const baseType = lower.split(";", 1)[0]?.trim() ?? "";
+	return baseType.startsWith("application/") && baseType.endsWith("+json");
+}
 function resolveRefInDoc(doc, ref) {
 	if (!ref.startsWith("#/")) return void 0;
 	const parts = ref.slice(2).split("/");
@@ -173,6 +209,7 @@ function resolveRefInDoc(doc, ref) {
 	for (const part of parts) {
 		if (!isObject(current)) return void 0;
 		const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
+		if (isPrototypePollutingKey(decoded)) return void 0;
 		current = current[decoded];
 	}
 	return isObject(current) ? current : void 0;

package/dist/openapi/resolve.d.mts

@@ -1,3 +1,4 @@
+import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
 import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequestBody } from "./parser.mjs";
 
 //#region src/openapi/resolve.d.ts
@@ -14,41 +15,101 @@ import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequest
  * same form `<SchemaComponent>` does, keeping the OpenAPI components on
  * the same pipeline as the top-level adapter.
  *
- * The cache is keyed by the caller-supplied document so subsequent calls
- * with the same input bypass both normalisation and parsing.
+ * When `diagnostics` is supplied, normalisation events
+ * (`duplicate-body-parameter`, `dropped-swagger-feature`,
+ * `unknown-json-schema-dialect`, `divisible-by-conflict`,
+ * `relative-ref-resolved`, etc.) are forwarded to the sink. Passing
+ * diagnostics also bypasses the cache so each call observes the
+ * normalisation pipeline running against the supplied sink — caching
+ * would silently swallow every emission after the first.
+ *
+ * The cache is keyed by the caller-supplied document so subsequent
+ * cache-eligible calls with the same input bypass both normalisation
+ * and parsing.
  */
-declare function getParsed(doc: Record<string, unknown>): OpenApiDocument;
+declare function getParsed(doc: Record<string, unknown>, diagnostics?: DiagnosticsOptions): OpenApiDocument;
 /**
  * Coerce an unknown value to a record, returning an empty record
  * for non-objects.
  */
 declare function toDoc(value: unknown): Record<string, unknown>;
+/**
+ * Path-Item-level metadata. OpenAPI 3.1 added `summary` and `description`
+ * to Path Item Objects alongside the existing operation-level fields.
+ * Both are plain strings (no Markdown rendering at this layer).
+ */
+interface PathItemInfo {
+  summary: string | undefined;
+  description: string | undefined;
+}
 interface ResolvedOperation {
   operation: OperationInfo;
+  pathItem: PathItemInfo;
   parameters: ParameterInfo[];
   requestBody: ReturnType<typeof getRequestBody>;
   responses: ResponseInfo[];
 }
+/**
+ * Resolve an operation against an already-parsed document. Throws if
+ * the operation is not found.
+ *
+ * Used by callers that have already obtained a parsed document via
+ * {@link getParsed} — most importantly the React components, which
+ * supply `diagnostics` to `getParsed` and must avoid re-running the
+ * normalisation pipeline (every re-run would emit each diagnostic
+ * again into the sink).
+ */
+declare function resolveOperationFromParsed(parsed: OpenApiDocument, path: string, method: string): ResolvedOperation;
 /**
  * Resolve an operation from an OpenAPI document by path and method.
  * Throws if the operation is not found.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
+ */
+declare function resolveOperation(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ResolvedOperation;
+/**
+ * Resolve parameters against an already-parsed document. See
+ * {@link resolveOperationFromParsed} for the rationale.
  */
-declare function resolveOperation(doc: Record<string, unknown>, path: string, method: string): ResolvedOperation;
+declare function resolveParametersFromParsed(parsed: OpenApiDocument, path: string, method: string): ParameterInfo[];
 /**
  * Resolve parameters for an operation. Returns empty array if none.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
  */
-declare function resolveParameters(doc: Record<string, unknown>, path: string, method: string): ParameterInfo[];
+declare function resolveParameters(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ParameterInfo[];
+/**
+ * Resolve a request body against an already-parsed document. See
+ * {@link resolveOperationFromParsed} for the rationale.
+ */
+declare function resolveRequestBodyFromParsed(parsed: OpenApiDocument, path: string, method: string): ReturnType<typeof getRequestBody>;
 /**
  * Resolve request body for an operation. Returns undefined if none.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
  */
-declare function resolveRequestBody(doc: Record<string, unknown>, path: string, method: string): ReturnType<typeof getRequestBody>;
+declare function resolveRequestBody(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ReturnType<typeof getRequestBody>;
+/**
+ * Resolve a specific response against an already-parsed document. See
+ * {@link resolveOperationFromParsed} for the rationale.
+ */
+declare function resolveResponseFromParsed(parsed: OpenApiDocument, path: string, method: string, statusCode: string): ResponseInfo;
 /**
  * Resolve a specific response by status code. Throws if not found.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
  */
-declare function resolveResponse(doc: Record<string, unknown>, path: string, method: string, statusCode: string): ResponseInfo;
+declare function resolveResponse(doc: Record<string, unknown>, path: string, method: string, statusCode: string, diagnostics?: DiagnosticsOptions): ResponseInfo;
 /**
  * Resolve all responses for an operation.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
  */
-declare function resolveResponses(doc: Record<string, unknown>, path: string, method: string): ResponseInfo[];
+declare function resolveResponses(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ResponseInfo[];
 //#endregion
-export { ResolvedOperation, getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, resolveResponses, toDoc };
+export { PathItemInfo, ResolvedOperation, getParsed, resolveOperation, resolveOperationFromParsed, resolveParameters, resolveParametersFromParsed, resolveRequestBody, resolveRequestBodyFromParsed, resolveResponse, resolveResponseFromParsed, resolveResponses, toDoc };