schema-components 1.21.0 → 1.23.0

package/dist/core/cssClasses.d.mts

@@ -0,0 +1,52 @@
+//#region src/core/cssClasses.d.ts
+/**
+ * Shared CSS class names and visual placeholders used by every render
+ * pipeline (React, HTML-sync, HTML-stream). Centralising avoids drift
+ * between renderers and the bundled default stylesheet (`styles.css`).
+ *
+ * Class names are intentionally namespaced under `sc-` so consumer themes
+ * can pattern-match or override without collision risk.
+ */
+/** Common em-dash placeholder for empty / unset values. */
+declare const EM_DASH = "\u2014";
+/** Single-character ellipsis used in placeholders like "Select…". */
+declare const ELLIPSIS = "\u2026";
+/** Prefix applied to every generated DOM id by `buildInputId`. */
+declare const SC_ID_PREFIX = "sc-";
+/**
+ * Canonical CSS class names exposed by the default render pipelines.
+ * Keys are stable identifiers; values are the raw class strings emitted
+ * to the DOM. Add new entries here rather than embedding class literals
+ * in renderers — `styles.css` cross-references the same names.
+ */
+declare const SC_CLASSES: {
+  readonly value: "sc-value";
+  readonly valueEmpty: "sc-value sc-value--empty";
+  readonly field: "sc-field";
+  readonly label: "sc-label";
+  readonly input: "sc-input";
+  readonly hint: "sc-hint";
+  readonly required: "sc-required";
+  readonly object: "sc-object";
+  readonly array: "sc-array";
+  readonly record: "sc-record";
+  readonly tuple: "sc-tuple";
+  readonly tupleItem: "sc-tuple-item";
+  readonly tupleRest: "sc-tuple-rest";
+  readonly tupleIndex: "sc-tuple-index";
+  readonly discriminatedUnion: "sc-discriminated-union";
+  readonly tabs: "sc-tabs";
+  readonly tab: "sc-tab";
+  readonly tabActive: "sc-tab sc-tab--active";
+  readonly tabPanel: "sc-tab-panel";
+  readonly conditional: "sc-conditional";
+  readonly conditionalIf: "sc-conditional-if";
+  readonly conditionalThen: "sc-conditional-then";
+  readonly conditionalElse: "sc-conditional-else";
+  readonly negation: "sc-negation";
+  readonly never: "sc-never";
+  readonly recursive: "sc-recursive";
+};
+type ScClassKey = keyof typeof SC_CLASSES;
+//#endregion
+export { ELLIPSIS, EM_DASH, SC_CLASSES, SC_ID_PREFIX, ScClassKey };

package/dist/core/cssClasses.mjs

@@ -0,0 +1,51 @@
+//#region src/core/cssClasses.ts
+/**
+* Shared CSS class names and visual placeholders used by every render
+* pipeline (React, HTML-sync, HTML-stream). Centralising avoids drift
+* between renderers and the bundled default stylesheet (`styles.css`).
+*
+* Class names are intentionally namespaced under `sc-` so consumer themes
+* can pattern-match or override without collision risk.
+*/
+/** Common em-dash placeholder for empty / unset values. */
+const EM_DASH = "—";
+/** Single-character ellipsis used in placeholders like "Select…". */
+const ELLIPSIS = "…";
+/** Prefix applied to every generated DOM id by `buildInputId`. */
+const SC_ID_PREFIX = "sc-";
+/**
+* Canonical CSS class names exposed by the default render pipelines.
+* Keys are stable identifiers; values are the raw class strings emitted
+* to the DOM. Add new entries here rather than embedding class literals
+* in renderers — `styles.css` cross-references the same names.
+*/
+const SC_CLASSES = {
+	value: "sc-value",
+	valueEmpty: "sc-value sc-value--empty",
+	field: "sc-field",
+	label: "sc-label",
+	input: "sc-input",
+	hint: "sc-hint",
+	required: "sc-required",
+	object: "sc-object",
+	array: "sc-array",
+	record: "sc-record",
+	tuple: "sc-tuple",
+	tupleItem: "sc-tuple-item",
+	tupleRest: "sc-tuple-rest",
+	tupleIndex: "sc-tuple-index",
+	discriminatedUnion: "sc-discriminated-union",
+	tabs: "sc-tabs",
+	tab: "sc-tab",
+	tabActive: "sc-tab sc-tab--active",
+	tabPanel: "sc-tab-panel",
+	conditional: "sc-conditional",
+	conditionalIf: "sc-conditional-if",
+	conditionalThen: "sc-conditional-then",
+	conditionalElse: "sc-conditional-else",
+	negation: "sc-negation",
+	never: "sc-never",
+	recursive: "sc-recursive"
+};
+//#endregion
+export { ELLIPSIS, EM_DASH, SC_CLASSES, SC_ID_PREFIX };

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-CbBPsxSt.mjs";
+import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-BS2kaUyE.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-QEwOtQAA.mjs";
+import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-g_MCTQel.mjs";
 export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError };

