schema-components 1.21.0 → 1.23.0

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 { appendPointer, 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-DaSrnr8g.mjs";
+import { a as normaliseJsonSchema$1, o as normaliseOpenApiSchemas } from "../normalise-DCYp06Sr.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -18,60 +19,295 @@ 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";
 }
 /**
-* Wraps z.toJSONSchema() for a runtime-validated Zod schema.
+* Heuristic: a non-Zod object that exposes either a Standard Schema
+* `~standard.validate` entry point (valibot, arktype, and any pure
+* Standard-Schema-conformant library) or both legacy `.parse`/`.safeParse`
+* callables is almost certainly an instance of a competing schema
+* library. 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.
+*
+* Standard Schema detection takes priority: the spec mandates a
+* `~standard` property carrying `{ validate, vendor, version }`. Pure
+* Standard Schema implementations may not expose any `.parse`/`.safeParse`
+* surface (those are a Zod / convenience API, not part of the spec), so
+* the legacy heuristic alone would miss them. See
+* https://standardschema.dev/ for the contract.
+*/
+function isLikelyOtherSchemaLib(input) {
+	if (!isObject(input)) return false;
+	if (hasProperty(input, "_zod") || hasProperty(input, "_def")) return false;
+	if (isObject(input["~standard"])) return true;
+	const parse = input.parse;
+	const safeParse = input.safeParse;
+	return typeof parse === "function" && typeof safeParse === "function";
+}
+/**
+* Extract the Standard Schema vendor string from a non-Zod input, when
+* present. Returns `undefined` if the input does not advertise itself
+* via the `~standard.vendor` field. Used to enrich the
+* `unsupported-schema` error message with the library name so the
+* consumer knows whether they have valibot, arktype, or another
+* implementation in front of them.
+*/
+function extractStandardSchemaVendor(input) {
+	const vendor = getProperty(getProperty(input, "~standard"), "vendor");
+	return typeof vendor === "string" && vendor.length > 0 ? vendor : void 0;
+}
+function callToJsonSchema(schema, io = "output") {
+	try {
+		return z.toJSONSchema(schema, {
+			target: "draft-2020-12",
+			unrepresentable: "throw",
+			cycles: "ref",
+			io
+		});
+	} catch (err) {
+		throw classifyZodConversionError(err, schema);
+	}
+}
+/**
+* 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:
+*
+* - `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.
+*
+* 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 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."]]);
+/**
+* Pre-conversion screening. Walks the entire Zod schema tree looking for
+* silently-misrendered or caveat-bearing constructs and surfaces each as
+* either a hard rejection (raised as a `SchemaNormalisationError`) or a
+* diagnostic on the configured sink:
+*
+* - `z.promise(T)` at any depth → rejection (see
+*   {@link PRECONVERSION_UNREPRESENTABLE_TAGS}). Each nested occurrence
+*   first emits a `zod-promise-nested-unwrap` diagnostic so consumers
+*   with a sink see every offending location before the throw fires.
+*   The root occurrence still throws via the same path so behaviour is
+*   uniform regardless of position in the tree.
+* - `z.codec(...)` at the root → `zod-codec-output-only` diagnostic.
+* - `z.codec(...)` nested below the root →
+*   `zod-codec-nested-output-only` diagnostic per occurrence.
+* - `z.preprocess(...)` at any depth → `zod-preprocess-output-only`
+*   diagnostic per occurrence. Preprocess never throws inside Zod (it
+*   silently rewrites to the output side), so the diagnostic is the
+*   only consumer-visible signal.
+*
+* Detection is structural — `_zod.def.type` plus `_zod.traits` (where
+* present) — and is depth-capped via {@link MAX_REF_DEPTH} with a
+* `visited` set to defend against cyclic graphs. JSON-pointer fragments
+* are accumulated as the walk descends so diagnostics report the exact
+* subschema location rather than `""`.
+*
+* 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.
+*/
+function screenPreConversion(input, diagnostics) {
+	let rejection;
+	screenPreConversionWalk(input, "", 0, true, /* @__PURE__ */ new Set(), diagnostics, (err) => {
+		rejection ??= err;
+	});
+	if (rejection !== void 0) throw rejection;
+}
+/**
+* Inner recursion for {@link screenPreConversion}. Visits every Zod
+* node reachable from `node`, emitting diagnostics and capturing
+* rejections through `recordRejection`. The walk is targeted: only
+* `_zod.def` is descended into (sibling `_zod.*` members are
+* implementation surface and never carry user schemas — same rule as
+* {@link containsNestedZod3Inner}).
 *
-* The _zod guard in normaliseZod4 has confirmed this is a valid Zod schema,
-* 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.
+* The `pointer` parameter tracks the JSON Pointer to the current
+* subschema so diagnostics carry an accurate location. The `isRoot`
+* flag distinguishes the entry call from recursive descents so
+* `zod-codec-output-only` (root) and `zod-codec-nested-output-only`
+* (nested) fire from the same code path.
+*/
+function screenPreConversionWalk(node, pointer, depth, isRoot, visited, diagnostics, recordRejection) {
+	if (depth >= 64) return;
+	if (!isObject(node)) return;
+	if (visited.has(node)) return;
+	visited.add(node);
+	const zod = getProperty(node, "_zod");
+	if (!isObject(zod)) return;
+	const def = getProperty(zod, "def");
+	if (!isObject(def)) return;
+	const tag = def.type;
+	if (typeof tag === "string") {
+		const unrepresentableMessage = PRECONVERSION_UNREPRESENTABLE_TAGS.get(tag);
+		if (unrepresentableMessage !== void 0) {
+			if (tag === "promise") emitDiagnostic(diagnostics, {
+				code: "zod-promise-nested-unwrap",
+				message: `z.promise(...) detected at ${formatPointer(pointer)}. 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.`,
+				pointer,
+				detail: { zodType: "promise" }
+			});
+			recordRejection(new SchemaNormalisationError(unrepresentableMessage, node, "zod-type-unrepresentable", tag));
+		}
+	}
+	if (tag === "pipe" && hasTrait(zod, "$ZodCodec")) if (isRoot) 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" }
+	});
+	else emitDiagnostic(diagnostics, {
+		code: "zod-codec-nested-output-only",
+		message: `z.codec(...) detected at ${formatPointer(pointer)}. Only the OUTPUT side is rendered by schema-components; the input side is invisible to the converted schema even though safeParse still consumes the input shape.`,
+		pointer,
+		detail: { zodType: "codec" }
+	});
+	if (tag === "pipe" && hasTrait(zod, "$ZodPreprocess")) emitDiagnostic(diagnostics, {
+		code: "zod-preprocess-output-only",
+		message: `z.preprocess(...) detected at ${formatPointer(pointer)}. Zod silently renders the OUTPUT-side schema; the preprocess function and its input shape are invisible to the rendered schema. If you need the input shape, restructure the schema to declare it directly.`,
+		pointer,
+		detail: { zodType: "preprocess" }
+	});
+	screenPreConversionDescend(def, pointer, depth + 1, visited, diagnostics, recordRejection);
+}
+/**
+* Descend into the values of a Zod `def` object, visiting every nested
+* Zod schema. `def` shapes are heterogeneous, so we walk recursively
+* through plain objects and arrays until we find a value with a
+* `_zod.def` marker — those nodes are the user-supplied sub-schemas.
 *
-* 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:
+* Pointer accumulation:
 *
-* - 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.
-* - 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.
-* - 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.
+* - For `def.shape.<key>` we emit pointers of the form
+*   `/properties/<key>`, matching the JSON Schema rendering of an
+*   object's properties so diagnostics line up with what consumers see
+*   in the rendered output.
+* - For `def.items[<i>]` we emit `/items/<i>`.
+* - For `def.options[<i>]` we emit `/anyOf/<i>` so union members line
+*   up with their JSON Schema position.
+* - For pipe `def.in` / `def.out` we emit `/in` / `/out`.
+* - Everything else descends without extending the pointer (the
+*   diagnostic stays anchored at the parent location).
 *
-* The original error is preserved on each classified error via the `cause`
-* field so consumers can still inspect the Zod stack trace.
+* The pointer scheme is deliberately conservative — it errs on the
+* side of "parent-anchored" when the JSON Schema name for a Zod field
+* is ambiguous, rather than fabricating a synthetic location.
 */
