schema-components 1.22.0 → 1.24.0

package/dist/openapi/resolve.mjs

@@ -3,8 +3,9 @@ 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-DVEJQmF7.mjs";
-import { getParameters, getRequestBody, getResponses, listOperations, listWebhooks, 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, listAllOperations, parseOpenApiDocument } from "./parser.mjs";
 //#region src/openapi/resolve.ts
 /**
 * OpenAPI document resolution and caching.
@@ -27,25 +28,55 @@ 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);
-	if (diagnostics !== void 0 && version?.major === 3 && docHasXmlAnywhere(doc)) emitDiagnostic(diagnostics, {
+	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: "",
@@ -54,17 +85,38 @@ function getParsed(doc, diagnostics) {
 			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);
-		if (normalisedDoc !== doc) docCache.set(normalisedDoc, parsed);
-	}
-	return parsed;
+	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()
+	};
+}
+/**
+* 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
@@ -177,25 +229,6 @@ function detectUnsupportedCrossSchemaRefs(doc, diagnostics) {
 	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,
 * following a single `$ref` hop into `components/pathItems` (OpenAPI 3.1)
 * if present. Returns `undefined` when the path is not present or the
@@ -205,44 +238,71 @@ function docHasXmlAnywhere(node) {
 * still surfacing path-item-level metadata to the React layer.
 */
 function lookupPathItemNode(parsed, path, diagnostics) {
-	const fromPaths = resolvePathItemNode(parsed, getProperty(getProperty(parsed.doc, "paths"), 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, getProperty(getProperty(parsed.doc, "webhooks"), path), diagnostics);
+	return resolvePathItemNode(parsed, webhooksEntry, diagnostics);
+}
+/**
+* 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 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];
+	}
+	return isObject(node) ? node : void 0;
 }
 function resolvePathItemNode(parsed, pathItem, diagnostics) {
 	if (!isObject(pathItem)) return void 0;
-	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)) {
+	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 }
 			});
-			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;
-	}
-	emitDiagnostic(diagnostics, {
-		code: "path-item-ref-too-deep",
-		message: `Path Item Object $ref chain exceeded ${String(8)} hops`,
-		pointer: "",
-		detail: { maxHops: 8 }
+		},
+		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) {
@@ -265,7 +325,7 @@ function extractPathItemInfo(pathItem) {
 */
 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);
