schema-components 1.28.2 → 2.0.0

package/dist/html/streamRenderers.d.mts

@@ -1,13 +1,41 @@
-import { j as WalkedField } from "../types-BTB73MB8.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
-import { o as HtmlResolver } from "../renderer-Ul9taFYp.mjs";
+import { j as WalkedField } from "../types-BrYbjC7_.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
+import { HtmlResolver } from "../core/renderer.mjs";
 import { HtmlElement } from "./html.mjs";
 
 //#region src/html/streamRenderers.d.ts
+/**
+ * Serialise the opening tag of an element so a generator can yield it
+ * without the matching closing tag. Void elements (e.g. `input`) are
+ * emitted self-closed so the chunk is structurally valid on its own.
+ */
 declare function yieldOpen(el: HtmlElement): string;
+/**
+ * Serialise the closing tag of an element so a generator can yield it
+ * after its children. Returns an empty string for void elements (their
+ * opening tag was emitted self-closed by {@link yieldOpen}).
+ */
 declare function yieldClose(el: HtmlElement): string;
+/**
+ * Render a leaf {@link WalkedField} entirely as a single HTML chunk.
+ * Used inside the streaming generators when descent into containers is
+ * complete. Falls back to a `<span>`-wrapped value when no renderer is
+ * registered for the field type.
+ */
 declare function renderLeaf(tree: WalkedField, value: unknown, mergedResolver: HtmlResolver, path: string): string;
+/**
+ * Drain {@link streamField} into a single string. Used when a streamed
+ * sub-tree needs to be embedded inside a non-streaming chunk (e.g. as
+ * children of a parent element).
+ */
 declare function renderFieldSync(tree: WalkedField, value: unknown, mergedResolver: HtmlResolver, path: string, rawResolver: HtmlResolver, currentDepth: number, diagnostics: DiagnosticsOptions | undefined): string;
+/**
+ * Render a {@link WalkedField} as a generator that yields HTML chunks
+ * at natural boundaries (opening tag, one chunk per child, closing
+ * tag). Threads `currentDepth` so cyclic walked-field graphs terminate
+ * at `MAX_RENDER_DEPTH` with a recursion sentinel rather than
+ * overflowing the stack.
+ */
 declare function streamField(tree: WalkedField, value: unknown, mergedResolver: HtmlResolver, path: string, rawResolver: HtmlResolver, currentDepth?: number, diagnostics?: DiagnosticsOptions): Iterable<string, void, undefined>;
 //#endregion
 export { renderFieldSync, renderLeaf, streamField, yieldClose, yieldOpen };

package/dist/html/streamRenderers.mjs

@@ -2,22 +2,38 @@ import { isObject } from "../core/guards.mjs";
 import "../core/limits.mjs";
 import { emitDiagnostic } from "../core/diagnostics.mjs";
 import { SC_CLASSES } from "../core/cssClasses.mjs";
+import { panelIdFor, tabIdFor } from "../core/idPath.mjs";
 import { getHtmlRenderFn } from "../core/renderer.mjs";
 import { matchUnionOption, resolveDiscriminatedActive } from "../core/unionMatch.mjs";
 import { VOID_ELEMENTS, h, raw, serialize, serializeAttributes } from "./html.mjs";
 import { ariaLabelAttrs, buildHintElement, buildInputId, joinPath, requiredIndicator } from "./a11y.mjs";
-import { panelId, tabId } from "./renderers.mjs";
 import { recursionSentinelHtml } from "./renderToHtml.mjs";
 //#region src/html/streamRenderers.ts
+/**
+* Serialise the opening tag of an element so a generator can yield it
+* without the matching closing tag. Void elements (e.g. `input`) are
+* emitted self-closed so the chunk is structurally valid on its own.
+*/
 function yieldOpen(el) {
 	const attrStr = serializeAttributes(el.attributes);
 	if (VOID_ELEMENTS.has(el.tag)) return `<${el.tag}${attrStr} />`;
 	return `<${el.tag}${attrStr}>`;
 }
+/**
+* Serialise the closing tag of an element so a generator can yield it
+* after its children. Returns an empty string for void elements (their
+* opening tag was emitted self-closed by {@link yieldOpen}).
+*/
 function yieldClose(el) {
 	if (VOID_ELEMENTS.has(el.tag)) return "";
 	return `</${el.tag}>`;
 }
