schema-components 1.20.0 → 1.22.0

package/README.md

@@ -16,7 +16,7 @@ Peer dependencies: `zod@^4.0.0`, `react@^18.0.0 || ^19.0.0`.
 
 ### Zod version requirement
 
-schema-components requires **Zod 4**. If you are on Zod 3, see the [Zod 4 migration guide](https://zod.dev/v4/migration). The library detects Zod 3 inputs and throws a descriptive error rather than silently misbehaving.
+schema-components requires **Zod 4**. If you are on Zod 3, see the [Zod 4 migration guide](https://zod.dev/v4/migration). If a Zod 3 schema is passed (detected via `_def.typeName`), a descriptive `SchemaNormalisationError` is raised pointing at the Zod 4 migration guide. Schemas from other Standard Schema libraries are not currently supported.
 
 ## `SchemaComponent`
 

package/dist/core/adapter.d.mts

@@ -1,10 +1,34 @@
-import { T as SchemaMeta, m as JsonObject } from "../types-C9zw9wbX.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { m as JsonObject, w as SchemaMeta } from "../types-BrRMV0en.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-D0QCYGv0.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;
-type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi";
+type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi" | "unsupported-schema-lib";
+/**
+ * Classify the input schema by its structural markers.
+ *
+ * - `zod4` — has a `_zod` marker (further validation that `_zod.def` is a
+ *   non-null object happens inside `normaliseZod4`).
+ * - `zod3` — has `_def` and no `_zod`. The `typeName` field is no longer
+ *   required: any `_def` without `_zod` is treated as a probable Zod 3
+ *   schema. Third-party libraries that expose `_def` without `_zod` are
+ *   nearly always Zod 3 forks; surfacing the migration message is the
+ *   correct response.
+ * - `openapi` — has `openapi` or `swagger` at the root.
+ * - `unsupported-schema-lib` — has `parse` and `safeParse` callables but
+ *   no `_zod` and no `_def` marker. This catches Standard Schema
+ *   implementations (valibot, arktype, etc.) that would otherwise flow
+ *   through as "malformed JSON Schema".
+ * - `jsonSchema` — fallback for anything that does not match the above.
+ */
 declare function detectSchemaKind(input: unknown): SchemaKind;
+/**
+ * Exposed for unit testing — lets the contract test enumerate every rule's
+ * `prefix` value and assert mutual non-prefixing.
+ */
+declare const __CLASSIFIER_RULES_FOR_TEST: readonly {
+  readonly prefix: string;
+}[];
 interface NormalisedSchema {
   /** JSON Schema object — the authoritative schema for rendering. */
   jsonSchema: JsonObject;
@@ -21,4 +45,4 @@ interface NormaliseOptions {
 }
 declare function normaliseSchema(input: unknown, ref?: string, options?: NormaliseOptions): NormalisedSchema;
 //#endregion
-export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaKind, type SchemaMeta, detectSchemaKind, normaliseSchema };
+export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaKind, type SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, normaliseSchema };

package/dist/core/adapter.mjs

@@ -1,9 +1,10 @@
 import { getProperty, hasProperty, isObject } from "./guards.mjs";
+import "./limits.mjs";
 import { SchemaNormalisationError } from "./errors.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { dereference } from "./ref.mjs";
 import { detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2, matchJsonSchemaDraftUri } from "./version.mjs";
-import { a as normaliseOpenApiSchemas, i as normaliseJsonSchema$1 } from "../normalise-CMMEl4cd.mjs";
+import { a as normaliseOpenApiSchemas, i as normaliseJsonSchema$1 } from "../normalise-DVEJQmF7.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -18,13 +19,46 @@ import { z } from "zod";
 * All narrowing uses type guards — no type assertions.
 */
 const schemaCache = /* @__PURE__ */ new WeakMap();
+/**
+* Classify the input schema by its structural markers.
+*
+* - `zod4` — has a `_zod` marker (further validation that `_zod.def` is a
+*   non-null object happens inside `normaliseZod4`).
+* - `zod3` — has `_def` and no `_zod`. The `typeName` field is no longer
+*   required: any `_def` without `_zod` is treated as a probable Zod 3
+*   schema. Third-party libraries that expose `_def` without `_zod` are
+*   nearly always Zod 3 forks; surfacing the migration message is the
+*   correct response.
+* - `openapi` — has `openapi` or `swagger` at the root.
+* - `unsupported-schema-lib` — has `parse` and `safeParse` callables but
+*   no `_zod` and no `_def` marker. This catches Standard Schema
+*   implementations (valibot, arktype, etc.) that would otherwise flow
+*   through as "malformed JSON Schema".
+* - `jsonSchema` — fallback for anything that does not match the above.
+*/
 function detectSchemaKind(input) {
 	if (hasProperty(input, "_zod")) return "zod4";
 	if (hasProperty(input, "_def") && !hasProperty(input, "_zod")) return "zod3";
 	if (hasProperty(input, "openapi") || hasProperty(input, "swagger")) return "openapi";
+	if (isLikelyOtherSchemaLib(input)) return "unsupported-schema-lib";
 	return "jsonSchema";
 }
 /**
+* Heuristic: a non-Zod object exposing both `.parse` and `.safeParse` as
+* callables is almost certainly an instance of a competing schema library
+* (Standard Schema, valibot, arktype, etc.). schema-components requires
+* Zod 4 throughout — surfacing the unsupported library by name beats
+* letting the input drop through to the JSON Schema branch where it
+* would fail as "malformed JSON Schema" without explanation.
+*/
+function isLikelyOtherSchemaLib(input) {
+	if (!isObject(input)) return false;
+	if (hasProperty(input, "_zod") || hasProperty(input, "_def")) return false;
+	const parse = input.parse;
+	const safeParse = input.safeParse;
+	return typeof parse === "function" && typeof safeParse === "function";
+}
+/**
 * Wraps z.toJSONSchema() for a runtime-validated Zod schema.
 *
 * The _zod guard in normaliseZod4 has confirmed this is a valid Zod schema,
@@ -32,107 +66,388 @@ function detectSchemaKind(input) {
 * that z.toJSONSchema expects. This is the library boundary equivalent of
 * object → Record<string, unknown> — the type mismatch is genuinely unavoidable.
 *
+* # Options
+*
+* `z.toJSONSchema` is invoked with an explicit options object rather than
+* Zod's defaults so the conversion contract is pinned and stable:
+*
+* - `target: "draft-2020-12"` — matches the walker's draft target.
+* - `unrepresentable: "throw"` — keeps the unrepresentable-type rules in
+*   the classifier table firing instead of silently emitting `{}`.
+* - `cycles: "ref"` — converts cyclic graphs into $ref pairs rather than
+*   throwing. Cycles in user schemas surface through the walker's $ref
+*   resolution rather than the adapter.
+* - `io: "output"` — convert the OUTPUT side of every transform / pipe /
+*   codec. The input side is invisible to the converted schema, even
+*   though `safeParse` on the same Zod schema consumes the input shape.
+*   For transforms this divergence is fatal and the call throws via
+*   `Transforms cannot be represented`; for `z.codec(...)` the call
+*   succeeds but only the output side is rendered. Consumers receive a
+*   `zod-codec-output-only` diagnostic in the codec case so the
+*   asymmetry is visible — see `screenPreConversion`.
+*
+* # Error classification
+*
 * 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
-* - Dynamic catch values whose handler throws ("Dynamic catch values are not
-*   supported") → zod-type-unrepresentable with zodType "dynamic-catch"
+* - Nested Zod 3 schemas inside a Zod 4 tree → zod3-unsupported.
+*   Detected structurally (presence of `_def.typeName` markers anywhere
+*   in the schema tree) so the check works across V8, JavaScriptCore,
+*   and SpiderMonkey, none of which agree on the wording of
+*   "Cannot read properties of undefined".
+* - Transforms → zod-transform-unsupported. This also catches `z.codec(…)`
+*   because Zod implements codecs as a pipe + transform internally, so
+*   they trip the same processor when round-tripping is forced. (Plain
+*   `z.toJSONSchema(codec)` itself does NOT throw because Zod picks one
+*   side of the codec; the static rejection in `typeInference.ts` is the
+*   compile-time guard.)
+* - Dynamic catch values whose handler throws → zod-type-unrepresentable
+*   with zodType "dynamic-catch".
 * - Unrepresentable types — bigint, date, map, set, symbol, function, custom,
 *   undefined, void, NaN, and the literal-only forms `z.literal(undefined)`
 *   ("undefined-literal") and `z.literal(<bigint>)` ("bigint-literal") →
-*   zod-type-unrepresentable
+*   zod-type-unrepresentable.
 * - The catch-all "Non-representable type encountered: <type>" fallback Zod
 *   emits for any new schema kind without a registered processor →
-*   zod-type-unrepresentable with zodType set to the offending def.type
-* - Anything else → zod-conversion-failed
+*   zod-type-unrepresentable with zodType set to the offending def.type.
+* - Cycle detected (`cycles: "throw"`) → zod-cycle-detected.
+* - Duplicate schema id → zod-duplicate-id.
+* - "Unprocessed schema. This is a bug in Zod." → zod-conversion-bug.
+* - "Error converting schema to JSON." → zod-conversion-failed (explicit
+*   classification rather than the generic fallback so the contract test
+*   protects the prefix from drift).
+* - Anything else → zod-conversion-failed.
 *
 * The original error is preserved on each classified error via the `cause`
 * field so consumers can still inspect the Zod stack trace.
 */
 function callToJsonSchema(schema) {
 	try {
-		return z.toJSONSchema(schema);
+		return z.toJSONSchema(schema, {
+			target: "draft-2020-12",
+			unrepresentable: "throw",
+			cycles: "ref",
+			io: "output"
+		});
 	} 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.
-*
-* Sources (verbatim message prefixes):
-* - zod/src/v4/core/json-schema-processors.ts L104 (bigint), L110 (symbol),
-*   L126 (undefined), L132 (void), L150 (date), L169 (literal-undefined),
-*   L175 (literal-bigint), L204 (NaN), L246 (custom), L252 (function),
-*   L264 (map), L270 (set), L521 (dynamic catch).
-* - zod/src/v4/core/to-json-schema.ts L182 (non-representable type fallback).
+* Zod `def.type` tags that have no useful JSON Schema representation but
+* do NOT throw when passed through `z.toJSONSchema`. Each tag is handled
+* by Zod with a processor that silently rewrites the output:
 *
-* The kept message prefix is the shortest substring that uniquely identifies
-* the source — the test in tests/zod-error-wording-contract.unit.test.ts
-* asserts each prefix is still present in the live Zod output so a Zod
-* patch upgrade that changes wording fails the build.
+* - `promise` — `promiseProcessor` unwraps the inner type, dropping the
+*   `Promise<...>` wrapper without any error. (`json-schema-processors.ts`,
+*   the body of `promiseProcessor` calls `process(def.innerType, ...)`.)
+*   schema-components considers this a silent shape mismatch — the input
+*   tree advertised a `Promise<T>` and the consumer would render `T`
+*   without ever being told the wrapping was lost.
 *
-* Note: the more specific literal-* prefixes precede the generic "BigInt"
-* prefix so the literal classifications win. JavaScript object iteration
-* order preserves insertion order, and the loop short-circuits on first
-* match, so ordering here is load-bearing.
+* Detection happens BEFORE the call to `z.toJSONSchema` so the response is
+* an immediate `SchemaNormalisationError` with `kind:
+* "zod-type-unrepresentable"`, matching the philosophy of
+* `UnrepresentableZodType` in `typeInference.ts` — these types are
+* rejected, not coerced.
 */
-const UNREPRESENTABLE_ZOD_TYPES = [
-	["Literal `undefined` cannot be represented", "undefined-literal"],
-	["BigInt literals cannot be represented", "bigint-literal"],
-	["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"],
-	["Custom types cannot be represented", "custom"],
-	["Undefined cannot be represented", "undefined"],
-	["Void cannot be represented", "void"],
-	["NaN cannot be represented", "nan"]
-];
+const PRECONVERSION_UNREPRESENTABLE_TAGS = new Map([["promise", "z.promise(T) cannot be represented in JSON Schema. Zod silently unwraps it to the inner type, which would leave the rendered schema out of sync with the source. Resolve the promise at the data boundary before passing the value to the component."]]);
 /**
-* Marker for Zod's catch-all message when a brand-new schema type has no
-* registered processor (e.g. ahead of a Zod patch adding a new schema kind).
+* Pre-conversion screening. Inspects the root `_zod.def.type` tag for
+* known-problematic types that either silently misrender (handled via
+* {@link PRECONVERSION_UNREPRESENTABLE_TAGS}, raising a
+* `SchemaNormalisationError`) or render correctly but with consumer-visible
+* caveats (codecs, raising a `zod-codec-output-only` diagnostic).
 *
-* Source: zod/src/v4/core/to-json-schema.ts L182
-*   `[toJSONSchema]: Non-representable type encountered: ${def.type}`
+* Design choice: `z.never()` is NOT classified here. The Zod processor for
+* `never` already produces `{ not: {} }`, which the walker understands via
+* its `walkBooleanSchema(false)` branch (`walker.ts` boolean-schema
+* handling). Throwing a `zod-type-unrepresentable` for `never` would break
+* the legitimate "this field cannot hold any value" use case that the
+* walker already supports. Documented for posterity so future passes do
+* not "fix" it.
 */
-const NON_REPRESENTABLE_TYPE_MARKER = "[toJSONSchema]: Non-representable type encountered:";
+function screenPreConversion(input, def, diagnostics) {
+	const tag = def.type;
+	if (typeof tag !== "string") return;
+	const unrepresentableMessage = PRECONVERSION_UNREPRESENTABLE_TAGS.get(tag);
+	if (unrepresentableMessage !== void 0) throw new SchemaNormalisationError(unrepresentableMessage, input, "zod-type-unrepresentable", tag);
+	if (tag === "pipe" && isCodecSchema(input)) emitDiagnostic(diagnostics, {
+		code: "zod-codec-output-only",
+		message: "z.codec(...) was passed at the schema root. Only the OUTPUT side is rendered by schema-components; the input side may differ. If you intend to render the input side instead, restructure the codec so the input type is the rendered shape.",
+		pointer: "",
+		detail: { zodType: "codec" }
+	});
+}
+/**
+* True when `input` is a `z.codec(...)` instance. Detection looks for the
+* `$ZodCodec` entry in `_zod.traits` — the same marker `z.toJSONSchema`'s
+* own `isTransforming` helper uses to distinguish codecs from generic
+* pipes.
+*/
+function isCodecSchema(input) {
+	const zod = getProperty(input, "_zod");
+	if (!isObject(zod)) return false;
+	const traits = zod.traits;
+	if (traits instanceof Set) return traits.has("$ZodCodec");
+	return false;
+}
+/**
+* Escape a string for inclusion in a `RegExp`. Required because Zod
+* messages contain `[`, `]`, `.`, `(`, and `)` characters which have regex
+* meaning. The set covers every character with special meaning in a
+* JavaScript regular-expression source — RegExp.escape is not yet widely
+* available so we escape manually.
+*/
+function escapeRegExp(literal) {
+	return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Compile a prefix into an anchored regex that captures any trailing text
+* (used by rules that need to extract dynamic data such as the duplicate id
+* or the def.type that tripped the non-representable fallback).
+*/
+function anchored(prefix) {
+	return new RegExp(`^${escapeRegExp(prefix)}(.*)$`, "s");
+}
 /**
-* Marker for dynamic catch failures — Zod throws when `def.catchValue(...)`
-* itself throws while building the JSON Schema default.
+* Build the message body shared by every unrepresentable-type rule.
+*/
+function unrepresentableMessage(typeName, fullMessage) {
+	return `Zod type ${typeName} cannot be represented in JSON Schema and is not supported by schema-components. Original message: ${fullMessage}`;
+}
+/**
+* Classifier rules ordered most-specific first. Order is load-bearing:
+* `Literal \`undefined\` cannot be represented` must precede the broader
+* `Undefined cannot be represented` so the literal classification wins
+* even when both share a leading word. A consistency check in the unit
+* test suite asserts no two `prefix` values are prefixes of each other —
+* any future rule that breaks the invariant fails the build.
+*
+* Verbatim sources (kept aligned with `tests/zod-error-wording-contract.unit.test.ts`).
+* Source files are referenced by message-content anchors rather than line
+* numbers — line numbers drift across Zod patch releases but the message
+* strings themselves are stable and protected by the contract test suite:
 *
-* Source: zod/src/v4/core/json-schema-processors.ts L521
+* - `zod/src/v4/core/json-schema-processors.ts` — emits `BigInt cannot be
+*   represented`, `Symbols cannot be represented`, `Undefined cannot be
+*   represented`, `Void cannot be represented`, `Date cannot be
+*   represented`, `Literal \`undefined\` cannot be represented`,
+*   `BigInt literals cannot be represented`, `NaN cannot be represented`,
+*   `Custom types cannot be represented`, `Function types cannot be
+*   represented`, `Transforms cannot be represented`, `Map cannot be
+*   represented`, `Set cannot be represented`, `Dynamic catch values are
+*   not supported`.
+* - `zod/src/v4/core/to-json-schema.ts` — emits `[toJSONSchema]:
+*   Non-representable type encountered: ${def.type}` (the catch-all
+*   fallback), `Unprocessed schema. This is a bug in Zod.` (the
+*   internal-bug branch), `Duplicate schema id "${id}" detected during
+*   JSON Schema conversion.` (the duplicate-id branch), `Cycle detected:
+*   ` (the cycle-throw branch), and `Error converting schema to JSON.`
+*   (the Standard Schema boundary wrapper).
+*/
+const CLASSIFIER_RULES = [
+	{
+		prefix: "Literal `undefined` cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "undefined-literal",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("undefined-literal", full), schema, "zod-type-unrepresentable", "undefined-literal", cause)
+	},
+	{
+		prefix: "BigInt literals cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "bigint-literal",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("bigint-literal", full), schema, "zod-type-unrepresentable", "bigint-literal", cause)
+	},
+	{
+		prefix: "BigInt cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "bigint",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("bigint", full), schema, "zod-type-unrepresentable", "bigint", cause)
+	},
+	{
+		prefix: "Date cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "date",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("date", full), schema, "zod-type-unrepresentable", "date", cause)
+	},
+	{
+		prefix: "Map cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "map",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("map", full), schema, "zod-type-unrepresentable", "map", cause)
+	},
+	{
+		prefix: "Set cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "set",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("set", full), schema, "zod-type-unrepresentable", "set", cause)
+	},
+	{
+		prefix: "Symbols cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "symbol",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("symbol", full), schema, "zod-type-unrepresentable", "symbol", cause)
+	},
+	{
+		prefix: "Function types cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "function",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("function", full), schema, "zod-type-unrepresentable", "function", cause)
+	},
+	{
+		prefix: "Custom types cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "custom",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("custom", full), schema, "zod-type-unrepresentable", "custom", cause)
+	},
+	{
+		prefix: "Undefined cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "undefined",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("undefined", full), schema, "zod-type-unrepresentable", "undefined", cause)
+	},
+	{
+		prefix: "Void cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "void",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("void", full), schema, "zod-type-unrepresentable", "void", cause)
+	},
+	{
+		prefix: "NaN cannot be represented",
+		kind: "zod-type-unrepresentable",
+		zodType: "nan",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(unrepresentableMessage("nan", full), schema, "zod-type-unrepresentable", "nan", cause)
+	},
+	{
+		prefix: "Transforms cannot be represented",
+		kind: "zod-transform-unsupported",
+		build: (_m, cause, schema) => 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. (Note: z.codec(...) is implemented as a transform internally — codecs that force round-tripping trip this same rule.)", schema, "zod-transform-unsupported", void 0, cause)
+	},
+	{
+		prefix: "Dynamic catch values are not supported",
+		kind: "zod-type-unrepresentable",
+		zodType: "dynamic-catch",
+		build: (_m, cause, schema) => new SchemaNormalisationError("Zod catch values that depend on runtime computation cannot be represented in JSON Schema. Provide a static catch value or remove the .catch() call.", schema, "zod-type-unrepresentable", "dynamic-catch", cause)
+	},
+	{
+		prefix: "[toJSONSchema]: Non-representable type encountered:",
+		kind: "zod-type-unrepresentable",
+		build: (match, cause, schema, full) => {
+			const trailing = match[1]?.trim() ?? "";
+			const typeName = trailing.length > 0 ? trailing.split(/\s+/)[0] : void 0;
+			return new SchemaNormalisationError(`Zod encountered a schema kind${typeName !== void 0 ? ` "${typeName}"` : ""} with no JSON Schema processor registered. This usually means Zod added a new schema type that schema-components does not yet support. Original message: ${full}`, schema, "zod-type-unrepresentable", typeName, cause);
+		}
+	},
+	{
+		prefix: "Cycle detected: ",
+		kind: "zod-cycle-detected",
+		build: (match, cause, schema, full) => {
+			return new SchemaNormalisationError(`Zod detected a cycle in the schema graph at ${(match[1] ?? "").split(/\s+/)[0] ?? ""}. schema-components calls z.toJSONSchema with { cycles: "ref" } so legitimate cyclic graphs convert to $ref pairs; this error surfaces only when Zod is unable to break the cycle even under the "ref" policy. Restructure the schema to break the cycle, or use an explicit $ref-based definition. Original message: ${full}`, schema, "zod-cycle-detected", void 0, cause);
+		}
+	},
+	{
+		prefix: "Duplicate schema id \"",
+		kind: "zod-duplicate-id",
+		build: (match, cause, schema, full) => {
+			const trailing = match[1] ?? "";
+			const closing = trailing.indexOf("\"");
+			return new SchemaNormalisationError(`Two different Zod schemas share the same id "${closing === -1 ? trailing : trailing.slice(0, closing)}". JSON Schema requires distinct ids when multiple schemas are bundled together. Give each schema its own .meta({ id: ... }) or remove the duplicate. Original message: ${full}`, schema, "zod-duplicate-id", void 0, cause);
+		}
+	},
+	{
+		prefix: "Unprocessed schema. This is a bug in Zod.",
+		kind: "zod-conversion-bug",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(`Zod failed to process this schema during JSON Schema conversion and reports it as an internal bug. File an issue on the Zod tracker with a reproduction. Original message: ${full}`, schema, "zod-conversion-bug", void 0, cause)
+	},
+	{
+		prefix: "Error converting schema to JSON.",
+		kind: "zod-conversion-failed",
+		build: (_m, cause, schema, full) => new SchemaNormalisationError(`z.toJSONSchema() failed to produce a Standard Schema payload. Inspect the underlying cause for the original error. Original message: ${full}`, schema, "zod-conversion-failed", void 0, cause)
+	}
+];
+/**
+* Compiled regex form of {@link CLASSIFIER_RULES} — built once at module
+* load. Avoids per-error compilation.
+*/
+const COMPILED_CLASSIFIER_RULES = CLASSIFIER_RULES.map((rule) => ({
+	rule,
+	pattern: anchored(rule.prefix)
+}));
+/**
+* Maximum recursion depth for {@link containsNestedZod3}. Reuses the
+* shared {@link MAX_REF_DEPTH} so the runtime walk and the compile-time
+* `DEFAULT_MAX_DEPTH` (type-aliased to the same value) stay in lockstep.
 */
-const DYNAMIC_CATCH_MARKER = "Dynamic catch values are not supported";
 /**
-* 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.
+* Walk an arbitrary value looking for Zod 3 markers (`_def` without
+* `_zod`). Zod 4 schemas always carry `_zod.def`; Zod 3 schemas carry
+* `_def` (with or without a `typeName` field — third-party Zod-3-style
+* libraries occasionally omit `typeName`). Presence of `_def` without
+* `_zod` anywhere in the tree means a Zod 3 (or Zod-3-like) schema was
+* nested inside a Zod 4 input, which is what trips the V8
+* `"Cannot read properties of undefined"` failure.
+*
+* Engine-agnostic by construction — the detector inspects schema shape
+* instead of pattern-matching against the runtime's TypeError message,
+* so it works equivalently under V8, JavaScriptCore (Bun/Safari), and
+* SpiderMonkey (Firefox) — none of which agree on the wording.
+*
+* Performance shortcuts:
+*
+* - **Targeted descent into Zod 4 nodes.** Once a node is identified as a
+*   Zod 4 schema (`_zod.def` is an object), the only branch that can
+*   carry user-supplied sub-schemas is `_zod.def` itself. Zod's other
+*   internal members (`_zod.traits`, `_zod.parse`, `_zod.bag`, etc.) are
+*   implementation surface and never contain user schemas, so walking
+*   them on every conversion failure is wasted work. Switching to a
+*   targeted descent (only `_zod.def` plus the schema root's `_def`
+*   field) trims the walk dramatically.
+* - **Depth cap.** Recursion is bounded by {@link MAX_REF_DEPTH}
+*   so a pathological schema graph cannot cause stack overflow. The
+*   `visited` set still defends against cyclic references; the depth
+*   cap defends against deep-but-acyclic trees.
 */
-const NESTED_ZOD3_MARKER = "Cannot read properties of undefined";
+function containsNestedZod3(value, visited) {
+	return containsNestedZod3Inner(value, visited, 0);
+}
+function containsNestedZod3Inner(value, visited, depth) {
+	if (depth >= 64) return false;
+	if (value === null || typeof value !== "object") return false;
+	if (visited.has(value)) return false;
+	visited.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) if (containsNestedZod3Inner(item, visited, depth + 1)) return true;
+		return false;
+	}
+	if (!isObject(value)) return false;
+	const def = value._def;
+	const zod = value._zod;
+	if (zod === void 0 && isObject(def)) return true;
+	if (isObject(zod) && isObject(zod.def)) return containsNestedZod3Inner(zod.def, visited, depth + 1);
+	for (const key of Object.keys(value)) if (containsNestedZod3Inner(value[key], visited, depth + 1)) return true;
+	return false;
+}
 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", void 0, err);
-	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", void 0, err);
-	if (message.includes(DYNAMIC_CATCH_MARKER)) return new SchemaNormalisationError("Zod catch values that depend on runtime computation cannot be represented in JSON Schema. Provide a static catch value or remove the .catch() call.", schema, "zod-type-unrepresentable", "dynamic-catch", err);
-	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, err);
-	const nonReprIndex = message.indexOf(NON_REPRESENTABLE_TYPE_MARKER);
-	if (nonReprIndex !== -1) {
-		const trailing = message.slice(nonReprIndex + 51).trim();
-		const typeName = trailing.length > 0 ? trailing.split(/\s+/)[0] : void 0;
-		return new SchemaNormalisationError(`Zod encountered a schema kind${typeName !== void 0 ? ` "${typeName}"` : ""} with no JSON Schema processor registered. This usually means Zod added a new schema type that schema-components does not yet support. Original message: ${message}`, schema, "zod-type-unrepresentable", typeName, err);
+	if (containsNestedZod3(schema, /* @__PURE__ */ new Set())) 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", void 0, err);
+	for (const { rule, pattern } of COMPILED_CLASSIFIER_RULES) {
+		const match = pattern.exec(message);
+		if (match !== null) return rule.build(match, err, schema, message);
 	}
 	return new SchemaNormalisationError(`z.toJSONSchema() failed: ${message}`, schema, "zod-conversion-failed", void 0, err);
 }
