schema-components 1.21.0 → 1.22.0

package/dist/openapi/resolve.mjs

@@ -1,8 +1,10 @@
 import { getProperty, isObject } from "../core/guards.mjs";
+import "../core/limits.mjs";
+import { emitDiagnostic } from "../core/diagnostics.mjs";
 import { isPrototypePollutingKey } from "../core/uri.mjs";
 import { detectOpenApiVersion } from "../core/version.mjs";
-import { a as normaliseOpenApiSchemas } from "../normalise-DaSrnr8g.mjs";
-import { getParameters, getRequestBody, getResponses, listOperations, parseOpenApiDocument } from "./parser.mjs";
+import { a as normaliseOpenApiSchemas } from "../normalise-DVEJQmF7.mjs";
+import { getParameters, getRequestBody, getResponses, listOperations, listWebhooks, parseOpenApiDocument } from "./parser.mjs";
 //#region src/openapi/resolve.ts
 /**
 * OpenAPI document resolution and caching.
@@ -43,7 +45,20 @@ function getParsed(doc, diagnostics) {
 		if (cached !== void 0) return cached;
 	}
 	const version = detectOpenApiVersion(doc);
+	if (diagnostics !== void 0 && version?.major === 3 && docHasXmlAnywhere(doc)) emitDiagnostic(diagnostics, {
+		code: "dropped-swagger-feature",
+		message: `OpenAPI ${String(version.major)}.${String(version.minor)} xml Schema Object metadata is not rendered and will be ignored`,
+		pointer: "",
+		detail: {
+			feature: "xml",
+			source: "openapi-3.x"
+		}
+	});
 	const normalisedDoc = version !== void 0 ? normaliseOpenApiSchemas(doc, version, diagnostics) : doc;
+	if (diagnostics !== void 0) {
+		validateSecuritySchemeTypes(normalisedDoc, diagnostics);
+		detectUnsupportedCrossSchemaRefs(normalisedDoc, diagnostics);
+	}
 	const parsed = parseOpenApiDocument(normalisedDoc);
 	if (diagnostics === void 0) {
 		docCache.set(doc, parsed);
@@ -52,11 +67,133 @@ function getParsed(doc, diagnostics) {
 	return parsed;
 }
 /**
-* Coerce an unknown value to a record, returning an empty record
-* for non-objects.
+* Coerce an unknown value to a record, returning `undefined` when the
+* value is not a plain object. Callers MUST handle the `undefined` case
+* explicitly — typically by rendering a "doc not an object" diagnostic
+* and short-circuiting, never by silently substituting `{}`.
+*
+* A previous implementation fell back to `{}` for non-objects, which
+* masked configuration mistakes (passing a string, `null`, an array, or
+* `undefined` as the OpenAPI document) as an empty document with no
+* operations.
 */
 function toDoc(value) {
-	return isObject(value) ? value : {};
+	return isObject(value) ? value : void 0;
+}
+/**
+* Known security scheme types per the OpenAPI 3.0/3.1 specification.
+* `mutualTLS` was added in OpenAPI 3.1. Unknown values surface a
+* `unknown-security-scheme-type` diagnostic so authors notice typos
+* (e.g. `mutalTLS`) that would otherwise render with no warning.
+*/
+const KNOWN_SECURITY_SCHEME_TYPES = new Set([
+	"apiKey",
+	"http",
+	"oauth2",
+	"openIdConnect",
+	"mutualTLS"
+]);
+/**
+* Validate every `components.securitySchemes.<name>.type` against the
+* canonical OpenAPI security scheme types and emit
+* `unknown-security-scheme-type` for each entry whose type is not
+* recognised. Runs after normalisation so Swagger 2.0 documents (which
+* are already translated to OAS 3.x shapes by `translateSwaggerSecurityScheme`)
+* are validated alongside native 3.x documents.
+*/
+function validateSecuritySchemeTypes(doc, diagnostics) {
+	const components = doc.components;
+	if (!isObject(components)) return;
+	const schemes = components.securitySchemes;
+	if (!isObject(schemes)) return;
+	for (const [name, scheme] of Object.entries(schemes)) {
+		if (!isObject(scheme)) continue;
+		const type = scheme.type;
+		if (typeof type !== "string") {
+			emitDiagnostic(diagnostics, {
+				code: "unknown-security-scheme-type",
+				message: `Security scheme "${name}" has no type or a non-string type`,
+				pointer: `/components/securitySchemes/${name}/type`,
+				detail: {
+					name,
+					type
+				}
+			});
+			continue;
+		}
+		if (!KNOWN_SECURITY_SCHEME_TYPES.has(type)) emitDiagnostic(diagnostics, {
+			code: "unknown-security-scheme-type",
+			message: `Security scheme "${name}" declares unknown type "${type}"`,
+			pointer: `/components/securitySchemes/${name}/type`,
+			detail: {
+				name,
+				type
+			}
+		});
+	}
+}
+/**
+* Detect any `$ref` strings that survived normalisation in a non-
+* fragment shape (anything not starting with `#/` or `#`). After
+* `normaliseOpenApiSchemas` runs `resolveRelativeRefs`, every relative
+* `$ref` within a Schema Object is rewritten to an absolute fragment.
+* Refs that *cross* Schema Object boundaries — for example, a relative
+* ref inside one component schema pointing into another via a sibling
+* `$id` — cannot be resolved by the current pipeline (this is a
+* documented limitation; see the JSDoc on this function).
+*
+* Emit a single diagnostic per offending ref so consumers notice
+* silently broken references rather than discovering them only when
+* the walker fails to render the target.
+*
+* NOTE: We can't determine "crossing" cleanly from the parser alone —
+* doing so would require modelling every Schema Object's $id scope.
+* As a pragmatic approximation, any surviving non-`#`-prefixed `$ref`
+* is treated as cross-Schema-Object unsupported. False positives
+* (legitimate external refs that the consumer planned to bundle later)
+* are still useful — they confirm an unresolved reference is present.
+*/
+function detectUnsupportedCrossSchemaRefs(doc, diagnostics) {
+	const seenRefs = /* @__PURE__ */ new Set();
+	const walk = (node, pointer) => {
+		if (Array.isArray(node)) {
+			for (const [index, item] of node.entries()) walk(item, `${pointer}/${String(index)}`);
+			return;
+		}
+		if (!isObject(node)) return;
+		const ref = node.$ref;
+		if (typeof ref === "string" && !ref.startsWith("#") && !seenRefs.has(ref)) {
+			seenRefs.add(ref);
+			emitDiagnostic(diagnostics, {
+				code: "cross-schema-relative-ref-unsupported",
+				message: `Relative \`$ref\` "${ref}" was not resolved during normalisation; cross-Schema-Object relative refs are not currently supported`,
+				pointer,
+				detail: { ref }
+			});
+			return;
+		}
+		for (const [key, value] of Object.entries(node)) walk(value, `${pointer}/${key}`);
+	};
+	walk(doc, "");
+}
+/**
+* Recursively check whether any node in an OpenAPI document carries an
+* `xml` annotation. Walks both objects and arrays so the check works
+* for schemas in `components/schemas`, inline `paths`/`webhooks`
+* schemas, request bodies, responses, headers, and parameters. Used
+* by `getParsed` to surface the dropped-feature diagnostic for OAS
+* 3.0/3.1 — the Swagger 2.0 path has its own detection in
+* `swagger2.ts`.
+*/
+function docHasXmlAnywhere(node) {
+	if (Array.isArray(node)) {
+		for (const item of node) if (docHasXmlAnywhere(item)) return true;
+		return false;
+	}
+	if (!isObject(node)) return false;
+	if ("xml" in node && isObject(node.xml)) return true;
+	for (const value of Object.values(node)) if (docHasXmlAnywhere(value)) return true;
+	return false;
 }
 /**
 * Look up a Path Item Object on the (already-normalised) parsed document,
@@ -67,23 +204,46 @@ function toDoc(value) {
 * Implemented inside `resolve.ts` to avoid touching `parser.ts` while
 * still surfacing path-item-level metadata to the React layer.
 */
