schema-components 1.29.0 → 2.0.1

package/README.md

@@ -298,14 +298,20 @@ import { shadcnResolver } from "schema-components/themes/shadcn";
 ### MUI
 
 ```tsx
-import { registerMuiComponents } from "schema-components/themes/mui";
-import { shadcnResolver } from "schema-components/themes/shadcn";
-
-// Register MUI components at app startup
-registerMuiComponents();
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import { createMuiResolver } from "schema-components/themes/mui";
+import TextField from "@mui/material/TextField";
+import Checkbox from "@mui/material/Checkbox";
+import Typography from "@mui/material/Typography";
+import Box from "@mui/material/Box";
+import MenuItem from "@mui/material/MenuItem";
+import FormControlLabel from "@mui/material/FormControlLabel";
+
+const muiResolver = createMuiResolver({
+  TextField, Checkbox, Typography, Box, MenuItem, FormControlLabel,
+});
 
-// Use via SchemaProvider
-<SchemaProvider resolver={shadcnResolver}>
+<SchemaProvider resolver={muiResolver}>
   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
 </SchemaProvider>
 ```
@@ -313,12 +319,17 @@ registerMuiComponents();
 ### Mantine
 
 ```tsx
-import { registerMantineComponents } from "schema-components/themes/mantine";
-import { shadcnResolver } from "schema-components/themes/shadcn";
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import { createMantineResolver } from "schema-components/themes/mantine";
+import {
+  TextInput, NumberInput, Switch, Select, Fieldset, Text,
+} from "@mantine/core";
 
-registerMantineComponents();
+const mantineResolver = createMantineResolver({
+  TextInput, NumberInput, Switch, Select, Fieldset, Text,
+});
 
-<SchemaProvider resolver={shadcnResolver}>
+<SchemaProvider resolver={mantineResolver}>
   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
 </SchemaProvider>
 ```
@@ -326,12 +337,23 @@ registerMantineComponents();
 ### Radix Themes
 
 ```tsx
-import { registerRadixComponents } from "schema-components/themes/radix";
-import { shadcnResolver } from "schema-components/themes/shadcn";
-
-registerRadixComponents();
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import { createRadixResolver } from "schema-components/themes/radix";
+import { Box, Checkbox, Flex, Select, Text, TextField } from "@radix-ui/themes";
+
+const radixResolver = createRadixResolver({
+  Box,
+  Checkbox,
+  Flex,
+  SelectRoot: Select.Root,
+  SelectTrigger: Select.Trigger,
+  SelectContent: Select.Content,
+  SelectItem: Select.Item,
+  Text,
+  TextField: TextField.Root,
+});
 
-<SchemaProvider resolver={shadcnResolver}>
+<SchemaProvider resolver={radixResolver}>
   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
 </SchemaProvider>
 ```

package/dist/core/adapter.d.mts

