schema-components 1.18.1 → 1.19.0

package/dist/core/adapter.d.mts

@@ -1,5 +1,5 @@
 import { T as SchemaMeta, m as JsonObject } from "../types-D_5ST7SS.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-VgEKI_Ct.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;

package/dist/core/adapter.mjs

@@ -1,8 +1,9 @@
 import { getProperty, hasProperty, isObject } from "./guards.mjs";
+import { SchemaNormalisationError } from "./errors.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { dereference } from "./ref.mjs";
-import { detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2 } from "./version.mjs";
-import { i as normaliseOpenApiSchemas, r as normaliseJsonSchema$1 } from "../normalise-tL9FckAk.mjs";
+import { detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2, matchJsonSchemaDraftUri } from "./version.mjs";
+import { a as normaliseOpenApiSchemas, i as normaliseJsonSchema$1 } from "../normalise-C0ofw3W6.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -30,9 +31,55 @@ function detectSchemaKind(input) {
 * but TypeScript cannot represent "has _zod.def" as the $ZodType parameter
 * that z.toJSONSchema expects. This is the library boundary equivalent of
 * object → Record<string, unknown> — the type mismatch is genuinely unavoidable.
+*
+* Any exception thrown by z.toJSONSchema is classified into a
+* SchemaNormalisationError so the caller does not have to re-parse error
+* message strings. The classification covers:
+*
+* - Nested Zod 3 schemas inside a Zod 4 tree (which surface as
+*   "Cannot read properties of undefined (reading 'def')") → zod3-unsupported
+* - Transforms ("Transforms cannot be represented") → zod-transform-unsupported
+* - Unrepresentable types ("BigInt cannot be represented", "Date cannot be
+*   represented", etc.) → zod-type-unrepresentable
+* - Anything else → zod-conversion-failed
 */
 function callToJsonSchema(schema) {
-	return z.toJSONSchema(schema);
+	try {
+		return z.toJSONSchema(schema);
+	} catch (err) {
+		throw classifyZodConversionError(err, schema);
+	}
+}
+/**
+* Error messages emitted by Zod 4's z.toJSONSchema for unrepresentable types.
+* Mapping is exact-prefix on the message and the corresponding Zod type name
+* surfaced to the consumer via SchemaNormalisationError.zodType.
+*
+* Source: zod/src/v4/core/to-json-schema.ts ("cannot be represented" messages).
+*/
+const UNREPRESENTABLE_ZOD_TYPES = [
+	["BigInt cannot be represented", "bigint"],
+	["Date cannot be represented", "date"],
+	["Map cannot be represented", "map"],
+	["Set cannot be represented", "set"],
+	["Symbols cannot be represented", "symbol"],
+	["Function types cannot be represented", "function"],
+	["Undefined cannot be represented", "undefined"],
+	["Void cannot be represented", "void"],
+	["NaN cannot be represented", "nan"]
+];
+/**
+* The cryptic error produced when z.toJSONSchema encounters a nested Zod 3
+* schema (one without `_zod.def`). Reproduced verbatim from Node's TypeError
+* for property access on undefined.
+*/
+const NESTED_ZOD3_MARKER = "Cannot read properties of undefined";
+function classifyZodConversionError(err, schema) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (message.includes(NESTED_ZOD3_MARKER)) return new SchemaNormalisationError("A nested Zod 3 schema was found inside a Zod 4 schema. schema-components requires Zod 4 throughout the schema tree. See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4", schema, "zod3-unsupported");
+	if (message.includes("Transforms cannot be represented")) return new SchemaNormalisationError("Zod transforms cannot be represented in JSON Schema. Remove the .transform() call, or pre-transform the input before passing it to the component.", schema, "zod-transform-unsupported");
+	for (const [prefix, typeName] of UNREPRESENTABLE_ZOD_TYPES) if (message.includes(prefix)) return new SchemaNormalisationError(`Zod type ${typeName} cannot be represented in JSON Schema and is not supported by schema-components. Original message: ${message}`, schema, "zod-type-unrepresentable", typeName);
+	return new SchemaNormalisationError(`z.toJSONSchema() failed: ${message}`, schema, "zod-conversion-failed");
 }
 function normaliseSchema(input, ref, options) {
 	if (ref === void 0 && isObject(input)) {
@@ -46,14 +93,14 @@ function normaliseSchema(input, ref, options) {
 			result = normaliseZod4(input);
 			break;
 		case "zod3":
-			result = normaliseZod3();
+			result = normaliseZod3(input);
 			break;
 		case "openapi":
-			if (!isObject(input)) throw new Error("Invalid OpenAPI document");
+			if (!isObject(input)) throw new SchemaNormalisationError("Invalid OpenAPI document", input, "openapi-invalid");
 			result = normaliseOpenApi(input, ref, options);
 			break;
 		case "jsonSchema":
-			if (!isObject(input)) throw new Error("Invalid JSON Schema");
+			if (!isObject(input)) throw new SchemaNormalisationError("Invalid JSON Schema", input, "invalid-json-schema");
 			result = normaliseJsonSchema(input, options?.diagnostics);
 			break;
 	}
@@ -62,10 +109,10 @@ function normaliseSchema(input, ref, options) {
 }
 function normaliseZod4(input) {
 	const zod = getProperty(input, "_zod");
-	if (!isObject(zod)) throw new Error("Invalid Zod 4 schema: missing _zod property");
-	if (!("def" in zod)) throw new Error("Invalid Zod 4 schema: missing _zod.def");
+	if (!isObject(zod)) throw new SchemaNormalisationError("Invalid Zod 4 schema: missing _zod property", input, "invalid-zod");
+	if (!("def" in zod)) throw new SchemaNormalisationError("Invalid Zod 4 schema: missing _zod.def", input, "invalid-zod");
 	const jsonSchema = callToJsonSchema(input);
-	if (!isObject(jsonSchema)) throw new Error("z.toJSONSchema() did not produce an object");
+	if (!isObject(jsonSchema)) throw new SchemaNormalisationError("z.toJSONSchema() did not produce an object", input, "invalid-zod");
 	return {
 		jsonSchema,
 		zodSchema: input,
@@ -75,7 +122,8 @@ function normaliseZod4(input) {
 }
 function normaliseJsonSchema(jsonSchema, diagnostics) {
 	let draft;
-	if (typeof jsonSchema.$schema !== "string") {
+	const $schema = jsonSchema.$schema;
+	if (typeof $schema !== "string") {
 		const inferred = inferJsonSchemaDraftWithReason(jsonSchema);
 		draft = inferred.draft;
 		emitDiagnostic(diagnostics, {
@@ -87,16 +135,31 @@ function normaliseJsonSchema(jsonSchema, diagnostics) {
 				draft: inferred.draft
 			}
 		});
-	} else draft = detectJsonSchemaDraft(jsonSchema);
-	const normalised = normaliseJsonSchema$1(jsonSchema, draft);
+	} else {
+		const matched = matchJsonSchemaDraftUri($schema);
+		if (matched === void 0) {
+			draft = "draft-2020-12";
+			emitDiagnostic(diagnostics, {
+				code: "assumed-draft",
+				message: `Unknown $schema URI "${$schema}"; assuming draft-2020-12`,
+				pointer: "",
+				detail: {
+					inferredFrom: "unknown-uri",
+					draft,
+					uri: $schema
+				}
+			});
+		} else draft = matched;
+	}
+	const normalised = normaliseJsonSchema$1(jsonSchema, draft, diagnostics);
 	return {
 		jsonSchema: normalised,
 		rootMeta: extractRootMetaFromJson(normalised),
 		rootDocument: normalised
 	};
 }
-function normaliseZod3() {
-	throw new Error("Zod 3 schemas are not supported. schema-components requires Zod 4. Detected: Zod 3 (has _def without _zod). See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4");
+function normaliseZod3(input) {
+	throw new SchemaNormalisationError("Zod 3 schemas are not supported. schema-components requires Zod 4. Detected: Zod 3 (has _def without _zod). See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4", input, "zod3-unsupported");
 }
 /**
 * Mapping of Swagger 2.0 $ref prefixes to their OpenAPI 3.x equivalents.

package/dist/core/constraints.d.mts

@@ -1,5 +1,5 @@
 import { D as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-D_5ST7SS.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-VgEKI_Ct.mjs";
 
 //#region src/core/constraints.d.ts
 declare function extractStringConstraints(schema: Record<string, unknown>, diagnostics?: DiagnosticsOptions, pointer?: string): StringConstraints;

package/dist/core/diagnostics.d.mts

@@ -1,2 +1,2 @@
-import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-BYk63jsC.mjs";
+import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-VgEKI_Ct.mjs";
 export { Diagnostic, DiagnosticCode, DiagnosticSink, DiagnosticsOptions, appendPointer, emitDiagnostic };

package/dist/core/errors.d.mts

@@ -1,2 +1,2 @@
-import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-C5zRC2PU.mjs";
+import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-CnGjT1cg.mjs";
 export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError };

package/dist/core/errors.mjs

@@ -32,10 +32,16 @@ var SchemaError = class extends Error {
 */
 var SchemaNormalisationError = class extends SchemaError {
 	kind;
-	constructor(message, schema, kind) {
+	/**
+	* For `zod-type-unrepresentable`, the offending Zod type name
+	* (e.g. "bigint", "date", "map", "set"). `undefined` for other kinds.
+	*/
+	zodType;
+	constructor(message, schema, kind, zodType) {
 		super(message, schema);
 		this.name = "SchemaNormalisationError";
 		this.kind = kind;
+		this.zodType = zodType;
 	}
 };
 /**

package/dist/core/formats.mjs

@@ -19,7 +19,15 @@ const FORMAT_PATTERNS = {
 	"relative-json-pointer": /^(0|[1-9][0-9]*)(#?([/]([^/~]|~0|~1)*)*)?$/,
 	duration: /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+(\.\d+)?S)?)?$/,
 	"idn-email": /^[^\s@]+@[^\s@]+\.[^\s@]+$/u,
-	"idn-hostname": /^[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?(\.[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?)*$/iu
+	"idn-hostname": /^[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?(\.[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?)*$/iu,
+	cuid: /^[cC][0-9a-z]{6,}$/,
+	cuid2: /^[0-9a-z]+$/,
+	nanoid: /^[a-zA-Z0-9_-]{21}$/,
+	cidrv4: /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/,
+	cidrv6: /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|::|([0-9a-fA-F]{1,4})?::([0-9a-fA-F]{1,4}:?){0,6})\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$/,
+	base64: /^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$/,
+	base64url: /^[A-Za-z0-9_-]*$/,
+	e164: /^\+[1-9]\d{6,14}$/
 };
 /**
 * Format validators that use predicate functions instead of regex.

package/dist/core/merge.d.mts

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

package/dist/core/normalise.d.mts

@@ -1,5 +1,5 @@
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
-import { n as JsonSchemaDraft, r as OpenApiVersionInfo } from "../version-B5NV-35j.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-VgEKI_Ct.mjs";
+import { n as JsonSchemaDraft, r as OpenApiVersionInfo } from "../version-XNH7PRGP.mjs";
 
 //#region src/core/normalise.d.ts
 type NodeTransform = (node: Record<string, unknown>) => Record<string, unknown>;
@@ -8,9 +8,32 @@ type NodeTransform = (node: Record<string, unknown>) => Record<string, unknown>;
  * and recursing into every sub-schema location.
  */
 declare function deepNormalise(schema: Record<string, unknown>, transform: NodeTransform): Record<string, unknown>;
+/**
+ * Per-node context threaded through `deepNormaliseWithContext`.
+ *
+ * Carries the diagnostics sink and the JSON Pointer to the current
+ * node so per-node transforms can emit pointer-accurate diagnostics
+ * when they translate or reject legacy constructs.
+ */
+interface NodeContext {
+  diagnostics: DiagnosticsOptions | undefined;
+  pointer: string;
+}
+type NodeTransformWithContext = (node: Record<string, unknown>, ctx: NodeContext) => Record<string, unknown>;
+/**
+ * Deep-normalise a JSON Schema object, threading a context (diagnostics
+ * sink + JSON Pointer) through each recursive call. Used by the JSON
+ * Schema normalisation path so per-node transforms can emit diagnostics
+ * with accurate pointers.
+ *
+ * Mirrors `deepNormalise` structurally — keep the two in sync when
+ * adding new sub-schema locations.
+ */
+declare function deepNormaliseWithContext(schema: Record<string, unknown>, transform: NodeTransformWithContext, ctx: NodeContext): Record<string, unknown>;
 /**
  * Normalise Draft 04 `exclusiveMinimum`/`exclusiveMaximum` from boolean
- * to number form.
+ * to number form, plus the other Draft 04 translations applied to a
+ * single node.
  *
  * In Draft 04:
  * - `exclusiveMinimum: true` + `minimum: 5` → value must be > 5
@@ -22,13 +45,23 @@ declare function deepNormalise(schema: Record<string, unknown>, transform: NodeT
  *
  * The transform converts boolean form to number form so the walker can
  * treat `exclusiveMinimum`/`exclusiveMaximum` uniformly as numbers.
+ *
+ * This function preserves the no-context signature for the OpenAPI 3.0
+ * and Swagger 2.0 normalisers that compose it directly. The JSON Schema
+ * normalisation path uses {@link normaliseDraft04NodeWithContext} via
+ * {@link deepNormaliseWithContext} to thread diagnostics.
  */
 declare function normaliseDraft04Node(node: Record<string, unknown>): Record<string, unknown>;
 /**
  * Normalise a JSON Schema to canonical Draft 2020-12 form.
  * Deep-clones the input — the original is never mutated.
+ *
+ * When `diagnostics` is supplied, per-node transforms emit diagnostics
+ * for legacy-keyword rewrites and invalid constructs (e.g. `divisibleBy`
+ * conflicts, non-string entries in a `dependentRequired` array, legacy
+ * `dependencies` reaching the 2020-12 path).
  */
-declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: JsonSchemaDraft): Record<string, unknown>;
+declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: JsonSchemaDraft, diagnostics?: DiagnosticsOptions): Record<string, unknown>;
 /**
  * Normalise an OpenAPI document's schemas for walker consumption.
  * Handles version-specific keyword transformations.
@@ -38,4 +71,4 @@ declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: Jso
  */
 declare function normaliseOpenApiSchemas(doc: Record<string, unknown>, version: OpenApiVersionInfo, diagnostics?: DiagnosticsOptions): Record<string, unknown>;
 //#endregion
-export { NodeTransform, deepNormalise, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };
+export { NodeContext, NodeTransform, NodeTransformWithContext, deepNormalise, deepNormaliseWithContext, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };

package/dist/core/normalise.mjs

@@ -1,2 +1,2 @@
-import { i as normaliseOpenApiSchemas, n as normaliseDraft04Node, r as normaliseJsonSchema, t as deepNormalise } from "../normalise-tL9FckAk.mjs";
-export { deepNormalise, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };
+import { a as normaliseOpenApiSchemas, i as normaliseJsonSchema, n as deepNormaliseWithContext, r as normaliseDraft04Node, t as deepNormalise } from "../normalise-C0ofw3W6.mjs";
+export { deepNormalise, deepNormaliseWithContext, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };

package/dist/core/openapi30.d.mts

@@ -32,10 +32,39 @@ declare function normaliseOpenApi30Discriminator(node: Record<string, unknown>):
  */
 declare function normaliseOpenApi30Combined(node: Record<string, unknown>): Record<string, unknown>;
 /**
- * Deep-normalise all schemas in an OpenAPI 3.0.x document.
- * Walks components/schemas, path operations, parameters, request bodies,
- * and responses — applying `nullable` normalisation to each schema.
+ * Per-schema normaliser supplied by the caller. Given a Schema Object,
+ * returns the normalised (deep-cloned) Schema Object. The visitor is
+ * agnostic to which transforms run inside.
+ */
+type SchemaNormaliser = (schema: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Deep-clone the parent first, then patch back any keys whose values were
+ * rewritten by the visitor. This preserves immutability of the original
+ * document while keeping the visitor straightforward to write.
+ */
+/**
+ * Deep-normalise every Schema Object in an OpenAPI document.
+ *
+ * Walks: `paths.*` (operations + path-level parameters), `webhooks.*`
+ * (3.1), `components.schemas`, `components.parameters`,
+ * `components.responses`, `components.requestBodies`,
+ * `components.headers`, `components.callbacks`, `components.pathItems`
+ * (3.1). For each Schema-bearing location, applies the supplied
+ * `normaliseSchema` function.
+ *
+ * The walker is structural (it understands OAS document shapes) and
+ * delegates the per-schema transformation. For OAS 3.0 the caller
+ * passes a full Draft 04 + nullable + discriminator + example
+ * normaliser; for OAS 3.1 the caller passes a discriminator-only
+ * normaliser so the walker's discriminated-union detection sees the
+ * injected `const`s regardless of OAS minor version.
+ */
+declare function deepNormaliseOpenApiDoc(doc: Record<string, unknown>, normaliseSchema: SchemaNormaliser): Record<string, unknown>;
+/**
+ * Backwards-compatible wrapper retaining the historic `deepNormalise`
+ * signature used by callers in `normalise.ts`. Always applies the full
+ * 3.0 combined transform via `deepNormalise(schema, normaliseOpenApi30Combined)`.
  */
 declare function deepNormaliseOpenApi30Doc(doc: Record<string, unknown>, deepNormalise: (schema: Record<string, unknown>, transform: NodeTransform) => Record<string, unknown>): Record<string, unknown>;
 //#endregion
-export { deepNormaliseOpenApi30Doc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };
+export { deepNormaliseOpenApi30Doc, deepNormaliseOpenApiDoc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };

package/dist/core/openapi30.mjs

@@ -1,2 +1,2 @@
-import { c as normaliseOpenApi30Discriminator, l as normaliseOpenApi30Node, o as deepNormaliseOpenApi30Doc, s as normaliseOpenApi30Combined } from "../normalise-tL9FckAk.mjs";
-export { deepNormaliseOpenApi30Doc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };
+import { c as deepNormaliseOpenApiDoc, d as normaliseOpenApi30Node, l as normaliseOpenApi30Combined, s as deepNormaliseOpenApi30Doc, u as normaliseOpenApi30Discriminator } from "../normalise-C0ofw3W6.mjs";
+export { deepNormaliseOpenApi30Doc, deepNormaliseOpenApiDoc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };

package/dist/core/ref.d.mts

@@ -1,2 +1,2 @@
-import { a as findAnchor, i as dereference, n as RefOptions, o as resolveRef, r as countDistinctRefs, t as ExternalResolver } from "../ref-Ckt5liZs.mjs";
+import { a as findAnchor, i as dereference, n as RefOptions, o as resolveRef, r as countDistinctRefs, t as ExternalResolver } from "../ref-Bb43ZURY.mjs";
 export { ExternalResolver, RefOptions, countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/renderer.d.mts

@@ -1,2 +1,2 @@
-import { a as HtmlRenderProps, c as RenderFunction, d as getHtmlRenderFn, f as getRenderFunction, h as typeToKey, i as HtmlRenderFunction, l as RenderProps, m as mergeResolvers, n as BaseFieldProps, o as HtmlResolver, p as mergeHtmlResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as buildRenderProps } from "../renderer-BAGoX4AK.mjs";
+import { a as HtmlRenderProps, c as RenderFunction, d as getHtmlRenderFn, f as getRenderFunction, h as typeToKey, i as HtmlRenderFunction, l as RenderProps, m as mergeResolvers, n as BaseFieldProps, o as HtmlResolver, p as mergeHtmlResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as buildRenderProps } from "../renderer-BQqiXUYP.mjs";
 export { AllConstraints, BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, buildRenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/renderer.mjs

@@ -33,6 +33,7 @@ const RESOLVER_KEYS = [
 	"string",
 	"number",
 	"boolean",
+	"null",
 	"enum",
 	"object",
 	"array",
@@ -45,17 +46,21 @@ const RESOLVER_KEYS = [
 	"recursive",
 	"literal",
 	"file",
+	"never",
 	"unknown"
 ];
 /**
 * 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".
 */
 function typeToKey(type) {
 	switch (type) {
 		case "string":
 		case "number":
 		case "boolean":
+		case "null":
 		case "enum":
 		case "object":
 		case "array":
@@ -68,8 +73,8 @@ function typeToKey(type) {
 		case "recursive":
 		case "literal":
 		case "file":
+		case "never":
 		case "unknown": return type;
-		default: return "unknown";
 	}
 }
 /**

package/dist/core/swagger2.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-VgEKI_Ct.mjs";
 import { NodeTransform } from "./normalise.mjs";
 
 //#region src/core/swagger2.d.ts

package/dist/core/swagger2.mjs

@@ -1,2 +1,2 @@
-import { a as normaliseSwagger2Document } from "../normalise-tL9FckAk.mjs";
+import { o as normaliseSwagger2Document } from "../normalise-C0ofw3W6.mjs";
 export { normaliseSwagger2Document };

package/dist/core/version.d.mts

@@ -1,2 +1,2 @@
-import { a as detectOpenApiVersion, c as isOpenApi30, i as detectJsonSchemaDraft, l as isOpenApi31, n as JsonSchemaDraft, o as inferJsonSchemaDraft, r as OpenApiVersionInfo, s as inferJsonSchemaDraftWithReason, t as InferredDraft, u as isSwagger2 } from "../version-B5NV-35j.mjs";
-export { InferredDraft, JsonSchemaDraft, OpenApiVersionInfo, detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraft, inferJsonSchemaDraftWithReason, isOpenApi30, isOpenApi31, isSwagger2 };
+import { a as detectOpenApiVersion, c as isOpenApi30, d as matchJsonSchemaDraftUri, i as detectJsonSchemaDraft, l as isOpenApi31, n as JsonSchemaDraft, o as inferJsonSchemaDraft, r as OpenApiVersionInfo, s as inferJsonSchemaDraftWithReason, t as InferredDraft, u as isSwagger2 } from "../version-XNH7PRGP.mjs";
+export { InferredDraft, JsonSchemaDraft, OpenApiVersionInfo, detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraft, inferJsonSchemaDraftWithReason, isOpenApi30, isOpenApi31, isSwagger2, matchJsonSchemaDraftUri };

package/dist/core/version.mjs

@@ -15,6 +15,22 @@ const DRAFT_URIS = new Map([
 	["https://json-schema.org/draft-04/schema#", "draft-04"]
 ]);
 /**
+* Match a `$schema` URI string to a known draft. Returns `undefined`
+* when the URI matches none of the documented Draft 04 – Draft 2020-12
+* schema URIs (including the known prefix patterns) — callers can use
+* this to distinguish an authoritative match from a silent fallback.
+*/
+function matchJsonSchemaDraftUri(uri) {
+	const exact = DRAFT_URIS.get(uri);
+	if (exact !== void 0) return exact;
+	for (const [draftUri, draft] of DRAFT_URIS) if (uri.startsWith(draftUri) || uri === draftUri) return draft;
+	if (uri.includes("/draft/2020-12/")) return "draft-2020-12";
+	if (uri.includes("/draft/2019-09/")) return "draft-2019-09";
+	if (uri.includes("/draft-07")) return "draft-07";
+	if (uri.includes("/draft-06")) return "draft-06";
+	if (uri.includes("/draft-04")) return "draft-04";
+}
+/**
 * Detect the JSON Schema draft version from a schema's `$schema` URI.
 * When `$schema` is absent, uses heuristic keyword detection via
 * `inferJsonSchemaDraft` to guess the draft version.
@@ -24,14 +40,8 @@ const DRAFT_URIS = new Map([
 function detectJsonSchemaDraft(schema) {
 	const $schema = schema.$schema;
 	if (typeof $schema === "string") {
-		const exact = DRAFT_URIS.get($schema);
-		if (exact !== void 0) return exact;
-		for (const [uri, draft] of DRAFT_URIS) if ($schema.startsWith(uri) || $schema === uri) return draft;
-		if ($schema.includes("/draft/2020-12/")) return "draft-2020-12";
-		if ($schema.includes("/draft/2019-09/")) return "draft-2019-09";
-		if ($schema.includes("/draft-07")) return "draft-07";
-		if ($schema.includes("/draft-06")) return "draft-06";
-		if ($schema.includes("/draft-04")) return "draft-04";
+		const matched = matchJsonSchemaDraftUri($schema);
+		if (matched !== void 0) return matched;
 		return "draft-2020-12";
 	}
 	return inferJsonSchemaDraft(schema);
@@ -148,4 +158,4 @@ function isSwagger2(version) {
 	return version.major === 2;
 }
 //#endregion
-export { detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraft, inferJsonSchemaDraftWithReason, isOpenApi30, isOpenApi31, isSwagger2 };
+export { detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraft, inferJsonSchemaDraftWithReason, isOpenApi30, isOpenApi31, isSwagger2, matchJsonSchemaDraftUri };

package/dist/core/walkBuilders.d.mts

@@ -1,6 +1,6 @@
 import { M as WalkedField, O as StringField, T as SchemaMeta, b as NumberField, c as FieldBase, j as UnknownField, o as Editability, p as FileField, r as BooleanField, v as NullField } from "../types-D_5ST7SS.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
-import { t as ExternalResolver } from "../ref-Ckt5liZs.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-VgEKI_Ct.mjs";
+import { t as ExternalResolver } from "../ref-Bb43ZURY.mjs";
 
 //#region src/core/walkBuilders.d.ts
 declare function getString(obj: Record<string, unknown>, key: string): string | undefined;

package/dist/{diagnostics-BYk63jsC.d.mts → diagnostics-VgEKI_Ct.d.mts}

@@ -16,7 +16,7 @@
  * Machine-readable codes identifying each class of diagnostic.
  * Stable across releases — consumers can pattern-match on these.
  */
-type DiagnosticCode = "unresolved-ref" | "unknown-keyword" | "unknown-format" | "invalid-const" | "unsupported-type" | "dropped-swagger-feature" | "external-ref" | "type-negation-fallback" | "conditional-fallback" | "assumed-draft" | "depth-exceeded" | "allof-conflict" | "discriminator-inconsistent";
+type DiagnosticCode = "unresolved-ref" | "unknown-keyword" | "unknown-format" | "invalid-const" | "unsupported-type" | "dropped-swagger-feature" | "external-ref" | "type-negation-fallback" | "conditional-fallback" | "assumed-draft" | "depth-exceeded" | "allof-conflict" | "discriminator-inconsistent" | "divisible-by-conflict" | "legacy-dependencies-split" | "dependent-required-invalid";
 /**
  * A single diagnostic emitted during schema processing.
  */

package/dist/{errors-C5zRC2PU.d.mts → errors-CnGjT1cg.d.mts}

@@ -27,8 +27,13 @@ declare class SchemaError extends Error {
  * JSON Schema, missing OpenAPI ref, unsupported ref format.
  */
 declare class SchemaNormalisationError extends SchemaError {
-  readonly kind: "invalid-zod" | "zod3-unsupported" | "invalid-json-schema" | "openapi-missing-ref" | "openapi-invalid" | "unknown";
-  constructor(message: string, schema: unknown, kind: SchemaNormalisationError["kind"]);
+  readonly kind: "invalid-zod" | "zod3-unsupported" | "zod-transform-unsupported" | "zod-type-unrepresentable" | "zod-conversion-failed" | "invalid-json-schema" | "openapi-missing-ref" | "openapi-invalid" | "unknown";
+  /**
+   * For `zod-type-unrepresentable`, the offending Zod type name
+   * (e.g. "bigint", "date", "map", "set"). `undefined` for other kinds.
+   */
+  readonly zodType: string | undefined;
+  constructor(message: string, schema: unknown, kind: SchemaNormalisationError["kind"], zodType?: string);
 }
 /**
  * A theme adapter's render function threw during rendering.

package/dist/html/a11y.d.mts

@@ -1,5 +1,5 @@
 import { M as WalkedField } from "../types-D_5ST7SS.mjs";
-import { t as AllConstraints } from "../renderer-BAGoX4AK.mjs";
+import { t as AllConstraints } from "../renderer-BQqiXUYP.mjs";
 import { HtmlAttributes, HtmlNode } from "./html.mjs";
 
 //#region src/html/a11y.d.ts

package/dist/html/renderToHtml.d.mts

@@ -1,5 +1,5 @@
 import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BAGoX4AK.mjs";
+import { o as HtmlResolver } from "../renderer-BQqiXUYP.mjs";
 
 //#region src/html/renderToHtml.d.ts
 interface RenderToHtmlOptions {

package/dist/html/renderToHtmlStream.d.mts

@@ -1,5 +1,5 @@
 import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BAGoX4AK.mjs";
+import { o as HtmlResolver } from "../renderer-BQqiXUYP.mjs";
 
 //#region src/html/renderToHtmlStream.d.ts
 interface StreamRenderOptions {

package/dist/html/renderers.d.mts

@@ -1,5 +1,5 @@
 import { M as WalkedField } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BAGoX4AK.mjs";
+import { o as HtmlResolver } from "../renderer-BQqiXUYP.mjs";
 
 //#region src/html/renderers.d.ts
 declare function dateInputType(format: string | undefined): string | undefined;

package/dist/html/renderers.mjs

@@ -378,6 +378,32 @@ function renderConditionalHtml(props) {
 function renderNegationHtml(props) {
 	return serialize(h("div", { class: "sc-negation" }, raw("not: ...")));
 }
+/**
+* Render a null field — `z.null()` or `{ type: "null" }`.
+*
+* The only valid value is `null`, so render an em-dash placeholder.
+*/
+function renderNullHtml(props) {
+	return serialize(h("span", {
+		class: "sc-value sc-value--empty",
+		id: fieldId(props.path),
+		...ariaReadonlyAttrs()
+	}, "—"));
+}
+/**
+* Render a never field — `z.never()` or a `false` schema.
+*
+* `never` indicates a position that cannot hold any value. Render a
+* visible placeholder rather than throwing because some valid schemas
+* intentionally contain `never` branches.
+*/
+function renderNeverHtml(props) {
+	return serialize(h("span", {
+		class: "sc-value sc-never",
+		id: fieldId(props.path),
+		...ariaReadonlyAttrs()
+	}, h("em", {}, "never matches")));
+}
 function matchUnionOption(options, value) {
 	if (typeof value === "string") return options.find((o) => o.type === "string" || o.type === "enum");
 	if (typeof value === "number") return options.find((o) => o.type === "number");
@@ -389,6 +415,7 @@ const defaultHtmlResolver = {
 	string: renderStringHtml,
 	number: renderNumberHtml,
 	boolean: renderBooleanHtml,
+	null: renderNullHtml,
 	enum: renderEnumHtml,
 	object: renderObjectHtml,
 	array: renderArrayHtml,
@@ -401,6 +428,7 @@ const defaultHtmlResolver = {
 	negation: renderNegationHtml,
 	recursive: renderRecursiveHtml,
 	file: renderFileHtml,
+	never: renderNeverHtml,
 	unknown: renderUnknownHtml
 };
 //#endregion

package/dist/html/streamRenderers.d.mts

@@ -1,5 +1,5 @@
 import { M as WalkedField } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-BAGoX4AK.mjs";
+import { o as HtmlResolver } from "../renderer-BQqiXUYP.mjs";
 import { HtmlElement } from "./html.mjs";
 
 //#region src/html/streamRenderers.d.ts