-function lookupPathItemNode(parsed, path) {
-	return resolvePathItemNode(parsed, getProperty(getProperty(parsed.doc, "paths"), path));
+function lookupPathItemNode(parsed, path, diagnostics) {
+	const fromPaths = resolvePathItemNode(parsed, getProperty(getProperty(parsed.doc, "paths"), path), diagnostics);
+	if (fromPaths !== void 0) return fromPaths;
+	return resolvePathItemNode(parsed, getProperty(getProperty(parsed.doc, "webhooks"), path), diagnostics);
 }
-function resolvePathItemNode(parsed, pathItem) {
+function resolvePathItemNode(parsed, pathItem, diagnostics) {
 	if (!isObject(pathItem)) return void 0;
-	const ref = getProperty(pathItem, "$ref");
-	if (typeof ref !== "string") return pathItem;
-	if (!ref.startsWith("#/")) return pathItem;
-	const parts = ref.slice(2).split("/");
-	let current = parsed.doc;
-	for (const part of parts) {
-		if (!isObject(current)) return void 0;
-		const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
-		if (isPrototypePollutingKey(decoded)) return void 0;
-		current = current[decoded];
+	const visited = /* @__PURE__ */ new Set();
+	let current = pathItem;
+	for (let hop = 0; hop < 8; hop++) {
+		const ref = getProperty(current, "$ref");
+		if (typeof ref !== "string") return current;
+		if (!ref.startsWith("#/")) return current;
+		if (visited.has(ref)) {
+			emitDiagnostic(diagnostics, {
+				code: "cyclic-path-item-ref",
+				message: `Cyclic Path Item Object $ref "${ref}"`,
+				pointer: ref,
+				detail: { ref }
+			});
+			return;
+		}
+		visited.add(ref);
+		const parts = ref.slice(2).split("/");
+		let node = parsed.doc;
+		for (const part of parts) {
+			if (!isObject(node)) return void 0;
+			const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
+			if (isPrototypePollutingKey(decoded)) return void 0;
+			node = node[decoded];
+		}
+		if (!isObject(node)) return current;
+		current = node;
 	}
-	return isObject(current) ? current : pathItem;
+	emitDiagnostic(diagnostics, {
+		code: "path-item-ref-too-deep",
+		message: `Path Item Object $ref chain exceeded ${String(8)} hops`,
+		pointer: "",
+		detail: { maxHops: 8 }
+	});
 }
 function extractPathItemInfo(pathItem) {
 	const summary = pathItem.summary;
@@ -103,10 +263,10 @@ function extractPathItemInfo(pathItem) {
 * normalisation pipeline (every re-run would emit each diagnostic
 * again into the sink).
 */
-function resolveOperationFromParsed(parsed, path, method) {
-	const operation = listOperations(parsed).find((op) => op.path === path && op.method === method);
+function resolveOperationFromParsed(parsed, path, method, diagnostics) {
+	const pathItemNode = lookupPathItemNode(parsed, path, diagnostics);
+	const operation = [...listOperations(parsed), ...listWebhooks(parsed).flatMap((w) => w.operations)].find((op) => op.path === path && op.method === method);
 	if (operation === void 0) throw new Error(`Operation not found: ${method.toUpperCase()} ${path}`);
-	const pathItemNode = lookupPathItemNode(parsed, path);
 	if (pathItemNode === void 0) throw new Error(`Path item missing for ${method.toUpperCase()} ${path}`);
 	return {
 		operation,
@@ -124,7 +284,7 @@ function resolveOperationFromParsed(parsed, path, method) {
 * events surface to the caller's sink.
 */
 function resolveOperation(doc, path, method, diagnostics) {
-	return resolveOperationFromParsed(getParsed(doc, diagnostics), path, method);
+	return resolveOperationFromParsed(getParsed(doc, diagnostics), path, method, diagnostics);
 }
 /**
 * Resolve parameters against an already-parsed document. See

package/dist/react/SchemaComponent.d.mts

@@ -1,8 +1,8 @@
-import { M as WalkedField, T as SchemaMeta, d as FieldOverrides, u as FieldOverride } from "../types-BnxPEElk.mjs";
-import { t as Diagnostic } from "../diagnostics-CbBPsxSt.mjs";
-import { t as SchemaError } from "../errors-QEwOtQAA.mjs";
-import { l as RenderProps, r as ComponentResolver } from "../renderer-DI6ZYf7a.mjs";
-import { c as PathOfType, l as RejectUnrepresentableZod, n as FromJSONSchema, u as ResolveOpenAPIRef } from "../typeInference-Bxw3NOG1.mjs";
+import { d as FieldOverrides, j as WalkedField, u as FieldOverride, w as SchemaMeta } from "../types-BrRMV0en.mjs";
+import { t as Diagnostic } from "../diagnostics-D0QCYGv0.mjs";
+import { t as SchemaError } from "../errors-DpFwqs5C.mjs";
+import { l as RenderProps, r as ComponentResolver } from "../renderer-BaRlQIuN.mjs";
+import { d as RejectUnrepresentableZod, f as ResolveOpenAPIRef, i as FromJSONSchemaMode, p as TypeAtPath, r as FromJSONSchema, u as PathOfType } from "../typeInference-DkcUHfaM.mjs";
 import { z } from "zod";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { ReactNode } from "react";
@@ -39,7 +39,54 @@ declare function registerWidget(name: string, render: (props: RenderProps) => un
 type InferFields<T, Ref extends string | undefined> = T extends z.ZodType ? FieldOverrides<z.infer<T>> : T extends {
   openapi: unknown;
 } ? Ref extends string ? FieldOverrides<ResolveOpenAPIRef<T & Record<string, unknown>, Ref>> : Record<string, FieldOverride> : T extends object ? unknown extends FromJSONSchema<T> ? Record<string, FieldOverride> : FieldOverrides<FromJSONSchema<T>> : Record<string, FieldOverride>;
-interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined> {
+/**
+ * Infer the data type carried by the schema input.
+ *
+ * Mirrors {@link InferFields}'s dispatch order: Zod schema → `z.infer`,
+ * OpenAPI doc + ref → `ResolveOpenAPIRef`, plain JSON Schema object →
+ * `FromJSONSchema`, everything else → `unknown`. The `Mode` parameter
+ * is plumbed through to `FromJSONSchema` / `ResolveOpenAPIRef` so
+ * `readOnly` / `writeOnly` keywords participate in the inferred
+ * object shape — `"output"` for the rendered value, `"input"` for the
+ * `onChange` argument.
+ *
+ * When the schema's value type cannot be statically determined (e.g.
+ * a runtime `Record<string, unknown>` JSON Schema, or an OpenAPI doc
+ * without a ref), the result falls back to `unknown` so callers can
+ * still supply arbitrary values.
+ */
+type InferSchemaValue<T, Ref extends string | undefined, Mode extends FromJSONSchemaMode> = T extends z.ZodType ? Mode extends "input" ? z.input<T> : z.output<T> : T extends {
+  openapi: unknown;
+} ? Ref extends string ? ResolveOpenAPIRef<T & Record<string, unknown>, Ref, [], Mode> : unknown : T extends object ? FromJSONSchema<T, Record<string, never>, [], Mode> | (unknown extends FromJSONSchema<T> ? unknown : never) extends infer V ? V : unknown : unknown;
+/**
+ * Narrow an inferred value type to the sub-shape at `P`, or return
+ * the original value type when `P` is `undefined` (no path supplied).
+ */
+type NarrowAtPath<V, P extends string | undefined> = P extends string ? TypeAtPath<V, P> : V;
+/**
+ * Public alias mapping a schema input to the rendered value type.
+ * Use to narrow a runtime callback inside the body of an `onChange`
+ * handler:
+ *
+ * ```tsx
+ * <SchemaComponent
+ *   schema={userSchema}
+ *   onChange={(v) => {
+ *     const user = v as InferredOutputValue<typeof userSchema>;
+ *     // ...narrowly typed access on `user`
+ *   }}
+ * />
+ * ```
+ *
+ * The `onChange` argument is typed `unknown` at the props boundary
+ * because the walker propagates `unknown` values through the render
+ * pipeline. Narrowing on the consumer side is therefore an explicit
+ * step and never a silent contract gap.
+ */
+type InferredOutputValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined> = NarrowAtPath<InferSchemaValue<T, Ref, "output">, P>;
+/** Companion to {@link InferredOutputValue} for `"input"`-mode shapes. */
+type InferredInputValue<T, Ref extends string | undefined = undefined, P extends string | undefined = undefined> = NarrowAtPath<InferSchemaValue<T, Ref, "input">, P>;
+interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined, P extends string | undefined = undefined> {
   /**
    * Zod schema, JSON Schema object, or OpenAPI document.
    *
@@ -53,9 +100,51 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   schema: RejectUnrepresentableZod<T>;
   /** For OpenAPI: a ref string like "#/components/schemas/User" or "/users/post". */
   ref?: Ref;
-  /** Current value to render. */
+  /**
+   * Optional dot-separated path used purely for type narrowing.
+   * When the schema is typed, the path is restricted to the valid
+   * dot-paths reachable through the schema's inferred value.
+   *
+   * RUNTIME CAVEAT: this prop is currently type-level only. The
+   * render pipeline still operates on the root schema; sub-path
+   * value resolution is provided by the dedicated `<SchemaField>`
+   * component, which already implements `resolvePath` /
+   * `setNestedValue`. The `path` prop here documents intent at the
+   * type level (and prepares the API surface) so consumers can
+   * declare narrow typed wrappers without runtime regressions. Use
+   * `<SchemaField>` when a sub-path render is required at runtime.
+   */
+  path?: P;
+  /**
+   * Current value to render.
+   *
+   * TYPE BOUNDARY NOTE: kept as `unknown` at the props boundary so
+   * existing call sites — including legitimate edge-case fixtures
+   * that pass deliberately invalid values to exercise fallback code
+   * paths — continue to typecheck. Use {@link InferredOutputValue}
+   * to narrow on the consumer side:
+   *
+   * ```tsx
+   * const user: InferredOutputValue<typeof userSchema> = { ... };
+   * <SchemaComponent schema={userSchema} value={user} readOnly />
+   * ```
+   *
+   * The narrowing is fully expressible through the helper alias
+   * without forcing every existing caller to update their value
+   * shapes for `exactOptionalPropertyTypes` / enum literal widening.
+   */
   value?: unknown;
-  /** Called when the value changes (editable fields). */
+  /**
+   * Called when the value changes (editable fields).
+   *
+   * TYPE BOUNDARY NOTE: the parameter is typed `unknown` rather
+   * than the inferred input shape because the walker pipeline only
+   * propagates `unknown` values and a narrow contravariant callback
+   * signature is not assignable from an `unknown`-emitting source
+   * without an unsafe boundary cast. The {@link InferredInputValue}
+   * alias is the recommended way for callers to narrow on the
+   * consumer side — `onChange={(v) => { const u = v as InferredInputValue<typeof schema>; ... }}`.
+   */
   onChange?: (value: unknown) => void;
   /** Run schema.safeParse() on change and surface errors via onValidationError. */
   validate?: boolean;
@@ -87,31 +176,7 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    */
   idPrefix?: string;
 }
-declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined>({
-  schema: schemaInput,
-  ref: refInput,
-  value,
-  onChange,
-  validate,
-  onValidationError,
-  onError,
-  onDiagnostic,
-  strict,
-  fields,
-  meta: componentMeta,
-  readOnly,
-  writeOnly,
-  description,
-  widgets: instanceWidgets,
-  idPrefix
-}: SchemaComponentProps<T, Ref>): ReactNode;
-/**
- * Default root-path sentinel used when no `idPrefix` is supplied AND the
- * component is rendered outside a React tree (e.g. server-side bundling
- * test harnesses). Production callers receive a `useId()`-derived prefix
- * that is unique per instance.
- */
-declare const ROOT_PATH = "root";
+declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined, P extends string | undefined = undefined>(props: SchemaComponentProps<T, Ref, P>): ReactNode;
 /**
  * Append a child path suffix to a parent path. When the suffix is omitted
  * (e.g. transparent wrappers like union options), the parent path is
@@ -154,7 +219,7 @@ interface SchemaFieldProps<T = unknown, Ref extends string | undefined = undefin
   validate?: boolean;
   onValidationError?: (error: unknown) => void;
 }
-declare function SchemaField<T = unknown, Ref extends string | undefined = undefined, P extends string = string>({
+declare function SchemaField<T = unknown, Ref extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)>({
   path,
   schema: schemaInput,
   ref: refInput,
@@ -165,4 +230,4 @@ declare function SchemaField<T = unknown, Ref extends string | undefined = undef
   onValidationError
 }: SchemaFieldProps<T, Ref, P>): ReactNode;
 //#endregion
-export { ROOT_PATH, SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, WidgetMap, joinPath, registerWidget, renderField, sanitisePrefix };
+export { InferredInputValue, InferredOutputValue, SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, WidgetMap, joinPath, registerWidget, renderField, sanitisePrefix };

package/dist/react/SchemaComponent.mjs

@@ -1,5 +1,6 @@
 "use client";
 import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import "../core/limits.mjs";
 import { SchemaFieldError, SchemaNormalisationError, SchemaRenderError } from "../core/errors.mjs";
 import { normaliseSchema } from "../core/adapter.mjs";
 import { buildRenderProps, getRenderFunction, mergeResolvers } from "../core/renderer.mjs";
@@ -46,7 +47,8 @@ const globalWidgets = /* @__PURE__ */ new Map();
 function registerWidget(name, render) {
 	globalWidgets.set(name, render);
 }
-function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, onDiagnostic, strict, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets, idPrefix }) {
+function SchemaComponent(props) {
+	const { schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, onDiagnostic, strict, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets, idPrefix } = props;
 	const userResolver = useContext(UserResolverContext);
 	const contextWidgets = useContext(WidgetsContext);
 	const generatedId = useId();
@@ -87,7 +89,17 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 	}
 	const handleChange = useCallback((nextValue) => {
 		if (validate) {
-			const error = runValidation(zodSchema, jsonSchema, nextValue, onDiagnostic);
+			let error;
+			try {
+				error = runValidation(zodSchema, jsonSchema, nextValue, onDiagnostic);
+			} catch (err) {
+				const normalised = err instanceof SchemaNormalisationError ? err : new SchemaNormalisationError(err instanceof Error ? err.message : "Fallback validation failed", schemaInput, "zod-conversion-failed", void 0, err);
+				if (onError !== void 0) {
+					onError(normalised);
+					return;
+				}
+				throw normalised;
+			}
 			if (error !== void 0) {
 				onValidationError?.(error);
 				dispatchFieldErrors(fields, error);
@@ -101,7 +113,9 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 		onChange,
 		onValidationError,
 		fields,
-		onDiagnostic
+		onDiagnostic,
+		onError,
+		schemaInput
 	]);
 	const walkOptions = {
 		componentMeta: mergedMeta,
@@ -119,13 +133,6 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild, rootPath, instanceWidgets, contextWidgets, 0);
 }
 /**
-* Default root-path sentinel used when no `idPrefix` is supplied AND the
-* component is rendered outside a React tree (e.g. server-side bundling
-* test harnesses). Production callers receive a `useId()`-derived prefix
-* that is unique per instance.
-*/
-const ROOT_PATH = "root";
-/**
 * Append a child path suffix to a parent path. When the suffix is omitted
 * (e.g. transparent wrappers like union options), the parent path is
 * returned unchanged so the child inherits the parent's id.
@@ -146,6 +153,21 @@ function sanitisePrefix(value) {
 	if (sanitised.length === 0) throw new Error(`Cannot derive a DOM-safe id prefix from "${value}". Pass an explicit idPrefix prop.`);
 	return sanitised;
 }
+/**
+* Run validation against the supplied value.
+*
+* Returns the validation error (Zod error or equivalent) on failure, or
+* `undefined` when the value is valid OR when the fallback validation
+* path was skipped because a diagnostic sink absorbed the conversion
+* failure.
+*
+* Throws `SchemaNormalisationError` (kind `zod-conversion-failed`) when
+* the JSON-Schema → Zod fallback is taken AND no diagnostic sink is
+* wired up. The project's no-silent-fallback rule requires the failure
+* to surface somewhere — diagnostics if the consumer opted in, an error
+* otherwise — so the caller can route it through `onError` / an error
+* boundary rather than have validation quietly disappear.
+*/
 function runValidation(zodSchema, jsonSchema, value, onDiagnostic) {
 	if (zodSchema !== void 0 && isObject(zodSchema)) {
 		const safeParseFn = zodSchema.safeParse;
@@ -159,8 +181,16 @@ function runValidation(zodSchema, jsonSchema, value, onDiagnostic) {
 	try {
 		parsed = z.fromJSONSchema(jsonSchema);
 	} catch (err) {
-		emitFromJsonSchemaDiagnostic(err, onDiagnostic);
-		return;
+		if (onDiagnostic !== void 0) {
+			onDiagnostic({
+				code: "unsupported-type",
+				message: `Skipping fallback validation: z.fromJSONSchema could not round-trip the normalised JSON Schema. Original message: ${err instanceof Error ? err.message : "z.fromJSONSchema threw a non-Error value"}`,
+				pointer: "",
+				detail: { source: "z.fromJSONSchema" }
+			});
+			return;
+		}
+		throw new SchemaNormalisationError(`Fallback validation failed: z.fromJSONSchema could not round-trip the normalised JSON Schema. Original message: ${err instanceof Error ? err.message : "z.fromJSONSchema threw a non-Error value"}`, jsonSchema, "zod-conversion-failed", void 0, err);
 	}
 	if (isObject(parsed)) {
 		const safeParseFn = parsed.safeParse;
@@ -170,39 +200,13 @@ function runValidation(zodSchema, jsonSchema, value, onDiagnostic) {
 		}
 	}
 }
-/**
-* Emit a diagnostic when `z.fromJSONSchema` refuses to round-trip the
-* already-normalised JSON Schema. The diagnostic reuses the existing
-* `unsupported-type` code because the failure mode is the same — a
-* keyword/structure Zod cannot represent — and the consumer should be
-* able to opt in to noticing it via the existing diagnostics channel.
-*
-* Best-effort: when no `onDiagnostic` sink is configured we still swallow
-* the throw (the alternative would crash the React render for a
-* non-essential validation step), matching the silent-fallback contract
-* the rest of the diagnostics system uses.
-*/
-function emitFromJsonSchemaDiagnostic(err, onDiagnostic) {
-	if (onDiagnostic === void 0) return;
-	onDiagnostic({
-		code: "unsupported-type",
-		message: `Skipping fallback validation: z.fromJSONSchema could not round-trip the normalised JSON Schema. Original message: ${err instanceof Error ? err.message : "z.fromJSONSchema threw a non-Error value"}`,
-		pointer: "",
-		detail: { source: "z.fromJSONSchema" }
-	});
-}
-/** Maximum rendering depth before treating a field as recursive. */
-const MAX_RENDER_DEPTH = 10;
 function renderField(tree, value, onChange, userResolver, renderChild, path, instanceWidgets, contextWidgets, depth = 0) {
-	if (path.length === 0) throw new Error("renderField requires a non-empty path. Pass ROOT_PATH for the root field and use renderChild's pathSuffix to derive child paths.");
-	if (depth >= MAX_RENDER_DEPTH) {
-		const refTarget = tree.type === "recursive" ? tree.refTarget : "";
-		return /* @__PURE__ */ jsx("fieldset", { children: /* @__PURE__ */ jsxs("em", { children: [
-			"↻ ",
-			(typeof tree.meta.description === "string" ? tree.meta.description : refTarget) || "schema",
-			" (recursive)"
-		] }) });
-	}
+	if (path.length === 0) throw new Error("renderField requires a non-empty path. Pass the root path (derived from `idPrefix` or `useId()`) for the root field, and use renderChild's pathSuffix to derive child paths.");
+	if (depth >= 10) return /* @__PURE__ */ jsx("fieldset", { children: /* @__PURE__ */ jsxs("em", { children: [
+		"↻ ",
+		typeof tree.meta.description === "string" ? tree.meta.description : "schema",
+		" (recursive)"
+	] }) });
 	const componentHint = tree.meta.component;
 	if (typeof componentHint === "string") {
 		const widget = instanceWidgets?.get(componentHint) ?? contextWidgets?.get(componentHint) ?? globalWidgets.get(componentHint);
@@ -283,6 +287,16 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 /**
 * Dispatch Zod errors to per-field onValidationError callbacks.
 * Walks the fields override tree and matches errors by path prefix.
+*
+* The `fields` parameter mirrors the runtime shape produced by
+* `InferFields<T, Ref>` at the props boundary — either a typed
+* `FieldOverrides<...>` tree (for narrowable schemas) or the loose
+* `Record<string, FieldOverride>` fallback. Both reduce to the same
+* runtime shape, and the runtime narrowing below
+* (`toRecordOrUndefined`) handles `undefined` and non-object inputs
+* defensively. Typing the parameter as the union — rather than the
+* `unknown` that earlier revisions used — keeps the type contract
+* visible to readers without changing runtime behaviour.
 */
 function dispatchFieldErrors(fields, error) {
 	if (fields === void 0 || !isObject(error)) return;
@@ -314,4 +328,4 @@ function isCallable(value) {
 	return typeof value === "function";
 }
 //#endregion
-export { ROOT_PATH, SchemaComponent, SchemaField, SchemaProvider, joinPath, registerWidget, renderField, sanitisePrefix };
+export { SchemaComponent, SchemaField, SchemaProvider, joinPath, registerWidget, renderField, sanitisePrefix };

package/dist/react/SchemaView.d.mts

@@ -1,6 +1,6 @@
-import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
-import { t as Diagnostic } from "../diagnostics-CbBPsxSt.mjs";
-import { r as ComponentResolver } from "../renderer-DI6ZYf7a.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.mjs";
+import { t as Diagnostic } from "../diagnostics-D0QCYGv0.mjs";
+import { r as ComponentResolver } from "../renderer-BaRlQIuN.mjs";
 import { WidgetMap } from "./SchemaComponent.mjs";
 import { ReactNode } from "react";
 

package/dist/react/SchemaView.mjs

@@ -1,3 +1,4 @@
+import "../core/limits.mjs";
 import { SchemaNormalisationError, SchemaRenderError } from "../core/errors.mjs";
 import { normaliseSchema } from "../core/adapter.mjs";
 import { buildRenderProps, getRenderFunction, mergeResolvers } from "../core/renderer.mjs";
@@ -74,10 +75,9 @@ function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: c
 	};
 	const tree = walk(jsonSchema, walkOptions);
 	const userResolver = resolver !== void 0 ? mergeResolvers(resolver, headlessResolver) : headlessResolver;
-	const MAX_SERVER_DEPTH = 10;
 	const makeRenderChild = (currentDepth, parentPath) => (childTree, childValue, pathSuffix) => {
 		const childPath = joinPath(parentPath, pathSuffix);
-		if (currentDepth >= MAX_SERVER_DEPTH) return createElement("fieldset", null, createElement("em", null, `\u21bb ${typeof childTree.meta.description === "string" ? childTree.meta.description : childTree.type === "recursive" ? childTree.refTarget : "schema"} (recursive)`));
+		if (currentDepth >= 10) return createElement("fieldset", null, createElement("em", null, `\u21bb ${typeof childTree.meta.description === "string" ? childTree.meta.description : "schema"} (recursive)`));
 		return renderFieldServer(childTree, childValue, userResolver, makeRenderChild(currentDepth + 1, childPath), childPath, widgets);
 	};
 	const renderChild = makeRenderChild(0, rootPath);

package/dist/react/fieldPath.d.mts

@@ -1,4 +1,4 @@
-import { M as WalkedField } from "../types-BnxPEElk.mjs";
+import { j as WalkedField } from "../types-BrRMV0en.mjs";
 
 //#region src/react/fieldPath.d.ts
 /**

package/dist/react/headless.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-DI6ZYf7a.mjs";
+import { r as ComponentResolver } from "../renderer-BaRlQIuN.mjs";
 
 //#region src/react/headless.d.ts
 /**

package/dist/react/headless.mjs

@@ -1,4 +1,4 @@
-import { renderArray, renderBoolean, renderConditional, renderDiscriminatedUnion, renderEnum, renderFile, renderLiteral, renderNegation, renderNever, renderNull, renderNumber, renderObject, renderRecord, renderRecursive, renderString, renderTuple, renderUnion, renderUnknown } from "./headlessRenderers.mjs";
+import { renderArray, renderBoolean, renderConditional, renderDiscriminatedUnion, renderEnum, renderFile, renderLiteral, renderNegation, renderNever, renderNull, renderNumber, renderObject, renderRecord, renderString, renderTuple, renderUnion, renderUnknown } from "./headlessRenderers.mjs";
 //#region src/react/headless.tsx
 /**
 * The headless resolver uses props.renderChild for recursive rendering.
@@ -27,7 +27,6 @@ const headlessResolver = {
 	negation: renderNegation,
 	literal: renderLiteral,
 	file: renderFile,
-	recursive: renderRecursive,
 	never: renderNever,
 	unknown: renderUnknown
 };