@formspec/core 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/core.d.ts

@@ -0,0 +1,1459 @@
+/**
+ * `@formspec/core` - Core type definitions for FormSpec
+ *
+ * This package provides the foundational types used throughout the FormSpec ecosystem:
+ * - Form element types (fields, groups, conditionals)
+ * - Field and form state types
+ * - Data source registry for dynamic enums
+ * - Canonical IR types (FormIR, FieldNode, TypeNode, ConstraintNode, AnnotationNode, etc.)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Discriminated union of all annotation types.
+ * Annotations are value-influencing: they describe or present a field
+ * but do not affect which values are valid.
+ *
+ * @public
+ */
+export declare type AnnotationNode = DisplayNameAnnotationNode | DescriptionAnnotationNode | RemarksAnnotationNode | FormatAnnotationNode | PlaceholderAnnotationNode | DefaultValueAnnotationNode | DeprecatedAnnotationNode | FormatHintAnnotationNode | CustomAnnotationNode;
+
+/**
+ * Union of all field types.
+ *
+ * @public
+ */
+export declare type AnyField = TextField<string> | NumberField<string> | BooleanField<string> | StaticEnumField<string, readonly EnumOptionValue[]> | DynamicEnumField<string, string> | DynamicSchemaField<string> | ArrayField<string, readonly FormElement[]> | ObjectField<string, readonly FormElement[]>;
+
+/**
+ * Array uniqueness constraint.
+ *
+ * @public
+ */
+export declare interface ArrayCardinalityConstraintNode {
+    readonly kind: "constraint";
+    readonly constraintKind: "uniqueItems";
+    readonly value: true;
+    readonly path?: PathTarget;
+    readonly provenance: Provenance;
+}
+
+/**
+ * An array field containing repeating items.
+ *
+ * Use this for lists of values (e.g., multiple addresses, line items).
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Items - The form elements that define each array item
+ *
+ * @public
+ */
+export declare interface ArrayField<N extends string, Items extends readonly FormElement[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an array field */
+    readonly _field: "array";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Form elements that define the schema for each array item */
+    readonly items: Items;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Minimum number of items required */
+    readonly minItems?: number;
+    /** Maximum number of items allowed */
+    readonly maxItems?: number;
+}
+
+/**
+ * Array type with a single items type.
+ *
+ * @public
+ */
+export declare interface ArrayTypeNode {
+    readonly kind: "array";
+    readonly items: TypeNode;
+}
+
+/**
+ * A boolean checkbox field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface BooleanField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a boolean field */
+    readonly _field: "boolean";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
+
+/**
+ * Built-in constraint names mapped to their expected value type for parsing.
+ * Constraints are surface-agnostic — they manifest as both TSDoc tags
+ * (e.g., `@minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).
+ *
+ * Keys use camelCase matching JSON Schema property names.
+ *
+ * @public
+ */
+export declare const BUILTIN_CONSTRAINT_DEFINITIONS: {
+    readonly minimum: "number";
+    readonly maximum: "number";
+    readonly exclusiveMinimum: "number";
+    readonly exclusiveMaximum: "number";
+    readonly multipleOf: "number";
+    readonly minLength: "number";
+    readonly maxLength: "number";
+    readonly minItems: "number";
+    readonly maxItems: "number";
+    readonly uniqueItems: "boolean";
+    readonly pattern: "string";
+    readonly const: "json";
+    readonly enumOptions: "json";
+};
+
+/**
+ * Registration for mapping a built-in TSDoc tag onto a custom constraint when
+ * it is used on a particular custom type.
+ *
+ * @public
+ */
+export declare interface BuiltinConstraintBroadeningRegistration {
+    /** The built-in tag being broadened, without the `@` prefix. */
+    readonly tagName: BuiltinConstraintName;
+    /** The custom constraint to emit for this built-in tag. */
+    readonly constraintName: string;
+    /** Parser from raw TSDoc text to extension payload. */
+    readonly parseValue: (raw: string) => JsonValue;
+}
+
+/**
+ * Type of a built-in constraint name.
+ *
+ * @public
+ */
+export declare type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;
+
+/**
+ * A conditional wrapper that shows/hides elements based on another field's value.
+ *
+ * @typeParam FieldName - The field to check
+ * @typeParam Value - The value that triggers the condition
+ * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
+ */
+export declare interface Conditional<FieldName extends string, Value, Elements extends readonly FormElement[]> {
+    /** Type discriminator - identifies this as a conditional element */
+    readonly _type: "conditional";
+    /** Name of the field whose value determines visibility */
+    readonly field: FieldName;
+    /** Value that triggers the condition (shows nested elements) */
+    readonly value: Value;
+    /** Form elements shown when condition is met */
+    readonly elements: Elements;
+}
+
+/**
+ * Conditional visibility based on another field's value.
+ *
+ * @public
+ */
+export declare interface ConditionalLayoutNode {
+    readonly kind: "conditional";
+    /** The field whose value triggers visibility. */
+    readonly fieldName: string;
+    /** The value that makes the condition true (SHOW). */
+    readonly value: JsonValue;
+    /** Elements shown when the condition is met. */
+    readonly elements: readonly FormIRElement[];
+    readonly provenance: Provenance;
+}
+
+/**
+ * Literal-value equality constraint.
+ *
+ * @public
+ */
+export declare interface ConstConstraintNode {
+    readonly kind: "constraint";
+    readonly constraintKind: "const";
+    readonly value: JsonValue;
+    readonly path?: PathTarget;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Discriminated union of all constraint types.
+ * Constraints are set-influencing: they narrow the set of valid values.
+ *
+ * @public
+ */
+export declare type ConstraintNode = NumericConstraintNode | LengthConstraintNode | PatternConstraintNode | ArrayCardinalityConstraintNode | EnumMemberConstraintNode | ConstConstraintNode | CustomConstraintNode;
+
+/**
+ * Semantic metadata for ordered custom constraints that should participate in
+ * the generic contradiction/broadening logic.
+ *
+ * @public
+ */
+export declare interface ConstraintSemanticRole {
+    /**
+     * Logical family identifier shared by related constraints, for example
+     * `"decimal-bound"` or `"date-bound"`.
+     */
+    readonly family: string;
+    /** Whether this constraint acts as a lower or upper bound. */
+    readonly bound: "lower" | "upper" | "exact";
+    /** Whether equality is allowed when comparing against the bound. */
+    readonly inclusive: boolean;
+}
+
+/**
+ * Declarative authoring-side registration for a custom TSDoc constraint tag.
+ *
+ * @public
+ */
+export declare interface ConstraintTagRegistration {
+    /** Tag name without the `@` prefix, e.g. `"maxSigFig"`. */
+    readonly tagName: string;
+    /** The custom constraint that this tag should produce. */
+    readonly constraintName: string;
+    /** Parser from raw TSDoc text to JSON-serializable payload. */
+    readonly parseValue: (raw: string) => JsonValue;
+    /**
+     * Optional precise applicability predicate for the field type being parsed.
+     * When omitted, the target custom constraint registration controls type
+     * applicability during validation.
+     */
+    readonly isApplicableToType?: (type: TypeNode) => boolean;
+}
+
+/**
+ * Creates initial field state with default values.
+ *
+ * @typeParam T - The value type of the field
+ * @param value - The initial value for the field
+ * @returns Initial field state
+ *
+ * @public
+ */
+export declare function createInitialFieldState<T>(value: T): FieldState<T>;
+
+/**
+ * Extension-registered custom annotation.
+ *
+ * @public
+ */
+export declare interface CustomAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "custom";
+    /** Extension-qualified ID: `"<vendor-prefix>/<extension-name>/<annotation-name>"` */
+    readonly annotationId: string;
+    readonly value: JsonValue;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Registration for a custom annotation that may produce JSON Schema keywords.
+ *
+ * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.
+ * They describe or present a field but do not affect which values are valid.
+ *
+ * @public
+ */
+export declare interface CustomAnnotationRegistration {
+    /** The annotation name, unique within the extension. */
+    readonly annotationName: string;
+    /**
+     * Optionally converts the annotation value into JSON Schema keywords.
+     * If omitted, the annotation has no JSON Schema representation (UI-only).
+     */
+    readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;
+}
+
+/**
+ * Extension-registered custom constraint.
+ *
+ * @public
+ */
+export declare interface CustomConstraintNode {
+    readonly kind: "constraint";
+    readonly constraintKind: "custom";
+    /** Extension-qualified ID: `"<vendor-prefix>/<extension-name>/<constraint-name>"` */
+    readonly constraintId: string;
+    /** JSON-serializable payload defined by the extension. */
+    readonly payload: JsonValue;
+    /** How this constraint composes with others of the same `constraintId`. */
+    readonly compositionRule: "intersect" | "override";
+    readonly path?: PathTarget;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Registration for a custom constraint that maps to JSON Schema keywords.
+ *
+ * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.
+ *
+ * @public
+ */
+export declare interface CustomConstraintRegistration {
+    /** The constraint name, unique within the extension. */
+    readonly constraintName: string;
+    /**
+     * How this constraint composes with other constraints of the same kind.
+     * - "intersect": combine with logical AND (both must hold)
+     * - "override": last writer wins
+     */
+    readonly compositionRule: "intersect" | "override";
+    /**
+     * TypeNode kinds this constraint is applicable to, or `null` for any type.
+     * Used by the validator to emit TYPE_MISMATCH diagnostics.
+     */
+    readonly applicableTypes: readonly TypeNode["kind"][] | null;
+    /**
+     * Optional precise type predicate used when kind-level applicability is too
+     * broad (for example, constraints that apply to integer-like primitives but
+     * not strings).
+     */
+    readonly isApplicableToType?: (type: TypeNode) => boolean;
+    /**
+     * Optional comparator for payloads belonging to the same custom constraint.
+     * Return values follow the `Array.prototype.sort()` contract.
+     */
+    readonly comparePayloads?: (left: JsonValue, right: JsonValue) => number;
+    /**
+     * Optional semantic family metadata for generic contradiction/broadening
+     * handling across ordered constraints.
+     */
+    readonly semanticRole?: ConstraintSemanticRole;
+    /**
+     * Converts the custom constraint's payload into JSON Schema keywords.
+     *
+     * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.
+     * @param vendorPrefix - The vendor prefix for extension keywords.
+     * @returns A JSON Schema fragment with the constraint keywords.
+     */
+    readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;
+}
+
+/**
+ * Custom type registered by an extension.
+ *
+ * @public
+ */
+export declare interface CustomTypeNode {
+    readonly kind: "custom";
+    /**
+     * The extension-qualified type identifier.
+     * Format: `"<vendor-prefix>/<extension-name>/<type-name>"`
+     * e.g., `"x-stripe/monetary/MonetaryAmount"`
+     */
+    readonly typeId: string;
+    /**
+     * Opaque payload serialized by the extension that registered this type.
+     * Must be JSON-serializable.
+     */
+    readonly payload: JsonValue;
+}
+
+/**
+ * Registration for a custom type that maps to a JSON Schema representation.
+ *
+ * Custom types are referenced via {@link CustomTypeNode} in the IR and
+ * resolved to JSON Schema via `toJsonSchema` during generation.
+ *
+ * @public
+ */
+export declare interface CustomTypeRegistration {
+    /** The type name, unique within the extension. */
+    readonly typeName: string;
+    /**
+     * Optional TypeScript surface names that should resolve to this custom type
+     * during TSDoc/class analysis. Defaults to `typeName` when omitted.
+     */
+    readonly tsTypeNames?: readonly string[];
+    /**
+     * Converts the custom type's payload into a JSON Schema fragment.
+     *
+     * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.
+     * @param vendorPrefix - The vendor prefix for extension keywords (e.g., "x-stripe").
+     * @returns A JSON Schema fragment representing this type.
+     */
+    readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;
+    /**
+     * Optional broadening of built-in constraint tags so they can apply to this
+     * custom type without modifying the core built-in constraint tables.
+     */
+    readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration[];
+}
+
+/**
+ * A single option returned by a data source resolver.
+ *
+ * @typeParam T - The data type for additional option metadata
+ *
+ * @public
+ */
+export declare interface DataSourceOption<T = unknown> {
+    /** The value stored when this option is selected */
+    readonly value: string;
+    /** The display label for this option */
+    readonly label: string;
+    /** Optional additional data associated with this option */
+    readonly data?: T;
+}
+
+/**
+ * Registry for dynamic data sources.
+ *
+ * Extend this interface via module augmentation to register your data sources:
+ *
+ * @example
+ * ```typescript
+ * declare module "@formspec/core" {
+ *   interface DataSourceRegistry {
+ *     countries: { id: string; code: string; name: string };
+ *     templates: { id: string; name: string; category: string };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface DataSourceRegistry {
+}
+
+/**
+ * Gets the value type for a registered data source.
+ *
+ * If the source has an `id` property, that becomes the value type.
+ * Otherwise, defaults to `string`.
+ *
+ * @public
+ */
+export declare type DataSourceValueType<Source extends string> = Source extends keyof DataSourceRegistry ? DataSourceRegistry[Source] extends {
+    id: infer ID;
+} ? ID : string : string;
+
+/**
+ * Default-value annotation.
+ *
+ * @public
+ */
+export declare interface DefaultValueAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "defaultValue";
+    /** Must be JSON-serializable and type-compatible (verified during Validate phase). */
+    readonly value: JsonValue;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Defines a custom annotation registration. Currently an identity function
+ * that provides type-checking and IDE autocompletion.
+ *
+ * @param reg - The custom annotation registration.
+ * @returns The same registration, validated at the type level.
+ *
+ * @public
+ */
+export declare function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration;
+
+/**
+ * Defines a custom constraint registration. Currently an identity function
+ * that provides type-checking and IDE autocompletion.
+ *
+ * @param reg - The custom constraint registration.
+ * @returns The same registration, validated at the type level.
+ *
+ * @public
+ */
+export declare function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration;
+
+/**
+ * Defines a custom TSDoc constraint tag registration.
+ *
+ * @param reg - The custom tag registration.
+ * @returns The same registration, validated at the type level.
+ *
+ * @public
+ */
+export declare function defineConstraintTag(reg: ConstraintTagRegistration): ConstraintTagRegistration;
+
+/**
+ * Defines a custom type registration. Currently an identity function that
+ * provides type-checking and IDE autocompletion.
+ *
+ * @param reg - The custom type registration.
+ * @returns The same registration, validated at the type level.
+ *
+ * @public
+ */
+export declare function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration;
+
+/**
+ * Defines a complete extension. Currently an identity function that provides
+ * type-checking and IDE autocompletion for the definition shape.
+ *
+ * @param def - The extension definition.
+ * @returns The same definition, validated at the type level.
+ *
+ * @public
+ */
+export declare function defineExtension(def: ExtensionDefinition): ExtensionDefinition;
+
+/**
+ * Deprecated annotation.
+ *
+ * @public
+ */
+export declare interface DeprecatedAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "deprecated";
+    /** Optional deprecation message. */
+    readonly message?: string;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Description annotation.
+ *
+ * @public
+ */
+export declare interface DescriptionAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "description";
+    readonly value: string;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Display-name annotation.
+ *
+ * @public
+ */
+export declare interface DisplayNameAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "displayName";
+    readonly value: string;
+    readonly provenance: Provenance;
+}
+
+/**
+ * A field with dynamic enum options (fetched from a data source at runtime).
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Source - The data source key (from DataSourceRegistry)
+ *
+ * @public
+ */
+export declare interface DynamicEnumField<N extends string, Source extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a dynamic enum field */
+    readonly _field: "dynamic_enum";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Data source key for fetching options at runtime */
+    readonly source: Source;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Field names whose values are needed to fetch options */
+    readonly params?: readonly string[];
+}
+
+/**
+ * A field that loads its schema dynamically (e.g., from an extension).
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface DynamicSchemaField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a dynamic schema field */
+    readonly _field: "dynamic_schema";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Identifier for the schema source */
+    readonly schemaSource: string;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Field names whose values are needed to configure the schema */
+    readonly params?: readonly string[];
+}
+
+/**
+ * Dynamic type whose schema is resolved at runtime from a named data source.
+ *
+ * @public
+ */
+export declare interface DynamicTypeNode {
+    readonly kind: "dynamic";
+    readonly dynamicKind: "enum" | "schema";
+    /** Key identifying the runtime data source or schema provider. */
+    readonly sourceKey: string;
+    /**
+     * For dynamic enums: field names whose current values are passed as
+     * parameters to the data source resolver.
+     */
+    readonly parameterFields: readonly string[];
+}
+
+/**
+ * A member of a static enum type.
+ *
+ * @public
+ */
+export declare interface EnumMember {
+    /** The serialized value stored in data. */
+    readonly value: string | number;
+    /** Optional per-member display name. */
+    readonly displayName?: string;
+}
+
+/**
+ * Enum member subset constraint that only narrows the allowed member set.
+ *
+ * @public
+ */
+export declare interface EnumMemberConstraintNode {
+    readonly kind: "constraint";
+    readonly constraintKind: "allowedMembers";
+    readonly members: readonly (string | number)[];
+    readonly path?: PathTarget;
+    readonly provenance: Provenance;
+}
+
+/**
+ * An enum option with a separate ID and display label.
+ *
+ * Use this when the stored value (id) should differ from the display text (label).
+ *
+ * @public
+ */
+export declare interface EnumOption {
+    readonly id: string;
+    readonly label: string;
+}
+
+/**
+ * Valid enum option types: either plain strings or objects with id/label.
+ *
+ * @public
+ */
+export declare type EnumOptionValue = string | EnumOption;
+
+/**
+ * Static enum type with members known at build time.
+ *
+ * @public
+ */
+export declare interface EnumTypeNode {
+    readonly kind: "enum";
+    readonly members: readonly EnumMember[];
+}
+
+/**
+ * Predicate types for conditional logic.
+ *
+ * Predicates are used with `when()` to define conditions in a readable way.
+ */
+/**
+ * An equality predicate that checks if a field equals a specific value.
+ *
+ * @typeParam K - The field name to check
+ * @typeParam V - The value to compare against
+ *
+ * @public
+ */
+export declare interface EqualsPredicate<K extends string, V> {
+    /** Predicate type discriminator */
+    readonly _predicate: "equals";
+    /** Name of the field to check */
+    readonly field: K;
+    /** Value that the field must equal */
+    readonly value: V;
+}
+
+/**
+ * A complete extension definition bundling types, constraints, annotations,
+ * and vocabulary keywords.
+ *
+ * @example
+ * ```typescript
+ * const monetaryExtension = defineExtension({
+ *   extensionId: "x-stripe/monetary",
+ *   types: [
+ *     defineCustomType({
+ *       typeName: "Decimal",
+ *       toJsonSchema: (_payload, prefix) => ({
+ *         type: "string",
+ *         [`${prefix}-decimal`]: true,
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare interface ExtensionDefinition {
+    /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
+    readonly extensionId: string;
+    /** Custom type registrations provided by this extension. */
+    readonly types?: readonly CustomTypeRegistration[];
+    /** Custom constraint registrations provided by this extension. */
+    readonly constraints?: readonly CustomConstraintRegistration[];
+    /** Authoring-side TSDoc tag registrations provided by this extension. */
+    readonly constraintTags?: readonly ConstraintTagRegistration[];
+    /** Custom annotation registrations provided by this extension. */
+    readonly annotations?: readonly CustomAnnotationRegistration[];
+    /** Vocabulary keyword registrations provided by this extension. */
+    readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];
+}
+
+/**
+ * Response from a data source resolver function.
+ *
+ * @typeParam T - The data type for option metadata
+ *
+ * @public
+ */
+export declare interface FetchOptionsResponse<T = unknown> {
+    /** The available options */
+    readonly options: readonly DataSourceOption<T>[];
+    /** Validity state of the fetch operation */
+    readonly validity: "valid" | "invalid" | "unknown";
+    /** Optional message (e.g., error description) */
+    readonly message?: string;
+}
+
+/**
+ * A single form field after canonicalization.
+ *
+ * @public
+ */
+export declare interface FieldNode {
+    readonly kind: "field";
+    /** The field's key in the data schema. */
+    readonly name: string;
+    /** The resolved type of this field. */
+    readonly type: TypeNode;
+    /** Whether this field is required in the data schema. */
+    readonly required: boolean;
+    /** Set-influencing constraints, after merging. */
+    readonly constraints: readonly ConstraintNode[];
+    /** Value-influencing annotations, after merging. */
+    readonly annotations: readonly AnnotationNode[];
+    /** Where this field was declared. */
+    readonly provenance: Provenance;
+    /**
+     * Debug only — ordered list of constraint/annotation nodes that participated
+     * in merging, including dominated ones.
+     */
+    readonly mergeHistory?: readonly {
+        readonly node: ConstraintNode | AnnotationNode;
+        readonly dominated: boolean;
+    }[];
+}
+
+/**
+ * Represents the runtime state of a single form field.
+ *
+ * @typeParam T - The value type of the field
+ *
+ * @public
+ */
+export declare interface FieldState<T> {
+    /** Current value of the field */
+    readonly value: T;
+    /** Whether the field has been modified by the user */
+    readonly dirty: boolean;
+    /** Whether the field has been focused and blurred */
+    readonly touched: boolean;
+    /** Current validity state */
+    readonly validity: Validity;
+    /** Validation error messages, if any */
+    readonly errors: readonly string[];
+}
+
+/**
+ * Schema format annotation, for example `email`, `date`, or `uri`.
+ *
+ * @public
+ */
+export declare interface FormatAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "format";
+    readonly value: string;
+    readonly provenance: Provenance;
+}
+
+/**
+ * UI rendering hint — does not affect schema validation.
+ * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.
+ *
+ * @public
+ */
+export declare interface FormatHintAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "formatHint";
+    /** Renderer-specific format identifier: "textarea", "radio", "date", "color", etc. */
+    readonly format: string;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Union of all form element types (fields and structural elements).
+ *
+ * @public
+ */
+export declare type FormElement = AnyField | Group<readonly FormElement[]> | Conditional<string, unknown, readonly FormElement[]>;
+
+/**
+ * The complete Canonical Intermediate Representation for a form.
+ *
+ * Output of the Canonicalize phase; input to Validate, Generate (JSON Schema),
+ * and Generate (UI Schema) phases.
+ *
+ * Serializable to JSON — no live compiler objects.
+ *
+ * @public
+ */
+export declare interface FormIR {
+    readonly kind: "form-ir";
+    /**
+     * Schema version for the IR format itself.
+     * Should equal `IR_VERSION`.
+     */
+    readonly irVersion: string;
+    /** Top-level elements of the form: fields and layout nodes. */
+    readonly elements: readonly FormIRElement[];
+    /** Root-level annotations derived from the source declaration itself. */
+    readonly rootAnnotations?: readonly AnnotationNode[];
+    /**
+     * Registry of named types referenced by fields in this form.
+     * Keys are fully-qualified type names matching `ReferenceTypeNode.name`.
+     */
+    readonly typeRegistry: Readonly<Record<string, TypeDefinition>>;
+    /** Root-level metadata for the form itself. */
+    readonly annotations?: readonly AnnotationNode[];
+    /** Provenance of the form definition itself. */
+    readonly provenance: Provenance;
+}
+
+/**
+ * Union of all IR element types.
+ *
+ * @public
+ */
+export declare type FormIRElement = FieldNode | LayoutNode;
+
+/**
+ * A complete form specification.
+ *
+ * @typeParam Elements - Tuple of top-level form elements
+ *
+ * @public
+ */
+export declare interface FormSpec<Elements extends readonly FormElement[]> {
+    /** Top-level form elements */
+    readonly elements: Elements;
+}
+
+/**
+ * Represents the runtime state of an entire form.
+ *
+ * @typeParam Schema - The form schema type (maps field names to value types)
+ *
+ * @public
+ */
+export declare interface FormState<Schema extends Record<string, unknown>> {
+    /** State for each field, keyed by field name */
+    readonly fields: {
+        readonly [K in keyof Schema]: FieldState<Schema[K]>;
+    };
+    /** Whether any field has been modified */
+    readonly dirty: boolean;
+    /** Whether the form is currently being submitted */
+    readonly submitting: boolean;
+    /** Overall form validity (derived from all field validities) */
+    readonly validity: Validity;
+}
+
+/**
+ * A visual grouping of form elements.
+ *
+ * Groups provide visual organization and can be rendered as fieldsets or sections.
+ *
+ * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
+ */
+export declare interface Group<Elements extends readonly FormElement[]> {
+    /** Type discriminator - identifies this as a group element */
+    readonly _type: "group";
+    /** Display label for the group */
+    readonly label: string;
+    /** Form elements contained within this group */
+    readonly elements: Elements;
+}
+
+/**
+ * A visual grouping of form elements.
+ *
+ * @public
+ */
+export declare interface GroupLayoutNode {
+    readonly kind: "group";
+    readonly label: string;
+    /** Elements contained in this group — may be fields or nested groups. */
+    readonly elements: readonly FormIRElement[];
+    readonly provenance: Provenance;
+}
+
+/**
+ * The current IR format version. Centralized here so all canonicalizers
+ * and consumers reference a single source of truth.
+ *
+ * @public
+ */
+export declare const IR_VERSION: "0.1.0";
+
+/**
+ * Narrows a `FormElement` to an array field.
+ *
+ * @public
+ */
+export declare function isArrayField(element: FormElement): element is ArrayField<string, readonly FormElement[]>;
+
+/**
+ * Narrows a `FormElement` to a boolean checkbox field.
+ *
+ * @public
+ */
+export declare function isBooleanField(element: FormElement): element is BooleanField<string>;
+
+/**
+ * Type guard: checks whether a tag name is a known built-in constraint.
+ *
+ * Uses `Object.hasOwn()` rather than `in` to prevent prototype-chain
+ * matches on names like `"toString"` or `"constructor"`.
+ *
+ * Callers should normalize with {@link normalizeConstraintTagName} first
+ * if the input may be PascalCase.
+ *
+ * @public
+ */
+export declare function isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName;
+
+/**
+ * Narrows a `FormElement` to a conditional wrapper.
+ *
+ * @public
+ */
+export declare function isConditional(element: FormElement): element is Conditional<string, unknown, readonly FormElement[]>;
+
+/**
+ * Narrows a `FormElement` to a dynamic enum field.
+ *
+ * @public
+ */
+export declare function isDynamicEnumField(element: FormElement): element is DynamicEnumField<string, string>;
+
+/**
+ * Narrows a `FormElement` to a dynamic schema field.
+ *
+ * @public
+ */
+export declare function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string>;
+
+/**
+ * Narrows a `FormElement` to any field type.
+ *
+ * @public
+ */
+export declare function isField(element: FormElement): element is AnyField;
+
+/**
+ * Narrows a `FormElement` to a visual group.
+ *
+ * @public
+ */
+export declare function isGroup(element: FormElement): element is Group<readonly FormElement[]>;
+
+/**
+ * Narrows a `FormElement` to a numeric input field.
+ *
+ * @public
+ */
+export declare function isNumberField(element: FormElement): element is NumberField<string>;
+
+/**
+ * Narrows a `FormElement` to an object field.
+ *
+ * @public
+ */
+export declare function isObjectField(element: FormElement): element is ObjectField<string, readonly FormElement[]>;
+
+/**
+ * Narrows a `FormElement` to a static enum field.
+ *
+ * @public
+ */
+export declare function isStaticEnumField(element: FormElement): element is StaticEnumField<string, readonly EnumOptionValue[]>;
+
+/**
+ * Narrows a `FormElement` to a text input field.
+ *
+ * @public
+ */
+export declare function isTextField(element: FormElement): element is TextField<string>;
+
+/**
+ * A JSON-serializable value. All IR nodes must be representable as JSON.
+ *
+ * @public
+ */
+export declare type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+
+/**
+ * Union of layout node types.
+ *
+ * @public
+ */
+export declare type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;
+
+/**
+ * String length and array item count constraints.
+ *
+ * `minLength`/`maxLength` apply to strings; `minItems`/`maxItems` apply to
+ * arrays. They share the same node shape because the composition rules are
+ * identical.
+ *
+ * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode("string")`;
+ * `minItems`/`maxItems` require `ArrayTypeNode`.
+ *
+ * @public
+ */
+export declare interface LengthConstraintNode {
+    readonly kind: "constraint";
+    readonly constraintKind: "minLength" | "maxLength" | "minItems" | "maxItems";
+    readonly value: number;
+    readonly path?: PathTarget;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Normalizes a constraint tag name from PascalCase to camelCase.
+ *
+ * Lowercases the first character so that e.g. `"Minimum"` becomes `"minimum"`.
+ * Callers must strip the `@` prefix before calling this function.
+ *
+ * @example
+ * normalizeConstraintTagName("Minimum")   // "minimum"
+ * normalizeConstraintTagName("MinLength") // "minLength"
+ * normalizeConstraintTagName("minimum")   // "minimum" (idempotent)
+ *
+ * @public
+ */
+export declare function normalizeConstraintTagName(tagName: string): string;
+
+/**
+ * A numeric input field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface NumberField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a number field */
+    readonly _field: "number";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Minimum allowed value */
+    readonly min?: number;
+    /** Maximum allowed value */
+    readonly max?: number;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Value must be a multiple of this number (use 1 for integer semantics) */
+    readonly multipleOf?: number;
+}
+
+/**
+ * Numeric constraints: bounds and multipleOf.
+ *
+ * `minimum` and `maximum` are inclusive; `exclusiveMinimum` and
+ * `exclusiveMaximum` are exclusive bounds (matching JSON Schema 2020-12
+ * semantics).
+ *
+ * Type applicability: may only attach to fields with `PrimitiveTypeNode("number")`
+ * or a `ReferenceTypeNode` that resolves to one.
+ *
+ * @public
+ */
+export declare interface NumericConstraintNode {
+    readonly kind: "constraint";
+    readonly constraintKind: "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf";
+    readonly value: number;
+    /** If present, targets a nested sub-field rather than the field itself. */
+    readonly path?: PathTarget;
+    readonly provenance: Provenance;
+}
+
+/**
+ * An object field containing nested properties.
+ *
+ * Use this for grouping related fields under a single key in the schema.
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Properties - The form elements that define the object's properties
+ *
+ * @public
+ */
+export declare interface ObjectField<N extends string, Properties extends readonly FormElement[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an object field */
+    readonly _field: "object";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Form elements that define the properties of this object */
+    readonly properties: Properties;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
+
+/**
+ * A named property within an object type.
+ *
+ * @public
+ */
+export declare interface ObjectProperty {
+    readonly name: string;
+    readonly type: TypeNode;
+    readonly optional: boolean;
+    /**
+     * Use-site constraints on this property.
+     * Distinct from constraints on the property's type — these are
+     * use-site constraints (e.g., `@minimum :amount 0` targets the
+     * `amount` property of a `MonetaryAmount` field).
+     */
+    readonly constraints: readonly ConstraintNode[];
+    /** Use-site annotations on this property. */
+    readonly annotations: readonly AnnotationNode[];
+    readonly provenance: Provenance;
+}
+
+/**
+ * Object type with named properties.
+ *
+ * @public
+ */
+export declare interface ObjectTypeNode {
+    readonly kind: "object";
+    /**
+     * Named properties of this object. Order is preserved from the source
+     * declaration for deterministic output.
+     */
+    readonly properties: readonly ObjectProperty[];
+    /**
+     * Whether additional properties beyond those listed are permitted.
+     * Ordinary static object types default to true under the current spec.
+     * Explicitly closed-object modes may still set this to false.
+     */
+    readonly additionalProperties: boolean;
+}
+
+/**
+ * A path targeting a sub-field within a complex type.
+ * Used by constraints and annotations to target nested properties.
+ *
+ * @public
+ */
+export declare interface PathTarget {
+    /**
+     * Sequence of property names forming a path from the annotated field's type
+     * to the target sub-field.
+     * e.g., `["value"]` or `["address", "zip"]`
+     */
+    readonly segments: readonly string[];
+}
+
+/**
+ * String pattern constraint (ECMA-262 regex without delimiters).
+ *
+ * Multiple `pattern` constraints on the same field compose via intersection:
+ * all patterns must match simultaneously.
+ *
+ * Type applicability: requires `PrimitiveTypeNode("string")`.
+ *
+ * @public
+ */
+export declare interface PatternConstraintNode {
+    readonly kind: "constraint";
+    readonly constraintKind: "pattern";
+    /** ECMA-262 regular expression, without delimiters. */
+    readonly pattern: string;
+    readonly path?: PathTarget;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Placeholder annotation.
+ *
+ * @public
+ */
+export declare interface PlaceholderAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "placeholder";
+    readonly value: string;
+    readonly provenance: Provenance;
+}
+
+/**
+ * Union of all predicate types.
+ *
+ * Currently only supports equality, but can be extended with:
+ * - `OneOfPredicate` - field value is one of several options
+ * - `NotPredicate` - negation of another predicate
+ * - `AndPredicate` / `OrPredicate` - logical combinations
+ *
+ * @public
+ */
+export declare type Predicate<K extends string = string, V = unknown> = EqualsPredicate<K, V>;
+
+/**
+ * Primitive types mapping directly to JSON Schema primitives.
+ *
+ * Note: integer is NOT a primitive kind — integer semantics are expressed
+ * via a `multipleOf: 1` constraint on a number type.
+ *
+ * @public
+ */
+export declare interface PrimitiveTypeNode {
+    readonly kind: "primitive";
+    readonly primitiveKind: "string" | "number" | "integer" | "bigint" | "boolean" | "null";
+}
+
+/**
+ * Describes the origin of an IR node.
+ * Enables diagnostics that point to the source of a contradiction or error.
+ *
+ * @public
+ */
+export declare interface Provenance {
+    /** The authoring surface that produced this node. */
+    readonly surface: "tsdoc" | "chain-dsl" | "extension" | "inferred";
+    /** Absolute path to the source file. */
+    readonly file: string;
+    /** 1-based line number in the source file. */
+    readonly line: number;
+    /** 0-based column number in the source file. */
+    readonly column: number;
+    /** Length of the source span in characters (for IDE underline ranges). */
+    readonly length?: number;
+    /**
+     * The specific tag, call, or construct that produced this node.
+     * Examples: `@minimum`, `field.number({ min: 0 })`, `optional`
+     */
+    readonly tagName?: string;
+}
+
+/**
+ * Record (dictionary) type — an object with a string index signature and no
+ * named properties. Corresponds to `Record<string, T>` or `{ [k: string]: T }`.
+ *
+ * Emitted as `{ "type": "object", "additionalProperties": <value schema> }` in
+ * JSON Schema per spec 003 §2.5.
+ *
+ * @public
+ */
+export declare interface RecordTypeNode {
+    readonly kind: "record";
+    /** The type of each value in the dictionary. */
+    readonly valueType: TypeNode;
+}
+
+/**
+ * Named type reference preserved for `$defs` and `$ref` emission.
+ *
+ * @public
+ */
+export declare interface ReferenceTypeNode {
+    readonly kind: "reference";
+    /**
+     * The fully-qualified name of the referenced type.
+     * For TypeScript interfaces/type aliases: `"<module>#<TypeName>"`.
+     * For built-in types: the primitive kind string.
+     */
+    readonly name: string;
+    /**
+     * Type arguments if this is a generic instantiation.
+     * e.g., `Array<string>` → `{ name: "Array", typeArguments: [PrimitiveTypeNode("string")] }`
+     */
+    readonly typeArguments: readonly TypeNode[];
+}
+
+/**
+ * Remarks annotation — programmatic-persona documentation carried via
+ * the `x-<vendor>-remarks` JSON Schema extension keyword.
+ *
+ * Populated from `@remarks` TSDoc tag content. SDK codegen can include
+ * this in doc comments; API Documenter renders the source `@remarks`
+ * natively in a dedicated Remarks section.
+ *
+ * @public
+ */
+export declare interface RemarksAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "remarks";
+    readonly value: string;
+    readonly provenance: Provenance;
+}
+
+/**
+ * A field with static enum options (known at compile time).
+ *
+ * Options can be plain strings or objects with `id` and `label` properties.
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam O - Tuple of option values (strings or EnumOption objects)
+ *
+ * @public
+ */
+export declare interface StaticEnumField<N extends string, O extends readonly EnumOptionValue[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an enum field */
+    readonly _field: "enum";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Array of allowed option values */
+    readonly options: O;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
+
+/**
+ * Form element type definitions.
+ *
+ * These types define the structure of form specifications.
+ * The structure IS the definition - nesting implies layout and conditional logic.
+ */
+/**
+ * A text input field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface TextField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a text field */
+    readonly _field: "text";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Placeholder text shown when field is empty */
+    readonly placeholder?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Minimum string length */
+    readonly minLength?: number;
+    /** Maximum string length */
+    readonly maxLength?: number;
+    /** Regular expression pattern the value must match */
+    readonly pattern?: string;
+}
+
+/**
+ * A named type definition stored in the type registry.
+ *
+ * @public
+ */
+export declare interface TypeDefinition {
+    /** The fully-qualified reference name (key in the registry). */
+    readonly name: string;
+    /** The resolved type node. */
+    readonly type: TypeNode;
+    /** Constraints declared on the named type itself. */
+    readonly constraints?: readonly ConstraintNode[];
+    /** Root-level value metadata for a named type definition. */
+    readonly annotations?: readonly AnnotationNode[];
+    /** Where this type was declared. */
+    readonly provenance: Provenance;
+}
+
+/**
+ * Discriminated union of all type representations in the IR.
+ *
+ * @public
+ */
+export declare type TypeNode = PrimitiveTypeNode | EnumTypeNode | ArrayTypeNode | ObjectTypeNode | RecordTypeNode | UnionTypeNode | ReferenceTypeNode | DynamicTypeNode | CustomTypeNode;
+
+/**
+ * Union type for non-enum unions. Nullable types are represented as `T | null`.
+ *
+ * @public
+ */
+export declare interface UnionTypeNode {
+    readonly kind: "union";
+    readonly members: readonly TypeNode[];
+}
+
+/**
+ * Represents the validity state of a field or form.
+ *
+ * - `"valid"` - All validations pass
+ * - `"invalid"` - One or more validations failed
+ * - `"unknown"` - Validation state not yet determined (e.g., async validation pending)
+ *
+ * @public
+ */
+export declare type Validity = "valid" | "invalid" | "unknown";
+
+/**
+ * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
+ *
+ * @public
+ */
+export declare interface VocabularyKeywordRegistration {
+    /** The keyword name (without vendor prefix). */
+    readonly keyword: string;
+    /** JSON Schema that describes the valid values for this keyword. */
+    readonly schema: JsonValue;
+}
+
+export { }