schema-components 1.21.0 → 1.22.0

package/dist/openapi/ApiCallbacks.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.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-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.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-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.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-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.mjs";
 import { SecurityRequirement, SecurityScheme } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiSecurity.mjs

@@ -11,6 +11,18 @@ const OAUTH_FLOW_KEYS = [
 	"clientCredentials",
 	"authorizationCode"
 ];
+/**
+* Known Security Scheme `type` values per the OpenAPI 3.0/3.1 spec.
+* Used to flag unknown values in the rendered output so authors can
+* spot typos like `mutalTLS` without consulting the diagnostic sink.
+*/
+const KNOWN_SECURITY_SCHEME_TYPES = new Set([
+	"apiKey",
+	"http",
+	"oauth2",
+	"openIdConnect",
+	"mutualTLS"
+]);
 function readString(source, key) {
 	const value = source[key];
 	return typeof value === "string" ? value : void 0;
@@ -66,10 +78,12 @@ function ApiSecurity({ requirements, schemes }) {
 }
 function SchemeDetails({ scheme }) {
 	const flows = extractFlows(scheme.flows);
+	const isKnownType = scheme.type !== void 0 && KNOWN_SECURITY_SCHEME_TYPES.has(scheme.type);
 	return /* @__PURE__ */ jsxs(Fragment, { children: [
-		scheme.type !== void 0 && /* @__PURE__ */ jsx("span", {
+		scheme.type !== void 0 && /* @__PURE__ */ jsxs("span", {
 			"data-security-type": true,
-			children: scheme.type
+			"data-security-type-unknown": isKnownType ? void 0 : "true",
+			children: [scheme.type, !isKnownType && " (unknown type)"]
 		}),
 		scheme.description !== void 0 && /* @__PURE__ */ jsx("span", {
 			"data-security-description": true,

package/dist/openapi/components.d.mts

@@ -1,10 +1,85 @@
-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 { u as FieldOverride, w as SchemaMeta } from "../types-BrRMV0en.mjs";
+import { r as DiagnosticSink } from "../diagnostics-D0QCYGv0.mjs";
+import { a as InferParameterOverrides, g as UnsafeFields, o as InferRequestBodyFields, s as InferResponseFields } from "../typeInference-DkcUHfaM.mjs";
 import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/components.d.ts
+/**
+ * The canonical set of HTTP method strings recognised by OpenAPI 3.x.
+ * Used to constrain `Method` generics so autocomplete on typed
+ * documents only suggests methods the path item actually declares,
+ * not arbitrary string keys.
+ */
+type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+/**
+ * Extract the literal path keys from a document type, or the broad
+ * `string` fallback when the document is untyped at compile time.
+ *
+ * The `string extends keyof D["paths"]` guard distinguishes a typed
+ * `as const` document (whose `paths` map has literal keys) from a
+ * runtime `Record<string, unknown>` document (whose `keyof` collapses
+ * to `string`). For the runtime case we surface `string` so callers
+ * pass arbitrary path values without losing the existing freedom.
+ */
+type PathKeysOf<D> = D extends {
+  paths: infer P;
+} ? P extends Record<string, unknown> ? string extends keyof P ? string : Extract<keyof P, string> : string : string;
+/**
+ * Extract the methods declared on a specific path item, restricted to
+ * the OpenAPI-recognised method set so non-method extension keys
+ * (e.g. `summary`, `description`, `parameters`) do not pollute the
+ * autocomplete.
+ *
+ * Runtime documents (typed `Record<string, unknown>`) widen back to
+ * `string` so callers retain the freedom to pass arbitrary method
+ * strings without surfacing an `HttpMethod` constraint at runtime
+ * call sites.
+ */
+type MethodKeysOf<D, P extends string> = IsRuntimeDoc<D> extends true ? string : D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Extract<keyof Paths[P], HttpMethod> : HttpMethod : HttpMethod : HttpMethod;
+/**
+ * True for the runtime-document sentinel — a `Record<string, unknown>`
+ * (or wider) where `keyof` collapses to `string`. Used to drop
+ * narrow-constraint defaults so runtime callers retain the prior
+ * freedom to pass arbitrary path/method/status values.
+ */
+type IsRuntimeDoc<D> = D extends Record<string, unknown> ? string extends keyof D ? true : false : false;
+/**
+ * Extract the status-code keys declared by an operation's `responses`
+ * map. Includes class wildcards (`2XX`, etc.) and the `default`
+ * sentinel; runtime documents widen to `string`.
+ */
+type StatusKeysOf<D, P extends string, M extends string> = D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Paths[P] extends Record<string, unknown> ? M extends keyof Paths[P] ? Paths[P][M] extends {
+  responses: infer R;
+} ? R extends Record<string, unknown> ? string extends keyof R ? string : Extract<keyof R, string> : string : string : string : string : string : string : string;
+/**
+ * Extract the content-type keys declared on a request body's
+ * `content` map for the given path and method. Runtime documents
+ * widen to `string`.
+ */
+type RequestContentTypesOf<D, P extends string, M extends string> = D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Paths[P] extends Record<string, unknown> ? M extends keyof Paths[P] ? Paths[P][M] extends {
+  requestBody: {
+    content: infer C;
+  };
+} ? C extends Record<string, unknown> ? string extends keyof C ? string : Extract<keyof C, string> : string : string : string : string : string : string : string;
+/**
+ * Extract the content-type keys declared on a response entry's
+ * `content` map for the given path, method, and status. Runtime
+ * documents widen to `string`.
+ */
+type ResponseContentTypesOf<D, P extends string, M extends string, S extends string> = D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Paths[P] extends Record<string, unknown> ? M extends keyof Paths[P] ? Paths[P][M] extends {
+  responses: infer R;
+} ? R extends Record<string, unknown> ? S extends keyof R ? R[S] extends {
+  content: infer C;
+} ? C extends Record<string, unknown> ? string extends keyof C ? string : Extract<keyof C, string> : string : string : string : string : string : string : string : string : string : string;
 /**
  * Diagnostics props accepted by every top-level OpenAPI component.
  *
@@ -18,7 +93,7 @@ interface ApiDiagnosticsProps {
   onDiagnostic?: DiagnosticSink;
   strict?: boolean;
 }
-interface ApiOperationProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
+interface ApiOperationProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
@@ -26,7 +101,7 @@ interface ApiOperationProps<Doc = unknown, Path extends string = string, Method
   onRequestBodyChange?: (value: unknown) => void;
   responseValue?: unknown;
   meta?: SchemaMeta;
-  requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path & string, Method & string> : Record<string, FieldOverride>;
   /** Escape hatch for recursive schemas where type-level inference fails.
    * Typed as Record<string, FieldOverride> — use when the schema contains
    * deeply nested $ref chains.
@@ -35,7 +110,7 @@ interface ApiOperationProps<Doc = unknown, Path extends string = string, Method
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiOperation<Doc = unknown, Path extends string = string, Method extends string = string>({
+declare function ApiOperation<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>>({
   schema: doc,
   path,
   method,
@@ -48,16 +123,16 @@ declare function ApiOperation<Doc = unknown, Path extends string = string, Metho
   onDiagnostic,
   strict
 }: ApiOperationProps<Doc, Path, Method>): ReactNode;
-interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
+interface ApiParametersProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
   meta?: SchemaMeta;
-  overrides?: Doc extends Record<string, unknown> ? InferParameterOverrides<Doc, Path, Method> : Record<string, FieldOverride>;
+  overrides?: Doc extends Record<string, unknown> ? InferParameterOverrides<Doc, Path & string, Method & string> : Record<string, FieldOverride>;
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiParameters<Doc = unknown, Path extends string = string, Method extends string = string>({
+declare function ApiParameters<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>>({
   schema: doc,
   path,
   method,
@@ -67,18 +142,25 @@ declare function ApiParameters<Doc = unknown, Path extends string = string, Meth
   onDiagnostic,
   strict
 }: ApiParametersProps<Doc, Path, Method>): ReactNode;
-interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
+interface ApiRequestBodyProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, ContentType extends RequestContentTypesOf<Doc, Path, Method> = RequestContentTypesOf<Doc, Path, Method>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
+  /**
+   * Media type whose schema should be rendered for the request body.
+   * Defaults to the union of declared content types so callers can
+   * omit it; supply explicitly to narrow `fields` inference to a
+   * specific media type via {@link InferRequestBodyFields}.
+   */
+  contentType?: ContentType;
   value?: unknown;
   onChange?: (value: unknown) => void;
   meta?: SchemaMeta;
-  fields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  fields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path & string, Method & string, ContentType & string> : Record<string, FieldOverride>;
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiRequestBody<Doc = unknown, Path extends string = string, Method extends string = string>({
+declare function ApiRequestBody<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, ContentType extends RequestContentTypesOf<Doc, Path, Method> = RequestContentTypesOf<Doc, Path, Method>>({
   schema: doc,
   path,
   method,
@@ -89,19 +171,26 @@ declare function ApiRequestBody<Doc = unknown, Path extends string = string, Met
   widgets,
   onDiagnostic,
   strict
-}: ApiRequestBodyProps<Doc, Path, Method>): ReactNode;
-interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> extends ApiDiagnosticsProps {
+}: ApiRequestBodyProps<Doc, Path, Method, ContentType>): ReactNode;
+interface ApiResponseProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, Status extends StatusKeysOf<Doc, Path, Method> = StatusKeysOf<Doc, Path, Method>, ContentType extends ResponseContentTypesOf<Doc, Path, Method, Status> = ResponseContentTypesOf<Doc, Path, Method, Status>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
   status: Status;
+  /**
+   * Media type whose schema should be rendered. Defaults to the
+   * union of declared content types so callers can omit it;
+   * supply explicitly to narrow `fields` inference via
+   * {@link InferResponseFields}.
+   */
+  contentType?: ContentType;
   value?: unknown;
   meta?: SchemaMeta;
-  fields?: Doc extends Record<string, unknown> ? InferResponseFields<Doc, Path, Method, Status> : Record<string, FieldOverride>;
+  fields?: Doc extends Record<string, unknown> ? InferResponseFields<Doc, Path & string, Method & string, Status & string, ContentType & string> : Record<string, FieldOverride>;
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiResponse<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string>({
+declare function ApiResponse<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, Status extends StatusKeysOf<Doc, Path, Method> = StatusKeysOf<Doc, Path, Method>, ContentType extends ResponseContentTypesOf<Doc, Path, Method, Status> = ResponseContentTypesOf<Doc, Path, Method, Status>>({
   schema: doc,
   path,
   method,
@@ -112,6 +201,49 @@ declare function ApiResponse<Doc = unknown, Path extends string = string, Method
   widgets,
   onDiagnostic,
   strict
-}: ApiResponseProps<Doc, Path, Method, Status>): ReactNode;
+}: ApiResponseProps<Doc, Path, Method, Status, ContentType>): ReactNode;
+/**
+ * Render a single OpenAPI 3.1 webhook by name. A webhook is a Path Item
+ * Object under the document's top-level `webhooks` map; once resolved,
+ * its operations are structurally identical to operations under `paths`.
+ *
+ * Internally, this delegates to `ApiOperation` for each method present
+ * on the webhook's Path Item Object. The parser's `lookupPathItem`
+ * resolves webhook names through the same code path as paths, so
+ * `ApiOperation` works for both with no special-casing in the renderer.
+ */
+interface ApiWebhookProps extends ApiDiagnosticsProps {
+  schema: unknown;
+  /** Webhook name (key under the document's `webhooks` map). */
+  name: string;
+  /** Instance-scoped widgets, forwarded to each rendered operation. */
+  widgets?: WidgetMap;
+  meta?: SchemaMeta;
+}
+declare function ApiWebhook({
+  schema: doc,
+  name,
+  widgets,
+  meta,
+  onDiagnostic,
+  strict
+}: ApiWebhookProps): ReactNode;
+/**
+ * Render every OpenAPI 3.1 webhook declared on the document, one
+ * `<ApiWebhook>` per entry. Returns `null` when the document has no
+ * `webhooks` map or it is empty.
+ */
+interface ApiWebhooksProps extends ApiDiagnosticsProps {
+  schema: unknown;
+  widgets?: WidgetMap;
+  meta?: SchemaMeta;
+}
+declare function ApiWebhooks({
+  schema: doc,
+  widgets,
+  meta,
+  onDiagnostic,
+  strict
+}: ApiWebhooksProps): ReactNode;
 //#endregion
-export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps };
+export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps, ApiWebhook, ApiWebhookProps, ApiWebhooks, ApiWebhooksProps };

package/dist/openapi/components.mjs

@@ -1,10 +1,11 @@
 import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import { emitDiagnostic } from "../core/diagnostics.mjs";
 import { walk } from "../core/walker.mjs";
 import { ApiCallbacks } from "./ApiCallbacks.mjs";
 import { ApiLinks } from "./ApiLinks.mjs";
 import { ApiResponseHeaders } from "./ApiResponseHeaders.mjs";
 import { ApiSecurity } from "./ApiSecurity.mjs";
-import { getLinks, getSecurityRequirements, getSecuritySchemes, listCallbacks } from "./parser.mjs";
+import { getExternalDocs, getLinks, getSecurityRequirements, getSecuritySchemes, getXmlInfo, listCallbacks, listWebhooks } from "./parser.mjs";
 import { joinPath, renderField, sanitisePrefix } from "../react/SchemaComponent.mjs";
 import { getParsed, resolveOperationFromParsed, resolveParametersFromParsed, resolveRequestBodyFromParsed, resolveResponseFromParsed, toDoc } from "./resolve.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -30,6 +31,25 @@ function buildDiagnostics(onDiagnostic, strict) {
 	if (strict === true) opts.strict = true;
 	return opts;
 }
+/**
+* Coerce an `unknown` `schema` prop to a document record. Returns
+* `undefined` when the prop is not a plain object, surfacing a
+* `doc-not-object` diagnostic so silent "empty document" misbehaviour
+* (the historic `toDoc` `{}` fallback) is impossible.
+*
+* Components MUST short-circuit when this returns `undefined` rather
+* than rendering empty operation lists.
+*/
+function resolveRootDoc(doc, diagnostics) {
+	const resolved = toDoc(doc);
+	if (resolved === void 0) emitDiagnostic(diagnostics, {
+		code: "doc-not-object",
+		message: "OpenAPI document prop is not a plain object; nothing to render",
+		pointer: "",
+		detail: { received: typeof doc }
+	});
+	return resolved;
+}
 function noop() {}
 function renderSchema(schema, rootDocument, options) {
 	if (!isObject(schema)) throw new Error("renderSchema received a non-object schema from the resolver.");
@@ -49,14 +69,55 @@ function renderSchema(schema, rootDocument, options) {
 	};
 	return renderField(tree, options.value, options.onChange ?? noop, void 0, makeRenderChild(options.rootPath), options.rootPath, options.widgets);
 }
+/**
+* Render a Schema Object or Operation Object's `externalDocs` as a
+* simple anchor with optional descriptive text. Returns `null` when no
+* externalDocs are attached so callers can drop it into JSX without an
+* extra guard.
+*/
+function ExternalDocsLink({ externalDocs }) {
+	if (externalDocs === void 0) return null;
+	return /* @__PURE__ */ jsx("p", {
+		"data-external-docs": true,
+		children: /* @__PURE__ */ jsx("a", {
+			href: externalDocs.url,
+			children: externalDocs.description ?? externalDocs.url
+		})
+	});
+}
+/**
+* Render a Schema Object's `xml` metadata as a footnote. The library
+* does not render XML payloads natively, but the metadata still
+* carries author intent (namespaces, element names, wrapping rules).
+* Surface it so consumers can audit the dropped feature without
+* losing the underlying information.
+*/
+function SchemaXmlFootnote({ xml }) {
+	if (xml === void 0) return null;
+	return /* @__PURE__ */ jsx("aside", {
+		"data-schema-xml": true,
+		children: /* @__PURE__ */ jsxs("small", { children: [
+			"XML representation",
+			xml.name !== void 0 && ` — name: ${xml.name}`,
+			xml.namespace !== void 0 && ` — namespace: ${xml.namespace}`,
+			xml.prefix !== void 0 && ` — prefix: ${xml.prefix}`,
+			xml.attribute && " — attribute",
+			xml.wrapped && " — wrapped"
+		] })
+	});
+}
 function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const parsed = getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict));
-	const resolved = resolveOperationFromParsed(parsed, path, method);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const parsed = getParsed(rootDoc, diagnostics);
+	const resolved = resolveOperationFromParsed(parsed, path, method, diagnostics);
 	const securityReqs = getSecurityRequirements(parsed, path, method);
 	const securitySchemes = getSecuritySchemes(parsed);
 	const callbacks = listCallbacks(parsed, path, method);
-	const instancePrefix = sanitisePrefix(useId());
+	const operationExternalDocs = getExternalDocs(resolved.operation.operation);
+	const requestBodyXml = resolved.requestBody?.schema !== void 0 ? getXmlInfo(resolved.requestBody.schema) : void 0;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-operation": `${method.toUpperCase()} ${path}`,
 		children: [
@@ -64,6 +125,7 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 				operation: resolved.operation,
 				pathItem: resolved.pathItem
 			}),
+			/* @__PURE__ */ jsx(ExternalDocsLink, { externalDocs: operationExternalDocs }),
 			/* @__PURE__ */ jsx(ApiSecurity, {
 				requirements: securityReqs,
 				schemes: securitySchemes
@@ -98,7 +160,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 						meta,
 						widgets,
 						rootPath: joinPath(instancePrefix, "requestBody")
-					})
+					}),
+					/* @__PURE__ */ jsx(SchemaXmlFootnote, { xml: requestBodyXml })
 				]
 			}),
 			resolved.responses.length > 0 && /* @__PURE__ */ jsxs("section", {
@@ -119,9 +182,11 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 	});
 }
 function ApiParameters({ schema: doc, path, method, meta, overrides, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const params = resolveParametersFromParsed(getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict)), path, method);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const params = resolveParametersFromParsed(getParsed(rootDoc, diagnostics), path, method);
 	if (params.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-parameters": true,
@@ -136,10 +201,13 @@ function ApiParameters({ schema: doc, path, method, meta, overrides, widgets, on
 	});
 }
 function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const requestBody = resolveRequestBodyFromParsed(getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict)), path, method);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const requestBody = resolveRequestBodyFromParsed(getParsed(rootDoc, diagnostics), path, method);
 	if (requestBody?.schema === void 0) return null;