+/**
+* Render a leaf {@link WalkedField} entirely as a single HTML chunk.
+* Used inside the streaming generators when descent into containers is
+* complete. Falls back to a `<span>`-wrapped value when no renderer is
+* registered for the field type.
+*/
 function renderLeaf(tree, value, mergedResolver, path) {
 	const renderFn = getHtmlRenderFn(tree.type, mergedResolver);
 	if (renderFn !== void 0) return renderFn({
@@ -33,6 +49,11 @@ function renderLeaf(tree, value, mergedResolver, path) {
 	if (value === void 0 || value === null) return serialize(h("span", { class: SC_CLASSES.valueEmpty }, "—"));
 	return serialize(h("span", { class: SC_CLASSES.value }, typeof value === "string" ? value : JSON.stringify(value)));
 }
+/**
+* Drain {@link streamField} into a single string. Used when a streamed
+* sub-tree needs to be embedded inside a non-streaming chunk (e.g. as
+* children of a parent element).
+*/
 function renderFieldSync(tree, value, mergedResolver, path, rawResolver, currentDepth, diagnostics) {
 	return [...streamField(tree, value, mergedResolver, path, rawResolver, currentDepth, diagnostics)].join("");
 }
@@ -51,6 +72,13 @@ function typeMismatchPlaceholder(expectedShape) {
 		role: "alert"
 	}, `invalid value (expected ${expectedShape})`));
 }
+/**
+* Render a {@link WalkedField} as a generator that yields HTML chunks
+* at natural boundaries (opening tag, one chunk per child, closing
+* tag). Threads `currentDepth` so cyclic walked-field graphs terminate
+* at `MAX_RENDER_DEPTH` with a recursion sentinel rather than
+* overflowing the stack.
+*/
 function* streamField(tree, value, mergedResolver, path, rawResolver, currentDepth = 0, diagnostics) {
 	if (currentDepth >= 10) {
 		yield recursionSentinelHtml(typeof tree.meta.description === "string" ? tree.meta.description : "schema");
@@ -136,7 +164,7 @@ function* streamObject(tree, value, mergedResolver, path, rawResolver, currentDe
 				class: SC_CLASSES.label,
 				for: fieldId
 			}, ...labelContent), raw(childChunks)];
-			const hint = buildHintElement(key, field.constraints);
+			const hint = buildHintElement(fieldId, field.constraints);
 			if (hint !== void 0) fieldChildren.push(hint);
 			yield serialize(h("div", { class: SC_CLASSES.field }, ...fieldChildren));
 		}
@@ -209,8 +237,12 @@ function* streamRecord(tree, value, mergedResolver, path, rawResolver, currentDe
 		const container = h("div", attrs);
 		yield yieldOpen(container);
 		for (const [key, val] of Object.entries(obj)) {
+			const childInputId = buildInputId(path, key);
 			const childHtml = renderFieldSync(valueType, val, mergedResolver, joinPath(path, key), rawResolver, currentDepth + 1, diagnostics);
-			yield serialize(h("div", { class: SC_CLASSES.field }, h("label", { class: SC_CLASSES.label }, key), raw(childHtml)));
+			yield serialize(h("div", { class: SC_CLASSES.field }, h("label", {
+				class: SC_CLASSES.label,
+				for: childInputId
+			}, key), raw(childHtml)));
 		}
 		yield yieldClose(container);
 	}
@@ -239,7 +271,7 @@ function* streamDiscriminatedUnion(tree, value, mergedResolver, path, rawResolve
 		if (activeOption !== void 0) yield* streamField(activeOption, value, mergedResolver, path, rawResolver, currentDepth + 1, diagnostics);
 		return;
 	}