@@ -1,3 +1,213 @@
-import { m as JsonObject, w as SchemaMeta } from "../types-C2Ay1FEh.mjs";
-import { a as SchemaKind, c as extractRootMetaFromJson, i as SchemaIoSide, l as isCodecSchema, n as NormalisedSchema, o as __CLASSIFIER_RULES_FOR_TEST, r as SchemaInput, s as detectSchemaKind, t as NormaliseOptions, u as normaliseSchema } from "../adapter-DcWi4XXn.mjs";
-export { JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaIoSide, SchemaKind, SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, extractRootMetaFromJson, isCodecSchema, normaliseSchema };
+import { m as JsonObject, w as SchemaMeta } from "../types-BrYbjC7_.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
+
+//#region src/core/adapter.d.ts
+/**
+ * Classification produced by {@link detectSchemaKind} when inspecting a
+ * runtime schema input.
+ *
+ * @group Adapter
+ */
+type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi" | "unsupported-schema-lib";
+/**
+ * Classify a runtime schema input by structural markers — Zod 4, Zod 3,
+ * OpenAPI document, plain JSON Schema, or an unsupported third-party
+ * schema library.
+ *
+ * - `zod4` — has a `_zod` marker (further validation that `_zod.def` is a
+ *   non-null object happens inside `normaliseZod4`).
+ * - `zod3` — has `_def` and no `_zod`. The `typeName` field is no longer
+ *   required: any `_def` without `_zod` is treated as a probable Zod 3
+ *   schema. Third-party libraries that expose `_def` without `_zod` are
+ *   nearly always Zod 3 forks; surfacing the migration message is the
+ *   correct response.
+ * - `openapi` — has `openapi` or `swagger` at the root.
+ * - `unsupported-schema-lib` — has `parse` and `safeParse` callables but
+ *   no `_zod` and no `_def` marker. This catches Standard Schema
+ *   implementations (valibot, arktype, etc.) that would otherwise flow
+ *   through as "malformed JSON Schema".
+ * - `jsonSchema` — fallback for anything that does not match the above.
+ *
+ * @group Adapter
+ */
+declare function detectSchemaKind(input: unknown): SchemaKind;
+/**
+ * Wraps z.toJSONSchema() for a runtime-validated Zod schema.
+ *
+ * The _zod guard in normaliseZod4 has confirmed this is a valid Zod schema,
+ * but TypeScript cannot represent "has _zod.def" as the $ZodType parameter
+ * that z.toJSONSchema expects. This is the library boundary equivalent of
+ * object → Record<string, unknown> — the type mismatch is genuinely unavoidable.
+ *
+ * # Options
+ *
+ * `z.toJSONSchema` is invoked with an explicit options object rather than
+ * Zod's defaults so the conversion contract is pinned and stable:
+ *
+ * - `target: "draft-2020-12"` — matches the walker's draft target.
+ * - `unrepresentable: "throw"` — keeps the unrepresentable-type rules in
+ *   the classifier table firing instead of silently emitting `{}`.
+ * - `cycles: "ref"` — converts cyclic graphs into $ref pairs rather than
+ *   throwing. Cycles in user schemas surface through the walker's $ref
+ *   resolution rather than the adapter.
+ * - `io` — selects which side of every transform / pipe / codec is
+ *   converted. Defaults to `"output"` (the OUTPUT side); pass `"input"`
+ *   to render the INPUT side instead. The input side is invisible to
+ *   the converted schema when `io: "output"` is in force, even though
+ *   `safeParse` on the same Zod schema consumes the input shape. For
+ *   transforms this divergence is fatal and the call throws via
+ *   `Transforms cannot be represented`; for `z.codec(...)` the call
+ *   succeeds but only the selected side is rendered. Consumers receive
+ *   a `zod-codec-output-only` diagnostic in the codec case so the
+ *   asymmetry is visible — see `screenPreConversion`.
+ *
+ * # Error classification
+ *
+ * Any exception thrown by z.toJSONSchema is classified into a
+ * SchemaNormalisationError so the caller does not have to re-parse error
+ * message strings. The classification covers:
+ *
+ * - Nested Zod 3 schemas inside a Zod 4 tree → zod3-unsupported.
+ *   Detected structurally (presence of `_def.typeName` markers anywhere
+ *   in the schema tree) so the check works across V8, JavaScriptCore,
+ *   and SpiderMonkey, none of which agree on the wording of
+ *   "Cannot read properties of undefined".
+ * - Transforms → zod-transform-unsupported. This also catches `z.codec(…)`
+ *   because Zod implements codecs as a pipe + transform internally, so
+ * they trip the same processor when round-tripping is forced. (Plain
+ *   `z.toJSONSchema(codec)` itself does NOT throw because Zod picks one
+ *   side of the codec; the static rejection in `typeInference.ts` is the
+ *   compile-time guard.)
+ * - Dynamic catch values whose handler throws → zod-type-unrepresentable
+ *   with zodType "dynamic-catch".
+ * - Unrepresentable types — bigint, date, map, set, symbol, function, custom,
+ *   undefined, void, NaN, and the literal-only forms `z.literal(undefined)`
+ *   ("undefined-literal") and `z.literal(<bigint>)` ("bigint-literal") →
+ *   zod-type-unrepresentable.
+ * - The catch-all "Non-representable type encountered: <type>" fallback Zod
+ *   emits for any new schema kind without a registered processor →
+ *   zod-type-unrepresentable with zodType set to the offending def.type.
+ * - Cycle detected (`cycles: "throw"`) → zod-cycle-detected.
+ * - Duplicate schema id → zod-duplicate-id.
+ * - "Unprocessed schema. This is a bug in Zod." → zod-conversion-bug.
+ * - "Error converting schema to JSON." → zod-conversion-failed (explicit
+ *   classification rather than the generic fallback so the contract test
+ *   protects the prefix from drift).
+ * - Anything else → zod-conversion-failed.
+ *
+ * The original error is preserved on each classified error via the `cause`
+ * field so consumers can still inspect the Zod stack trace.
+ */
+/**
+ * Direction of the Zod transform / pipe / codec that
+ * {@link normaliseSchema} should surface to the renderer.
+ *
+ * - `"output"` (default) — the server-facing side of every transform,
+ *   matching `z.toJSONSchema`'s default and the historic adapter
+ *   behaviour.
+ * - `"input"` — the client-facing side; flips a `z.codec(...)` chain
+ *   so consumers can render its input shape.
+ *
+ * @group Adapter
+ */
+type SchemaIoSide = "input" | "output";
+/**
+ * True when `value` is a Zod schema implemented as a codec
+ * (`z.codec(...)`). Detection looks for the `$ZodCodec` marker on the
+ * schema's `_zod.traits` Set — the same structural check used by Zod
+ * itself in `to-json-schema.ts`'s `isTransforming` helper.
+ *
+ * Promoted from a duplicated local helper in `react/SchemaComponent.tsx`
+ * so the validation boundary inside `runValidation` can branch on
+ * codec-vs-not-codec without re-implementing the trait check. The
+ * shared helper anchors a single source of truth for codec detection:
+ * any future change to Zod's trait naming flows through here, not
+ * through two parallel copies.
+ *
+ * Returns `false` for non-objects, plain JSON Schema inputs, OpenAPI
+ * documents, or Zod schemas of any other kind. This is structural
+ * rather than nominal — a Zod 4 codec produced by any path that ends
+ * up tagging `_zod.traits` with `$ZodCodec` is recognised, including
+ * schemas wrapped by user-defined helpers.
+ */
+declare function isCodecSchema(value: unknown): boolean;
+/**
+ * Exposed for unit testing — lets the contract test enumerate every rule's
+ * `prefix` value and assert mutual non-prefixing.
+ */
+declare const __CLASSIFIER_RULES_FOR_TEST: readonly {
+  readonly prefix: string;
+}[];
+/**
+ * Result of {@link normaliseSchema}. Carries the canonical Draft 2020-12
+ * JSON Schema the walker consumes, the optional original Zod schema
+ * (used for validation), and the resolved root document so cross-document
+ * `$ref`s can be dereferenced downstream.
+ *
+ * @group Adapter
+ */
+interface NormalisedSchema {
+  /** JSON Schema object — the authoritative schema for rendering. */
+  jsonSchema: JsonObject;
+  /** Original Zod schema, if input was Zod. Used for validation. */
+  zodSchema?: unknown;
+  /** Root-level metadata. */
+  rootMeta: SchemaMeta | undefined;
+  /** The root document for $ref resolution. */
+  rootDocument: JsonObject;
+}
+/**
+ * Options accepted by {@link normaliseSchema}.
+ *
+ * @group Adapter
+ */
+interface NormaliseOptions {
+  /** Diagnostics channel for surfacing silent fallbacks. */
+  diagnostics?: DiagnosticsOptions;
+  /**
+   * Side of every transform / pipe / codec to render. Defaults to
+   * `"output"`, matching `z.toJSONSchema`'s default and the
+   * historic behaviour of the adapter. Passing `"input"` flips the
+   * conversion so consumers rendering the input shape of a
+   * `z.codec(...)` chain receive that side instead of the output
+   * side. Only the Zod 4 branch consults this option — JSON Schema
+   * and OpenAPI inputs are already a single canonical shape.
+   */
+  io?: SchemaIoSide;
+}
+/**
+ * Normalise any supported schema input — Zod 4 schema, plain JSON
+ * Schema (any draft), Swagger 2.0, OpenAPI 3.0 or 3.1 document — into
+ * a canonical Draft 2020-12 {@link NormalisedSchema} the walker can
+ * consume.
+ *
+ * Dispatches on {@link detectSchemaKind}, applies the appropriate
+ * version normaliser, and returns the JSON Schema alongside the
+ * original Zod schema (for validation) and the resolved root document
+ * (for cross-document `$ref` resolution). Throws
+ * `SchemaNormalisationError` for unsupported inputs (Zod 3, valibot,
+ * arktype, codec or other unrepresentable Zod types).
+ *
+ * @group Adapter
+ */
+declare function normaliseSchema(input: unknown, ref?: string, options?: NormaliseOptions): NormalisedSchema;
+/**
+ * Surface root-level metadata from the JSON Schema into the `rootMeta`
+ * shape consumed by the walker. Pulls `readOnly`, `writeOnly`,
+ * `description`, `title`, `deprecated`, `examples`, and `default`
+ * directly from the schema root.
+ *
+ * `examples` is forwarded only when present as an array (per JSON Schema
+ * Draft 2020-12 — Draft 04's `example` singular is normalised upstream).
+ * `default` is forwarded for any value the schema declares (any JSON
+ * value, including `null` and `false`); the presence check uses `in`
+ * so a literal `false` or `null` default is preserved.
+ *
+ * `examples` and `default` ride on the `[key: string]: unknown` index
+ * signature of {@link SchemaMeta}. They are not declared as named fields
+ * on `SchemaMeta` because that type lives in `types.ts` and is shared
+ * with the walker; the index signature is the agreed extension point.
+ */
+declare function extractRootMetaFromJson(jsonSchema: JsonObject): SchemaMeta | undefined;
+//#endregion
+export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaIoSide, SchemaKind, type SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, extractRootMetaFromJson, isCodecSchema, normaliseSchema };