package/dist/core/errors.mjs

@@ -1,17 +1,5 @@
 //#region src/core/errors.ts
 /**
-* Structured error types for schema-components.
-*
-* Every error produced by the library is one of these three types:
-*
-* - SchemaNormalisationError — the adapter failed to convert the input
-*   to JSON Schema (invalid Zod, bad OpenAPI ref, malformed schema)
-* - SchemaRenderError — a theme adapter's render function threw
-* - SchemaFieldError — a field path couldn't be resolved
-*
-* All extend `SchemaError` so consumers can catch the base class.
-*/
-/**
 * Base class for all schema-components errors.
 * Catch this to handle any library error uniformly.
 *
@@ -55,7 +43,11 @@ var SchemaNormalisationError = class extends SchemaError {
 * The `cause` is the original error from the render function.
 */
 var SchemaRenderError = class extends SchemaError {
-	/** The schema type being rendered when the error occurred. */
+	/**
+	* The schema type being rendered when the error occurred. Drawn from
+	* the walker's discriminant union so consumers can switch on it
+	* exhaustively without a wider `string` fallback.
+	*/
 	schemaType;
 	constructor(message, schema, schemaType, cause) {
 		super(message, schema, cause);

package/dist/core/fieldOrder.d.mts

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

package/dist/core/formats.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
 
 //#region src/core/formats.d.ts
 /**
@@ -9,6 +9,13 @@ import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
  * it reaches the regex engine.
  */
 declare const MAX_REGEX_PATTERN_LENGTH = 500;
+/**
+ * Map a JSON Schema string `format` to the matching HTML `<input type="…">`
+ * value, or `undefined` when the format does not correspond to a date/time
+ * input. Shared by the HTML and headless React renderers so a single
+ * mapping table governs both pipelines.
+ */
+declare function dateInputType(format: string | undefined): string | undefined;
 /**
  * A format validator: either a RegExp pattern or a predicate function.
  */
@@ -16,6 +23,27 @@ type FormatValidator = RegExp | ((value: string) => boolean);
 /**
  * Recognised JSON Schema formats with their validation patterns.
  * Unknown formats emit an `unknown-format` diagnostic and skip derivation.
+ *
+ * Draft origin reference — formats first standardised by each draft:
+ *
+ * - Draft 04: `date-time`, `email`, `hostname`, `ipv4`, `ipv6`, `uri`
+ * - Draft 06: `uri-reference`, `uri-template`, `json-pointer`
+ * - Draft 07: `date`, `time`, `idn-email`, `idn-hostname`, `iri`,
+ *   `iri-reference`, `regex`, `relative-json-pointer`
+ * - Draft 2019-09: `duration`, `uuid`
+ * - Vocabulary extensions / non-standard: `binary` (OpenAPI), and the
+ *   Zod-emitted formats `cuid`, `cuid2`, `nanoid`, `cidrv4`, `cidrv6`,
+ *   `base64`, `base64url`, `e164`, `emoji`, `ulid`, `xid`, `ksuid`,
+ *   `lowercase`, `uppercase`, `jwt`, `json-string`
+ *
+ * Policy: schema-components accepts ALL formats in ALL drafts. We do
+ * not reject (e.g.) `uri-reference` on a Draft 04 schema or `uuid` on
+ * a Draft 06 schema, even though the spec did not standardise those
+ * names until a later draft. This matches the behaviour of every
+ * mainstream JSON Schema validator (Ajv, jsonschema, etc.) and avoids
+ * spurious failures on legitimate real-world schemas that pre-date or
+ * post-date the dialect they declare. Authors who want strict draft-
+ * locked behaviour should validate with a dedicated meta-schema tool.
  */
 /**
  * Email format pattern, exported as a named const so callers that need a
@@ -37,4 +65,4 @@ declare const FORMAT_PATTERNS: Readonly<Record<string, RegExp>>;
  */
 declare function validateFormat(value: string, format: string, diagnostics?: DiagnosticsOptions, pointer?: string): boolean | undefined;
 //#endregion
-export { EMAIL_FORMAT_PATTERN, FORMAT_PATTERNS, FormatValidator, MAX_REGEX_PATTERN_LENGTH, validateFormat };
+export { EMAIL_FORMAT_PATTERN, FORMAT_PATTERNS, FormatValidator, MAX_REGEX_PATTERN_LENGTH, dateInputType, validateFormat };

package/dist/core/formats.mjs

@@ -9,8 +9,40 @@ import { emitDiagnostic } from "./diagnostics.mjs";
 */
 const MAX_REGEX_PATTERN_LENGTH = 500;
 /**
+* Map a JSON Schema string `format` to the matching HTML `<input type="…">`
+* value, or `undefined` when the format does not correspond to a date/time
+* input. Shared by the HTML and headless React renderers so a single
+* mapping table governs both pipelines.
+*/
+function dateInputType(format) {
+	if (format === "date") return "date";
+	if (format === "time") return "time";
+	if (format === "date-time" || format === "datetime") return "datetime-local";
+}
+/**
 * Recognised JSON Schema formats with their validation patterns.
 * Unknown formats emit an `unknown-format` diagnostic and skip derivation.
+*
+* Draft origin reference — formats first standardised by each draft:
+*
+* - Draft 04: `date-time`, `email`, `hostname`, `ipv4`, `ipv6`, `uri`
+* - Draft 06: `uri-reference`, `uri-template`, `json-pointer`
+* - Draft 07: `date`, `time`, `idn-email`, `idn-hostname`, `iri`,
+*   `iri-reference`, `regex`, `relative-json-pointer`
+* - Draft 2019-09: `duration`, `uuid`
+* - Vocabulary extensions / non-standard: `binary` (OpenAPI), and the
+*   Zod-emitted formats `cuid`, `cuid2`, `nanoid`, `cidrv4`, `cidrv6`,
+*   `base64`, `base64url`, `e164`, `emoji`, `ulid`, `xid`, `ksuid`,
+*   `lowercase`, `uppercase`, `jwt`, `json-string`
+*
+* Policy: schema-components accepts ALL formats in ALL drafts. We do
+* not reject (e.g.) `uri-reference` on a Draft 04 schema or `uuid` on
+* a Draft 06 schema, even though the spec did not standardise those
+* names until a later draft. This matches the behaviour of every
+* mainstream JSON Schema validator (Ajv, jsonschema, etc.) and avoids
+* spurious failures on legitimate real-world schemas that pre-date or
+* post-date the dialect they declare. Authors who want strict draft-
+* locked behaviour should validate with a dedicated meta-schema tool.
 */
 /**
 * Email format pattern, exported as a named const so callers that need a
@@ -156,4 +188,4 @@ function validateFormat(value, format, diagnostics, pointer = "") {
 	if (predicate !== void 0) return predicate(value);
 }
 //#endregion
-export { EMAIL_FORMAT_PATTERN, FORMAT_PATTERNS, MAX_REGEX_PATTERN_LENGTH, validateFormat };
+export { EMAIL_FORMAT_PATTERN, FORMAT_PATTERNS, MAX_REGEX_PATTERN_LENGTH, dateInputType, validateFormat };

package/dist/core/idPath.d.mts

@@ -0,0 +1,54 @@
+//#region src/core/idPath.d.ts
+/**
+ * Canonical DOM-id generation from structural paths.
+ *
+ * Every render pipeline (React headless, HTML sync, HTML stream) needs to
+ * derive stable DOM ids from the same path so `aria-controls`, `aria-labelledby`,
+ * and `htmlFor` references resolve consistently across pipelines.
+ *
+ * Previously each pipeline carried its own copy with subtly different
+ * normalisation (raw path in one place, dot/bracket-collapsed in another,
+ * whitelist-collapsed in a third). The streaming renderer's tab panel ids
+ * silently diverged from the sync renderer's because of that drift.
+ *
+ * Pipelines should import the helpers below rather than re-deriving them.
+ */
+/**
+ * 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.
+ *
+ * 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.
+ */
+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,
+ * 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.
+ */
+declare function fieldDomId(path: string): string;
+/**
+ * Derive the constraint-hint element id for a given field id.
+ * The hint element is wired to inputs via `aria-describedby`.
+ */
+declare function hintIdFor(fieldId: string): string;
+/**
+ * Derive the tab panel id for a discriminated-union container at `path`.
+ * Used by every renderer that emits a WAI-ARIA tabs widget so that the
+ * `aria-controls` on each tab and the `id` on the matching panel match.
+ */
+declare function panelIdFor(path: string): string;
+/**
+ * Derive the id for tab `i` within a discriminated-union container at `path`.
+ * Used to pair `aria-labelledby` on the active panel with the active tab's
+ * `id` across all renderers.
+ */
+declare function tabIdFor(path: string, index: number): string;
+//#endregion
+export { fieldDomId, hintIdFor, normaliseIdSegment, panelIdFor, tabIdFor };

package/dist/core/idPath.mjs

@@ -0,0 +1,66 @@
+import "./cssClasses.mjs";
+//#region src/core/idPath.ts
+/**
+* Canonical DOM-id generation from structural paths.
+*
+* Every render pipeline (React headless, HTML sync, HTML stream) needs to
+* derive stable DOM ids from the same path so `aria-controls`, `aria-labelledby`,
+* and `htmlFor` references resolve consistently across pipelines.
+*
+* Previously each pipeline carried its own copy with subtly different
+* normalisation (raw path in one place, dot/bracket-collapsed in another,
+* whitelist-collapsed in a third). The streaming renderer's tab panel ids
+* silently diverged from the sync renderer's because of that drift.
+*
+* Pipelines should import the helpers below rather than re-deriving them.
+*/
+/**
+* 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.
+*
+* 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.
+*/
+function normaliseIdSegment(value) {
+	return value.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/-+$/g, "");
+}
+/**
+* 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.
+*/
+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().");
+	return `sc-${normaliseIdSegment(path)}`;
+}
+/**
+* Derive the constraint-hint element id for a given field id.
+* The hint element is wired to inputs via `aria-describedby`.
+*/
+function hintIdFor(fieldId) {
+	return `${fieldId}-hint`;
+}
+/**
+* Derive the tab panel id for a discriminated-union container at `path`.
+* Used by every renderer that emits a WAI-ARIA tabs widget so that the
+* `aria-controls` on each tab and the `id` on the matching panel match.
+*/
+function panelIdFor(path) {
+	return `${fieldDomId(path)}-panel`;
+}
+/**
+* Derive the id for tab `i` within a discriminated-union container at `path`.
+* Used to pair `aria-labelledby` on the active panel with the active tab's
+* `id` across all renderers.
+*/
+function tabIdFor(path, index) {
+	return `${fieldDomId(path)}-tab-${String(index)}`;
+}
+//#endregion
+export { fieldDomId, hintIdFor, normaliseIdSegment, panelIdFor, tabIdFor };