+	const operation = listAllOperations(parsed).find((op) => op.path === path && op.method === method);
 	if (operation === void 0) throw new Error(`Operation not found: ${method.toUpperCase()} ${path}`);
 	if (pathItemNode === void 0) throw new Error(`Path item missing for ${method.toUpperCase()} ${path}`);
 	return {

package/dist/react/SchemaComponent.d.mts

@@ -1,8 +1,8 @@
-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 { d as FieldOverrides, j as WalkedField, u as FieldOverride, w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { t as Diagnostic } from "../diagnostics-Cbwak-ZX.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,7 +36,7 @@ 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>;
 /**
@@ -55,7 +55,7 @@ type InferFields<T, Ref extends string | undefined> = T extends z.ZodType ? Fiel
  * 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 {
+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;
 /**
@@ -132,6 +132,17 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    * 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
+   * 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;
   /**
@@ -144,6 +155,15 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
    * 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. */
@@ -181,6 +201,11 @@ declare function SchemaComponent<T = unknown, Ref extends string | undefined = u
  * 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;
 /**

package/dist/react/SchemaComponent.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import { getProperty, isObject, toRecordOrUndefined } from "../core/guards.mjs";
 import "../core/limits.mjs";
 import { SchemaFieldError, SchemaNormalisationError, SchemaRenderError } from "../core/errors.mjs";
 import { normaliseSchema } from "../core/adapter.mjs";
@@ -87,6 +87,7 @@ function SchemaComponent(props) {
 		}
 		throw error;
 	}
+	const fieldsRecord = toRecordOrUndefined(fields);
 	const handleChange = useCallback((nextValue) => {
 		if (validate) {
 			let error;
@@ -102,7 +103,7 @@ function SchemaComponent(props) {
 			}
 			if (error !== void 0) {
 				onValidationError?.(error);
-				dispatchFieldErrors(fields, error);
+				dispatchFieldErrors(fieldsRecord, error);
 			}
 		}
 		onChange?.(nextValue);
@@ -112,7 +113,7 @@ function SchemaComponent(props) {
 		jsonSchema,
 		onChange,
 		onValidationError,
-		fields,
+		fieldsRecord,
 		onDiagnostic,
 		onError,
 		schemaInput
@@ -120,7 +121,7 @@ function SchemaComponent(props) {
 	const walkOptions = {
 		componentMeta: mergedMeta,
 		rootMeta,
-		fieldOverrides: fields,
+		fieldOverrides: fieldsRecord,
 		rootDocument,
 		...diagnostics !== void 0 ? { diagnostics } : {}
 	};
@@ -136,10 +137,16 @@ function SchemaComponent(props) {
 * 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.
 */
 function joinPath(parent, suffix) {
 	if (suffix === void 0 || suffix.length === 0) return parent;
 	if (parent.length === 0) return suffix;
+	if (suffix.startsWith("[")) return `${parent}${suffix}`;
 	return `${parent}.${suffix}`;
 }
 /**
@@ -170,9 +177,9 @@ function sanitisePrefix(value) {
 */
 function runValidation(zodSchema, jsonSchema, value, onDiagnostic) {
 	if (zodSchema !== void 0 && isObject(zodSchema)) {
-		const safeParseFn = zodSchema.safeParse;
-		if (isCallable(safeParseFn)) {
-			const result = safeParseFn(value);
+		const validateFn = isCodecSchema(zodSchema) ? zodSchema.safeEncode : zodSchema.safeParse;
+		if (isCallable(validateFn)) {
+			const result = validateFn(value);
 			if (isObject(result) && "success" in result && result.success !== true) return result.error;
 			return;
 		}
@@ -261,12 +268,11 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 	if (fieldTree === void 0) throw new SchemaFieldError(`Field not found: ${path}`, schemaInput, path);
 	const fieldValue = resolveValue(value, path);
 	const handleChange = useCallback((nextFieldValue) => {
+		const newRootValue = setNestedValue(value, path, nextFieldValue);
 		if (validate) {
-			const newRootValue = setNestedValue(value, path, nextFieldValue);
 			const error = runValidation(zodSchema, jsonSchema, newRootValue);
 			if (error !== void 0) onValidationError?.(error);
 		}
-		const newRootValue = setNestedValue(value, path, nextFieldValue);
 		onChange?.(newRootValue);
 	}, [
 		validate,
@@ -288,24 +294,21 @@ 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.
+* The runtime shape of `fields` is always `Record<string, FieldOverride>`
+* after `InferFields<T, Ref>` is erased — the typed variants
+* (`FieldOverrides<U>`) and the loose `Record<string, FieldOverride>`
+* fallback share the same structural shape, so the dispatch logic only
+* needs the loose record. The previous parameter union
+* (`Record<string, FieldOverride> | FieldOverrides<unknown> |
+* undefined`) collapsed because `FieldOverrides<unknown>` reduces to
+* `{}`, contributing no extra precision while adding noise to readers.
 */
 function dispatchFieldErrors(fields, error) {
 	if (fields === void 0 || !isObject(error)) return;
 	if (!("issues" in error)) return;
 	const issues = error.issues;
 	if (!Array.isArray(issues)) return;
-	const overrides = toRecordOrUndefined(fields);
-	if (overrides === void 0) return;
-	for (const [key, override] of Object.entries(overrides)) {
+	for (const [key, override] of Object.entries(fields)) {
 		if (override === void 0 || typeof override !== "object") continue;
 		if (override === null) continue;
 		if (!("onValidationError" in override)) continue;
@@ -327,5 +330,26 @@ function isFieldErrorCallback(value) {
 function isCallable(value) {
 	return typeof value === "function";
 }
+/**
+* True when `value` is a Zod schema implemented as a codec.
+*
+* Detection looks for `"$ZodCodec"` in the schema's `_zod.traits`
+* Set, mirroring the runtime detection used inside
+* `core/adapter.ts` (`isCodecSchema` there) and Zod's own
+* `isTransforming` helper. Duplicated here rather than imported
+* because adapter.ts does not export the helper and is outside this
+* fix-cycle's owned files.
+*
+* TODO(round7-integration): replace with an `import` once
+* `isCodecSchema` is exported from `core/adapter.ts` (or promoted to
+* `core/guards.ts`) by a coordinating commit.
+*/
+function isCodecSchema(value) {
+	const zod = getProperty(value, "_zod");
+	if (!isObject(zod)) return false;
+	const traits = zod.traits;
+	if (traits instanceof Set) return traits.has("$ZodCodec");
+	return false;
+}
 //#endregion
 export { SchemaComponent, SchemaField, SchemaProvider, joinPath, registerWidget, renderField, sanitisePrefix };

package/dist/react/SchemaView.d.mts

@@ -1,16 +1,36 @@
-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 { w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { t as Diagnostic } from "../diagnostics-Cbwak-ZX.mjs";
+import { r as ComponentResolver } from "../renderer-CXJ8y0qw.mjs";
+import { RejectUnrepresentableZod } from "../core/typeInference.mjs";
 import { WidgetMap } from "./SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/SchemaView.d.ts
-interface SchemaViewProps {
-  /** Zod schema, JSON Schema object, or OpenAPI document. */
-  schema: unknown;
+interface SchemaViewProps<T = unknown, Ref extends string | undefined = undefined> {
+  /**
+   * Zod schema, JSON Schema object, or OpenAPI document.
+   *
+   * Subject to the same compile-time rejection of unrepresentable
+   * Zod 4 types as {@link SchemaComponentProps.schema} — see
+   * {@link RejectUnrepresentableZod}.
+   */
+  schema: RejectUnrepresentableZod<T>;
   /** For OpenAPI: a ref string like "#/components/schemas/User". */
-  ref?: string;
-  /** Current value to render. */
+  ref?: Ref;
+  /**
+   * Current value to render.
+   *
+   * TYPE BOUNDARY NOTE: mirrors `SchemaComponentProps.value` — kept
+   * as `unknown` so the same boundary holds for both the editable
+   * (`SchemaComponent`) and read-only (`SchemaView`) entry points.
+   * The {@link InferredOutputValue} alias is the recommended way
+   * for callers to narrow on the consumer side.
+   *
+   * TODO(round7-integration): promote to
+   * `InferSchemaValue<T, Ref, "output">` alongside the matching
+   * `SchemaComponent` change. See the type-boundary note on
+   * `SchemaComponentProps.value` for the migration coordination.
+   */
   value?: unknown;
   /** Per-field meta overrides. */
   fields?: Record<string, unknown>;
@@ -44,7 +64,7 @@ interface SchemaViewProps {
  * Always renders in read-only mode. For editable forms, use
  * `<SchemaComponent>` with `"use client"`.
  */
-declare function SchemaView({
+declare function SchemaView<T = unknown, Ref extends string | undefined = undefined>({
   schema: schemaInput,
   ref: refInput,
   value,
@@ -56,6 +76,6 @@ declare function SchemaView({
   onDiagnostic,
   strict,
   idPrefix
-}: SchemaViewProps): ReactNode;
+}: SchemaViewProps<T, Ref>): ReactNode;
 //#endregion
 export { SchemaView, SchemaViewProps };

package/dist/react/a11y.d.mts

@@ -0,0 +1,21 @@
+import { j as WalkedField } from "../types-BTB73MB8.mjs";
+
+//#region src/react/a11y.d.ts
+/**
+ * Build the ARIA attribute bundle for a renderer.
+ *
+ * - `aria-required="true"` whenever the field is non-optional.
+ * - `aria-label=<description>` when a non-empty description is supplied.
+ *
+ * Returns a plain `Record<string, string>` (rather than a typed
+ * attribute interface) so callers can spread the result into any JSX
+ * element type without per-element TypeScript widening.
+ *
+ * Each helper from `html/a11y.ts` returns its corresponding fragment
+ * separately. The React renderers merge them into a single object
+ * here because the headless renderers compose one attribute bag per
+ * `<input>` element rather than threading multiple bags through `h()`.
+ */
+declare function buildAriaAttrs(tree: WalkedField, description?: unknown): Record<string, string>;
+//#endregion
+export { buildAriaAttrs };

package/dist/react/a11y.mjs

@@ -0,0 +1,24 @@
+//#region src/react/a11y.ts
+/**
+* Build the ARIA attribute bundle for a renderer.
+*
+* - `aria-required="true"` whenever the field is non-optional.
+* - `aria-label=<description>` when a non-empty description is supplied.
+*
+* Returns a plain `Record<string, string>` (rather than a typed
+* attribute interface) so callers can spread the result into any JSX
+* element type without per-element TypeScript widening.
+*
+* Each helper from `html/a11y.ts` returns its corresponding fragment
+* separately. The React renderers merge them into a single object
+* here because the headless renderers compose one attribute bag per
+* `<input>` element rather than threading multiple bags through `h()`.
+*/
+function buildAriaAttrs(tree, description) {
+	const attrs = {};
+	if (tree.isOptional === false) attrs["aria-required"] = "true";
+	if (typeof description === "string" && description.length > 0) attrs["aria-label"] = description;
+	return attrs;
+}
+//#endregion
+export { buildAriaAttrs };

package/dist/react/fieldPath.d.mts

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

package/dist/react/headless.d.mts

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

package/dist/react/headlessRenderers.d.mts

@@ -1,5 +1,5 @@
-import { j as WalkedField } from "../types-BrRMV0en.mjs";
-import { l as RenderProps } from "../renderer-BaRlQIuN.mjs";
+import { j as WalkedField } from "../types-BTB73MB8.mjs";
+import { l as RenderProps } from "../renderer-CXJ8y0qw.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/headlessRenderers.d.ts
@@ -10,15 +10,14 @@ import { ReactNode } from "react";
 declare function toReactNode(value: unknown): ReactNode;
 /**
  * Build a stable, unique input ID from the path.
- * Used for `htmlFor`/`id` association between labels and inputs.
  *
- * Throws on an empty path: the previous "sc-field" fallback caused every
- * input across a form to share the same id, breaking label-input pairing
- * and screen reader navigation. Callers must thread a non-empty path
- * (see `ROOT_PATH` and `joinPath` in `SchemaComponent.tsx`).
+ * Re-exported alias for {@link fieldDomId} so external themes (shadcn,
+ * MUI, mantine, radix) keep importing `inputId` from the React entry
+ * point. Both the React and HTML renderers must derive the same id from
+ * the same path — `fieldDomId` in `core/idPath.ts` is the single
+ * source-of-truth.
  *
- * Dots and bracket indices in paths are converted to hyphens to keep the
- * id valid as a CSS selector and predictable in test queries.
+ * Throws on an empty path; see `fieldDomId` for the rationale.
  */
 declare function inputId(path: string): string;
 declare function renderString(props: RenderProps): ReactNode;