-function callToJsonSchema(schema) {
+function screenPreConversionDescend(def, parentPointer, depth, visited, diagnostics, recordRejection) {
+	if (depth >= 64) return;
+	const shape = getProperty(def, "shape");
+	if (isObject(shape)) {
+		const shapeBase = appendPointer(parentPointer, "properties");
+		for (const [key, value] of Object.entries(shape)) screenPreConversionWalk(value, appendPointer(shapeBase, key), depth + 1, false, visited, diagnostics, recordRejection);
+	}
+	const items = getProperty(def, "items");
+	if (Array.isArray(items)) {
+		const itemsBase = appendPointer(parentPointer, "items");
+		items.forEach((item, index) => {
+			screenPreConversionWalk(item, appendPointer(itemsBase, String(index)), depth + 1, false, visited, diagnostics, recordRejection);
+		});
+	} else if (isObject(items)) screenPreConversionWalk(items, appendPointer(parentPointer, "items"), depth + 1, false, visited, diagnostics, recordRejection);
+	const options = getProperty(def, "options");
+	if (Array.isArray(options)) {
+		const optionsBase = appendPointer(parentPointer, "anyOf");
+		options.forEach((option, index) => {
+			screenPreConversionWalk(option, appendPointer(optionsBase, String(index)), depth + 1, false, visited, diagnostics, recordRejection);
+		});
+	}
+	const inSide = getProperty(def, "in");
+	if (isObject(inSide)) screenPreConversionWalk(inSide, appendPointer(parentPointer, "in"), depth + 1, false, visited, diagnostics, recordRejection);
+	const outSide = getProperty(def, "out");
+	if (isObject(outSide)) screenPreConversionWalk(outSide, appendPointer(parentPointer, "out"), depth + 1, false, visited, diagnostics, recordRejection);
+	const innerType = getProperty(def, "innerType");
+	if (isObject(innerType)) screenPreConversionWalk(innerType, parentPointer, depth + 1, false, visited, diagnostics, recordRejection);
+	const valueType = getProperty(def, "valueType");
+	if (isObject(valueType)) screenPreConversionWalk(valueType, appendPointer(parentPointer, "additionalProperties"), depth + 1, false, visited, diagnostics, recordRejection);
+	const inner = safeCallNoArgs(getProperty(def, "getter"));
+	if (isObject(inner)) screenPreConversionWalk(inner, parentPointer, depth + 1, false, visited, diagnostics, recordRejection);
+}
+/**
+* Format an empty pointer as `<root>` so error messages do not contain
+* a stray bare `""`. Non-empty pointers are returned verbatim.
+*/
+function formatPointer(pointer) {
+	return pointer === "" ? "<root>" : pointer;
+}
+/**
+* True when a Zod node's `_zod.traits` set contains the named marker.
+* Returns false when traits is absent or not a Set — Zod always
+* populates it on real schemas, so the missing-Set case is treated as
+* "marker not present".
+*/
+function hasTrait(zod, traitName) {
+	const traits = zod.traits;
+	if (traits instanceof Set) return traits.has(traitName);
+	return false;
+}
+/**
+* Type guard narrowing `unknown` to a zero-argument function returning
+* `unknown`. The narrowing is genuinely structural: `typeof === "function"`
+* at runtime is exactly the membership test we want, and Zod has no
+* way to make a getter "have the wrong arity" without breaking its own
+* lazy implementation. Surfacing the narrowing through a guard means
+* the call site can invoke `fn()` without an `as` assertion and the
+* boundary lives in one named, documented location.
+*/
+function isNoArgFunction(value) {
+	return typeof value === "function";
+}
+/**
+* Invoke a value as a zero-argument function safely, returning whatever
+* the function returns or `undefined` if it throws or is not callable.
+* Centralises the lazy-schema getter invocation that both
+* {@link containsNestedZod3Inner} and {@link screenPreConversionDescend}
+* need; the throw is swallowed because the absence of a materialisable
+* inner is not a screening concern — downstream `z.toJSONSchema` will
+* surface any genuine construction failure with its own message.
+*/
+function safeCallNoArgs(candidate) {
+	if (!isNoArgFunction(candidate)) return void 0;
 	try {
-		return z.toJSONSchema(schema);
-	} catch (err) {
-		throw classifyZodConversionError(err, schema);
+		return candidate();
+	} catch {
+		return;
 	}
 }
 /**
@@ -106,14 +342,27 @@ function unrepresentableMessage(typeName, fullMessage) {
 * 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`):
-* - 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),
-*   L258 (transforms), L264 (map), L270 (set), L521 (dynamic catch).
-* - zod/src/v4/core/to-json-schema.ts L182 (non-representable type fallback),
-*   L225 + L364 (unprocessed schema), L235 (duplicate id), L307 (cycle),
-*   L522 (error converting).
+* 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:
+*
+* - `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 = [
 	{
@@ -203,8 +452,11 @@ const CLASSIFIER_RULES = [
 		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;
+			const trailing = match[1];
+			if (trailing === void 0) return describeUnparsableZodWording("Non-representable type prefix matched but no trailing capture", full, schema, cause);
+			const trimmed = trailing.trim();
+			const firstToken = trimmed.length > 0 ? trimmed.split(/\s+/)[0] : void 0;
+			const typeName = firstToken !== void 0 && firstToken.length > 0 ? firstToken : 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);
 		}
 	},
@@ -212,16 +464,22 @@ const CLASSIFIER_RULES = [
 		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] ?? ""}. Cycles can only be converted when z.toJSONSchema is called with { cycles: "ref" } — schema-components calls it without options for cache safety, so the cycle surfaces as an error. Restructure the schema to break the cycle, or use a $ref-based definition. Original message: ${full}`, schema, "zod-cycle-detected", void 0, cause);
+			const trailing = match[1];
+			if (trailing === void 0) return describeUnparsableZodWording("Cycle detected prefix matched but no trailing capture", full, schema, cause);
+			const path = trailing.split(/\s+/)[0];
+			if (path === void 0 || path.length === 0) return describeUnparsableZodWording("Cycle detected message contained no pointer token", full, schema, cause);
+			return new SchemaNormalisationError(`Zod detected a cycle in the schema graph at ${path}. 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 trailing = match[1];
+			if (trailing === void 0) return describeUnparsableZodWording("Duplicate schema id prefix matched but no trailing capture", full, schema, cause);
 			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);
+			if (closing === -1) return describeUnparsableZodWording("Duplicate schema id message had no closing quote", full, schema, cause);
+			return new SchemaNormalisationError(`Two different Zod schemas share the same id "${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);
 		}
 	},
 	{
@@ -244,33 +502,79 @@ const COMPILED_CLASSIFIER_RULES = CLASSIFIER_RULES.map((rule) => ({
 	pattern: anchored(rule.prefix)
 }));
 /**
-* Walk an arbitrary value looking for Zod 3 markers (`_def.typeName`).
-* Zod 4 schemas always carry a `_zod.def`; Zod 3 schemas carry `_def`
-* with a `typeName` field. Presence of the latter anywhere in the tree
-* means a Zod 3 schema was nested inside a Zod 4 input, which is what
-* trips the V8 `"Cannot read properties of undefined"` failure.
+* Build a structured `zod-conversion-failed` error for the case where a
+* classifier rule's prefix matched but the trailing capture or follow-on
+* parsing could not extract the expected payload (cycle pointer,
+* duplicate id, non-representable type name, ...).
+*
+* This replaces the previous pattern of substituting an empty string
+* fallback — `match[1] ?? ""` would silently produce error messages like
+* `"Zod detected a cycle in the schema graph at ."` whenever Zod's
+* wording drifted, hiding the regression behind a misleading message.
+* Raising a wording-regression error instead surfaces the drift loudly
+* so the classifier rule (and its contract test) can be repaired.
+*/
+function describeUnparsableZodWording(reason, fullMessage, schema, cause) {
+	return new SchemaNormalisationError(`Zod error matched a classifier prefix but the trailing message could not be parsed (${reason}). This usually means Zod has reworded the error since the classifier was last updated — the matching rule in adapter.ts CLASSIFIER_RULES needs to be revised to track the new wording. Original message: ${fullMessage}`, schema, "zod-conversion-failed", void 0, cause);
+}
+/**
+* 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.
+*/
+/**
+* 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.
 *
-* The walk is bounded by an explicit `visited` set so cyclical references
-* cannot cause stack overflow. The recursion follows both array elements
-* and own enumerable properties of every object encountered.
+* 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.
 */
 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 (containsNestedZod3(item, visited)) return true;
+		for (const item of value) if (containsNestedZod3Inner(item, visited, depth + 1)) return true;
 		return false;
 	}
 	if (!isObject(value)) return false;
 	const def = value._def;