package/dist/core/limits.d.mts

@@ -0,0 +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-Cw5QZND8.mjs";
+export { MAX_PATH_ITEM_REF_HOPS, MAX_REF_DEPTH, MAX_RENDER_DEPTH, MaxRefDepth };

package/dist/core/limits.mjs

@@ -0,0 +1,23 @@
+//#region src/core/limits.ts
+/**
+* Shared depth caps and hop counts used to bound recursion across
+* schema-components. All numeric limits live here so the renderer, the
+* ref resolver, the OpenAPI parser, and the type-level inference engine
+* agree on the same constants.
+*/
+/**
+* Maximum recursion depth for the schema walker, the React renderers,
+* the streaming HTML renderer, and the server-side renderer. Beyond
+* this depth a recursion sentinel is emitted instead of further descent
+* — the only safe response to a cyclic walked-field graph.
+*/
+const MAX_RENDER_DEPTH = 10;
+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.
+*/
+const MAX_PATH_ITEM_REF_HOPS = 8;
+//#endregion
+export { MAX_PATH_ITEM_REF_HOPS, MAX_REF_DEPTH, MAX_RENDER_DEPTH };

package/dist/core/merge.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
 
 //#region src/core/merge.d.ts
 /**
@@ -32,6 +32,15 @@ declare function mergeRefSiblings(referencer: Record<string, unknown>, resolvedM
  * - \`true\` is the always-valid schema and contributes no constraints —
  *   skip silently.
  *
+ * Type compatibility is enforced rather than papered over: two
+ * branches asserting incompatible primitive `type` keywords
+ * (e.g. `string` ∩ `number`) describe an unsatisfiable conjunction.
+ * `mergeAllOf` returns `false` and emits
+ * `schema-allof-incompatible` so the walker produces the same
+ * `NeverField` shape it gives a top-level `false` schema. Pretending
+ * the first type wins silently would silently weaken the constraint
+ * for any consumer that reads the merged result.
+ *
  * Non-boolean, non-object entries (e.g. arrays, numbers) are malformed
  * inputs that cannot represent a schema; skip them as before.
  */

