schema-components 1.21.0 → 1.23.0

package/dist/openapi/resolve.mjs

@@ -1,8 +1,11 @@
 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 { o as normaliseOpenApiSchemas, r as documentContainsKeyword } from "../normalise-DCYp06Sr.mjs";
+import { resolveRefChain } from "../core/refChain.mjs";
+import { getParameters, getRequestBody, getResponses, listOperations, listWebhooks, parseOpenApiDocument } from "./parser.mjs";
 //#region src/openapi/resolve.ts
 /**
 * OpenAPI document resolution and caching.
@@ -25,38 +28,205 @@ const docCache = /* @__PURE__ */ new WeakMap();
 * same form `<SchemaComponent>` does, keeping the OpenAPI components on
 * the same pipeline as the top-level adapter.
 *
-* 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.
+* ### Caching and diagnostics
 *
-* The cache is keyed by the caller-supplied document so subsequent
-* cache-eligible calls with the same input bypass both normalisation
-* and parsing.
+* Normalisation runs at most once per document identity. The full set
+* of doc-level diagnostics emitted during that single run is captured
+* into the cache alongside the parsed result. Each caller-supplied
+* sink receives the captured diagnostics exactly once per cached
+* entry, no matter how many times `getParsed` is called with that
+* `(doc, sink)` pair.
+*
+* The previous implementation bypassed the cache whenever
+* `diagnostics` was supplied and re-ran the entire normalisation
+* pipeline against the new sink. That fired every doc-level
+* diagnostic once per call, so a parent like `ApiWebhooks` that
+* renders `ApiWebhook` per webhook entry caused N-fold emission of a
+* single real cause. With the new strategy, cardinality stays at one
+* per real cause regardless of how many child renders share the
+* sink.
+*
+* Strict mode is treated as a per-call invariant — see
+* {@link replayCapturedDiagnostics} for the rationale.
 */
 function getParsed(doc, diagnostics) {
-	if (diagnostics === void 0) {
-		const cached = docCache.get(doc);
-		if (cached !== void 0) return cached;
+	let cached = docCache.get(doc);
+	if (cached === void 0) {
+		cached = buildCachedParse(doc);
+		docCache.set(doc, cached);
+		if (cached.parsed.doc !== doc) docCache.set(cached.parsed.doc, cached);
 	}
+	if (diagnostics?.diagnostics !== void 0 || diagnostics?.strict === true) replayCapturedDiagnostics(cached, diagnostics);
+	return cached.parsed;
+}
+/**
+* Run the normalisation, validation, and parse pipeline against a doc
+* once, capturing every emitted diagnostic into a private array. The
+* private array becomes the source of truth for later replay through
+* caller-supplied sinks.
+*
+* The internal capturing sink does NOT set `strict`. Letting strict
+* mode throw mid-walk would leave the cache empty and force every
+* subsequent caller to re-run the pipeline from scratch — and the
+* defect this caching strategy fixes was precisely that kind of
+* re-running. Strict is enforced instead during replay
+* (see {@link replayCapturedDiagnostics}).
+*/
+function buildCachedParse(doc) {
+	const captured = [];
+	const captureOpts = { diagnostics: (d) => captured.push(d) };
 	const version = detectOpenApiVersion(doc);
-	const normalisedDoc = version !== void 0 ? normaliseOpenApiSchemas(doc, version, diagnostics) : doc;
-	const parsed = parseOpenApiDocument(normalisedDoc);
-	if (diagnostics === void 0) {
-		docCache.set(doc, parsed);
-		if (normalisedDoc !== doc) docCache.set(normalisedDoc, parsed);
-	}
-	return parsed;
+	if (version?.major === 3 && documentContainsKeyword(doc, "xml")) emitDiagnostic(captureOpts, {
+		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, captureOpts) : doc;
+	validateSecuritySchemeTypes(normalisedDoc, captureOpts);
+	detectUnsupportedCrossSchemaRefs(normalisedDoc, captureOpts);
+	return {
+		parsed: parseOpenApiDocument(normalisedDoc),
+		diagnostics: captured,
+		notifiedSinks: /* @__PURE__ */ new WeakSet()
+	};
 }
 /**
-* Coerce an unknown value to a record, returning an empty record
-* for non-objects.
+* Replay each captured diagnostic through the caller-supplied options.
+*
+* Strict mode is treated as a per-call invariant: when `strict` is set
+* we always run the replay so the first captured diagnostic throws,
+* matching the historical fail-fast contract regardless of how many
+* times the cache has previously notified the sink.
+*
+* Non-strict, sink-bearing callers de-duplicate at the function-
+* identity boundary: a second call with the same `(doc, sink)` pair
+* short-circuits because the sink has already seen every captured
+* diagnostic. This is the cardinality-1 guarantee that fixes the
+* N-fold emission caused by parent-fans-out-into-children renders.
+*
+* The sink is only marked notified after a successful replay so a
+* strict throw mid-replay does not silence a follow-up non-strict
+* call that still wants the full captured set.
+*/
+function replayCapturedDiagnostics(cached, opts) {
+	const sink = opts.diagnostics;
+	if (!(opts.strict === true) && sink !== void 0 && cached.notifiedSinks.has(sink)) return;
+	for (const diagnostic of cached.diagnostics) emitDiagnostic(opts, diagnostic);
+	if (sink !== void 0) cached.notifiedSinks.add(sink);
+}
+/**
+* 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, "");
 }
 /**
 * Look up a Path Item Object on the (already-normalised) parsed document,
@@ -67,23 +237,73 @@ 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 paths = getProperty(parsed.doc, "paths");
+	const webhooks = getProperty(parsed.doc, "webhooks");
+	const pathsEntry = getProperty(paths, path);
+	const webhooksEntry = getProperty(webhooks, path);
+	if (isObject(pathsEntry) && isObject(webhooksEntry)) emitDiagnostic(diagnostics, {
+		code: "path-webhook-name-collision",
+		message: `Identifier "${path}" appears in both \`paths\` and \`webhooks\`; \`paths\` takes precedence`,
+		pointer: `/paths/${path.replace(/~/g, "~0").replace(/\//g, "~1")}`,
+		detail: { name: path }
+	});
+	const fromPaths = resolvePathItemNode(parsed, pathsEntry, diagnostics);
+	if (fromPaths !== void 0) return fromPaths;
+	return resolvePathItemNode(parsed, webhooksEntry, diagnostics);
 }
-function resolvePathItemNode(parsed, pathItem) {
-	if (!isObject(pathItem)) return void 0;
-	const ref = getProperty(pathItem, "$ref");
-	if (typeof ref !== "string") return pathItem;
-	if (!ref.startsWith("#/")) return pathItem;
+/**
+* Resolve a fragment `$ref` (must start with `#/`) against the parsed
+* document by walking the JSON Pointer one segment at a time. Returns
+* the resolved node only when every segment lands on a plain object;
+* returns `undefined` when any intermediate segment is missing or
+* non-object, or when the final node is not an object.
+*
+* Rejects `__proto__`, `constructor`, `prototype` segments — walking
+* into any of these reads `Object.prototype` and would let a crafted
+* pathItems `$ref` smuggle properties from the runtime prototype
+* chain into the resolved Path Item Object.
+*/
+function lookupFragmentRef(parsed, ref) {
+	if (!ref.startsWith("#/")) return void 0;
 	const parts = ref.slice(2).split("/");
-	let current = parsed.doc;
+	let node = parsed.doc;
 	for (const part of parts) {
-		if (!isObject(current)) return void 0;
+		if (!isObject(node)) return void 0;
 		const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
 		if (isPrototypePollutingKey(decoded)) return void 0;
-		current = current[decoded];
+		node = node[decoded];
 	}
-	return isObject(current) ? current : pathItem;
+	return isObject(node) ? node : void 0;
+}
+function resolvePathItemNode(parsed, pathItem, diagnostics) {
+	if (!isObject(pathItem)) return void 0;
+	return resolveRefChain(pathItem, {
+		lookup: (ref) => lookupFragmentRef(parsed, ref),
+		extractRef: (node) => {
+			const ref = getProperty(node, "$ref");
+			if (typeof ref !== "string") return void 0;
+			if (!ref.startsWith("#/")) return void 0;
+			return ref;
+		},
+		onCycle: (ref) => {
+			emitDiagnostic(diagnostics, {
+				code: "cyclic-path-item-ref",
+				message: `Cyclic Path Item Object $ref "${ref}"`,
+				pointer: ref,
+				detail: { ref }
+			});
+		},
+		onDepthExceeded: () => {
+			emitDiagnostic(diagnostics, {
+				code: "path-item-ref-too-deep",
+				message: `Path Item Object $ref chain exceeded ${String(8)} hops`,
+				pointer: "",
+				detail: { maxHops: 8 }
+			});
+		},
+		maxHops: 8
+	});
 }
 function extractPathItemInfo(pathItem) {
 	const summary = pathItem.summary;
@@ -103,10 +323,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 +344,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-BTB73MB8.mjs";
+import { t as Diagnostic } from "../diagnostics-BS2kaUyE.mjs";
+import { t as SchemaError } from "../errors-g_MCTQel.mjs";
+import { l as RenderProps, r as ComponentResolver } from "../renderer-CXJ8y0qw.mjs";
+import { FromJSONSchema, FromJSONSchemaMode, IsSwagger2Doc, PathOfType, RejectUnrepresentableZod, ResolveOpenAPIRef, TypeAtPath, __SchemaInferenceFellBack } from "../core/typeInference.mjs";
 import { z } from "zod";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { ReactNode } from "react";
@@ -36,10 +36,57 @@ declare function SchemaProvider({
  * or `<SchemaProvider>` instead.
  */
 declare function registerWidget(name: string, render: (props: RenderProps) => unknown): void;
-type InferFields<T, Ref extends string | undefined> = T extends z.ZodType ? FieldOverrides<z.infer<T>> : T extends {
+type InferFields<T, Ref extends string | undefined> = IsSwagger2Doc<T> extends true ? __SchemaInferenceFellBack : 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> = IsSwagger2Doc<T> extends true ? __SchemaInferenceFellBack : 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,71 @@ 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.
+   *
+   * TODO(round7-integration): promote to
+   * `NarrowAtPath<InferSchemaValue<T, Ref, "output">, P>` once the
+   * round-7 test fixtures (headless union, discriminated union,
+   * schemaview equivalence, type-inference issue fixes) are
+   * migrated to either narrow their fixtures or accept the loose
+   * boundary. The retype cascades through call sites that
+   * intentionally pass invalid values to exercise fallback paths
+   * (`value={undefined}`, off-discriminator values, etc.) and
+   * through fixtures whose enum/literal types widen at the call
+   * site. Coordinated migration is required.
+   */
   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>; ... }}`.
+   *
+   * TODO(round7-integration): promote to
+   * `(value: NarrowAtPath<InferSchemaValue<T, Ref, "input">, P>) => void`
+   * alongside the `value` retype. The contravariant boundary needs
+   * an internal cast at the only call site (`onChange?.(nextValue)`
+   * in `handleChange`) that the project's no-`as` rule disallows
+   * without explicit justification. The right place to introduce
+   * the cast is a tiny typed boundary helper accompanied by the
+   * fixture migration noted above.
+   */
   onChange?: (value: unknown) => void;
   /** Run schema.safeParse() on change and surface errors via onValidationError. */
   validate?: boolean;
@@ -87,35 +196,16 @@ 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
  * returned unchanged so the child inherits the parent's id.
+ *
+ * Bracketed array indices like `[0]` append directly so `tags` + `[0]`
+ * becomes `tags[0]` rather than `tags.[0]` — matching the canonical form
+ * used by `html/a11y.ts` `joinPath` and `react/fieldPath.ts` `resolvePath`,
+ * which already parses bracket notation when navigating WalkedField trees.
  */
 declare function joinPath(parent: string, suffix: string | undefined): string;
 /**
@@ -154,7 +244,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 +255,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 };