schema-components 1.22.0 → 1.23.0

package/README.md

@@ -16,7 +16,9 @@ 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). 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.
+schema-components requires **Zod 4**. If you are on Zod 3, see the [Zod 4 migration guide](https://zod.dev/v4/migration). Zod 3 schemas are detected structurally — any object exposing `_def` without the Zod 4 `_zod` marker is classified as Zod 3, with or without the historical `_def.typeName` field. (Some third-party Zod-3-style libraries omit `typeName`; the detector keys on the presence of `_def` alone.) A descriptive `SchemaNormalisationError` is raised pointing at the Zod 4 migration guide.
+
+Schemas from other libraries that conform to the [Standard Schema](https://standardschema.dev/) spec (valibot, arktype, ...) are also detected and rejected. When the input advertises a `~standard.vendor` field, the error message includes the vendor name so consumers know which library produced the input.
 
 ## `SchemaComponent`
 

package/dist/core/adapter.d.mts

@@ -1,5 +1,5 @@
-import { m as JsonObject, w as SchemaMeta } from "../types-BrRMV0en.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-D0QCYGv0.mjs";
+import { m as JsonObject, w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;
@@ -22,6 +22,82 @@ type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi" | "unsupported-sche
  * - `jsonSchema` — fallback for anything that does not match the above.
  */
 declare function detectSchemaKind(input: unknown): SchemaKind;
+/**
+ * Wraps z.toJSONSchema() for a runtime-validated Zod schema.
+ *
+ * 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.
+ *
+ * # 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` — selects which side of every transform / pipe / codec is
+ *   converted. Defaults to `"output"` (the OUTPUT side); pass `"input"`
+ *   to render the INPUT side instead. The input side is invisible to
+ *   the converted schema when `io: "output"` is in force, 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 selected 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 → 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.
+ *
+ * The original error is preserved on each classified error via the `cause`
+ * field so consumers can still inspect the Zod stack trace.
+ */
+/**
+ * IO side passed to {@link callToJsonSchema}. The Zod runtime accepts
+ * `"input" | "output"` for the corresponding `io` option on
+ * `z.toJSONSchema`. Defaults to `"output"` everywhere in the adapter
+ * pipeline; the parameter exists so a future renderer or component
+ * (currently SchemaComponent — see TODO below) can request the input
+ * side without forking the helper.
+ */
+type SchemaIoSide = "input" | "output";
 /**
  * Exposed for unit testing — lets the contract test enumerate every rule's
  * `prefix` value and assert mutual non-prefixing.
@@ -44,5 +120,23 @@ interface NormaliseOptions {
   diagnostics?: DiagnosticsOptions;
 }
 declare function normaliseSchema(input: unknown, ref?: string, options?: NormaliseOptions): NormalisedSchema;
+/**
+ * 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.
+ */
+declare function extractRootMetaFromJson(jsonSchema: JsonObject): SchemaMeta | undefined;
 //#endregion
-export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaKind, type SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, normaliseSchema };
+export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaIoSide, SchemaKind, type SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, extractRootMetaFromJson, normaliseSchema };

package/dist/core/adapter.mjs

@@ -1,10 +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-DVEJQmF7.mjs";
+import { a as normaliseJsonSchema$1, o as normaliseOpenApiSchemas } from "../normalise-DCYp06Sr.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -44,92 +44,49 @@ function detectSchemaKind(input) {
 	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.
+* 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";
 }
 /**
-* Wraps z.toJSONSchema() for a runtime-validated Zod schema.
-*
-* 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.
-*
-* # 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 → 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.
-*
-* The original error is preserved on each classified error via the `cause`
-* field so consumers can still inspect the Zod stack trace.
+* 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 callToJsonSchema(schema) {
+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: "output"
+			io
 		});
 	} catch (err) {
 		throw classifyZodConversionError(err, schema);
@@ -155,46 +112,205 @@ function callToJsonSchema(schema) {
 */
 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. 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).
+* 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.
 *
-* 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.
+* 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, def, diagnostics) {
+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 `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") 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, {
+	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: "",
+		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.
+*
+* Pointer accumulation:
+*
+* - 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 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 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);
 }
 /**
-* 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.
+* Format an empty pointer as `<root>` so error messages do not contain
+* a stray bare `""`. Non-empty pointers are returned verbatim.
 */
-function isCodecSchema(input) {
-	const zod = getProperty(input, "_zod");
-	if (!isObject(zod)) return false;
+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("$ZodCodec");
+	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 candidate();
+	} catch {
+		return;
+	}
+}
+/**
 * 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
@@ -336,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);
 		}
 	},
@@ -345,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] ?? ""}. 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);
+			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);
 		}
 	},
 	{
@@ -377,6 +502,22 @@ const COMPILED_CLASSIFIER_RULES = CLASSIFIER_RULES.map((rule) => ({
 	pattern: anchored(rule.prefix)
 }));
 /**
+* 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.
@@ -426,7 +567,13 @@ function containsNestedZod3Inner(value, visited, depth) {
 	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);
+	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;
 }
@@ -460,7 +607,10 @@ function normaliseSchema(input, ref, options) {
 		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 "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);
@@ -476,9 +626,8 @@ function normaliseSchema(input, ref, options) {
 function normaliseZod4(input, diagnostics) {
 	const zod = getProperty(input, "_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);
+	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 {
@@ -598,7 +747,7 @@ 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}`);
 }
@@ -631,4 +780,4 @@ function extractRootMetaFromJson(jsonSchema) {
 	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 { 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";
+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) {