package/dist/core/merge.mjs

@@ -116,6 +116,15 @@ function mergeRefSiblings(referencer, resolvedMeta) {
 * - \`true\` is the always-valid schema and contributes no constraints —
 *   skip silently.
 *
+* Type compatibility is enforced rather than papered over: two
+* branches asserting incompatible primitive `type` keywords
+* (e.g. `string` ∩ `number`) describe an unsatisfiable conjunction.
+* `mergeAllOf` returns `false` and emits
+* `schema-allof-incompatible` so the walker produces the same
+* `NeverField` shape it gives a top-level `false` schema. Pretending
+* the first type wins silently would silently weaken the constraint
+* for any consumer that reads the merged result.
+*
 * Non-boolean, non-object entries (e.g. arrays, numbers) are malformed
 * inputs that cannot represent a schema; skip them as before.
 */
@@ -150,16 +159,15 @@ function mergeAllOf(schemas, diagnostics, pointer = "") {
 		const entryType = getString(entry, "type");
 		if (entryType !== void 0) {
 			if (!("type" in merged)) merged.type = entryType;
-			else if (!deepEqual(merged.type, entryType)) emitDiagnostic(diagnostics, {
-				code: "allof-conflict",
-				message: `allOf branches define conflicting values for "type"; keeping the first occurrence and discarding subsequent values`,
-				pointer,
-				detail: {
-					key: "type",
-					kept: merged.type,
-					discarded: entryType
-				}
-			});
+			else if (!areCompatibleTypes(merged.type, entryType)) {
+				emitDiagnostic(diagnostics, {
+					code: "schema-allof-incompatible",
+					message: `allOf branches assert incompatible \`type\` keywords (${describeType(merged.type)} ∩ ${describeType(entryType)}); the conjunction is unsatisfiable`,
+					pointer,
+					detail: { types: [merged.type, entryType] }
+				});
+				return false;
+			}
 		}
 	}
 	if (Object.keys(properties).length > 0) merged.properties = properties;