package/dist/core/adapter.mjs

@@ -4,7 +4,7 @@ import { SchemaNormalisationError } from "./errors.mjs";
 import { appendPointer, emitDiagnostic } from "./diagnostics.mjs";
 import { dereference } from "./ref.mjs";
 import { detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2, matchJsonSchemaDraftUri } from "./version.mjs";
-import { a as normaliseJsonSchema$1, o as normaliseOpenApiSchemas } from "../normalise-Db1xaxgx.mjs";
+import { a as normaliseJsonSchema$1, o as normaliseOpenApiSchemas } from "../normalise-DB-Xtjmn.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**

package/dist/core/constraintHint.d.mts

@@ -0,0 +1,15 @@
+import { AllConstraints } from "./renderer.mjs";
+
+//#region src/core/constraintHint.d.ts
+/**
+ * Build a human-readable constraint description string.
+ *
+ * Returns `undefined` when no constraint worth announcing is present.
+ * Pattern hints are suppressed when a `format` is set because the
+ * format already implies the pattern and the resulting copy would be
+ * misleading ("Must match pattern" alongside a `format: "email"` field
+ * would read as if the schema required a non-email regex).
+ */
+declare function constraintHint(c: AllConstraints): string | undefined;
+//#endregion
+export { constraintHint };

