schema-components 1.28.2 → 2.0.0

package/dist/core/idPath.d.mts

@@ -21,16 +21,46 @@
  * Whitelist (not blacklist) so unexpected characters from free-text sources
  * — `meta.description`, label-derived suffixes, encoded JSON Pointers —
  * cannot leak into ids and break CSS selectors or aria associations.
+ *
+ * Non-ASCII inputs (e.g. CJK property names like `名前`, accented Latin
+ * like `café`, emoji like `🦄`) collapse under the whitelist to a short
+ * or empty string and would silently collide on `sc-`. To keep ids
+ * deterministic AND unique per input, the normaliser appends a short
+ * hash suffix derived from the original string whenever the whitelisted
+ * collapse:
+ *
+ *   - produces an empty string, OR
+ *   - dropped non-structural characters from the input (i.e. anything
+ *     besides the path joiners `.`, `[`, `]` and ASCII whitespace).
+ *
+ * Structural separator runs do NOT trigger the disambiguator so
+ * canonical paths like `user.preferences` and `tags[0]` keep their
+ * historic readable form (`user-preferences`, `tags-0`).
+ *
+ * The hash is a 32-bit FNV-1a variant rendered in base-36. It is
+ * deterministic (same input → same output), short (≤ 7 characters), and
+ * non-cryptographic — collision resistance is good enough for DOM ids,
+ * and a cryptographic primitive is unnecessary and not universally
+ * available (no `crypto` global in every JS runtime that consumes the
+ * library).
+ *
+ * The leading character is guaranteed to be an ASCII letter so the full
+ * `sc-<segment>` id is always a valid CSS identifier and `querySelector`
+ * target. Empty-collapse inputs receive a synthetic `u` (for "unicode")
+ * prefix on the hash so the id never starts with a digit.
  */
 declare function normaliseIdSegment(value: string): string;
 /**
- * Build the canonical `sc-`-prefixed DOM id for a structural path.
- * Use this as the base id for an input element; derived ids (panel, tab,
+ * Build the canonical `sc-`-prefixed DOM id for a structural path. Use
+ * this as the base id for an input element; derived ids (panel, tab,
  * hint) compose suffixes onto the returned string.
  *
- * Throws on an empty path: a previous "sc-field" fallback caused every
- * input across a form to share the same id, breaking label-input pairing
- * and screen reader navigation.
+ * An empty `path` is permitted — it surfaces as the bare prefix `sc-`
+ * so a leaf renderer at the schema root (e.g.
+ * `renderToHtml(z.string())`) still emits a usable id without throwing.
+ * Container renderers always thread a non-empty path through
+ * `renderChild`, so the empty-id case can never produce sibling
+ * collisions inside a structured form.
  */
 declare function fieldDomId(path: string): string;
 /**

package/dist/core/idPath.mjs

@@ -15,6 +15,17 @@ import "./cssClasses.mjs";
 * Pipelines should import the helpers below rather than re-deriving them.
 */
 /**
+* Characters the path joiners (`react/SchemaComponent.joinPath`,
+* `html/a11y.joinPath`) emit between segments — `.` between object
+* keys, `[` / `]` around array indices. The disambiguator below treats
+* these as benign structural separators: collapsing them into a hyphen
+* is part of the canonical id form and does NOT signal a collision
+* risk, so no hash suffix is appended for paths like `user.preferences`
+* or `tags[0]`. ASCII whitespace is included for the same reason —
+* label-derived suffixes may carry incidental whitespace.
+*/
+const STRUCTURAL_SEPARATOR_PATTERN = /^[.[\]\s]+$/;
+/**
 * Normalise a structural path into the id segment used after the `sc-`
 * prefix. Whitelist-based: any run of characters outside `[A-Za-z0-9_-]`
 * collapses to a single hyphen, with trailing hyphens stripped.
@@ -22,21 +33,82 @@ import "./cssClasses.mjs";
 * Whitelist (not blacklist) so unexpected characters from free-text sources
 * — `meta.description`, label-derived suffixes, encoded JSON Pointers —
 * cannot leak into ids and break CSS selectors or aria associations.
+*
+* Non-ASCII inputs (e.g. CJK property names like `名前`, accented Latin
+* like `café`, emoji like `🦄`) collapse under the whitelist to a short
+* or empty string and would silently collide on `sc-`. To keep ids
+* deterministic AND unique per input, the normaliser appends a short
+* hash suffix derived from the original string whenever the whitelisted
+* collapse:
+*
+*   - produces an empty string, OR
+*   - dropped non-structural characters from the input (i.e. anything
+*     besides the path joiners `.`, `[`, `]` and ASCII whitespace).
+*
+* Structural separator runs do NOT trigger the disambiguator so
+* canonical paths like `user.preferences` and `tags[0]` keep their
+* historic readable form (`user-preferences`, `tags-0`).
+*
+* The hash is a 32-bit FNV-1a variant rendered in base-36. It is
+* deterministic (same input → same output), short (≤ 7 characters), and
+* non-cryptographic — collision resistance is good enough for DOM ids,
+* and a cryptographic primitive is unnecessary and not universally
+* available (no `crypto` global in every JS runtime that consumes the
+* library).
+*
+* The leading character is guaranteed to be an ASCII letter so the full
+* `sc-<segment>` id is always a valid CSS identifier and `querySelector`
+* target. Empty-collapse inputs receive a synthetic `u` (for "unicode")
+* prefix on the hash so the id never starts with a digit.
 */
 function normaliseIdSegment(value) {
-	return value.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/-+$/g, "");
+	const collapsed = value.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/-+$/g, "");
+	if (collapsed.length === 0) return `u${hashSuffix(value)}`;
+	if (collapsed !== value && droppedNonStructural(value)) return `${collapsed}-${hashSuffix(value)}`;
+	return collapsed;
+}
+/**
+* True when `value` contains at least one character outside both the
+* id whitelist `[A-Za-z0-9_-]` and the structural separator set
+* (`.`, `[`, `]`, ASCII whitespace). Used by `normaliseIdSegment` to
+* decide whether a non-canonical dropped character (a real Unicode
+* character, a label-derived punctuation, etc.) means the collapse is
+* lossy and disambiguation is required.
+*/
+function droppedNonStructural(value) {
+	const nonWhitelisted = value.replace(/[A-Za-z0-9_-]+/g, "");
+	if (nonWhitelisted.length === 0) return false;
+	return !STRUCTURAL_SEPARATOR_PATTERN.test(nonWhitelisted);
+}
+/**
+* Deterministic 32-bit FNV-1a hash of `value` rendered in base-36. Used
+* solely to disambiguate id segments that would otherwise collide after
+* the whitelisted character collapse; not security-sensitive, so a
+* non-cryptographic hash is sufficient and avoids depending on platform
+* `crypto` availability.
+*/
+function hashSuffix(value) {
+	let hash = 2166136261;
+	for (let i = 0; i < value.length; i++) {
+		hash ^= value.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36);
 }
 /**
-* Build the canonical `sc-`-prefixed DOM id for a structural path.
-* Use this as the base id for an input element; derived ids (panel, tab,
+* Build the canonical `sc-`-prefixed DOM id for a structural path. Use
+* this as the base id for an input element; derived ids (panel, tab,
 * hint) compose suffixes onto the returned string.
 *
-* Throws on an empty path: a previous "sc-field" fallback caused every
-* input across a form to share the same id, breaking label-input pairing
-* and screen reader navigation.
+* An empty `path` is permitted — it surfaces as the bare prefix `sc-`
+* so a leaf renderer at the schema root (e.g.
+* `renderToHtml(z.string())`) still emits a usable id without throwing.
+* Container renderers always thread a non-empty path through
+* `renderChild`, so the empty-id case can never produce sibling
+* collisions inside a structured form.
 */
 function fieldDomId(path) {
-	if (path.length === 0) throw new Error("fieldDomId requires a non-empty path. Thread a root path from the renderer entry point and derive children via joinPath().");
+	if (path.length === 0) return "sc-";
 	return `sc-${normaliseIdSegment(path)}`;
 }
 /**

package/dist/core/inferValue.d.mts

@@ -0,0 +1,2 @@
+import { a as InferredValue, i as InferredOutputValue, n as InferSchemaValue, r as InferredInputValue, t as InferFields } from "../inferValue-PPXWJpbN.mjs";
+export { InferFields, InferSchemaValue, InferredInputValue, InferredOutputValue, InferredValue };

package/dist/core/inferValue.mjs

@@ -0,0 +1 @@
+export {};

package/dist/core/limits.d.mts

@@ -1,2 +1,2 @@
-import { i as MaxRefDepth, n as MAX_REF_DEPTH, r as MAX_RENDER_DEPTH, t as MAX_PATH_ITEM_REF_HOPS } from "../limits-DJhgx5Ay.mjs";
+import { i as MaxRefDepth, n as MAX_REF_DEPTH, r as MAX_RENDER_DEPTH, t as MAX_PATH_ITEM_REF_HOPS } from "../limits-x4OiyJxh.mjs";
 export { MAX_PATH_ITEM_REF_HOPS, MAX_REF_DEPTH, MAX_RENDER_DEPTH, MaxRefDepth };

package/dist/core/limits.mjs

@@ -12,11 +12,17 @@
 * — the only safe response to a cyclic walked-field graph.
 */
 const MAX_RENDER_DEPTH = 10;