@@ -167,6 +175,37 @@ function mergeAllOf(schemas, diagnostics, pointer = "") {
 	return merged;
 }
 /**
+* Two `type` keyword values are compatible when their intersection is
+* non-empty. Identical strings always agree; `"integer"` is a subset
+* of `"number"` per JSON Schema 2020-12 §6.1.1 so the conjunction
+* collapses to `"integer"` and is treated as compatible here.
+* Mismatched primitives (`"string"` ∩ `"number"`, `"boolean"` ∩
+* `"object"`, etc.) describe an unsatisfiable intersection.
+*
+* `kept` carries the running merged value, which may already be an
+* array form produced by an earlier merge — in that case we conservatively
+* require deep equality to count as compatible, since narrowing the
+* intersection of two arbitrary type-array sets is out of scope here.
+*/
+function areCompatibleTypes(kept, incoming) {
+	if (typeof kept === "string") {
+		if (kept === incoming) return true;
+		if (kept === "integer" && incoming === "number" || kept === "number" && incoming === "integer") return true;
+		return false;
+	}
+	return deepEqual(kept, incoming);
+}
+/**
+* Human-readable label for a `type` keyword value used in the
+* `schema-allof-incompatible` diagnostic message. Strings render
+* quoted; non-strings (array forms, malformed values) render via
+* `JSON.stringify` so the message still carries useful context.
+*/
+function describeType(value) {
+	if (typeof value === "string") return `"${value}"`;
+	return JSON.stringify(value);
+}
+/**
 * Detect `anyOf: [T, { type: "null" }]` → nullable T.
 * Returns the non-null schema and a nullable flag.
 */