package/dist/core/constraintHint.mjs

@@ -0,0 +1,24 @@
+//#region src/core/constraintHint.ts
+/**
+* Build a human-readable constraint description string.
+*
+* Returns `undefined` when no constraint worth announcing is present.
+* Pattern hints are suppressed when a `format` is set because the
+* format already implies the pattern and the resulting copy would be
+* misleading ("Must match pattern" alongside a `format: "email"` field
+* would read as if the schema required a non-email regex).
+*/
+function constraintHint(c) {
+	const parts = [];
+	if (c.minLength !== void 0) parts.push(`Minimum ${String(c.minLength)} characters`);
+	if (c.maxLength !== void 0) parts.push(`Maximum ${String(c.maxLength)} characters`);
+	if (c.minimum !== void 0) parts.push(`Minimum ${String(c.minimum)}`);
+	if (c.maximum !== void 0) parts.push(`Maximum ${String(c.maximum)}`);
+	if (c.pattern !== void 0 && c.format === void 0) parts.push("Must match pattern");
+	if (c.minItems !== void 0) parts.push(`Minimum ${String(c.minItems)} items`);
+	if (c.maxItems !== void 0) parts.push(`Maximum ${String(c.maxItems)} items`);
+	if (parts.length === 0) return void 0;
+	return parts.join(". ");
+}
+//#endregion
+export { constraintHint };

package/dist/core/constraints.d.mts

@@ -1,5 +1,5 @@
-import { E as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-C2Ay1FEh.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-ByEzkjrA.mjs";
+import { E as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-BrYbjC7_.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
 
 //#region src/core/constraints.d.ts
 /**

package/dist/core/constraints.mjs

@@ -30,7 +30,7 @@ function extractStringConstraints(schema, diagnostics, pointer = "") {
 		c.format = format;
 		const pattern = FORMAT_PATTERNS[format];
 		if (pattern !== void 0) c.formatPattern = pattern;
-		else if (format !== "binary") emitDiagnostic(diagnostics, {
+		else if (format !== "binary" && format !== "password") emitDiagnostic(diagnostics, {
 			code: "unknown-format",
 			message: `Unknown format: ${format}`,
 			pointer,

package/dist/core/diagnostics.d.mts

@@ -1,2 +1,2 @@
-import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-ByEzkjrA.mjs";
+import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-BTrm3O6J.mjs";
 export { Diagnostic, DiagnosticCode, DiagnosticSink, DiagnosticsOptions, appendPointer, emitDiagnostic };

package/dist/core/errors.d.mts

@@ -1,2 +1,2 @@
-import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-D8JndRwI.mjs";
+import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-Dki7tji4.mjs";
 export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError };

package/dist/core/fieldOrder.d.mts

@@ -1,4 +1,4 @@
-import { j as WalkedField } from "../types-C2Ay1FEh.mjs";
+import { j as WalkedField } from "../types-BrYbjC7_.mjs";
 
 //#region src/core/fieldOrder.d.ts
 /**

package/dist/core/formats.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-ByEzkjrA.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
 
 //#region src/core/formats.d.ts
 /**

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-DswmqWuy.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

@@ -18,6 +18,11 @@ 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-ByEzkjrA.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
 
 //#region src/core/merge.d.ts
 /**
@@ -76,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