+/** Runtime constant matching the type-level {@link MaxRefDepth} bound. */
 const MAX_REF_DEPTH = 64;
 /**
 * Maximum number of `$ref` hops permitted when walking a chain of
 * OpenAPI Path Item Object references. Beyond this a
 * `path-item-ref-too-deep` diagnostic is emitted and resolution stops.
+*
+* Also the default `maxHops` for the generic `resolveRefChain` helper
+* in `core/refChain.ts`, so every ref-chain walker — Path Item refs,
+* Parameter / Response refs, Reference Object chains, etc. — shares
+* the same hop cap.
 */
 const MAX_PATH_ITEM_REF_HOPS = 8;
 //#endregion

package/dist/core/merge.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
 
 //#region src/core/merge.d.ts
 /**
@@ -45,6 +45,11 @@ declare function mergeRefSiblings(referencer: Record<string, unknown>, resolvedM
  * inputs that cannot represent a schema; skip them as before.
  */
 declare function mergeAllOf(schemas: unknown[], diagnostics?: DiagnosticsOptions, pointer?: string): Record<string, unknown> | false;
+/**
+ * Result returned by {@link normaliseAnyOf} when an `anyOf` schema
+ * collapses to a nullable shape: the non-null branch and the nullable
+ * flag.
+ */
 interface NormalisedAnyOf {
   inner: Record<string, unknown>;
   isNullable: boolean;
@@ -54,6 +59,11 @@ interface NormalisedAnyOf {
  * Returns the non-null schema and a nullable flag.
  */
 declare function normaliseAnyOf(options: unknown[]): NormalisedAnyOf | undefined;
+/**
+ * Result returned by {@link detectDiscriminated} when a `oneOf` schema
+ * is structurally a discriminated union: the option schemas plus the
+ * shared property name carrying the const discriminator.
+ */
 interface Discriminated {
   options: Record<string, unknown>[];
   discriminator: string;
@@ -66,6 +76,17 @@ interface Discriminated {
  * uses `kind` while another uses `type`) detection fails and a
  * `discriminator-inconsistent` diagnostic is emitted so callers can
  * see why the union falls back to a generic oneOf.
+ *
+ * When two or more options share the same discriminator `const` value,
+ * the union is still treated as discriminated — the first-match
+ * behaviour in `resolveDiscriminatedActive` (in `core/unionMatch.ts`)
+ * resolves the active option — but a `discriminator-duplicate`
+ * diagnostic is emitted so the unreachable branch is visible to the
+ * consumer. Changing the behaviour to fall back to a generic union
+ * would be a silent regression for the much commoner case of two
+ * intentionally-identical discriminator values appearing in distinct
+ * sub-schemas (e.g. an `allOf`-driven hierarchy where the base option
+ * duplicates the leaf).
  */
 declare function detectDiscriminated(options: unknown[], diagnostics?: DiagnosticsOptions, pointer?: string): Discriminated | undefined;
 //#endregion

package/dist/core/merge.mjs

@@ -1,5 +1,6 @@
 import { isObject } from "./guards.mjs";
-import { emitDiagnostic } from "./diagnostics.mjs";
+import { appendPointer, emitDiagnostic } from "./diagnostics.mjs";
+import { isPrototypePollutingKey } from "./uri.mjs";
 //#region src/core/merge.ts
 /**
 * Schema merging, nullable detection, and discriminated union detection.
@@ -137,7 +138,18 @@ function mergeAllOf(schemas, diagnostics, pointer = "") {
 		if (entry === true) continue;
 		if (!isObject(entry)) continue;
 		const props = getObject(entry, "properties");
-		if (props !== void 0) for (const [key, value] of Object.entries(props)) properties[key] = value;
+		if (props !== void 0) for (const [key, value] of Object.entries(props)) {
+			if (isPrototypePollutingKey(key)) {
+				emitDiagnostic(diagnostics, {
+					code: "prototype-polluting-property",
+					message: `Refusing to merge prototype-polluting property name from allOf branch: ${key}`,
+					pointer: appendPointer(pointer, `properties/${key}`),
+					detail: { propertyName: key }
+				});
+				continue;
+			}
+			properties[key] = value;
+		}
 		const req = getArray(entry, "required");
 		if (req !== void 0) {
 			for (const r of req) if (typeof r === "string" && !required.includes(r)) required.push(r);
@@ -232,6 +244,17 @@ function normaliseAnyOf(options) {
 * uses `kind` while another uses `type`) detection fails and a
 * `discriminator-inconsistent` diagnostic is emitted so callers can
 * see why the union falls back to a generic oneOf.
+*
+* When two or more options share the same discriminator `const` value,
+* the union is still treated as discriminated — the first-match
+* behaviour in `resolveDiscriminatedActive` (in `core/unionMatch.ts`)
+* resolves the active option — but a `discriminator-duplicate`
+* diagnostic is emitted so the unreachable branch is visible to the
+* consumer. Changing the behaviour to fall back to a generic union
+* would be a silent regression for the much commoner case of two
+* intentionally-identical discriminator values appearing in distinct
+* sub-schemas (e.g. an `allOf`-driven hierarchy where the base option
+* duplicates the leaf).
 */
 function detectDiscriminated(options, diagnostics, pointer = "") {
 	if (options.length === 0) return void 0;
@@ -263,10 +286,50 @@ function detectDiscriminated(options, diagnostics, pointer = "") {
 		return;
 	}
 	if (discriminator === void 0) return void 0;
+	const objectOptions = options.filter(isObject);
+	emitDuplicateDiscriminatorDiagnostic(objectOptions, discriminator, diagnostics, pointer);
 	return {
-		options: options.filter(isObject),
+		options: objectOptions,
 		discriminator
 	};
 }
+/**
+* Inspect the discriminator `const` value declared on each option and
+* emit a `discriminator-duplicate` diagnostic when two or more options
+* share the same value. The diagnostic detail carries the offending
+* value plus the indices of the colliding options so consumers can
+* point at them directly.
+*/
+function emitDuplicateDiscriminatorDiagnostic(options, discriminator, diagnostics, pointer) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const [index, option] of options.entries()) {
+		const props = getObject(option, "properties");
+		if (props === void 0) continue;
+		const discriminatorSchema = getObject(props, discriminator);
+		if (discriminatorSchema === void 0) continue;
+		if (!("const" in discriminatorSchema)) continue;
+		const constValue = discriminatorSchema.const;
+		const key = JSON.stringify(constValue);
+		const existing = groups.get(key);
+		if (existing === void 0) groups.set(key, {
+			value: constValue,
+			indices: [index]
+		});
+		else existing.indices.push(index);
+	}
+	for (const { value, indices } of groups.values()) {
+		if (indices.length < 2) continue;
+		emitDiagnostic(diagnostics, {
+			code: "discriminator-duplicate",
+			message: `oneOf options ${indices.join(", ")} share the same discriminator value for "${discriminator}" (${JSON.stringify(value)}); only the first option is reachable`,
+			pointer,
+			detail: {
+				discriminator,
+				value,
+				indices
+			}
+		});
+	}
+}
 //#endregion
 export { ANNOTATION_SIBLINGS, detectDiscriminated, mergeAllOf, mergeRefSiblings, normaliseAnyOf };

package/dist/core/normalise.d.mts

@@ -1,7 +1,15 @@
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
-import { i as OpenApiVersionInfo, r as JsonSchemaDraft } from "../version-ZzL5R6cS.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
+import { i as OpenApiVersionInfo, r as JsonSchemaDraft } from "../version-DL8U5RuA.mjs";
 
 //#region src/core/normalise.d.ts
+/**
+ * Per-node transform applied by {@link deepNormalise} when no
+ * diagnostics context needs to be threaded — see
+ * {@link NodeTransformWithContext} for the variant used by the JSON
+ * Schema normalisation path.
+ *
+ * @group Adapter
+ */
 type NodeTransform = (node: Record<string, unknown>) => Record<string, unknown>;
 /**
  * Deep-normalise a JSON Schema object by applying a per-node transform
@@ -43,6 +51,13 @@ interface NodeContext {
   documentHasRecursiveAnchor: boolean;
   declaredDraft: JsonSchemaDraft | undefined;
 }
+/**
+ * Per-node transform applied by {@link deepNormaliseWithContext}.
+ * Receives the supplied {@link NodeContext} alongside the node so
+ * draft-specific rewrites can emit diagnostics with accurate pointers.
+ *
+ * @group Adapter
+ */
 type NodeTransformWithContext = (node: Record<string, unknown>, ctx: NodeContext) => Record<string, unknown>;
 /**
  * Deep-normalise a JSON Schema object, threading a context (diagnostics

package/dist/core/normalise.mjs

@@ -1,2 +1,2 @@
-import { a as normaliseJsonSchema, i as normaliseDraft04Node, n as deepNormaliseWithContext, o as normaliseOpenApiSchemas, r as documentContainsKeyword, s as selectDraftTransform, t as deepNormalise } from "../normalise-Db1xaxgx.mjs";
+import { a as normaliseJsonSchema, i as normaliseDraft04Node, n as deepNormaliseWithContext, o as normaliseOpenApiSchemas, r as documentContainsKeyword, s as selectDraftTransform, t as deepNormalise } from "../normalise-DB-Xtjmn.mjs";
 export { deepNormalise, deepNormaliseWithContext, documentContainsKeyword, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas, selectDraftTransform };

package/dist/core/openapi30.mjs

@@ -1,2 +1,2 @@
-import { d as deepNormaliseOpenApiDoc, f as liftExampleToExamples, h as normaliseOpenApi30Node, l as applyDiscriminatorAllOfPrepass, m as normaliseOpenApi30Discriminator, p as normaliseOpenApi30Combined, u as deepNormaliseOpenApi30Doc } from "../normalise-Db1xaxgx.mjs";
+import { d as deepNormaliseOpenApiDoc, f as liftExampleToExamples, h as normaliseOpenApi30Node, l as applyDiscriminatorAllOfPrepass, m as normaliseOpenApi30Discriminator, p as normaliseOpenApi30Combined, u as deepNormaliseOpenApi30Doc } from "../normalise-DB-Xtjmn.mjs";
 export { applyDiscriminatorAllOfPrepass, deepNormaliseOpenApi30Doc, deepNormaliseOpenApiDoc, liftExampleToExamples, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };

package/dist/core/openapiConstants.d.mts

@@ -12,6 +12,7 @@
  * Spec: https://spec.openapis.org/oas/v3.1.1#path-item-object
  */
 declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/** Canonical OpenAPI 3.x HTTP method literal, derived from {@link HTTP_METHODS}. */
 type HttpMethod = (typeof HTTP_METHODS)[number];
 /**
  * Swagger 2.0 omits `trace` — the keyword was introduced in OpenAPI 3.0.

package/dist/core/ref.d.mts

@@ -1,2 +1,2 @@
-import { a as dereference, i as countDistinctRefs, n as RECURSIVE_ANCHOR_SENTINEL, o as findAnchor, r as RefOptions, s as resolveRef, t as ExternalResolver } from "../ref-TdeMfaV_.mjs";
+import { a as dereference, i as countDistinctRefs, n as RECURSIVE_ANCHOR_SENTINEL, o as findAnchor, r as RefOptions, s as resolveRef, t as ExternalResolver } from "../ref-DdsbekXX.mjs";
 export { ExternalResolver, RECURSIVE_ANCHOR_SENTINEL, RefOptions, countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/refChain.d.mts

@@ -13,8 +13,6 @@
  * detect cycles, and tracking hop count against `maxHops`. The caller chooses
  * what to do on cycle or depth-cap via `onCycle` / `onDepthExceeded`.
  */
-/** Maximum number of `$ref` hops permitted by default. */
-declare const DEFAULT_REF_CHAIN_MAX_HOPS = 8;
 /**
  * Configuration for a single chain resolution.
  *
@@ -51,7 +49,8 @@ interface ResolveRefChainOptions<T> {
   readonly onDepthExceeded?: (ref: string) => T | undefined;
   /**
    * Maximum number of `$ref` hops permitted before `onDepthExceeded` fires.
-   * Defaults to `DEFAULT_REF_CHAIN_MAX_HOPS`.
+   * Defaults to `MAX_PATH_ITEM_REF_HOPS` from `core/limits.ts`, the
+   * canonical cap shared with the OpenAPI Path Item ref walker.
    */
   readonly maxHops?: number;
   /**
@@ -67,4 +66,4 @@ interface ResolveRefChainOptions<T> {
  */
 declare function resolveRefChain<T>(initial: T, options: ResolveRefChainOptions<T>): T | undefined;
 //#endregion
-export { DEFAULT_REF_CHAIN_MAX_HOPS, ResolveRefChainOptions, resolveRefChain };
+export { ResolveRefChainOptions, resolveRefChain };

package/dist/core/refChain.mjs

@@ -1,3 +1,4 @@
+import "./limits.mjs";
 //#region src/core/refChain.ts
 /**
 * Generic single-pass `$ref` chain resolver.
@@ -13,8 +14,6 @@
 * detect cycles, and tracking hop count against `maxHops`. The caller chooses
 * what to do on cycle or depth-cap via `onCycle` / `onDepthExceeded`.
 */
-/** Maximum number of `$ref` hops permitted by default. */
-const DEFAULT_REF_CHAIN_MAX_HOPS = 8;
 function defaultExtractRef(node) {
 	if (typeof node !== "object" || node === null) return void 0;
 	if (!("$ref" in node)) return void 0;
@@ -41,4 +40,4 @@ function resolveRefChain(initial, options) {
 	}
 }
 //#endregion
-export { DEFAULT_REF_CHAIN_MAX_HOPS, resolveRefChain };
+export { resolveRefChain };

package/dist/core/renderer.d.mts

@@ -1,2 +1,199 @@
-import { a as HtmlRenderProps, c as RenderFunction, d as getHtmlRenderFn, f as getRenderFunction, h as typeToKey, i as HtmlRenderFunction, l as RenderProps, m as mergeResolvers, n as BaseFieldProps, o as HtmlResolver, p as mergeHtmlResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as buildRenderProps } from "../renderer-Ul9taFYp.mjs";
-export { AllConstraints, BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, buildRenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };
+import { E as StringConstraints, f as FileConstraints, j as WalkedField, t as ArrayConstraints, w as SchemaMeta, x as ObjectConstraints, y as NumberConstraints } from "../types-BrYbjC7_.mjs";
+
+//#region src/core/renderer.d.ts
+/**
+ * Flat intersection of all constraint types.
+ * Used in renderer props where the render function receives the union
+ * but knows (by resolver key) which subset applies.
+ *
+ * The walker's discriminated WalkedField enforces type-correct constraints
+ * at construction time; the renderer consumes them as this flat type.
+ */
+type AllConstraints = StringConstraints & NumberConstraints & ArrayConstraints & ObjectConstraints & FileConstraints;
+/**
+ * Properties available on every schema field, regardless of rendering target.
+ * Both React and HTML renderers receive these.
+ *
+ * Per-type schema data — enum values, object fields, array element schema,
+ * union options, record key/value types, tuple `prefixItems`, conditional
+ * if/then/else clauses, negation `negated`, recursive `refTarget`, literal
+ * values — lives on the discriminated `tree`. Renderers narrow on
+ * `tree.type` and read from the matching variant; there are no duplicate
+ * sibling fields on these props.
+ */
+interface BaseFieldProps {
+  /** Current field value. */
+  value: unknown;
+  /** Whether to render as read-only display. */
+  readOnly: boolean;
+  /** Whether to render as an empty input. */
+  writeOnly: boolean;
+  /** Schema metadata for this field. */
+  meta: SchemaMeta;
+  /** Constraints from schema checks. */
+  constraints: AllConstraints;
+  /** Dot-separated path from root (e.g. "address.city"). */
+  path: string;
+  /** Example values from the schema's `examples` keyword. */
+  examples?: unknown[];
+  /** Walked field tree for recursive rendering. */
+  tree: WalkedField;
+}
+/**
+ * Props for React render functions. Extends BaseFieldProps with:
+ * - `onChange` — callback to propagate value changes back to state
+ * - `renderChild` — recursively renders a child field, threading onChange
+ */
+interface RenderProps extends BaseFieldProps {
+  /** Callback to update the field value. */
+  onChange: (value: unknown) => void;
+  /**
+   * Render a child field. Theme adapters call this to recursively render
+   * nested structures (object fields, array elements, union options).
+   * The resolver and rendering context are already wired in.
+   *
+   * @param tree - The walked field tree for the child
+   * @param value - The child's current value
+   * @param onChange - Callback receiving the child's next value
+   * @param pathSuffix - Path segment from the parent (e.g. "city",
+   *   "[0]"). Joined to the parent's path with a dot, or substituted
+   *   when the parent acts as a transparent wrapper (union options).
+   *   Required for every container — without it children inherit no
+   *   path and `inputId()` will throw.
+   */
+  renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void, pathSuffix?: string) => unknown;
+}
+/**
+ * Props for HTML render functions. Extends BaseFieldProps with:
+ * - `renderChild` — recursively renders a child field to HTML string
+ *
+ * No `onChange` — HTML rendering is pure output with no event handling.
+ */
+interface HtmlRenderProps extends BaseFieldProps {
+  /**
+   * Render a child field to an HTML string. Theme adapters call this
+   * to recursively render nested structures.
+   *
+   * @param tree - The walked field tree for the child
+   * @param value - The child's current value
+   * @param pathSuffix - Path segment from the parent (e.g. "city",
+   *   "[0]"). When omitted, the child's description is used as fallback.
+   */
+  renderChild: (tree: WalkedField, value: unknown, pathSuffix?: string) => string;
+}
+/**
+ * Build the `RenderProps` object handed to a resolver render function or a
+ * widget. Used by both the server-side `<SchemaView>` (which has no
+ * `onChange`) and the client-side `<SchemaComponent>` (which threads an
+ * `onChange` callback).
+ *
+ * When `onChange` is `undefined` the caller is rendering in read-only mode:
+ * a noop `onChange` is wired up, `readOnly` is forced to `true`, and
+ * `writeOnly` is forced to `false`. Otherwise the editability is taken
+ * from `tree.editability`.
+ */
+declare function buildRenderProps(tree: WalkedField, value: unknown, onChange: ((next: unknown) => void) | undefined, renderChild: RenderProps["renderChild"], path: string): RenderProps;
+/**
+ * Signature for a React render function attached to a
+ * {@link ComponentResolver}. Receives the per-field {@link RenderProps}
+ * built by the walker and returns any ReactNode-compatible value.
+ */
+type RenderFunction = (props: RenderProps) => unknown;
+/**
+ * Widget map — maps component hints (from `.meta({ component })`) to render
+ * functions. A per-render bag consumed by every renderer surface that
+ * dispatches widget overrides; conceptually parallel to
+ * {@link ComponentResolver} but keyed by user-supplied hint names rather
+ * than schema types.
+ *
+ * Scoped at three levels in the React renderer:
+ *
+ * 1. **Per-instance** — `widgets` prop on `<SchemaComponent>`
+ * 2. **Context-scoped** — `widgets` prop on `<SchemaProvider>`
+ * 3. **Global** — `registerWidget()` (app-wide defaults)
+ *
+ * Resolution order: instance → context → global → resolver → headless.
+ */
+type WidgetMap = ReadonlyMap<string, RenderFunction>;
+/**
+ * Theme adapter — maps every schema field type to its React renderer.
+ * Unset keys fall back to the headless resolver. Pass to
+ * `SchemaProvider` (or `SchemaView.resolver`) to drive every
+ * schema-driven render with a specific theme.
+ */
+interface ComponentResolver {
+  string?: RenderFunction;
+  number?: RenderFunction;
+  boolean?: RenderFunction;
+  null?: RenderFunction;
+  enum?: RenderFunction;
+  object?: RenderFunction;
+  array?: RenderFunction;
+  tuple?: RenderFunction;
+  record?: RenderFunction;
+  union?: RenderFunction;
+  discriminatedUnion?: RenderFunction;
+  conditional?: RenderFunction;
+  negation?: RenderFunction;
+  literal?: RenderFunction;
+  file?: RenderFunction;
+  never?: RenderFunction;
+  unknown?: RenderFunction;
+}
+/** An HTML render function returns a string. */
+type HtmlRenderFunction = (props: HtmlRenderProps) => string;
+/**
+ * HTML resolver — maps schema types to HTML string renderers.
+ * Structurally mirrors ComponentResolver but produces strings.
+ */
+interface HtmlResolver {
+  string?: HtmlRenderFunction;
+  number?: HtmlRenderFunction;
+  boolean?: HtmlRenderFunction;
+  null?: HtmlRenderFunction;
+  enum?: HtmlRenderFunction;
+  object?: HtmlRenderFunction;
+  array?: HtmlRenderFunction;
+  tuple?: HtmlRenderFunction;
+  record?: HtmlRenderFunction;
+  union?: HtmlRenderFunction;
+  discriminatedUnion?: HtmlRenderFunction;
+  conditional?: HtmlRenderFunction;
+  negation?: HtmlRenderFunction;
+  literal?: HtmlRenderFunction;
+  file?: HtmlRenderFunction;
+  never?: HtmlRenderFunction;
+  unknown?: HtmlRenderFunction;
+}
+/**
+ * Canonical list of resolver keys, one per {@link WalkedField} variant.
+ * Iterated by the resolver merge helpers so adding a new key here is the
+ * single point of change when a new field variant is introduced.
+ */
+declare const RESOLVER_KEYS: readonly ["string", "number", "boolean", "null", "enum", "object", "array", "tuple", "record", "union", "discriminatedUnion", "conditional", "negation", "literal", "file", "never", "unknown"];
+type ResolverKey = (typeof RESOLVER_KEYS)[number];
+/**
+ * Map a schema type to the resolver key that handles it.
+ * Every WalkedField variant has a direct resolver key — exhaustive switch
+ * ensures new variants surface as a type error rather than silently
+ * falling through to "unknown".
+ */
+declare function typeToKey(type: WalkedField["type"]): ResolverKey;
+/**
+ * Look up the render function for a schema type in a ComponentResolver.
+ */
+declare function getRenderFunction(type: WalkedField["type"], resolver: ComponentResolver): RenderFunction | undefined;
+/**
+ * Look up the render function for a schema type in an HtmlResolver.
+ */
+declare function getHtmlRenderFn(type: WalkedField["type"], resolver: HtmlResolver): HtmlRenderFunction | undefined;
+/**
+ * Merge two ComponentResolvers — user values take priority, fallback fills gaps.
+ */
+declare function mergeResolvers(user: ComponentResolver, fallback: ComponentResolver): ComponentResolver;
+/**
+ * Merge two HtmlResolvers — user values take priority, fallback fills gaps.
+ */
+declare function mergeHtmlResolvers(user: HtmlResolver, fallback: HtmlResolver): HtmlResolver;
+//#endregion
+export { AllConstraints, BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, WidgetMap, buildRenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/renderer.mjs

@@ -29,6 +29,11 @@ function buildRenderProps(tree, value, onChange, renderChild, path) {
 	if (tree.examples !== void 0) props.examples = tree.examples;
 	return props;
 }
+/**
+* Canonical list of resolver keys, one per {@link WalkedField} variant.
+* Iterated by the resolver merge helpers so adding a new key here is the
+* single point of change when a new field variant is introduced.
+*/
 const RESOLVER_KEYS = [
 	"string",
 	"number",

package/dist/core/swagger2.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
 import { NodeTransform } from "./normalise.mjs";
 
 //#region src/core/swagger2.d.ts