schema-components 1.18.1 → 1.20.0

package/dist/react/headlessRenderers.mjs

@@ -1,5 +1,6 @@
 import { isObject } from "../core/guards.mjs";
 import { sortFieldsByOrder } from "../core/fieldOrder.mjs";
+import { isSafeHyperlink, isSafeMailtoAddress } from "../core/uri.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { isValidElement, useCallback, useEffect, useRef } from "react";
 //#region src/react/headlessRenderers.tsx
@@ -83,13 +84,13 @@ function renderString(props) {
 			children: "—"
 		});
 		const format = props.constraints.format;
-		if (format === "email") return /* @__PURE__ */ jsx("a", {
+		if (format === "email" && isSafeMailtoAddress(strValue)) return /* @__PURE__ */ jsx("a", {
 			href: `mailto:${strValue}`,
 			id,
 			"aria-readonly": "true",
 			children: strValue
 		});
-		if (format === "uri" || format === "url") return /* @__PURE__ */ jsx("a", {
+		if ((format === "uri" || format === "url") && isSafeHyperlink(strValue)) return /* @__PURE__ */ jsx("a", {
 			href: strValue,
 			id,
 			"aria-readonly": "true",
@@ -595,6 +596,155 @@ function renderRecursive(props) {
 		" (recursive)"
 	] }) });
 }
+/**
+* Render a literal field — `z.literal("a")` or `{ const: 5 }`.
+*
+* Literals are non-editable by nature (the value is fixed at the schema
+* level), so both read-only and editable modes display the literal value(s).
+* Multiple literals (`z.literal(["a", "b"])`) render comma-separated.
+*/
+function renderLiteral(props) {
+	const id = inputId(props.path);
+	if (props.tree.type !== "literal") return null;
+	const values = props.tree.literalValues;
+	if (values.length === 0) return /* @__PURE__ */ jsx("span", {
+		id,
+		"aria-readonly": "true",
+		children: "—"
+	});
+	return /* @__PURE__ */ jsx("span", {
+		id,
+		"aria-readonly": "true",
+		children: values.map((v) => v === null ? "null" : String(v)).join(", ")
+	});
+}
+/**
+* Render a null field — `z.null()` or `{ type: "null" }`.
+*
+* The only valid value is `null`, so render an em-dash placeholder
+* regardless of mode. There is nothing the user can usefully change.
+*/
+function renderNull(props) {
+	return /* @__PURE__ */ jsx("span", {
+		id: inputId(props.path),
+		"aria-readonly": "true",
+		children: "—"
+	});
+}
+/**
+* Render a never field — `z.never()` or `{ not: {} }` / `false` schema.
+*
+* `never` indicates a position that cannot hold any value. We render a
+* visible placeholder rather than throwing because some valid schemas
+* intentionally contain `never` branches (e.g. exhaustive discriminated
+* unions), and a runtime crash on render would be worse than a visible
+* indicator.
+*/
+function renderNever(props) {
+	return /* @__PURE__ */ jsx("span", {
+		id: inputId(props.path),
+		"aria-readonly": "true",
+		className: "sc-never",
+		children: /* @__PURE__ */ jsx("em", { children: "never matches" })
+	});
+}
+/**
+* Render a tuple field — `z.tuple([z.string(), z.number()])` or
+* `{ prefixItems: [...] }`.
+*
+* Positional rendering: each `prefixItems` entry is rendered at its index.
+* The structural index (e.g. `[0]`) is passed as the path suffix so
+* children get unique ids and labels.
+*/
+function renderTuple(props) {
+	if (props.tree.type !== "tuple") return null;
+	const prefixItems = props.tree.prefixItems;
+	const restItems = props.tree.restItems;
+	const arr = Array.isArray(props.value) ? props.value : [];
+	if (prefixItems.length === 0 && restItems === void 0 && arr.length === 0) return null;
+	const restCount = restItems !== void 0 ? Math.max(arr.length - prefixItems.length, 0) : 0;
+	return /* @__PURE__ */ jsxs("div", {
+		role: "group",
+		"aria-label": props.meta.description ?? void 0,
+		children: [prefixItems.map((element, i) => {
+			const itemValue = arr[i];
+			const childOnChange = (v) => {
+				const next = arr.slice();
+				next[i] = v;
+				props.onChange(next);
+			};
+			return /* @__PURE__ */ jsx("div", { children: toReactNode(props.renderChild(element, itemValue, childOnChange, `[${String(i)}]`)) }, String(i));
+		}), restItems !== void 0 && Array.from({ length: restCount }, (_, j) => {
+			const i = prefixItems.length + j;
+			const itemValue = arr[i];
+			const childOnChange = (v) => {
+				const next = arr.slice();
+				next[i] = v;
+				props.onChange(next);
+			};
+			return /* @__PURE__ */ jsx("div", { children: toReactNode(props.renderChild(restItems, itemValue, childOnChange, `[${String(i)}]`)) }, `rest-${String(i)}`);
+		})]
+	});
+}
+/**
+* Render a conditional field — JSON Schema `if`/`then`/`else`.
+*
+* Conditional schemas describe constraints rather than a single value
+* shape, so the renderer surfaces each clause as a labelled fieldset.
+* This mirrors the HTML renderer's annotation approach and gives a
+* predictable structure for theme adapters that want to override it.
+*/
+function renderConditional(props) {
+	if (props.tree.type !== "conditional") return null;
+	const { ifClause, thenClause, elseClause } = props.tree;
+	return /* @__PURE__ */ jsxs("fieldset", {
+		className: "sc-conditional",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "sc-conditional-if",
+				children: [
+					/* @__PURE__ */ jsx("strong", { children: "if:" }),
+					" ",
+					toReactNode(props.renderChild(ifClause, props.value, props.onChange))
+				]
+			}),
+			thenClause !== void 0 && /* @__PURE__ */ jsxs("div", {
+				className: "sc-conditional-then",
+				children: [
+					/* @__PURE__ */ jsx("strong", { children: "then:" }),
+					" ",
+					toReactNode(props.renderChild(thenClause, props.value, props.onChange))
+				]
+			}),
+			elseClause !== void 0 && /* @__PURE__ */ jsxs("div", {
+				className: "sc-conditional-else",
+				children: [
+					/* @__PURE__ */ jsx("strong", { children: "else:" }),
+					" ",
+					toReactNode(props.renderChild(elseClause, props.value, props.onChange))
+				]
+			})
+		]
+	});
+}
+/**
+* Render a negation field — JSON Schema `{ not: { ... } }`.
+*
+* Negation describes a constraint ("value must NOT match this schema")
+* rather than a value shape. The renderer surfaces the negated schema
+* beneath an explanatory preamble.
+*/
+function renderNegation(props) {
+	if (props.tree.type !== "negation") return null;
+	return /* @__PURE__ */ jsxs("fieldset", {
+		className: "sc-negation",
+		children: [
+			/* @__PURE__ */ jsx("strong", { children: "Must NOT match:" }),
+			" ",
+			toReactNode(props.renderChild(props.tree.negated, props.value, props.onChange))
+		]
+	});
+}
 function renderUnknown(props) {
 	const id = inputId(props.path);
 	if (props.readOnly) {
@@ -627,4 +777,4 @@ function matchUnionOption(options, value) {
 	if (typeof value === "object" && value !== null) return options.find((o) => o.type === "object");
 }
 //#endregion
-export { defaultRecordValue, discriminatedUnionValueForTab, inputId, nextRecordKey, renameRecordKey, renderArray, renderBoolean, renderDiscriminatedUnion, renderEnum, renderFile, renderNumber, renderObject, renderRecord, renderRecursive, renderString, renderUnion, renderUnknown, toReactNode };
+export { defaultRecordValue, discriminatedUnionValueForTab, inputId, nextRecordKey, renameRecordKey, renderArray, renderBoolean, renderConditional, renderDiscriminatedUnion, renderEnum, renderFile, renderLiteral, renderNegation, renderNever, renderNull, renderNumber, renderObject, renderRecord, renderRecursive, renderString, renderTuple, renderUnion, renderUnknown, toReactNode };

package/dist/{ref-Ckt5liZs.d.mts → ref-C8JbwfiS.d.mts}

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "./diagnostics-BYk63jsC.mjs";
+import { i as DiagnosticsOptions } from "./diagnostics-CbBPsxSt.mjs";
 
 //#region src/core/ref.d.ts
 /**

package/dist/{renderer-BAGoX4AK.d.mts → renderer-SOIbJBtk.d.mts}

@@ -1,4 +1,4 @@
-import { D as StringConstraints, M as WalkedField, T as SchemaMeta, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "./types-D_5ST7SS.mjs";
+import { D as StringConstraints, M as WalkedField, T as SchemaMeta, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "./types-C9zw9wbX.mjs";
 
 //#region src/core/renderer.d.ts
 /**
@@ -98,6 +98,7 @@ interface ComponentResolver {
   string?: RenderFunction;
   number?: RenderFunction;
   boolean?: RenderFunction;
+  null?: RenderFunction;
   enum?: RenderFunction;
   object?: RenderFunction;
   array?: RenderFunction;
@@ -110,6 +111,7 @@ interface ComponentResolver {
   recursive?: RenderFunction;
   literal?: RenderFunction;
   file?: RenderFunction;
+  never?: RenderFunction;
   unknown?: RenderFunction;
 }
 /** An HTML render function returns a string. */
@@ -122,6 +124,7 @@ interface HtmlResolver {
   string?: HtmlRenderFunction;
   number?: HtmlRenderFunction;
   boolean?: HtmlRenderFunction;
+  null?: HtmlRenderFunction;
   enum?: HtmlRenderFunction;
   object?: HtmlRenderFunction;
   array?: HtmlRenderFunction;
@@ -134,13 +137,16 @@ interface HtmlResolver {
   recursive?: HtmlRenderFunction;
   literal?: HtmlRenderFunction;
   file?: HtmlRenderFunction;
+  never?: HtmlRenderFunction;
   unknown?: HtmlRenderFunction;
 }
-declare const RESOLVER_KEYS: readonly ["string", "number", "boolean", "enum", "object", "array", "tuple", "record", "union", "discriminatedUnion", "conditional", "negation", "recursive", "literal", "file", "unknown"];
+declare const RESOLVER_KEYS: readonly ["string", "number", "boolean", "null", "enum", "object", "array", "tuple", "record", "union", "discriminatedUnion", "conditional", "negation", "recursive", "literal", "file", "never", "unknown"];
 type ResolverKey = (typeof RESOLVER_KEYS)[number];
 /**
  * Map a schema type to the resolver key that handles it.
- * `discriminatedUnion` → `union`. Unknown types → `unknown`.
+ * Every WalkedField variant has a direct resolver key — exhaustive switch
+ * ensures new variants surface as a type error rather than silently
+ * falling through to "unknown".
  */
 declare function typeToKey(type: WalkedField["type"]): ResolverKey;
 /**

package/dist/themes/mantine.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-BAGoX4AK.mjs";
+import { r as ComponentResolver } from "../renderer-SOIbJBtk.mjs";
 
 //#region src/themes/mantine.d.ts
 /**

package/dist/themes/mui.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-BAGoX4AK.mjs";
+import { r as ComponentResolver } from "../renderer-SOIbJBtk.mjs";
 
 //#region src/themes/mui.d.ts
 /**

package/dist/themes/radix.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-BAGoX4AK.mjs";
+import { r as ComponentResolver } from "../renderer-SOIbJBtk.mjs";
 
 //#region src/themes/radix.d.ts
 /**

package/dist/themes/shadcn.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-BAGoX4AK.mjs";
+import { r as ComponentResolver } from "../renderer-SOIbJBtk.mjs";
 
 //#region src/themes/shadcn.d.ts
 declare const shadcnResolver: ComponentResolver;

package/dist/{typeInference-5JiqIZ8t.d.mts → typeInference-CDoD_LZ_.d.mts}

@@ -1,6 +1,43 @@
-import { d as FieldOverrides, u as FieldOverride } from "./types-D_5ST7SS.mjs";
+import { d as FieldOverrides, u as FieldOverride } from "./types-C9zw9wbX.mjs";
+import { z } from "zod";
 
 //#region src/core/typeInference.d.ts
+/**
+ * Zod 4 types that `z.toJSONSchema()` rejects at runtime because they
+ * have no JSON Schema representation. The runtime adapter
+ * (`packages/core/src/core/adapter.ts` lines 106-116) catches the
+ * thrown error and surfaces it as a `SchemaNormalisationError` with
+ * kind `zod-type-unrepresentable` — but the failure only happens on
+ * first render. Statically rejecting these types at the props boundary
+ * gives the same diagnostic at compile time.
+ *
+ * SOURCE-OF-TRUTH: list mirrors `UNREPRESENTABLE_ZOD_TYPES` in
+ * `adapter.ts`. Add or remove entries here whenever the runtime list
+ * changes.
+ */
+type UnrepresentableZodType = z.ZodBigInt | z.ZodDate | z.ZodMap | z.ZodSet | z.ZodSymbol | z.ZodFunction | z.ZodUndefined | z.ZodVoid | z.ZodNaN | z.ZodCodec;
+/**
+ * Brand returned in place of a rejected Zod input. The descriptive
+ * literal is what TypeScript displays when the rejection fires, so
+ * developers see why their schema is incompatible.
+ */
+interface UnrepresentableZodSchemaError {
+  readonly __schemaComponentsError: "Zod 4 type has no JSON Schema representation. See SchemaNormalisationError code 'zod-type-unrepresentable'.";
+}
+/**
+ * Reject Zod 4 inputs whose runtime conversion is known to throw.
+ *
+ * - When `T` is one of the {@link UnrepresentableZodType} variants, the
+ *   resolved type is {@link UnrepresentableZodSchemaError}, which is
+ *   not assignable from any legitimate Zod / JSON Schema / OpenAPI
+ *   input — so the prop fails to typecheck.
+ * - Anything else (Zod 4 schemas that DO convert, JSON Schema literals,
+ *   OpenAPI documents, `unknown` for runtime inputs) passes through
+ *   unchanged.
+ *
+ * Wrapped in a tuple to suppress distribution over union types.
+ */
+type RejectUnrepresentableZod<T> = [T] extends [UnrepresentableZodType] ? UnrepresentableZodSchemaError : T;
 /**
  * Convert a readonly tuple/array of values to a union type.
  * Handles both `as const` readonly tuples and mutable arrays.
@@ -30,6 +67,17 @@ type ArrayToUnion<A> = A extends readonly unknown[] ? A[number] : never;
  * - patternProperties -> merged into loose index signature
  */
 type FromJSONSchema<S, Defs extends Record<string, unknown> = Record<string, never>> = S extends {
+  nullable: true;
+} ?
+/**
+* OpenAPI 3.0 `nullable: true` — surface the keyword wherever it
+* appears (not just inside `ResolveMaybeRef`). The runtime path
+* rewrites this to `anyOf: [T, { type: "null" }]` via
+* `normaliseOpenApi30Node` (`openapi30.ts`). Mirroring at the
+* `FromJSONSchema` level means nested fields inside refs preserve
+* nullability when resolved.
+*/
+FromJSONSchema<Omit<S, "nullable">, Defs> | null : S extends {
   $ref: infer R extends string;
 } ? ResolveSchemaRef<R, Defs> : S extends {
   $recursiveRef: string;
@@ -113,9 +161,16 @@ type DEFAULT_MAX_DEPTH = 10;
  * Supports:
  * - `#` (root)
  * - `#/$defs/Name` and `#/definitions/Name` (named definitions)
+ * - `#/components/schemas/Name` (OpenAPI 3.x component schemas)
  * - `#SomeName` ($anchor, $dynamicAnchor resolved from definitions)
+ *
+ * `#/components/schemas/` is resolved here for parity with the runtime's
+ * `dereference` (`ref.ts` line 217), which walks any `#/...` JSON Pointer
+ * uniformly. When the runtime walker encounters an inline `$ref` inside
+ * a Zod-converted or hand-written JSON Schema that points into the
+ * OpenAPI component tree, this branch produces the corresponding type.
  */
-type ResolveSchemaRef<R extends string, Defs extends Record<string, unknown>, Depth extends number = 0> = Depth extends DEFAULT_MAX_DEPTH ? __SchemaInferenceFellBack : R extends "#" ? unknown : R extends `#/$defs/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#/definitions/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#${infer AnchorName}` ? AnchorName extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[AnchorName], Defs>> : unknown : unknown;
+type ResolveSchemaRef<R extends string, Defs extends Record<string, unknown>, Depth extends number = 0> = Depth extends DEFAULT_MAX_DEPTH ? __SchemaInferenceFellBack : R extends "#" ? unknown : R extends `#/$defs/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#/definitions/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#/components/schemas/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#${infer AnchorName}` ? AnchorName extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[AnchorName], Defs>> : unknown : unknown;
 /**
  * Merge an allOf array into an intersection type.
  */
@@ -178,12 +233,21 @@ type OmitArrayHelpers<S> = Omit<S, "prefixItems" | "items" | "additionalProperti
 /**
  * Parse an array schema: prefixItems -> tuple, items -> T[], or unknown[].
  *
+ * Draft 04 used tuple-form `items` (an array of schemas) for tuple typing;
+ * Draft 2020-12 renamed this to `prefixItems`. The runtime normaliser in
+ * `packages/core/src/core/normalise.ts` (lines 526-534) rewrites the legacy
+ * form to `prefixItems` before the walker sees it. We mirror that rewrite
+ * here so `as const` literals using the legacy form infer the same tuple
+ * type at compile time.
+ *
  * `contains` / `minContains` / `maxContains` constrain elements at runtime
  * but don't change the compile-time array element type.
  */
 type ArraySchemaToTs<S, Defs extends Record<string, unknown>> = S extends {
   prefixItems: infer P;
 } ? PrefixItemsToTuple<P, Defs> : S extends {
+  items: infer I extends readonly unknown[];
+} ? PrefixItemsToTuple<I, Defs> : S extends {
   items: infer I;
 } ? FromJSONSchema<I, Defs>[] : unknown[];
 /**
@@ -243,14 +307,26 @@ type ExtractRawDefs<S> = S extends {
 } ? D extends Record<string, unknown> ? D : Record<string, never> : Record<string, never>;
 /**
  * Build a map of `$anchor` name -> schema from a definitions block.
- * Scans each definition value for `$anchor` or `$dynamicAnchor` and
- * creates entries like `{ Tree: <schema-with-$anchor-Tree> }`.
+ * Scans each definition value for `$anchor`, `$dynamicAnchor`, or the
+ * Draft 2019-09 `$recursiveAnchor` keyword and creates entries like
+ * `{ Tree: <schema-with-$anchor-Tree> }`.
+ *
+ * SOURCE-OF-TRUTH: mirrors `normaliseDraft201909NodeWithContext` in
+ * `packages/core/src/core/normalise.ts` (lines 638-650), which rewrites
+ * `$recursiveAnchor: true` to `$anchor: "__recursive__"` and a string
+ * `$recursiveAnchor: "name"` to `$anchor: "name"`. The corresponding
+ * `$recursiveRef: "#"` therefore resolves through the same `Defs` map
+ * as a modern `$ref: "#__recursive__"`.
  */
 type ExtractAnchors<D extends Record<string, unknown>> = { [K in keyof D as D[K] extends {
   $anchor: infer A extends string;
 } ? A : D[K] extends {
   $dynamicAnchor: infer A extends string;
-} ? A : never]: D[K] };
+} ? A : D[K] extends {
+  $recursiveAnchor: infer A extends string;
+} ? A : D[K] extends {
+  $recursiveAnchor: true;
+} ? "__recursive__" : never]: D[K] };
 /**
  * Convert a union to an intersection.
  * `A | B` -> `A & B`. Used for allOf merging.
@@ -275,92 +351,161 @@ type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) exten
 type ResolveOpenAPIRef<Spec extends Record<string, unknown>, Ref extends string> = Ref extends `#/components/schemas/${infer Name}` ? Spec["components"] extends Record<string, unknown> ? Spec["components"]["schemas"] extends Record<string, unknown> ? Name extends keyof Spec["components"]["schemas"] ? FromJSONSchema<Spec["components"]["schemas"][Name]> : unknown : unknown : unknown : Ref extends `#/definitions/${infer Name}` ? Spec["definitions"] extends Record<string, unknown> ? Name extends keyof Spec["definitions"] ? FromJSONSchema<Spec["definitions"][Name]> : unknown : unknown : Ref extends `#/paths/${infer PathRest}` ? ResolvePathBasedRef<Spec, PathRest> : unknown;
 /**
  * Resolve a path-based $ref after the `#/paths/` prefix.
- * Splits on `/` and navigates the document tree.
+ * Splits on `/` and navigates the document tree, decoding JSON Pointer
+ * tilde escapes (`~1` -> `/`, `~0` -> `~`) on every segment.
  *
- * Note: JSON Pointer tilde encoding (~1 for /, ~0 for ~) is not decoded
- * at the type level. For `as const` literals, use the literal path
- * character directly (e.g. `#/paths//pets/get/...`).
+ * SOURCE-OF-TRUTH: mirrors runtime `dereference` in
+ * `packages/core/src/core/ref.ts` (line 226), which applies the same
+ * `~1` -> `/`, `~0` -> `~` substitutions per RFC 6901 §4. The runtime
+ * uses ordered string replacement; the type-level mirror does the same
+ * via {@link DecodeJsonPointerSegment}.
  */
 type ResolvePathBasedRef<Spec extends Record<string, unknown>, PathRest extends string> = Spec["paths"] extends Record<string, unknown> ? ResolvePathSegments<Spec["paths"], SplitPath<PathRest>> : unknown;
+/**
+ * Replace every occurrence of `From` with `To` inside `S`.
+ *
+ * Pure type-level alternative to `String.prototype.replaceAll` used for
+ * JSON Pointer escape decoding. Terminates when no further match is
+ * found in the tail.
+ */
+type ReplaceAll<S extends string, From extends string, To extends string> = S extends `${infer Head}${From}${infer Tail}` ? `${Head}${To}${ReplaceAll<Tail, From, To>}` : S;
+/**
+ * Decode a single JSON Pointer reference token per RFC 6901 §4:
+ * apply `~1` -> `/` first, then `~0` -> `~`. The order matters — an
+ * encoded `~` containing a literal `1` (e.g. `~01`) must remain `~1`
+ * after decoding, which only works when `~1` is processed first.
+ */
+type DecodeJsonPointerSegment<S extends string> = ReplaceAll<ReplaceAll<S, "~1", "/">, "~0", "~">;
 /**
  * Split a path string on `/` into a tuple of segments.
  * The first segment is the path key (may be empty for `/pets` -> `""` / `"pets"`).
  */
 type SplitPath<S extends string> = S extends `${infer Head}/${infer Tail}` ? [Head, ...SplitPath<Tail>] : [S];
 /**
- * Recursively navigate into a document object by path segments.
+ * Recursively navigate into a document object by path segments. Each
+ * segment is JSON-Pointer-decoded before indexing so encoded forms such
+ * as `~1pets` correctly resolve to the `"/pets"` key.
  */
-type ResolvePathSegments<Doc, Segs extends string[]> = Segs extends [infer Head extends string, ...infer Rest extends string[]] ? Doc extends Record<string, unknown> ? Rest extends [] ? Doc[Head] : ResolvePathSegments<Doc[Head], Rest> : unknown : unknown;
+type ResolvePathSegments<Doc, Segs extends string[]> = Segs extends [infer Head extends string, ...infer Rest extends string[]] ? Doc extends Record<string, unknown> ? DecodeJsonPointerSegment<Head> extends infer Decoded extends string ? Rest extends [] ? Doc[Decoded] : ResolvePathSegments<Doc[Decoded], Rest> : unknown : unknown : unknown;
 /** Navigate to a path item in an OpenAPI document. */
 type PathItemOf<Doc, Path extends string> = Doc extends {
   paths: Record<string, unknown>;
 } ? Path extends keyof Doc["paths"] ? Doc["paths"][Path] : unknown : unknown;
 /** Navigate to an operation within a path item. */
 type OperationOf<PathItem, Method extends string> = PathItem extends Record<string, unknown> ? Method extends keyof PathItem ? PathItem[Method] : unknown : unknown;
-/** Extract the schema from request body content (any media type). */
+/**
+ * Extract the schema from request body content (any media type).
+ *
+ * `Record<string, { schema: infer S }>` already subsumes the previous
+ * `application/json`-specific branch — if the JSON content matches the
+ * specific shape it also matches the general index-signature pattern.
+ * The narrower branch was therefore unreachable and has been removed.
+ */
 type RequestBodySchemaOf<Op> = Op extends {
   requestBody: {
     content: Record<string, {
       schema: infer S;
     }>;
   };
-} ? S : Op extends {
-  requestBody: {
-    content: {
-      "application/json": {
-        schema: infer S;
-      };
-    };
-  };
 } ? S : unknown;
-/** Extract the schema from response content (any media type). */
+/**
+ * Extract the schema from response content (any media type).
+ *
+ * Same rationale as `RequestBodySchemaOf`: the index-signature branch
+ * subsumes the `application/json` branch, which was unreachable.
+ */
 type ResponseSchemaOf<Op, Status extends string> = Op extends {
   responses: Record<string, unknown>;
 } ? Status extends keyof Op["responses"] ? Op["responses"][Status] extends {
   content: Record<string, {
     schema: infer S;
   }>;
-} ? S : Op["responses"][Status] extends {
-  content: {
-    "application/json": {
-      schema: infer S;
-    };
-  };
 } ? S : unknown : unknown : unknown;
-/** Resolve a schema that may be a $ref pointer. */
+/**
+ * Resolve a schema that may be a `$ref` pointer.
+ *
+ * The `nullable: true` handling lives inside `FromJSONSchema` so it
+ * applies uniformly to direct schemas, refs, and nested fields. This
+ * helper only dispatches between ref-resolution and plain inference.
+ */
 type ResolveMaybeRef<Doc, S> = S extends {
   $ref: infer R extends string;
-} ? ResolveOpenAPIRef<Doc & Record<string, unknown>, R> : S extends {
-  nullable: true;
-} & Record<string, unknown> ? FromJSONSchema<Omit<S, "nullable">> | null : S extends Record<string, unknown> ? FromJSONSchema<S> : unknown;
+} ? ResolveOpenAPIRef<Doc & Record<string, unknown>, R> : S extends Record<string, unknown> ? FromJSONSchema<S> : unknown;
 /** Extract parameter names from an operation. */
 type ParameterNamesOf<Doc, Path extends string, Method extends string> = OperationOf<PathItemOf<Doc, Path>, Method> extends {
   parameters: readonly unknown[];
 } ? OperationOf<PathItemOf<Doc, Path>, Method>["parameters"][number] extends {
   name: infer N;
 } ? N extends string ? N : never : never : never;