package/dist/core/normalise.d.mts

@@ -1,5 +1,5 @@
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
-import { i as OpenApiVersionInfo, r as JsonSchemaDraft } from "../version-D-u7aMfy.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
+import { i as OpenApiVersionInfo, r as JsonSchemaDraft } from "../version-BFTVLsdb.mjs";
 
 //#region src/core/normalise.d.ts
 type NodeTransform = (node: Record<string, unknown>) => Record<string, unknown>;
@@ -20,10 +20,28 @@ declare function deepNormalise(schema: Record<string, unknown>, transform: NodeT
  * Carries the diagnostics sink and the JSON Pointer to the current
  * node so per-node transforms can emit pointer-accurate diagnostics
  * when they translate or reject legacy constructs.
+ *
+ * `documentHasDynamicAnchor` is set once at the entry point by scanning
+ * the input for any `$dynamicAnchor`/`$recursiveAnchor` keyword. Per-
+ * node transforms read it to decide whether a `$dynamicRef`/`$recursiveRef`
+ * rewrite needs a `dynamic-ref-degraded` diagnostic — a ref pointing at
+ * an anchor in the document body cannot be statically resolved without
+ * losing dynamic-scope semantics, while a document with no dynamic
+ * anchors at all has no semantics to lose.
+ *
+ * `documentHasRecursiveAnchor` is the same idea for Draft 2019-09's
+ * `$recursiveAnchor` keyword.
+ *
+ * `declaredDraft` carries the draft the normaliser is operating under
+ * (when known) so per-node transforms can emit `keyword-out-of-draft`
+ * diagnostics for keywords introduced in a later draft.
  */
 interface NodeContext {
   diagnostics: DiagnosticsOptions | undefined;
   pointer: string;
+  documentHasDynamicAnchor: boolean;
+  documentHasRecursiveAnchor: boolean;
+  declaredDraft: JsonSchemaDraft | undefined;
 }
 type NodeTransformWithContext = (node: Record<string, unknown>, ctx: NodeContext) => Record<string, unknown>;
 /**
@@ -58,6 +76,25 @@ declare function deepNormaliseWithContext(schema: Record<string, unknown>, trans
  * {@link deepNormaliseWithContext} to thread diagnostics.
  */
 declare function normaliseDraft04Node(node: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Pick the per-node transform that normalises a single Schema Object to
+ * canonical Draft 2020-12 form for the supplied draft. Exposed so the
+ * OpenAPI 3.1 path can honour a non-default `jsonSchemaDialect`
+ * declaration by routing each Schema Object through the matching
+ * transform without re-implementing the dispatch.
+ */
+declare function selectDraftTransform(draft: JsonSchemaDraft): NodeTransformWithContext;
+/**
+ * Scan a JSON document body for the presence of a named keyword
+ * anywhere in the structure. Walks both arrays and objects without
+ * regard to schema-vs-data position — the caller is responsible for
+ * passing a keyword whose presence is meaningful at any depth.
+ *
+ * Cycle-safe: cyclic references introduced by the OpenAPI bundler's
+ * `structuredClone` of external refs are short-circuited via the
+ * `visited` set so the scan terminates.
+ */
+declare function documentContainsKeyword(value: unknown, keyword: string, visited?: WeakSet<object>): boolean;
 /**
  * Normalise a JSON Schema to canonical Draft 2020-12 form.
  * Deep-clones the input — the original is never mutated.
@@ -77,4 +114,4 @@ declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: Jso
  */
 declare function normaliseOpenApiSchemas(doc: Record<string, unknown>, version: OpenApiVersionInfo, diagnostics?: DiagnosticsOptions): Record<string, unknown>;
 //#endregion
-export { NodeContext, NodeTransform, NodeTransformWithContext, deepNormalise, deepNormaliseWithContext, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };
+export { NodeContext, NodeTransform, NodeTransformWithContext, deepNormalise, deepNormaliseWithContext, documentContainsKeyword, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas, selectDraftTransform };

package/dist/core/normalise.mjs

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

package/dist/core/openapi30.d.mts

@@ -1,6 +1,20 @@
 import { NodeTransform } from "./normalise.mjs";
 
 //#region src/core/openapi30.d.ts
+/**
+ * Lift OpenAPI 3.x singular `example` onto the plural `examples` key.
+ *
+ * Two output shapes are spec-correct depending on the parent object type:
+ *   - `"array"` — Schema Object: `examples: [example]` (Draft 2020-12 plural).
+ *   - `"map"`   — Parameter / Header / Media Type Object: an Examples Map
+ *                 keyed by name. The single value is wrapped under the
+ *                 synthetic key `default` to produce a valid one-entry map
+ *                 of one Example Object.
+ *
+ * When both `example` and `examples` coexist the spec declares them mutually
+ * exclusive — `example` is dropped and `examples` wins.
+ */
+declare function liftExampleToExamples(node: Record<string, unknown>, shape: "array" | "map"): void;
 /**
  * Normalise OpenAPI 3.0.x `nullable` keyword to `anyOf [T, null]`.
  *
@@ -90,4 +104,4 @@ declare function deepNormaliseOpenApiDoc(doc: Record<string, unknown>, normalise
  */
 declare function deepNormaliseOpenApi30Doc(doc: Record<string, unknown>, deepNormalise: (schema: Record<string, unknown>, transform: NodeTransform) => Record<string, unknown>): Record<string, unknown>;
 //#endregion
-export { applyDiscriminatorAllOfPrepass, deepNormaliseOpenApi30Doc, deepNormaliseOpenApiDoc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };
+export { applyDiscriminatorAllOfPrepass, deepNormaliseOpenApi30Doc, deepNormaliseOpenApiDoc, liftExampleToExamples, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };

package/dist/core/openapi30.mjs

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