schema-components 1.20.0 → 1.22.0

package/dist/openapi/resolve.mjs

@@ -1,7 +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-CMMEl4cd.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.
@@ -24,25 +27,173 @@ const docCache = /* @__PURE__ */ new WeakMap();
 * same form `<SchemaComponent>` does, keeping the OpenAPI components on
 * the same pipeline as the top-level adapter.
 *
-* The cache is keyed by the caller-supplied document so subsequent calls
-* with the same input bypass both normalisation and parsing.
+* When `diagnostics` is supplied, normalisation events
+* (`duplicate-body-parameter`, `dropped-swagger-feature`,
+* `unknown-json-schema-dialect`, `divisible-by-conflict`,
+* `relative-ref-resolved`, etc.) are forwarded to the sink. Passing
+* diagnostics also bypasses the cache so each call observes the
+* normalisation pipeline running against the supplied sink — caching
+* would silently swallow every emission after the first.
+*
+* The cache is keyed by the caller-supplied document so subsequent
+* cache-eligible calls with the same input bypass both normalisation
+* and parsing.
 */
-function getParsed(doc) {
-	const cached = docCache.get(doc);
-	if (cached !== void 0) return cached;
+function getParsed(doc, diagnostics) {
+	if (diagnostics === void 0) {
+		const cached = docCache.get(doc);
+		if (cached !== void 0) return cached;
+	}
 	const version = detectOpenApiVersion(doc);
-	const normalisedDoc = version !== void 0 ? normaliseOpenApiSchemas(doc, version) : 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);
-	docCache.set(doc, parsed);
-	if (normalisedDoc !== doc) docCache.set(normalisedDoc, parsed);
+	if (diagnostics === void 0) {
+		docCache.set(doc, parsed);
+		if (normalisedDoc !== doc) docCache.set(normalisedDoc, parsed);
+	}
 	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,
@@ -53,22 +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, "~");
-		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;
@@ -79,14 +254,19 @@ function extractPathItemInfo(pathItem) {
 	};
 }
 /**
-* Resolve an operation from an OpenAPI document by path and method.
-* Throws if the operation is not found.
+* Resolve an operation against an already-parsed document. Throws if
+* the operation is not found.
+*
+* Used by callers that have already obtained a parsed document via
+* {@link getParsed} — most importantly the React components, which
+* supply `diagnostics` to `getParsed` and must avoid re-running the
+* normalisation pipeline (every re-run would emit each diagnostic
+* again into the sink).
 */
-function resolveOperation(doc, path, method) {
-	const parsed = getParsed(doc);
-	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,
@@ -97,30 +277,73 @@ function resolveOperation(doc, path, method) {
 	};
 }
 /**
+* Resolve an operation from an OpenAPI document by path and method.
+* Throws if the operation is not found.
+*
+* `diagnostics` is forwarded to {@link getParsed} so normalisation
+* events surface to the caller's sink.
+*/
+function resolveOperation(doc, path, method, diagnostics) {
+	return resolveOperationFromParsed(getParsed(doc, diagnostics), path, method, diagnostics);
+}
+/**
+* Resolve parameters against an already-parsed document. See
+* {@link resolveOperationFromParsed} for the rationale.
+*/
+function resolveParametersFromParsed(parsed, path, method) {
+	return getParameters(parsed, path, method);
+}
+/**
 * Resolve parameters for an operation. Returns empty array if none.
+*
+* `diagnostics` is forwarded to {@link getParsed} so normalisation
+* events surface to the caller's sink.
 */
-function resolveParameters(doc, path, method) {
-	return getParameters(getParsed(doc), path, method);
+function resolveParameters(doc, path, method, diagnostics) {
+	return resolveParametersFromParsed(getParsed(doc, diagnostics), path, method);
+}
+/**
+* Resolve a request body against an already-parsed document. See
+* {@link resolveOperationFromParsed} for the rationale.
+*/
+function resolveRequestBodyFromParsed(parsed, path, method) {
+	return getRequestBody(parsed, path, method);
 }
 /**
 * Resolve request body for an operation. Returns undefined if none.
+*
+* `diagnostics` is forwarded to {@link getParsed} so normalisation
+* events surface to the caller's sink.
 */
-function resolveRequestBody(doc, path, method) {
-	return getRequestBody(getParsed(doc), path, method);
+function resolveRequestBody(doc, path, method, diagnostics) {
+	return resolveRequestBodyFromParsed(getParsed(doc, diagnostics), path, method);
 }
 /**
-* Resolve a specific response by status code. Throws if not found.
+* Resolve a specific response against an already-parsed document. See
+* {@link resolveOperationFromParsed} for the rationale.
 */
-function resolveResponse(doc, path, method, statusCode) {
-	const response = getResponses(getParsed(doc), path, method).find((r) => r.statusCode === statusCode);
+function resolveResponseFromParsed(parsed, path, method, statusCode) {
+	const response = getResponses(parsed, path, method).find((r) => r.statusCode === statusCode);
 	if (response === void 0) throw new Error(`Response not found: ${statusCode}`);
 	return response;
 }
 /**
+* Resolve a specific response by status code. Throws if not found.
+*
+* `diagnostics` is forwarded to {@link getParsed} so normalisation
+* events surface to the caller's sink.
+*/
+function resolveResponse(doc, path, method, statusCode, diagnostics) {
+	return resolveResponseFromParsed(getParsed(doc, diagnostics), path, method, statusCode);
+}
+/**
 * Resolve all responses for an operation.
+*
+* `diagnostics` is forwarded to {@link getParsed} so normalisation
+* events surface to the caller's sink.
 */
-function resolveResponses(doc, path, method) {
-	return getResponses(getParsed(doc), path, method);
+function resolveResponses(doc, path, method, diagnostics) {
+	return getResponses(getParsed(doc, diagnostics), path, method);
 }
 //#endregion
-export { getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, resolveResponses, toDoc };
+export { getParsed, resolveOperation, resolveOperationFromParsed, resolveParameters, resolveParametersFromParsed, resolveRequestBody, resolveRequestBodyFromParsed, resolveResponse, resolveResponseFromParsed, resolveResponses, toDoc };

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-C9zw9wbX.mjs";
-import { t as Diagnostic } from "../diagnostics-CbBPsxSt.mjs";
-import { t as SchemaError } from "../errors-C2iABcn9.mjs";
-import { l as RenderProps, r as ComponentResolver } from "../renderer-SOIbJBtk.mjs";
-import { c as PathOfType, l as RejectUnrepresentableZod, n as FromJSONSchema, u as ResolveOpenAPIRef } from "../typeInference-CDoD_LZ_.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 };