+/**
+ * Detect whether a document is Swagger 2.0 (OpenAPI 2.0).
+ *
+ * SOURCE-OF-TRUTH: mirrors runtime `isSwagger2` in
+ * `packages/core/src/core/version.ts`, which checks for `swagger: "2.0"`.
+ * The runtime path also recognises top-level `definitions` / parameters in
+ * the body location, but `swagger: "2.0"` is the canonical marker.
+ *
+ * Type-level Swagger 2.0 documents cannot be fully normalised at compile
+ * time — the rewrite reorders the document tree (definitions →
+ * components/schemas, body parameters → requestBody, etc.) in ways
+ * TypeScript's mapped-type machinery cannot express. Detecting the
+ * version is tractable, so we surface `__SchemaInferenceFellBack`
+ * deliberately rather than silently producing `unknown`.
+ */
+type IsSwagger2Doc<Doc> = Doc extends {
+  swagger: "2.0";
+} ? true : false;
 /**
  * Infer the TypeScript type of an OpenAPI operation's request body.
+ *
+ * Swagger 2.0 documents are not normalised at the type level. When the
+ * input is Swagger 2.0, this returns `__SchemaInferenceFellBack` so
+ * callers can detect the fallback explicitly via a conditional type.
  */
-type OpenAPIRequestBodyType<Doc, Path extends string, Method extends string> = ResolveMaybeRef<Doc, RequestBodySchemaOf<OperationOf<PathItemOf<Doc, Path>, Method>>>;
+type OpenAPIRequestBodyType<Doc, Path extends string, Method extends string> = IsSwagger2Doc<Doc> extends true ? __SchemaInferenceFellBack : ResolveMaybeRef<Doc, RequestBodySchemaOf<OperationOf<PathItemOf<Doc, Path>, Method>>>;
 /**
  * Infer the TypeScript type of an OpenAPI operation's response.
+ *
+ * Swagger 2.0 documents are not normalised at the type level. When the
+ * input is Swagger 2.0, this returns `__SchemaInferenceFellBack` so
+ * callers can detect the fallback explicitly via a conditional type.
+ */
+type OpenAPIResponseType<Doc, Path extends string, Method extends string, Status extends string> = IsSwagger2Doc<Doc> extends true ? __SchemaInferenceFellBack : ResolveMaybeRef<Doc, ResponseSchemaOf<OperationOf<PathItemOf<Doc, Path>, Method>, Status>>;
+/**
+ * Convert a resolved request/response type into the corresponding
+ * `fields` prop type used by ApiRequestBody / ApiResponse:
+ *
+ * - `__SchemaInferenceFellBack` (Swagger 2.0, depth-exceeded refs) is
+ *   preserved verbatim so callers can detect the brand.
+ * - `unknown` (no schema found at the supplied path/status) falls back
+ *   to the loose `Record<string, FieldOverride>` shape so runtime
+ *   documents still typecheck.
+ * - Any other concrete type is mapped through `FieldOverrides`.
+ *
+ * The brand check intentionally precedes the `unknown` check. The brand
+ * is a structural object type and is therefore NOT assignable to
+ * `unknown extends T` — checking that first would always short-circuit
+ * to the loose `Record` fallback and the brand would never surface.
  */