-	const tabPanelId = panelId(path);
+	const tabPanelId = panelIdFor(path);
 	const wrapper = h("div", { class: SC_CLASSES.discriminatedUnion });
 	yield yieldOpen(wrapper);
 	const tabButtons = options.map((_opt, i) => {
@@ -247,8 +279,8 @@ function* streamDiscriminatedUnion(tree, value, mergedResolver, path, rawResolve
 			type: "button",
 			role: "tab",
 			class: i === activeIndex ? SC_CLASSES.tabActive : SC_CLASSES.tab,
-			id: tabId(path, i),
-			"aria-selected": i === activeIndex ? "true" : void 0,
+			id: tabIdFor(path, i),
+			"aria-selected": i === activeIndex ? "true" : "false",
 			"aria-controls": tabPanelId,
 			tabindex: i === activeIndex ? "0" : "-1"
 		}, optionLabels[i]);
@@ -256,12 +288,13 @@ function* streamDiscriminatedUnion(tree, value, mergedResolver, path, rawResolve
 	yield serialize(h("div", {
 		role: "tablist",
 		class: SC_CLASSES.tabs,
-		"aria-label": "Select variant"
+		"aria-label": "Select variant",
+		"aria-orientation": "horizontal"
 	}, ...tabButtons));
 	const panelOpen = h("div", {
 		role: "tabpanel",
 		id: tabPanelId,
-		"aria-labelledby": tabId(path, activeIndex)
+		"aria-labelledby": tabIdFor(path, activeIndex)
 	});
 	yield yieldOpen(panelOpen);
 	if (activeOption !== void 0) yield* streamField(activeOption, value, mergedResolver, path, rawResolver, currentDepth + 1, diagnostics);

package/dist/inferValue-PPXWJpbN.d.mts

@@ -0,0 +1,77 @@
+import { d as FieldOverrides, u as FieldOverride } from "./types-BrYbjC7_.mjs";
+import { SchemaIoSide } from "./core/adapter.mjs";
+import { FromJSONSchema, FromJSONSchemaMode, IsSwagger2Doc, ResolveOpenAPIRef, TypeAtPath, __SchemaInferenceFellBack } from "./core/typeInference.mjs";
+import { z } from "zod";
+
+//#region src/core/inferValue.d.ts
+/**
+ * Recursive mapped type that mirrors a schema's shape for per-field
+ * overrides. Dispatches on the schema kind in the same order as
+ * {@link InferSchemaValue} so the inferred override map tracks the
+ * inferred value shape.
+ *
+ * Exported so `<SchemaView>` and other consumers can type their
+ * `fields` prop against the same machinery `<SchemaComponent>` uses.
+ *
+ * @group Components
+ */
+type InferFields<T, Ref extends string | undefined> = IsSwagger2Doc<T> extends true ? __SchemaInferenceFellBack : T extends z.ZodType ? FieldOverrides<z.infer<T>> : T extends {
+  openapi: unknown;
+} ? Ref extends string ? FieldOverrides<ResolveOpenAPIRef<T & Record<string, unknown>, Ref>> : Record<string, FieldOverride> : T extends object ? unknown extends FromJSONSchema<T> ? Record<string, FieldOverride> : FieldOverrides<FromJSONSchema<T>> : Record<string, FieldOverride>;
+/**
+ * Infer the data type carried by the schema input.
+ *
+ * Mirrors {@link InferFields}'s dispatch order: Zod schema → `z.infer`,
+ * OpenAPI doc + ref → `ResolveOpenAPIRef`, plain JSON Schema object →
+ * `FromJSONSchema`, everything else → `unknown`. The `Mode` parameter
+ * is plumbed through to `FromJSONSchema` / `ResolveOpenAPIRef` so
+ * `readOnly` / `writeOnly` keywords participate in the inferred
+ * object shape — `"output"` for the rendered value, `"input"` for the
+ * `onChange` argument.
+ *
+ * When the schema's value type cannot be statically determined (e.g.
+ * a runtime `Record<string, unknown>` JSON Schema, or an OpenAPI doc
+ * without a ref), the result falls back to `unknown` so callers can
+ * still supply arbitrary values.
+ */
+type InferSchemaValue<T, Ref extends string | undefined, Mode extends FromJSONSchemaMode> = IsSwagger2Doc<T> extends true ? __SchemaInferenceFellBack : T extends z.ZodType ? Mode extends "input" ? z.input<T> : z.output<T> : T extends {
+  openapi: unknown;
+} ? Ref extends string ? ResolveOpenAPIRef<T & Record<string, unknown>, Ref, [], Mode> : unknown : T extends object ? FromJSONSchema<T, Record<string, never>, [], Mode> | (unknown extends FromJSONSchema<T> ? unknown : never) extends infer V ? V : unknown : unknown;
+/**
+ * Narrow an inferred value type to the sub-shape at `P`, or return
+ * the original value type when `P` is `undefined` (no path supplied).
+ */
+type NarrowAtPath<V, P extends string | undefined> = P extends string ? TypeAtPath<V, P> : V;
+/**
+ * Public alias mapping a schema input to the rendered value type.
+ *
+ * Picks the OUTPUT side (server → client) of every transform / pipe /
+ * codec. For an `<SchemaComponent io="output">` or `<SchemaView
+ * io="output">` (both defaults), this is the inferred shape of
+ * `value` and the parameter of `onChange`.
+ */
+type InferredOutputValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined> = NarrowAtPath<InferSchemaValue<T, Ref, "output">, P>;
+/**
+ * Companion to {@link InferredOutputValue} for `"input"`-mode shapes.
+ *
+ * Picks the INPUT side (client → server) of every transform / pipe /
+ * codec. Surfaces as the inferred shape of `value` / `onChange` when
+ * a consumer renders `<SchemaComponent io="input">`. For JSON Schema
+ * inputs with `readOnly`/`writeOnly` annotations, the INPUT mode
+ * omits properties marked `readOnly: true`.
+ */
+type InferredInputValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined> = NarrowAtPath<InferSchemaValue<T, Ref, "input">, P>;
+/**
+ * Resolve the schema-driven value type for either I/O direction.
+ *
+ * Thin convenience over {@link InferredOutputValue} /
+ * {@link InferredInputValue} so consumers that decide between the
+ * two at the type level (e.g. a generic wrapper component) can pass
+ * the chosen direction as a type argument rather than branch on it
+ * with conditional types. Falls back to `unknown` when the schema's
+ * value type cannot be statically inferred, identical to the
+ * underlying helpers.
+ */
+type InferredValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> = NarrowAtPath<InferSchemaValue<T, Ref, Mode>, P>;
+//#endregion
+export { InferredValue as a, InferredOutputValue as i, InferSchemaValue as n, InferredInputValue as r, InferFields as t };

package/dist/{limits-DJhgx5Ay.d.mts → limits-x4OiyJxh.d.mts}

@@ -18,11 +18,17 @@ declare const MAX_RENDER_DEPTH = 10;
  * and compile-time bounds agree.
  */
 type MaxRefDepth = 64;
+/** Runtime constant matching the type-level {@link MaxRefDepth} bound. */
 declare const MAX_REF_DEPTH: MaxRefDepth;
 /**
  * Maximum number of `$ref` hops permitted when walking a chain of
  * OpenAPI Path Item Object references. Beyond this a
  * `path-item-ref-too-deep` diagnostic is emitted and resolution stops.
+ *
+ * Also the default `maxHops` for the generic `resolveRefChain` helper
+ * in `core/refChain.ts`, so every ref-chain walker — Path Item refs,
+ * Parameter / Response refs, Reference Object chains, etc. — shares
+ * the same hop cap.
  */
 declare const MAX_PATH_ITEM_REF_HOPS = 8;
 //#endregion

package/dist/{normalise-Db1xaxgx.mjs → normalise-DB-Xtjmn.mjs}

@@ -1,5 +1,6 @@
 import { isObject } from "./core/guards.mjs";
 import { appendPointer, emitDiagnostic } from "./core/diagnostics.mjs";
+import { isPrototypePollutingKey } from "./core/uri.mjs";
 import { RECURSIVE_ANCHOR_SENTINEL } from "./core/ref.mjs";
 import { isOpenApi30, isOpenApi31, isSwagger2, matchJsonSchemaDraftUri, readJsonSchemaDialect } from "./core/version.mjs";
 import { SWAGGER_2_METHODS, rewriteSwaggerRefPrefix } from "./core/openapiConstants.mjs";
@@ -801,7 +802,18 @@ function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
 	const producesResolution = resolveSwaggerContentTypes(operation.produces, doc.produces);
 	const produces = producesResolution.types;
 	const consumes = consumesResolution.types;
-	for (const [key, value] of Object.entries(operation)) if (key !== "parameters" && key !== "responses" && key !== "produces" && key !== "consumes") result[key] = value;
+	for (const [key, value] of Object.entries(operation)) if (key !== "parameters" && key !== "responses" && key !== "produces" && key !== "consumes") {
+		if (isPrototypePollutingKey(key)) {
+			emitDiagnostic(diagnostics, {
+				code: "prototype-polluting-property",
+				message: `Refusing to copy prototype-polluting property name into normalised operation: ${key}`,
+				pointer: appendPointer(`/paths/${path}/${method}`, key),
+				detail: { propertyName: key }
+			});
+			continue;
+		}
+		result[key] = value;
+	}
 	const params = operation.parameters;
 	if (Array.isArray(params)) {
 		const nonBodyParams = [];
@@ -1038,6 +1050,15 @@ function normaliseSwaggerParameter(param, doc, diagnostics, pointer = "") {
 	const result = {};
 	for (const [key, value] of Object.entries(param)) {
 		if (PARAM_KEYWORDS_LIFTED_INTO_SCHEMA.has(key)) continue;
+		if (isPrototypePollutingKey(key)) {
+			emitDiagnostic(diagnostics, {
+				code: "prototype-polluting-property",
+				message: `Refusing to copy prototype-polluting property name into normalised parameter: ${key}`,
+				pointer: appendPointer(pointer, key),
+				detail: { propertyName: key }
+			});
+			continue;
+		}
 		result[key] = value;
 	}
 	if (typeof param.type === "string") if (param.type === "file" && param.in !== "formData") {
@@ -1186,7 +1207,18 @@ function normaliseSwaggerResponses(responses, doc, produces, producesSource, dia
 function normaliseSwaggerSingleResponse(response, doc, produces, producesSource = "synthesised", diagnostics, path, method, statusCode) {
 	const resolved = resolveSwaggerResponse(response, doc);
 	const normalised = {};
-	for (const [key, value] of Object.entries(resolved)) if (key !== "schema" && key !== "headers") normalised[key] = value;
+	for (const [key, value] of Object.entries(resolved)) if (key !== "schema" && key !== "headers") {
+		if (isPrototypePollutingKey(key)) {
+			emitDiagnostic(diagnostics, {
+				code: "prototype-polluting-property",
+				message: `Refusing to copy prototype-polluting property name into normalised response: ${key}`,
+				pointer: path !== void 0 && method !== void 0 && statusCode !== void 0 ? appendPointer(`/paths/${path}/${method}/responses/${statusCode}`, key) : key,
+				detail: { propertyName: key }
+			});
+			continue;
+		}
+		normalised[key] = value;
+	}
 	const schema = resolved.schema;
 	if (isObject(schema)) {
 		const content = {};
@@ -1232,6 +1264,15 @@ function normaliseSwaggerHeader(header, diagnostics, pointer = "") {
 	const result = {};
 	for (const [key, value] of Object.entries(header)) {
 		if (PARAM_KEYWORDS_LIFTED_INTO_SCHEMA.has(key)) continue;
+		if (isPrototypePollutingKey(key)) {
+			emitDiagnostic(diagnostics, {
+				code: "prototype-polluting-property",
+				message: `Refusing to copy prototype-polluting property name into normalised header: ${key}`,
+				pointer: appendPointer(pointer, key),
+				detail: { propertyName: key }
+			});
+			continue;
+		}
 		result[key] = value;
 	}
 	if (typeof header.type === "string") result.schema = buildSchemaFromSwaggerParameterShape(header);

package/dist/openapi/ApiCallbacks.d.mts

@@ -1,14 +1,26 @@
-import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { w as SchemaMeta } from "../types-BrYbjC7_.mjs";
 import { CallbackInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/ApiCallbacks.d.ts
+/**
+ * Props accepted by {@link ApiCallbacks}.
+ *
+ * @group OpenAPI
+ */
 interface ApiCallbacksProps {
   /** Callback definitions for this operation. */
   callbacks: CallbackInfo[];
   /** Optional meta overrides. */
   meta?: SchemaMeta;
 }
+/**
+ * Render OpenAPI callback definitions declared on an operation. Each
+ * callback name is displayed alongside its operations. Read-only —
+ * intended for documentation rather than interactive editing.
+ *
+ * @group OpenAPI
+ */
 declare function ApiCallbacks({
   callbacks
 }: ApiCallbacksProps): ReactNode;

package/dist/openapi/ApiCallbacks.mjs

@@ -1,5 +1,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/openapi/ApiCallbacks.tsx
+/**
+* Render OpenAPI callback definitions declared on an operation. Each
+* callback name is displayed alongside its operations. Read-only —
+* intended for documentation rather than interactive editing.
+*
+* @group OpenAPI
+*/
 function ApiCallbacks({ callbacks }) {
 	if (callbacks.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {

package/dist/openapi/ApiLinks.d.mts

@@ -1,14 +1,26 @@
-import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { w as SchemaMeta } from "../types-BrYbjC7_.mjs";
 import { LinkInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/ApiLinks.d.ts
+/**
+ * Props accepted by {@link ApiLinks}.
+ *
+ * @group OpenAPI
+ */
 interface ApiLinksProps {
   /** Link definitions for a response. */
   links: LinkInfo[];
   /** Optional meta overrides. */
   meta?: SchemaMeta;
 }
+/**
+ * Render OpenAPI link definitions attached to a response. Displays each
+ * link's name, target operation (`operationId` or `operationRef`),
+ * description, and parameter mappings. Read-only.
+ *
+ * @group OpenAPI
+ */
 declare function ApiLinks({
   links
 }: ApiLinksProps): ReactNode;

package/dist/openapi/ApiLinks.mjs

@@ -1,5 +1,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/openapi/ApiLinks.tsx
+/**
+* Render OpenAPI link definitions attached to a response. Displays each
+* link's name, target operation (`operationId` or `operationRef`),
+* description, and parameter mappings. Read-only.
+*
+* @group OpenAPI
+*/
 function ApiLinks({ links }) {
 	if (links.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {

package/dist/openapi/ApiResponseHeaders.d.mts

@@ -1,14 +1,26 @@
-import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { w as SchemaMeta } from "../types-BrYbjC7_.mjs";
 import { HeaderInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/ApiResponseHeaders.d.ts
+/**
+ * Props accepted by {@link ApiResponseHeaders}.
+ *
+ * @group OpenAPI
+ */
 interface ApiResponseHeadersProps {
   /** Header definitions for a response. */
   headers: Map<string, HeaderInfo>;
   /** Optional meta overrides. */
   meta?: SchemaMeta;
 }
+/**
+ * Render the header definitions declared on an OpenAPI response. Shows
+ * each header's name, description, type, required flag, and deprecation
+ * marker. Read-only.
+ *
+ * @group OpenAPI
+ */
 declare function ApiResponseHeaders({
   headers
 }: ApiResponseHeadersProps): ReactNode;

package/dist/openapi/ApiResponseHeaders.mjs

@@ -1,5 +1,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/openapi/ApiResponseHeaders.tsx
+/**
+* Render the header definitions declared on an OpenAPI response. Shows
+* each header's name, description, type, required flag, and deprecation
+* marker. Read-only.
+*
+* @group OpenAPI
+*/
 function ApiResponseHeaders({ headers }) {
 	if (headers.size === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {

package/dist/openapi/ApiSecurity.d.mts

@@ -1,8 +1,13 @@
-import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { w as SchemaMeta } from "../types-BrYbjC7_.mjs";
 import { SecurityRequirement, SecurityScheme } from "./parser.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/ApiSecurity.d.ts
+/**
+ * Props accepted by {@link ApiSecurity}.
+ *
+ * @group OpenAPI
+ */
 interface ApiSecurityProps {
   /** Security requirements for this operation. */
   requirements: SecurityRequirement[];
@@ -11,6 +16,14 @@ interface ApiSecurityProps {
   /** Optional meta overrides. */
   meta?: SchemaMeta;
 }
+/**
+ * Render the security requirements that apply to an OpenAPI operation,
+ * resolved against the document's component security schemes. Displays
+ * each scheme's type, description, location, scopes, and the full set
+ * of OAuth 2 flows when applicable. Read-only.
+ *
+ * @group OpenAPI
+ */
 declare function ApiSecurity({
   requirements,
   schemes

package/dist/openapi/ApiSecurity.mjs

@@ -1,4 +1,5 @@
 import { isObject } from "../core/guards.mjs";
+import { isSafeHyperlink } from "../core/uri.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/openapi/ApiSecurity.tsx
 /**
@@ -53,6 +54,14 @@ function extractFlows(flows) {
 	}
 	return result;
 }
+/**
+* Render the security requirements that apply to an OpenAPI operation,
+* resolved against the document's component security schemes. Displays
+* each scheme's type, description, location, scopes, and the full set
+* of OAuth 2 flows when applicable. Read-only.
+*
+* @group OpenAPI
+*/
 function ApiSecurity({ requirements, schemes }) {
 	if (requirements.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
@@ -105,11 +114,14 @@ function SchemeDetails({ scheme }) {
 			"data-security-apikey-in": true,
 			children: scheme.location
 		}),
-		scheme.openIdConnectUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+		scheme.openIdConnectUrl !== void 0 && (isSafeHyperlink(scheme.openIdConnectUrl) ? /* @__PURE__ */ jsx("a", {
 			"data-security-openid-url": true,
 			href: scheme.openIdConnectUrl,
 			children: scheme.openIdConnectUrl
-		}),
+		}) : /* @__PURE__ */ jsx("span", {
+			"data-security-openid-url": true,
+			children: scheme.openIdConnectUrl
+		})),
 		flows.length > 0 && /* @__PURE__ */ jsx("section", {
 			"data-security-flows": true,
 			children: flows.map((flow) => /* @__PURE__ */ jsx(FlowDetails, { flow }, flow.name))
@@ -124,21 +136,30 @@ function FlowDetails({ flow }) {
 				"data-security-flow-name": true,
 				children: flow.name
 			}),
-			flow.authorizationUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+			flow.authorizationUrl !== void 0 && (isSafeHyperlink(flow.authorizationUrl) ? /* @__PURE__ */ jsx("a", {
 				"data-security-flow-authorization-url": true,
 				href: flow.authorizationUrl,
 				children: flow.authorizationUrl
-			}),
-			flow.tokenUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+			}) : /* @__PURE__ */ jsx("span", {
+				"data-security-flow-authorization-url": true,
+				children: flow.authorizationUrl
+			})),
+			flow.tokenUrl !== void 0 && (isSafeHyperlink(flow.tokenUrl) ? /* @__PURE__ */ jsx("a", {
 				"data-security-flow-token-url": true,
 				href: flow.tokenUrl,
 				children: flow.tokenUrl
-			}),
-			flow.refreshUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+			}) : /* @__PURE__ */ jsx("span", {
+				"data-security-flow-token-url": true,
+				children: flow.tokenUrl
+			})),
+			flow.refreshUrl !== void 0 && (isSafeHyperlink(flow.refreshUrl) ? /* @__PURE__ */ jsx("a", {
 				"data-security-flow-refresh-url": true,
 				href: flow.refreshUrl,
 				children: flow.refreshUrl
-			}),
+			}) : /* @__PURE__ */ jsx("span", {
+				"data-security-flow-refresh-url": true,
+				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", {

package/dist/openapi/bundle.d.mts

@@ -27,6 +27,37 @@
  * Resolver function for external documents.
  * Called with the URI portion of an external $ref (everything before `#`).
  * Returns the parsed JSON document.
+ *
+ * ### Security warning — SSRF and local-file disclosure
+ *
+ * Consumers MUST validate the URI before fetching the target document.
+ * The bundler hands the resolver the raw `$ref` URI from the OpenAPI
+ * document — which is typically user-controlled — and any network or
+ * filesystem access the resolver performs runs with the host
+ * application's full privileges. An attacker-crafted document that
+ * references an internal endpoint or a local filesystem path will
+ * happily exfiltrate or expose data the application never intended to
+ * surface.
+ *
+ * At a minimum the resolver should:
+ *
+ * - Refuse non-`https:` schemes by default. Permit `http:` only on an
+ *   explicit allow-list. Refuse `file:`, `data:`, `javascript:`,
+ *   `ftp:`, `gopher:`, and every other scheme outright.
+ * - Resolve the URI's hostname and refuse loopback addresses
+ *   (`127.0.0.0/8`, `::1`), link-local addresses (`169.254.0.0/16`,
+ *   `fe80::/10`), private ranges (`10.0.0.0/8`, `172.16.0.0/12`,
+ *   `192.168.0.0/16`, `fc00::/7`), and cloud-metadata IPs
+ *   (`169.254.169.254`, `fd00:ec2::254`).
+ * - Apply a strict allow-list of permitted hosts where possible.
+ * - Set request timeouts and a maximum response size.
+ * - Disable HTTP redirects, or re-validate the redirected URL against
+ *   the same denylist before following.
+ * - Reject responses that are not `application/json` or
+ *   `application/yaml`.
+ *
+ * The bundler itself performs no validation — that responsibility sits
+ * exclusively with the resolver implementation supplied by the caller.
  */
 type BundleResolver = (uri: string) => unknown;
 /**