+/**
+* Exposed for unit testing — lets the contract test enumerate every rule's
+* `prefix` value and assert mutual non-prefixing.
+*/
+const __CLASSIFIER_RULES_FOR_TEST = CLASSIFIER_RULES;
 function normaliseSchema(input, ref, options) {
-	if (ref === void 0 && isObject(input)) {
+	const usesDiagnostics = options?.diagnostics !== void 0;
+	const cacheEligible = ref === void 0 && isObject(input) && !usesDiagnostics;
+	if (cacheEligible) {
 		const cached = schemaCache.get(input);
 		if (cached !== void 0) return cached;
 	}
@@ -140,11 +455,12 @@ function normaliseSchema(input, ref, options) {
 	let result;
 	switch (kind) {
 		case "zod4":
-			result = normaliseZod4(input);
+			result = normaliseZod4(input, options?.diagnostics);
 			break;
 		case "zod3":
 			result = normaliseZod3(input);
 			break;
+		case "unsupported-schema-lib": throw new SchemaNormalisationError("Input looks like a schema from a non-Zod library — it exposes `parse` and `safeParse` but carries no Zod 4 (`_zod`) or Zod 3 (`_def`) marker. schema-components requires a Zod 4 schema. Convert the schema with the equivalent Zod 4 builder, or feed schema-components a JSON Schema / OpenAPI document instead. See the Zod 4 contract at https://zod.dev/v4 or run: pnpm add zod@^4", input, "unsupported-schema");
 		case "openapi":
 			if (!isObject(input)) throw new SchemaNormalisationError("Invalid OpenAPI document", input, "openapi-invalid");
 			result = normaliseOpenApi(input, ref, options);
@@ -154,13 +470,15 @@ function normaliseSchema(input, ref, options) {
 			result = normaliseJsonSchema(input, options?.diagnostics);
 			break;
 	}
-	if (ref === void 0 && isObject(input)) schemaCache.set(input, result);
+	if (cacheEligible) schemaCache.set(input, result);
 	return result;
 }
-function normaliseZod4(input) {
+function normaliseZod4(input, diagnostics) {
 	const zod = getProperty(input, "_zod");
-	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");
+	if (!isObject(zod)) throw new SchemaNormalisationError("Input is not a valid Zod 4 schema: `_zod` is present but is not an object. schema-components expected a Zod 4 schema produced by the `zod` package version 4 or later. See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4", input, "unsupported-schema");
+	const def = getProperty(zod, "def");
+	if (!isObject(def)) throw new SchemaNormalisationError("Input is not a valid Zod 4 schema: `_zod.def` is missing or not an object. schema-components expected a Zod 4 schema produced by the `zod` package version 4 or later. See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4", input, "unsupported-schema");
+	screenPreConversion(input, def, diagnostics);
 	const jsonSchema = callToJsonSchema(input);
 	if (!isObject(jsonSchema)) throw new SchemaNormalisationError("z.toJSONSchema() did not produce an object", input, "invalid-zod");
 	return {
@@ -284,6 +602,23 @@ function resolveOpenApiRef(doc, ref) {
 	}
 	throw new Error(`Unsupported OpenAPI ref format: ${ref}`);
 }
+/**
+* Surface root-level metadata from the JSON Schema into the `rootMeta`
+* shape consumed by the walker. Pulls `readOnly`, `writeOnly`,
+* `description`, `title`, `deprecated`, `examples`, and `default`
+* directly from the schema root.
+*
+* `examples` is forwarded only when present as an array (per JSON Schema
+* Draft 2020-12 — Draft 04's `example` singular is normalised upstream).
+* `default` is forwarded for any value the schema declares (any JSON
+* value, including `null` and `false`); the presence check uses `in`
+* so a literal `false` or `null` default is preserved.
+*
+* `examples` and `default` ride on the `[key: string]: unknown` index
+* signature of {@link SchemaMeta}. They are not declared as named fields
+* on `SchemaMeta` because that type lives in `types.ts` and is shared
+* with the walker; the index signature is the agreed extension point.
+*/
 function extractRootMetaFromJson(jsonSchema) {
 	const meta = {};
 	if (jsonSchema.readOnly === true) meta.readOnly = true;
@@ -291,7 +626,9 @@ function extractRootMetaFromJson(jsonSchema) {
 	if (typeof jsonSchema.description === "string") meta.description = jsonSchema.description;
 	if (typeof jsonSchema.title === "string") meta.title = jsonSchema.title;
 	if (typeof jsonSchema.deprecated === "boolean") meta.deprecated = jsonSchema.deprecated;
+	if (Array.isArray(jsonSchema.examples)) meta.examples = jsonSchema.examples;
+	if ("default" in jsonSchema) meta.default = jsonSchema.default;
 	return Object.keys(meta).length > 0 ? meta : void 0;
 }
 //#endregion
-export { detectSchemaKind, normaliseSchema };
+export { __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, normaliseSchema };

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-C9zw9wbX.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { E as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-BrRMV0en.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-D0QCYGv0.mjs";
 
 //#region src/core/constraints.d.ts
 declare function extractStringConstraints(schema: Record<string, unknown>, diagnostics?: DiagnosticsOptions, pointer?: string): StringConstraints;