-type OpenAPIResponseType<Doc, Path extends string, Method extends string, Status extends string> = ResolveMaybeRef<Doc, ResponseSchemaOf<OperationOf<PathItemOf<Doc, Path>, Method>, Status>>;
+type FieldsFromInferred<T> = [T] extends [__SchemaInferenceFellBack] ? __SchemaInferenceFellBack : unknown extends T ? Record<string, FieldOverride> : FieldOverrides<T>;
 /**
  * Infer the fields prop type for ApiRequestBody.
- * Surfaces `__SchemaInferenceFellBack` when the schema contains
- * recursive $ref chains that exceed type-level depth limits.
- * Falls back to `Record<string, FieldOverride>` for runtime documents.
+ *
+ * Surfaces `__SchemaInferenceFellBack` for Swagger 2.0 documents and
+ * for schemas whose $ref chains exceed type-level depth limits. Falls
+ * back to `Record<string, FieldOverride>` for runtime documents whose
+ * shape cannot be inferred at compile time.
  */
-type InferRequestBodyFields<Doc, Path extends string, Method extends string> = unknown extends OpenAPIRequestBodyType<Doc, Path, Method> ? OpenAPIRequestBodyType<Doc, Path, Method> extends __SchemaInferenceFellBack ? __SchemaInferenceFellBack : Record<string, FieldOverride> : FieldOverrides<OpenAPIRequestBodyType<Doc, Path, Method>>;
+type InferRequestBodyFields<Doc, Path extends string, Method extends string> = FieldsFromInferred<OpenAPIRequestBodyType<Doc, Path, Method>>;
 /**
  * Infer the fields prop type for ApiResponse.
- * Surfaces `__SchemaInferenceFellBack` when the schema contains
- * recursive $ref chains that exceed type-level depth limits.
- * Falls back to `Record<string, FieldOverride>` for runtime documents.
+ *
+ * Surfaces `__SchemaInferenceFellBack` for Swagger 2.0 documents and
+ * for schemas whose $ref chains exceed type-level depth limits. Falls
+ * back to `Record<string, FieldOverride>` for runtime documents whose
+ * shape cannot be inferred at compile time.
  */