-	if (value._zod === void 0 && isObject(def) && typeof def.typeName === "string") return true;
-	for (const key of Object.keys(value)) if (containsNestedZod3(value[key], visited)) return true;
+	const zod = value._zod;
+	if (zod === void 0 && isObject(def)) return true;
+	if (isObject(zod) && isObject(zod.def)) {
+		const def4 = zod.def;
+		if (def4.type === "lazy") {
+			if (containsNestedZod3Inner(safeCallNoArgs(def4.getter), visited, depth + 1)) return true;
+		}
+		return containsNestedZod3Inner(def4, 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) {
@@ -288,7 +592,9 @@ function classifyZodConversionError(err, schema) {
 */
 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;
 	}
@@ -296,11 +602,15 @@ 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": {
+			const vendor = extractStandardSchemaVendor(input);
+			throw new SchemaNormalisationError(`Input looks like a schema from a non-Zod library — ${vendor !== void 0 ? `it self-identifies as the Standard Schema implementation "${vendor}"` : "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);
@@ -310,13 +620,14 @@ 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");
+	if (!isObject(getProperty(zod, "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, diagnostics);
 	const jsonSchema = callToJsonSchema(input);
 	if (!isObject(jsonSchema)) throw new SchemaNormalisationError("z.toJSONSchema() did not produce an object", input, "invalid-zod");
 	return {
@@ -436,10 +747,27 @@ function resolveOpenApiRef(doc, ref) {
 	}
 	if (ref.startsWith("#/")) {
 		const resolved = dereference(ref, doc);
-		if (resolved !== void 0) return resolved;
+		if (resolved !== void 0 && typeof resolved !== "boolean") return resolved;
 	}
 	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;
@@ -447,7 +775,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 { __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, normaliseSchema };
+export { __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, extractRootMetaFromJson, 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-BnxPEElk.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-BTB73MB8.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
 
 //#region src/core/constraints.d.ts
 declare function extractStringConstraints(schema: Record<string, unknown>, diagnostics?: DiagnosticsOptions, pointer?: string): StringConstraints;

package/dist/core/constraints.mjs

@@ -1,4 +1,3 @@
-import { isObject } from "./guards.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { FORMAT_PATTERNS } from "./formats.mjs";
 //#region src/core/constraints.ts
@@ -10,10 +9,6 @@ function getNumber(obj, key) {
 	const value = obj[key];
 	return typeof value === "number" ? value : void 0;
 }
-function getObject(obj, key) {
-	const value = obj[key];
-	return isObject(value) ? value : void 0;
-}
 function extractStringConstraints(schema, diagnostics, pointer = "") {
 	const c = {};
 	const minLength = getNumber(schema, "minLength");
@@ -65,8 +60,6 @@ function extractArrayConstraints(schema) {
 	if (minContains !== void 0) c.minContains = minContains;
 	const maxContains = getNumber(schema, "maxContains");
 	if (maxContains !== void 0) c.maxContains = maxContains;
-	const unevaluatedItems = getObject(schema, "unevaluatedItems");
-	if (unevaluatedItems !== void 0) c.unevaluatedItems = unevaluatedItems;
 	return c;
 }
 function extractObjectConstraints(schema) {