+	const requestBodyXml = getXmlInfo(requestBody.schema);
 	return /* @__PURE__ */ jsxs("section", {
 		"data-request-body": true,
 		children: [
@@ -159,15 +227,18 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 				meta,
 				widgets,
 				rootPath: instancePrefix
-			})
+			}),
+			/* @__PURE__ */ jsx(SchemaXmlFootnote, { xml: requestBodyXml })
 		]
 	});
 }
 function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const parsed = getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict));
-	const response = resolveResponseFromParsed(parsed, path, method, status);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const parsed = getParsed(rootDoc, diagnostics);
+	const response = resolveResponseFromParsed(parsed, path, method, status);
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": status,
 		children: [
@@ -189,6 +260,49 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 		idPrefix: instancePrefix
 	});
 }
+function ApiWebhook({ schema: doc, name, widgets, meta, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const webhook = listWebhooks(getParsed(rootDoc, diagnostics)).find((w) => w.name === name);
+	if (webhook === void 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-webhook": name,
+		"data-instance": instancePrefix,
+		children: [/* @__PURE__ */ jsxs("h3", { children: ["Webhook: ", name] }), webhook.operations.map((op) => {
+			const opProps = {
+				schema: rootDoc,
+				path: name,
+				method: op.method
+			};
+			if (widgets !== void 0) opProps.widgets = widgets;
+			if (meta !== void 0) opProps.meta = meta;
+			return /* @__PURE__ */ jsx(ApiOperation, { ...opProps }, `${name}-${op.method}`);
+		})]
+	});
+}
+function ApiWebhooks({ schema: doc, widgets, meta, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const webhooks = listWebhooks(getParsed(rootDoc, diagnostics));
+	if (webhooks.length === 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-webhooks": true,
+		"data-instance": instancePrefix,
+		children: [/* @__PURE__ */ jsx("h2", { children: "Webhooks" }), webhooks.map((webhook) => {
+			const props = {
+				schema: rootDoc,
+				name: webhook.name
+			};
+			if (widgets !== void 0) props.widgets = widgets;
+			if (meta !== void 0) props.meta = meta;
+			return /* @__PURE__ */ jsx(ApiWebhook, { ...props }, webhook.name);
+		})]
+	});
+}
 function OperationHeader({ operation, pathItem }) {
 	return /* @__PURE__ */ jsxs("header", { children: [
 		(pathItem.summary !== void 0 || pathItem.description !== void 0) && /* @__PURE__ */ jsxs("div", {
@@ -293,4 +407,4 @@ function extractRootMetaFromSchema(jsonSchema) {
 	return Object.keys(meta).length > 0 ? meta : void 0;
 }
 //#endregion
-export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse };
+export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse, ApiWebhook, ApiWebhooks };

package/dist/openapi/parser.d.mts

@@ -1,4 +1,4 @@
-import { m as JsonObject } from "../types-BnxPEElk.mjs";
+import { m as JsonObject } from "../types-BrRMV0en.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 "../core/limits.mjs";
 import { isPrototypePollutingKey } from "../core/uri.mjs";
 //#region src/openapi/parser.ts
 function getString(value, key) {
@@ -44,11 +45,27 @@ const METHODS = [
 * (OpenAPI 3.1) if present. Returns `undefined` when the value is not a
 * path item, the ref is malformed, or the target does not resolve.
 */
+/**
+* Follow Path Item Object `$ref` chains (up to MAX_PATH_ITEM_REF_HOPS).
+* Returns the resolved Path Item, or `undefined` when the chain cycles,
+* exceeds the cap, or any intermediate ref fails to resolve. The
+* detailed diagnostics for cycle and depth-cap are emitted by the
+* mirroring resolver in `resolve.ts` — this parser-side resolver simply
+* stops walking.
+*/
 function resolvePathItem(parsed, pathItem) {
 	if (!isObject(pathItem)) return void 0;
-	const ref = getString(pathItem, "$ref");
-	if (ref === void 0) return pathItem;
-	return resolveRefInDoc(parsed.doc, ref) ?? void 0;
+	const visited = /* @__PURE__ */ new Set();
+	let current = pathItem;
+	for (let hop = 0; hop < 8; hop++) {
+		const ref = getString(current, "$ref");
+		if (ref === void 0) return current;
+		if (visited.has(ref)) return void 0;
+		visited.add(ref);
+		const target = resolveRefInDoc(parsed.doc, ref);
+		if (target === void 0) return void 0;
+		current = target;
+	}
 }
 function lookupPathItem(parsed, path) {
 	const resolved = resolvePathItem(parsed, getProperty(getProperty(parsed.doc, "paths"), path));
@@ -202,6 +219,21 @@ function isJsonSuffixMediaType(mediaType) {
 	const baseType = lower.split(";", 1)[0]?.trim() ?? "";
 	return baseType.startsWith("application/") && baseType.endsWith("+json");
 }
+/**
+* Resolve an in-document `$ref` against the supplied doc root.
+*
+* Limitation — cross-Schema-Object relative refs: refs that do NOT
+* start with `#/` are not resolved here. The `normaliseOpenApiSchemas`
+* pipeline (see `resolveRelativeRefs` in `core/normalise.ts`) rewrites
+* relative refs WITHIN a Schema Object using that schema's `$id` base
+* URI, but it does not currently model `$id` scopes that span Schema
+* Object boundaries (e.g. a sibling component schema with its own
+* `$id` that another schema's relative ref targets). Such refs survive
+* normalisation unchanged and fall through this function returning
+* `undefined`. `resolve.ts:detectUnsupportedCrossSchemaRefs` walks the
+* normalised doc and emits `cross-schema-relative-ref-unsupported` per
+* offending ref so consumers notice the silent failure.
+*/
 function resolveRefInDoc(doc, ref) {
 	if (!ref.startsWith("#/")) return void 0;
 	const parts = ref.slice(2).split("/");

package/dist/openapi/resolve.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-D0QCYGv0.mjs";
 import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequestBody } from "./parser.mjs";
 
 //#region src/openapi/resolve.d.ts
@@ -29,10 +29,17 @@ import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequest
  */
 declare function getParsed(doc: Record<string, unknown>, diagnostics?: DiagnosticsOptions): OpenApiDocument;
 /**
- * Coerce an unknown value to a record, returning an empty record
- * for non-objects.
+ * Coerce an unknown value to a record, returning `undefined` when the
+ * value is not a plain object. Callers MUST handle the `undefined` case
+ * explicitly — typically by rendering a "doc not an object" diagnostic
+ * and short-circuiting, never by silently substituting `{}`.
+ *
+ * A previous implementation fell back to `{}` for non-objects, which
+ * masked configuration mistakes (passing a string, `null`, an array, or
+ * `undefined` as the OpenAPI document) as an empty document with no
+ * operations.
  */
-declare function toDoc(value: unknown): Record<string, unknown>;
+declare function toDoc(value: unknown): Record<string, unknown> | undefined;
 /**
  * Path-Item-level metadata. OpenAPI 3.1 added `summary` and `description`
  * to Path Item Objects alongside the existing operation-level fields.
@@ -59,7 +66,7 @@ interface ResolvedOperation {
  * normalisation pipeline (every re-run would emit each diagnostic
  * again into the sink).
  */
-declare function resolveOperationFromParsed(parsed: OpenApiDocument, path: string, method: string): ResolvedOperation;
+declare function resolveOperationFromParsed(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): ResolvedOperation;
 /**
  * Resolve an operation from an OpenAPI document by path and method.
  * Throws if the operation is not found.