-type InferResponseFields<Doc, Path extends string, Method extends string, Status extends string> = unknown extends OpenAPIResponseType<Doc, Path, Method, Status> ? OpenAPIResponseType<Doc, Path, Method, Status> extends __SchemaInferenceFellBack ? __SchemaInferenceFellBack : Record<string, FieldOverride> : FieldOverrides<OpenAPIResponseType<Doc, Path, Method, Status>>;
+type InferResponseFields<Doc, Path extends string, Method extends string, Status extends string> = FieldsFromInferred<OpenAPIResponseType<Doc, Path, Method, Status>>;
 /**
  * Infer the overrides prop type for ApiParameters.
  * Falls back to `Record<string, FieldOverride>` for runtime documents.
@@ -385,4 +530,4 @@ type PathOfType<T, Prefix extends string = ""> = IsNarrowObject<T> extends true
  */
 type TypeAtPath<T, P extends string> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? TypeAtPath<T[Key], Rest> : unknown : P extends keyof T ? T[P] : unknown;
 //#endregion
-export { InferResponseFields as a, PathOfType as c, UnsafeFields as d, __SchemaInferenceFellBack as f, InferRequestBodyFields as i, ResolveOpenAPIRef as l, FromJSONSchema as n, OpenAPIRequestBodyType as o, InferParameterOverrides as r, OpenAPIResponseType as s, DEFAULT_MAX_DEPTH as t, TypeAtPath as u };
+export { InferResponseFields as a, PathOfType as c, TypeAtPath as d, UnrepresentableZodSchemaError as f, __SchemaInferenceFellBack as h, InferRequestBodyFields as i, RejectUnrepresentableZod as l, UnsafeFields as m, FromJSONSchema as n, OpenAPIRequestBodyType as o, UnrepresentableZodType as p, InferParameterOverrides as r, OpenAPIResponseType as s, DEFAULT_MAX_DEPTH as t, ResolveOpenAPIRef as u };

package/dist/{types-D_5ST7SS.d.mts → types-C9zw9wbX.d.mts}

@@ -184,6 +184,12 @@ interface TupleField extends FieldBase {
   constraints: ArrayConstraints;
   /** Positional element schemas from `prefixItems`. */
   prefixItems: WalkedField[];
+  /**
+   * Schema for items beyond the `prefixItems` length. In Draft 2020-12,
+   * `items` adjacent to `prefixItems` describes the rest element. When
+   * absent, additional items are permitted but unconstrained.
+   */
+  restItems?: WalkedField;
 }
 interface RecordField extends FieldBase {
   type: "record";