@formspec/core 0.1.0-alpha.16 → 0.1.0-alpha.17

package/dist/core.d.ts

@@ -105,6 +105,19 @@ export declare const BUILTIN_CONSTRAINT_DEFINITIONS: {
     readonly enumOptions: "json";
 };
 
+/**
+ * Registration for mapping a built-in TSDoc tag onto a custom constraint when
+ * it is used on a particular custom type.
+ */
+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. */
 export declare type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;
 
@@ -153,6 +166,40 @@ export declare interface ConstConstraintNode {
  */
 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.
+ */
+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.
+ */
+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.
  *
@@ -221,6 +268,22 @@ export declare interface CustomConstraintRegistration {
      * 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.
      *
@@ -256,6 +319,11 @@ export declare interface CustomTypeNode {
 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.
      *
@@ -264,6 +332,11 @@ export declare interface CustomTypeRegistration {
      * @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[];
 }
 
 /**
@@ -334,6 +407,14 @@ export declare function defineAnnotation(reg: CustomAnnotationRegistration): Cus
  */
 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.
+ */
+export declare function defineConstraintTag(reg: ConstraintTagRegistration): ConstraintTagRegistration;
+
 /**
  * Defines a custom type registration. Currently an identity function that
  * provides type-checking and IDE autocompletion.
@@ -517,6 +598,8 @@ export declare interface ExtensionDefinition {
     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. */

package/dist/extensions/index.d.ts

@@ -8,6 +8,7 @@
  *
  * @packageDocumentation
  */
+import type { BuiltinConstraintName } from "../types/constraint-definitions.js";
 import type { JsonValue, TypeNode } from "../types/ir.js";
 /**
  * Registration for a custom type that maps to a JSON Schema representation.
@@ -18,6 +19,11 @@ import type { JsonValue, TypeNode } from "../types/ir.js";
 export 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.
      *
@@ -26,6 +32,11 @@ export interface CustomTypeRegistration {
      * @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[];
 }
 /**
  * Registration for a custom constraint that maps to JSON Schema keywords.
@@ -46,6 +57,22 @@ export interface CustomConstraintRegistration {
      * 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.
      *
@@ -79,6 +106,50 @@ export interface VocabularyKeywordRegistration {
     /** JSON Schema that describes the valid values for this keyword. */
     readonly schema: JsonValue;
 }
+/**
+ * Declarative authoring-side registration for a custom TSDoc constraint tag.
+ */
+export 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;
+}
+/**
+ * Registration for mapping a built-in TSDoc tag onto a custom constraint when
+ * it is used on a particular custom type.
+ */
+export 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;
+}
+/**
+ * Semantic metadata for ordered custom constraints that should participate in
+ * the generic contradiction/broadening logic.
+ */
+export 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;
+}
 /**
  * A complete extension definition bundling types, constraints, annotations,
  * and vocabulary keywords.
@@ -106,6 +177,8 @@ export interface ExtensionDefinition {
     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. */
@@ -135,6 +208,13 @@ export declare function defineCustomType(reg: CustomTypeRegistration): CustomTyp
  * @returns The same registration, validated at the type level.
  */
 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.
+ */
+export declare function defineConstraintTag(reg: ConstraintTagRegistration): ConstraintTagRegistration;
 /**
  * Defines a custom annotation registration. Currently an identity function
  * that provides type-checking and IDE autocompletion.

package/dist/extensions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAM1D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9F;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,WAAW,GAAG,UAAU,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC;IAC7D;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9F;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7F;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC/D,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC/D,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;CACxE;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,sBAAsB,GAAG,sBAAsB,CAEpF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,4BAA4B,GAAG,4BAA4B,CAEhG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,4BAA4B,GAAG,4BAA4B,CAEhG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAM1D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7F;;;OAGG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,SAAS,uCAAuC,EAAE,CAAC;CAC5F;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,WAAW,GAAG,UAAU,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;IAC1D;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,MAAM,CAAC;IACzE;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9F;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7F;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;CAC3D;AAED;;;GAGG;AACH,MAAM,WAAW,uCAAuC;IACtD,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC/D,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC/D,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC/D,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;CACxE;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,sBAAsB,GAAG,sBAAsB,CAEpF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,4BAA4B,GAAG,4BAA4B,CAEhG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,yBAAyB,GAAG,yBAAyB,CAE7F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,4BAA4B,GAAG,4BAA4B,CAEhG"}

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   createInitialFieldState: () => createInitialFieldState,
   defineAnnotation: () => defineAnnotation,
   defineConstraint: () => defineConstraint,
+  defineConstraintTag: () => defineConstraintTag,
   defineCustomType: () => defineCustomType,
   defineExtension: () => defineExtension,
   isArrayField: () => isArrayField,
@@ -90,6 +91,9 @@ function defineCustomType(reg) {
 function defineConstraint(reg) {
   return reg;
 }
+function defineConstraintTag(reg) {
+  return reg;
+}
 function defineAnnotation(reg) {
   return reg;
 }
@@ -135,6 +139,7 @@ function isConditional(element) {
   createInitialFieldState,
   defineAnnotation,
   defineConstraint,
+  defineConstraintTag,
   defineCustomType,
   defineExtension,
   isArrayField,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/types/field-state.ts","../src/types/constraint-definitions.ts","../src/types/ir.ts","../src/extensions/index.ts","../src/guards.ts"],"sourcesContent":["/**\n * `@formspec/core` - Core type definitions for FormSpec\n *\n * This package provides the foundational types used throughout the FormSpec ecosystem:\n * - Form element types (fields, groups, conditionals)\n * - Field and form state types\n * - Data source registry for dynamic enums\n * - Canonical IR types (FormIR, FieldNode, TypeNode, ConstraintNode, AnnotationNode, etc.)\n *\n * @packageDocumentation\n */\n\n// Re-export all types\nexport type {\n  // Validity\n  Validity,\n\n  // Field state\n  FieldState,\n\n  // Form state\n  FormState,\n\n  // Data sources\n  DataSourceRegistry,\n  DataSourceOption,\n  FetchOptionsResponse,\n  DataSourceValueType,\n\n  // Elements\n  TextField,\n  NumberField,\n  BooleanField,\n  EnumOption,\n  EnumOptionValue,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  AnyField,\n  Group,\n  Conditional,\n  FormElement,\n  FormSpec,\n\n  // Predicates\n  EqualsPredicate,\n  Predicate,\n\n  // Built-in constraints\n  BuiltinConstraintName,\n\n  // Canonical IR\n  JsonValue,\n  Provenance,\n  PathTarget,\n  TypeNode,\n  PrimitiveTypeNode,\n  EnumMember,\n  EnumTypeNode,\n  ArrayTypeNode,\n  ObjectProperty,\n  ObjectTypeNode,\n  RecordTypeNode,\n  UnionTypeNode,\n  ReferenceTypeNode,\n  DynamicTypeNode,\n  CustomTypeNode,\n  ConstraintNode,\n  NumericConstraintNode,\n  LengthConstraintNode,\n  PatternConstraintNode,\n  ArrayCardinalityConstraintNode,\n  EnumMemberConstraintNode,\n  ConstConstraintNode,\n  CustomConstraintNode,\n  AnnotationNode,\n  DisplayNameAnnotationNode,\n  DescriptionAnnotationNode,\n  FormatAnnotationNode,\n  PlaceholderAnnotationNode,\n  DefaultValueAnnotationNode,\n  DeprecatedAnnotationNode,\n  FormatHintAnnotationNode,\n  CustomAnnotationNode,\n  FieldNode,\n  LayoutNode,\n  GroupLayoutNode,\n  ConditionalLayoutNode,\n  FormIRElement,\n  TypeDefinition,\n  FormIR,\n} from \"./types/index.js\";\n\n// Re-export functions and constants\nexport {\n  createInitialFieldState,\n  BUILTIN_CONSTRAINT_DEFINITIONS,\n  normalizeConstraintTagName,\n  isBuiltinConstraintName,\n  IR_VERSION,\n} from \"./types/index.js\";\n\n// Extension API\nexport type {\n  ExtensionDefinition,\n  CustomTypeRegistration,\n  CustomConstraintRegistration,\n  CustomAnnotationRegistration,\n  VocabularyKeywordRegistration,\n} from \"./extensions/index.js\";\n\nexport {\n  defineExtension,\n  defineCustomType,\n  defineConstraint,\n  defineAnnotation,\n} from \"./extensions/index.js\";\n\n// Re-export type guards\nexport {\n  isField,\n  isTextField,\n  isNumberField,\n  isBooleanField,\n  isStaticEnumField,\n  isDynamicEnumField,\n  isDynamicSchemaField,\n  isArrayField,\n  isObjectField,\n  isGroup,\n  isConditional,\n} from \"./guards.js\";\n","import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Built-in constraint definitions for FormSpec constraint validation.\n *\n * This is the single source of truth for which constraints FormSpec\n * recognizes. Both `@formspec/build` (schema generation)\n * and `@formspec/eslint-plugin` (lint-time validation) import from here.\n */\n\n/**\n * Built-in constraint names mapped to their expected value type for parsing.\n * Constraints are surface-agnostic — they manifest as both TSDoc tags\n * (e.g., `@minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).\n *\n * Keys use camelCase matching JSON Schema property names.\n */\nexport const BUILTIN_CONSTRAINT_DEFINITIONS = {\n  minimum: \"number\",\n  maximum: \"number\",\n  exclusiveMinimum: \"number\",\n  exclusiveMaximum: \"number\",\n  multipleOf: \"number\",\n  minLength: \"number\",\n  maxLength: \"number\",\n  minItems: \"number\",\n  maxItems: \"number\",\n  pattern: \"string\",\n  uniqueItems: \"boolean\",\n  const: \"json\",\n  enumOptions: \"json\",\n} as const;\n\n/** Type of a built-in constraint name. */\nexport type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;\n\n/**\n * Normalizes a constraint tag name from PascalCase to camelCase.\n *\n * Lowercases the first character so that e.g. `\"Minimum\"` becomes `\"minimum\"`.\n * Callers must strip the `@` prefix before calling this function.\n *\n * @example\n * normalizeConstraintTagName(\"Minimum\")   // \"minimum\"\n * normalizeConstraintTagName(\"MinLength\") // \"minLength\"\n * normalizeConstraintTagName(\"minimum\")   // \"minimum\" (idempotent)\n */\nexport function normalizeConstraintTagName(tagName: string): string {\n  return tagName.charAt(0).toLowerCase() + tagName.slice(1);\n}\n\n/**\n * Type guard: checks whether a tag name is a known built-in constraint.\n *\n * Uses `Object.hasOwn()` rather than `in` to prevent prototype-chain\n * matches on names like `\"toString\"` or `\"constructor\"`.\n *\n * Callers should normalize with {@link normalizeConstraintTagName} first\n * if the input may be PascalCase.\n */\nexport function isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName {\n  return Object.hasOwn(BUILTIN_CONSTRAINT_DEFINITIONS, tagName);\n}\n","/**\n * Canonical Intermediate Representation (IR) types for FormSpec.\n *\n * The IR is the shared intermediate structure that both authoring surfaces\n * (chain DSL and TSDoc-annotated types) compile to. All downstream operations\n * — JSON Schema generation, UI Schema generation, constraint validation,\n * diagnostics — consume the IR exclusively.\n *\n * All types are plain, serializable objects (no live compiler references).\n *\n * @see {@link https://github.com/stripe/formspec-workspace/blob/main/scratch/design/001-canonical-ir.md}\n */\n\n// =============================================================================\n// IR VERSION\n// =============================================================================\n\n/**\n * The current IR format version. Centralized here so all canonicalizers\n * and consumers reference a single source of truth.\n */\nexport const IR_VERSION = \"0.1.0\" as const;\n\n// =============================================================================\n// UTILITY TYPES\n// =============================================================================\n\n/**\n * A JSON-serializable value. All IR nodes must be representable as JSON.\n */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\n// =============================================================================\n// PROVENANCE\n// =============================================================================\n\n/**\n * Describes the origin of an IR node.\n * Enables diagnostics that point to the source of a contradiction or error.\n */\nexport interface Provenance {\n  /** The authoring surface that produced this node. */\n  readonly surface: \"tsdoc\" | \"chain-dsl\" | \"extension\" | \"inferred\";\n  /** Absolute path to the source file. */\n  readonly file: string;\n  /** 1-based line number in the source file. */\n  readonly line: number;\n  /** 0-based column number in the source file. */\n  readonly column: number;\n  /** Length of the source span in characters (for IDE underline ranges). */\n  readonly length?: number;\n  /**\n   * The specific tag, call, or construct that produced this node.\n   * Examples: `@minimum`, `field.number({ min: 0 })`, `optional`\n   */\n  readonly tagName?: string;\n}\n\n// =============================================================================\n// PATH TARGET\n// =============================================================================\n\n/**\n * A path targeting a sub-field within a complex type.\n * Used by constraints and annotations to target nested properties.\n */\nexport interface PathTarget {\n  /**\n   * Sequence of property names forming a path from the annotated field's type\n   * to the target sub-field.\n   * e.g., `[\"value\"]` or `[\"address\", \"zip\"]`\n   */\n  readonly segments: readonly string[];\n}\n\n// =============================================================================\n// TYPE NODES\n// =============================================================================\n\n/**\n * Discriminated union of all type representations in the IR.\n */\nexport type TypeNode =\n  | PrimitiveTypeNode\n  | EnumTypeNode\n  | ArrayTypeNode\n  | ObjectTypeNode\n  | RecordTypeNode\n  | UnionTypeNode\n  | ReferenceTypeNode\n  | DynamicTypeNode\n  | CustomTypeNode;\n\n/**\n * Primitive types mapping directly to JSON Schema primitives.\n *\n * Note: integer is NOT a primitive kind — integer semantics are expressed\n * via a `multipleOf: 1` constraint on a number type.\n */\nexport interface PrimitiveTypeNode {\n  readonly kind: \"primitive\";\n  readonly primitiveKind: \"string\" | \"number\" | \"boolean\" | \"null\";\n}\n\n/** A member of a static enum type. */\nexport interface EnumMember {\n  /** The serialized value stored in data. */\n  readonly value: string | number;\n  /** Optional per-member display name. */\n  readonly displayName?: string;\n}\n\n/** Static enum type — members known at build time. */\nexport interface EnumTypeNode {\n  readonly kind: \"enum\";\n  readonly members: readonly EnumMember[];\n}\n\n/** Array type with a single items type. */\nexport interface ArrayTypeNode {\n  readonly kind: \"array\";\n  readonly items: TypeNode;\n}\n\n/** A named property within an object type. */\nexport interface ObjectProperty {\n  readonly name: string;\n  readonly type: TypeNode;\n  readonly optional: boolean;\n  /**\n   * Use-site constraints on this property.\n   * Distinct from constraints on the property's type — these are\n   * use-site constraints (e.g., `@minimum :amount 0` targets the\n   * `amount` property of a `MonetaryAmount` field).\n   */\n  readonly constraints: readonly ConstraintNode[];\n  /** Use-site annotations on this property. */\n  readonly annotations: readonly AnnotationNode[];\n  readonly provenance: Provenance;\n}\n\n/** Object type with named properties. */\nexport interface ObjectTypeNode {\n  readonly kind: \"object\";\n  /**\n   * Named properties of this object. Order is preserved from the source\n   * declaration for deterministic output.\n   */\n  readonly properties: readonly ObjectProperty[];\n  /**\n   * Whether additional properties beyond those listed are permitted.\n   * Ordinary static object types default to true under the current spec.\n   * Explicitly closed-object modes may still set this to false.\n   */\n  readonly additionalProperties: boolean;\n}\n\n/**\n * Record (dictionary) type — an object with a string index signature and no\n * named properties. Corresponds to `Record<string, T>` or `{ [k: string]: T }`.\n *\n * Emitted as `{ \"type\": \"object\", \"additionalProperties\": <value schema> }` in\n * JSON Schema per spec 003 §2.5.\n */\nexport interface RecordTypeNode {\n  readonly kind: \"record\";\n  /** The type of each value in the dictionary. */\n  readonly valueType: TypeNode;\n}\n\n/** Union type for non-enum unions. Nullable types are `T | null` using this. */\nexport interface UnionTypeNode {\n  readonly kind: \"union\";\n  readonly members: readonly TypeNode[];\n}\n\n/** Named type reference — preserved as references for `$defs`/`$ref` emission. */\nexport interface ReferenceTypeNode {\n  readonly kind: \"reference\";\n  /**\n   * The fully-qualified name of the referenced type.\n   * For TypeScript interfaces/type aliases: `\"<module>#<TypeName>\"`.\n   * For built-in types: the primitive kind string.\n   */\n  readonly name: string;\n  /**\n   * Type arguments if this is a generic instantiation.\n   * e.g., `Array<string>` → `{ name: \"Array\", typeArguments: [PrimitiveTypeNode(\"string\")] }`\n   */\n  readonly typeArguments: readonly TypeNode[];\n}\n\n/** Dynamic type — schema resolved at runtime from a named data source. */\nexport interface DynamicTypeNode {\n  readonly kind: \"dynamic\";\n  readonly dynamicKind: \"enum\" | \"schema\";\n  /** Key identifying the runtime data source or schema provider. */\n  readonly sourceKey: string;\n  /**\n   * For dynamic enums: field names whose current values are passed as\n   * parameters to the data source resolver.\n   */\n  readonly parameterFields: readonly string[];\n}\n\n/** Custom type registered by an extension. */\nexport interface CustomTypeNode {\n  readonly kind: \"custom\";\n  /**\n   * The extension-qualified type identifier.\n   * Format: `\"<vendor-prefix>/<extension-name>/<type-name>\"`\n   * e.g., `\"x-stripe/monetary/MonetaryAmount\"`\n   */\n  readonly typeId: string;\n  /**\n   * Opaque payload serialized by the extension that registered this type.\n   * Must be JSON-serializable.\n   */\n  readonly payload: JsonValue;\n}\n\n// =============================================================================\n// CONSTRAINT NODES\n// =============================================================================\n\n/**\n * Discriminated union of all constraint types.\n * Constraints are set-influencing: they narrow the set of valid values.\n */\nexport type ConstraintNode =\n  | NumericConstraintNode\n  | LengthConstraintNode\n  | PatternConstraintNode\n  | ArrayCardinalityConstraintNode\n  | EnumMemberConstraintNode\n  | ConstConstraintNode\n  | CustomConstraintNode;\n\n/**\n * Numeric constraints: bounds and multipleOf.\n *\n * `minimum` and `maximum` are inclusive; `exclusiveMinimum` and\n * `exclusiveMaximum` are exclusive bounds (matching JSON Schema 2020-12\n * semantics).\n *\n * Type applicability: may only attach to fields with `PrimitiveTypeNode(\"number\")`\n * or a `ReferenceTypeNode` that resolves to one.\n */\nexport interface NumericConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind:\n    | \"minimum\"\n    | \"maximum\"\n    | \"exclusiveMinimum\"\n    | \"exclusiveMaximum\"\n    | \"multipleOf\";\n  readonly value: number;\n  /** If present, targets a nested sub-field rather than the field itself. */\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String length and array item count constraints.\n *\n * `minLength`/`maxLength` apply to strings; `minItems`/`maxItems` apply to\n * arrays. They share the same node shape because the composition rules are\n * identical.\n *\n * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode(\"string\")`;\n * `minItems`/`maxItems` require `ArrayTypeNode`.\n */\nexport interface LengthConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"minLength\" | \"maxLength\" | \"minItems\" | \"maxItems\";\n  readonly value: number;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String pattern constraint (ECMA-262 regex without delimiters).\n *\n * Multiple `pattern` constraints on the same field compose via intersection:\n * all patterns must match simultaneously.\n *\n * Type applicability: requires `PrimitiveTypeNode(\"string\")`.\n */\nexport interface PatternConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"pattern\";\n  /** ECMA-262 regular expression, without delimiters. */\n  readonly pattern: string;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Array uniqueness constraint. */\nexport interface ArrayCardinalityConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"uniqueItems\";\n  readonly value: true;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Enum member subset constraint (refinement — only narrows). */\nexport interface EnumMemberConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"allowedMembers\";\n  readonly members: readonly (string | number)[];\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Literal-value equality constraint. */\nexport interface ConstConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"const\";\n  readonly value: JsonValue;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom constraint. */\nexport interface CustomConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<constraint-name>\"` */\n  readonly constraintId: string;\n  /** JSON-serializable payload defined by the extension. */\n  readonly payload: JsonValue;\n  /** How this constraint composes with others of the same `constraintId`. */\n  readonly compositionRule: \"intersect\" | \"override\";\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// ANNOTATION NODES\n// =============================================================================\n\n/**\n * Discriminated union of all annotation types.\n * Annotations are value-influencing: they describe or present a field\n * but do not affect which values are valid.\n */\nexport type AnnotationNode =\n  | DisplayNameAnnotationNode\n  | DescriptionAnnotationNode\n  | FormatAnnotationNode\n  | PlaceholderAnnotationNode\n  | DefaultValueAnnotationNode\n  | DeprecatedAnnotationNode\n  | FormatHintAnnotationNode\n  | CustomAnnotationNode;\n\nexport interface DisplayNameAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"displayName\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DescriptionAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"description\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/** Schema format annotation (e.g. email/date/uri). */\nexport interface FormatAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"format\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface PlaceholderAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"placeholder\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DefaultValueAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"defaultValue\";\n  /** Must be JSON-serializable and type-compatible (verified during Validate phase). */\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\nexport interface DeprecatedAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"deprecated\";\n  /** Optional deprecation message. */\n  readonly message?: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * UI rendering hint — does not affect schema validation.\n * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.\n */\nexport interface FormatHintAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"formatHint\";\n  /** Renderer-specific format identifier: \"textarea\", \"radio\", \"date\", \"color\", etc. */\n  readonly format: string;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom annotation. */\nexport interface CustomAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<annotation-name>\"` */\n  readonly annotationId: string;\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FIELD NODE\n// =============================================================================\n\n/** A single form field after canonicalization. */\nexport interface FieldNode {\n  readonly kind: \"field\";\n  /** The field's key in the data schema. */\n  readonly name: string;\n  /** The resolved type of this field. */\n  readonly type: TypeNode;\n  /** Whether this field is required in the data schema. */\n  readonly required: boolean;\n  /** Set-influencing constraints, after merging. */\n  readonly constraints: readonly ConstraintNode[];\n  /** Value-influencing annotations, after merging. */\n  readonly annotations: readonly AnnotationNode[];\n  /** Where this field was declared. */\n  readonly provenance: Provenance;\n  /**\n   * Debug only — ordered list of constraint/annotation nodes that participated\n   * in merging, including dominated ones.\n   */\n  readonly mergeHistory?: readonly {\n    readonly node: ConstraintNode | AnnotationNode;\n    readonly dominated: boolean;\n  }[];\n}\n\n// =============================================================================\n// LAYOUT NODES\n// =============================================================================\n\n/** Union of layout node types. */\nexport type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;\n\n/** A visual grouping of form elements. */\nexport interface GroupLayoutNode {\n  readonly kind: \"group\";\n  readonly label: string;\n  /** Elements contained in this group — may be fields or nested groups. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Conditional visibility based on another field's value. */\nexport interface ConditionalLayoutNode {\n  readonly kind: \"conditional\";\n  /** The field whose value triggers visibility. */\n  readonly fieldName: string;\n  /** The value that makes the condition true (SHOW). */\n  readonly value: JsonValue;\n  /** Elements shown when the condition is met. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Union of all IR element types. */\nexport type FormIRElement = FieldNode | LayoutNode;\n\n// =============================================================================\n// TYPE REGISTRY\n// =============================================================================\n\n/** A named type definition stored in the type registry. */\nexport interface TypeDefinition {\n  /** The fully-qualified reference name (key in the registry). */\n  readonly name: string;\n  /** The resolved type node. */\n  readonly type: TypeNode;\n  /** Root-level value metadata for a named type definition. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Where this type was declared. */\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FORM IR (TOP-LEVEL)\n// =============================================================================\n\n/**\n * The complete Canonical Intermediate Representation for a form.\n *\n * Output of the Canonicalize phase; input to Validate, Generate (JSON Schema),\n * and Generate (UI Schema) phases.\n *\n * Serializable to JSON — no live compiler objects.\n */\nexport interface FormIR {\n  readonly kind: \"form-ir\";\n  /**\n   * Schema version for the IR format itself.\n   * Should equal `IR_VERSION`.\n   */\n  readonly irVersion: string;\n  /** Top-level elements of the form: fields and layout nodes. */\n  readonly elements: readonly FormIRElement[];\n  /**\n   * Registry of named types referenced by fields in this form.\n   * Keys are fully-qualified type names matching `ReferenceTypeNode.name`.\n   */\n  readonly typeRegistry: Readonly<Record<string, TypeDefinition>>;\n  /** Root-level metadata for the form itself. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Provenance of the form definition itself. */\n  readonly provenance: Provenance;\n}\n","/**\n * Extension API for registering custom types, constraints, annotations,\n * and vocabulary keywords with FormSpec.\n *\n * Extensions allow third-party packages (e.g., \"Decimal\", \"DateOnly\") to\n * plug into the FormSpec pipeline. The types and factory functions defined\n * here are consumed by the FormSpec build pipeline.\n *\n * @packageDocumentation\n */\n\nimport type { JsonValue, TypeNode } from \"../types/ir.js\";\n\n// =============================================================================\n// REGISTRATION TYPES\n// =============================================================================\n\n/**\n * Registration for a custom type that maps to a JSON Schema representation.\n *\n * Custom types are referenced via {@link CustomTypeNode} in the IR and\n * resolved to JSON Schema via `toJsonSchema` during generation.\n */\nexport interface CustomTypeRegistration {\n  /** The type name, unique within the extension. */\n  readonly typeName: string;\n  /**\n   * Converts the custom type's payload into a JSON Schema fragment.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords (e.g., \"x-stripe\").\n   * @returns A JSON Schema fragment representing this type.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom constraint that maps to JSON Schema keywords.\n *\n * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.\n */\nexport interface CustomConstraintRegistration {\n  /** The constraint name, unique within the extension. */\n  readonly constraintName: string;\n  /**\n   * How this constraint composes with other constraints of the same kind.\n   * - \"intersect\": combine with logical AND (both must hold)\n   * - \"override\": last writer wins\n   */\n  readonly compositionRule: \"intersect\" | \"override\";\n  /**\n   * TypeNode kinds this constraint is applicable to, or `null` for any type.\n   * Used by the validator to emit TYPE_MISMATCH diagnostics.\n   */\n  readonly applicableTypes: readonly TypeNode[\"kind\"][] | null;\n  /**\n   * Converts the custom constraint's payload into JSON Schema keywords.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords.\n   * @returns A JSON Schema fragment with the constraint keywords.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom annotation that may produce JSON Schema keywords.\n *\n * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.\n * They describe or present a field but do not affect which values are valid.\n */\nexport interface CustomAnnotationRegistration {\n  /** The annotation name, unique within the extension. */\n  readonly annotationName: string;\n  /**\n   * Optionally converts the annotation value into JSON Schema keywords.\n   * If omitted, the annotation has no JSON Schema representation (UI-only).\n   */\n  readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.\n */\nexport interface VocabularyKeywordRegistration {\n  /** The keyword name (without vendor prefix). */\n  readonly keyword: string;\n  /** JSON Schema that describes the valid values for this keyword. */\n  readonly schema: JsonValue;\n}\n\n// =============================================================================\n// EXTENSION DEFINITION\n// =============================================================================\n\n/**\n * A complete extension definition bundling types, constraints, annotations,\n * and vocabulary keywords.\n *\n * @example\n * ```typescript\n * const monetaryExtension = defineExtension({\n *   extensionId: \"x-stripe/monetary\",\n *   types: [\n *     defineCustomType({\n *       typeName: \"Decimal\",\n *       toJsonSchema: (_payload, prefix) => ({\n *         type: \"string\",\n *         [`${prefix}-decimal`]: true,\n *       }),\n *     }),\n *   ],\n * });\n * ```\n */\nexport interface ExtensionDefinition {\n  /** Globally unique extension identifier, e.g., \"x-stripe/monetary\". */\n  readonly extensionId: string;\n  /** Custom type registrations provided by this extension. */\n  readonly types?: readonly CustomTypeRegistration[];\n  /** Custom constraint registrations provided by this extension. */\n  readonly constraints?: readonly CustomConstraintRegistration[];\n  /** Custom annotation registrations provided by this extension. */\n  readonly annotations?: readonly CustomAnnotationRegistration[];\n  /** Vocabulary keyword registrations provided by this extension. */\n  readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];\n}\n\n// =============================================================================\n// FACTORY FUNCTIONS\n// =============================================================================\n\n/**\n * Defines a complete extension. Currently an identity function that provides\n * type-checking and IDE autocompletion for the definition shape.\n *\n * @param def - The extension definition.\n * @returns The same definition, validated at the type level.\n */\nexport function defineExtension(def: ExtensionDefinition): ExtensionDefinition {\n  return def;\n}\n\n/**\n * Defines a custom type registration. Currently an identity function that\n * provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom type registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom constraint registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom constraint registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom annotation registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom annotation registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration {\n  return reg;\n}\n","/**\n * Type guards for FormSpec form elements.\n *\n * Each guard narrows a {@link FormElement} to a specific field, group, or conditional type.\n */\n\nimport type {\n  FormElement,\n  AnyField,\n  TextField,\n  NumberField,\n  BooleanField,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  Group,\n  Conditional,\n  EnumOptionValue,\n} from \"./types/elements.js\";\n\n/** Narrows a FormElement to any field type. */\nexport function isField(element: FormElement): element is AnyField {\n  return element._type === \"field\";\n}\n\n/** Narrows a FormElement to a text input field. */\nexport function isTextField(element: FormElement): element is TextField<string> {\n  return element._type === \"field\" && element._field === \"text\";\n}\n\n/** Narrows a FormElement to a numeric input field. */\nexport function isNumberField(element: FormElement): element is NumberField<string> {\n  return element._type === \"field\" && element._field === \"number\";\n}\n\n/** Narrows a FormElement to a boolean checkbox field. */\nexport function isBooleanField(element: FormElement): element is BooleanField<string> {\n  return element._type === \"field\" && element._field === \"boolean\";\n}\n\n/** Narrows a FormElement to a static enum field. */\nexport function isStaticEnumField(\n  element: FormElement\n): element is StaticEnumField<string, readonly EnumOptionValue[]> {\n  return element._type === \"field\" && element._field === \"enum\";\n}\n\n/** Narrows a FormElement to a dynamic enum field. */\nexport function isDynamicEnumField(\n  element: FormElement\n): element is DynamicEnumField<string, string> {\n  return element._type === \"field\" && element._field === \"dynamic_enum\";\n}\n\n/** Narrows a FormElement to a dynamic schema field. */\nexport function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string> {\n  return element._type === \"field\" && element._field === \"dynamic_schema\";\n}\n\n/** Narrows a FormElement to an array field. */\nexport function isArrayField(\n  element: FormElement\n): element is ArrayField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"array\";\n}\n\n/** Narrows a FormElement to an object field. */\nexport function isObjectField(\n  element: FormElement\n): element is ObjectField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"object\";\n}\n\n/** Narrows a FormElement to a visual group. */\nexport function isGroup(element: FormElement): element is Group<readonly FormElement[]> {\n  return element._type === \"group\";\n}\n\n/** Narrows a FormElement to a conditional wrapper. */\nexport function isConditional(\n  element: FormElement\n): element is Conditional<string, unknown, readonly FormElement[]> {\n  return element._type === \"conditional\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;ACxBO,IAAM,iCAAiC;AAAA,EAC5C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,WAAW;AAAA,EACX,UAAU;AAAA,EACV,UAAU;AAAA,EACV,SAAS;AAAA,EACT,aAAa;AAAA,EACb,OAAO;AAAA,EACP,aAAa;AACf;AAgBO,SAAS,2BAA2B,SAAyB;AAClE,SAAO,QAAQ,OAAO,CAAC,EAAE,YAAY,IAAI,QAAQ,MAAM,CAAC;AAC1D;AAWO,SAAS,wBAAwB,SAAmD;AACzF,SAAO,OAAO,OAAO,gCAAgC,OAAO;AAC9D;;;ACvCO,IAAM,aAAa;;;ACsHnB,SAAS,gBAAgB,KAA+C;AAC7E,SAAO;AACT;AASO,SAAS,iBAAiB,KAAqD;AACpF,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;;;ACvJO,SAAS,QAAQ,SAA2C;AACjE,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,YAAY,SAAoD;AAC9E,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cAAc,SAAsD;AAClF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,eAAe,SAAuD;AACpF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,kBACd,SACgE;AAChE,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,mBACd,SAC6C;AAC7C,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,qBAAqB,SAA6D;AAChG,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,aACd,SACuD;AACvD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cACd,SACwD;AACxD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,QAAQ,SAAgE;AACtF,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,cACd,SACiE;AACjE,SAAO,QAAQ,UAAU;AAC3B;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/types/field-state.ts","../src/types/constraint-definitions.ts","../src/types/ir.ts","../src/extensions/index.ts","../src/guards.ts"],"sourcesContent":["/**\n * `@formspec/core` - Core type definitions for FormSpec\n *\n * This package provides the foundational types used throughout the FormSpec ecosystem:\n * - Form element types (fields, groups, conditionals)\n * - Field and form state types\n * - Data source registry for dynamic enums\n * - Canonical IR types (FormIR, FieldNode, TypeNode, ConstraintNode, AnnotationNode, etc.)\n *\n * @packageDocumentation\n */\n\n// Re-export all types\nexport type {\n  // Validity\n  Validity,\n\n  // Field state\n  FieldState,\n\n  // Form state\n  FormState,\n\n  // Data sources\n  DataSourceRegistry,\n  DataSourceOption,\n  FetchOptionsResponse,\n  DataSourceValueType,\n\n  // Elements\n  TextField,\n  NumberField,\n  BooleanField,\n  EnumOption,\n  EnumOptionValue,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  AnyField,\n  Group,\n  Conditional,\n  FormElement,\n  FormSpec,\n\n  // Predicates\n  EqualsPredicate,\n  Predicate,\n\n  // Built-in constraints\n  BuiltinConstraintName,\n\n  // Canonical IR\n  JsonValue,\n  Provenance,\n  PathTarget,\n  TypeNode,\n  PrimitiveTypeNode,\n  EnumMember,\n  EnumTypeNode,\n  ArrayTypeNode,\n  ObjectProperty,\n  ObjectTypeNode,\n  RecordTypeNode,\n  UnionTypeNode,\n  ReferenceTypeNode,\n  DynamicTypeNode,\n  CustomTypeNode,\n  ConstraintNode,\n  NumericConstraintNode,\n  LengthConstraintNode,\n  PatternConstraintNode,\n  ArrayCardinalityConstraintNode,\n  EnumMemberConstraintNode,\n  ConstConstraintNode,\n  CustomConstraintNode,\n  AnnotationNode,\n  DisplayNameAnnotationNode,\n  DescriptionAnnotationNode,\n  FormatAnnotationNode,\n  PlaceholderAnnotationNode,\n  DefaultValueAnnotationNode,\n  DeprecatedAnnotationNode,\n  FormatHintAnnotationNode,\n  CustomAnnotationNode,\n  FieldNode,\n  LayoutNode,\n  GroupLayoutNode,\n  ConditionalLayoutNode,\n  FormIRElement,\n  TypeDefinition,\n  FormIR,\n} from \"./types/index.js\";\n\n// Re-export functions and constants\nexport {\n  createInitialFieldState,\n  BUILTIN_CONSTRAINT_DEFINITIONS,\n  normalizeConstraintTagName,\n  isBuiltinConstraintName,\n  IR_VERSION,\n} from \"./types/index.js\";\n\n// Extension API\nexport type {\n  ExtensionDefinition,\n  CustomTypeRegistration,\n  CustomConstraintRegistration,\n  ConstraintTagRegistration,\n  BuiltinConstraintBroadeningRegistration,\n  ConstraintSemanticRole,\n  CustomAnnotationRegistration,\n  VocabularyKeywordRegistration,\n} from \"./extensions/index.js\";\n\nexport {\n  defineExtension,\n  defineCustomType,\n  defineConstraint,\n  defineConstraintTag,\n  defineAnnotation,\n} from \"./extensions/index.js\";\n\n// Re-export type guards\nexport {\n  isField,\n  isTextField,\n  isNumberField,\n  isBooleanField,\n  isStaticEnumField,\n  isDynamicEnumField,\n  isDynamicSchemaField,\n  isArrayField,\n  isObjectField,\n  isGroup,\n  isConditional,\n} from \"./guards.js\";\n","import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Built-in constraint definitions for FormSpec constraint validation.\n *\n * This is the single source of truth for which constraints FormSpec\n * recognizes. Both `@formspec/build` (schema generation)\n * and `@formspec/eslint-plugin` (lint-time validation) import from here.\n */\n\n/**\n * Built-in constraint names mapped to their expected value type for parsing.\n * Constraints are surface-agnostic — they manifest as both TSDoc tags\n * (e.g., `@minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).\n *\n * Keys use camelCase matching JSON Schema property names.\n */\nexport const BUILTIN_CONSTRAINT_DEFINITIONS = {\n  minimum: \"number\",\n  maximum: \"number\",\n  exclusiveMinimum: \"number\",\n  exclusiveMaximum: \"number\",\n  multipleOf: \"number\",\n  minLength: \"number\",\n  maxLength: \"number\",\n  minItems: \"number\",\n  maxItems: \"number\",\n  pattern: \"string\",\n  uniqueItems: \"boolean\",\n  const: \"json\",\n  enumOptions: \"json\",\n} as const;\n\n/** Type of a built-in constraint name. */\nexport type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;\n\n/**\n * Normalizes a constraint tag name from PascalCase to camelCase.\n *\n * Lowercases the first character so that e.g. `\"Minimum\"` becomes `\"minimum\"`.\n * Callers must strip the `@` prefix before calling this function.\n *\n * @example\n * normalizeConstraintTagName(\"Minimum\")   // \"minimum\"\n * normalizeConstraintTagName(\"MinLength\") // \"minLength\"\n * normalizeConstraintTagName(\"minimum\")   // \"minimum\" (idempotent)\n */\nexport function normalizeConstraintTagName(tagName: string): string {\n  return tagName.charAt(0).toLowerCase() + tagName.slice(1);\n}\n\n/**\n * Type guard: checks whether a tag name is a known built-in constraint.\n *\n * Uses `Object.hasOwn()` rather than `in` to prevent prototype-chain\n * matches on names like `\"toString\"` or `\"constructor\"`.\n *\n * Callers should normalize with {@link normalizeConstraintTagName} first\n * if the input may be PascalCase.\n */\nexport function isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName {\n  return Object.hasOwn(BUILTIN_CONSTRAINT_DEFINITIONS, tagName);\n}\n","/**\n * Canonical Intermediate Representation (IR) types for FormSpec.\n *\n * The IR is the shared intermediate structure that both authoring surfaces\n * (chain DSL and TSDoc-annotated types) compile to. All downstream operations\n * — JSON Schema generation, UI Schema generation, constraint validation,\n * diagnostics — consume the IR exclusively.\n *\n * All types are plain, serializable objects (no live compiler references).\n *\n * @see {@link https://github.com/stripe/formspec-workspace/blob/main/scratch/design/001-canonical-ir.md}\n */\n\n// =============================================================================\n// IR VERSION\n// =============================================================================\n\n/**\n * The current IR format version. Centralized here so all canonicalizers\n * and consumers reference a single source of truth.\n */\nexport const IR_VERSION = \"0.1.0\" as const;\n\n// =============================================================================\n// UTILITY TYPES\n// =============================================================================\n\n/**\n * A JSON-serializable value. All IR nodes must be representable as JSON.\n */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\n// =============================================================================\n// PROVENANCE\n// =============================================================================\n\n/**\n * Describes the origin of an IR node.\n * Enables diagnostics that point to the source of a contradiction or error.\n */\nexport interface Provenance {\n  /** The authoring surface that produced this node. */\n  readonly surface: \"tsdoc\" | \"chain-dsl\" | \"extension\" | \"inferred\";\n  /** Absolute path to the source file. */\n  readonly file: string;\n  /** 1-based line number in the source file. */\n  readonly line: number;\n  /** 0-based column number in the source file. */\n  readonly column: number;\n  /** Length of the source span in characters (for IDE underline ranges). */\n  readonly length?: number;\n  /**\n   * The specific tag, call, or construct that produced this node.\n   * Examples: `@minimum`, `field.number({ min: 0 })`, `optional`\n   */\n  readonly tagName?: string;\n}\n\n// =============================================================================\n// PATH TARGET\n// =============================================================================\n\n/**\n * A path targeting a sub-field within a complex type.\n * Used by constraints and annotations to target nested properties.\n */\nexport interface PathTarget {\n  /**\n   * Sequence of property names forming a path from the annotated field's type\n   * to the target sub-field.\n   * e.g., `[\"value\"]` or `[\"address\", \"zip\"]`\n   */\n  readonly segments: readonly string[];\n}\n\n// =============================================================================\n// TYPE NODES\n// =============================================================================\n\n/**\n * Discriminated union of all type representations in the IR.\n */\nexport type TypeNode =\n  | PrimitiveTypeNode\n  | EnumTypeNode\n  | ArrayTypeNode\n  | ObjectTypeNode\n  | RecordTypeNode\n  | UnionTypeNode\n  | ReferenceTypeNode\n  | DynamicTypeNode\n  | CustomTypeNode;\n\n/**\n * Primitive types mapping directly to JSON Schema primitives.\n *\n * Note: integer is NOT a primitive kind — integer semantics are expressed\n * via a `multipleOf: 1` constraint on a number type.\n */\nexport interface PrimitiveTypeNode {\n  readonly kind: \"primitive\";\n  readonly primitiveKind: \"string\" | \"number\" | \"boolean\" | \"null\";\n}\n\n/** A member of a static enum type. */\nexport interface EnumMember {\n  /** The serialized value stored in data. */\n  readonly value: string | number;\n  /** Optional per-member display name. */\n  readonly displayName?: string;\n}\n\n/** Static enum type — members known at build time. */\nexport interface EnumTypeNode {\n  readonly kind: \"enum\";\n  readonly members: readonly EnumMember[];\n}\n\n/** Array type with a single items type. */\nexport interface ArrayTypeNode {\n  readonly kind: \"array\";\n  readonly items: TypeNode;\n}\n\n/** A named property within an object type. */\nexport interface ObjectProperty {\n  readonly name: string;\n  readonly type: TypeNode;\n  readonly optional: boolean;\n  /**\n   * Use-site constraints on this property.\n   * Distinct from constraints on the property's type — these are\n   * use-site constraints (e.g., `@minimum :amount 0` targets the\n   * `amount` property of a `MonetaryAmount` field).\n   */\n  readonly constraints: readonly ConstraintNode[];\n  /** Use-site annotations on this property. */\n  readonly annotations: readonly AnnotationNode[];\n  readonly provenance: Provenance;\n}\n\n/** Object type with named properties. */\nexport interface ObjectTypeNode {\n  readonly kind: \"object\";\n  /**\n   * Named properties of this object. Order is preserved from the source\n   * declaration for deterministic output.\n   */\n  readonly properties: readonly ObjectProperty[];\n  /**\n   * Whether additional properties beyond those listed are permitted.\n   * Ordinary static object types default to true under the current spec.\n   * Explicitly closed-object modes may still set this to false.\n   */\n  readonly additionalProperties: boolean;\n}\n\n/**\n * Record (dictionary) type — an object with a string index signature and no\n * named properties. Corresponds to `Record<string, T>` or `{ [k: string]: T }`.\n *\n * Emitted as `{ \"type\": \"object\", \"additionalProperties\": <value schema> }` in\n * JSON Schema per spec 003 §2.5.\n */\nexport interface RecordTypeNode {\n  readonly kind: \"record\";\n  /** The type of each value in the dictionary. */\n  readonly valueType: TypeNode;\n}\n\n/** Union type for non-enum unions. Nullable types are `T | null` using this. */\nexport interface UnionTypeNode {\n  readonly kind: \"union\";\n  readonly members: readonly TypeNode[];\n}\n\n/** Named type reference — preserved as references for `$defs`/`$ref` emission. */\nexport interface ReferenceTypeNode {\n  readonly kind: \"reference\";\n  /**\n   * The fully-qualified name of the referenced type.\n   * For TypeScript interfaces/type aliases: `\"<module>#<TypeName>\"`.\n   * For built-in types: the primitive kind string.\n   */\n  readonly name: string;\n  /**\n   * Type arguments if this is a generic instantiation.\n   * e.g., `Array<string>` → `{ name: \"Array\", typeArguments: [PrimitiveTypeNode(\"string\")] }`\n   */\n  readonly typeArguments: readonly TypeNode[];\n}\n\n/** Dynamic type — schema resolved at runtime from a named data source. */\nexport interface DynamicTypeNode {\n  readonly kind: \"dynamic\";\n  readonly dynamicKind: \"enum\" | \"schema\";\n  /** Key identifying the runtime data source or schema provider. */\n  readonly sourceKey: string;\n  /**\n   * For dynamic enums: field names whose current values are passed as\n   * parameters to the data source resolver.\n   */\n  readonly parameterFields: readonly string[];\n}\n\n/** Custom type registered by an extension. */\nexport interface CustomTypeNode {\n  readonly kind: \"custom\";\n  /**\n   * The extension-qualified type identifier.\n   * Format: `\"<vendor-prefix>/<extension-name>/<type-name>\"`\n   * e.g., `\"x-stripe/monetary/MonetaryAmount\"`\n   */\n  readonly typeId: string;\n  /**\n   * Opaque payload serialized by the extension that registered this type.\n   * Must be JSON-serializable.\n   */\n  readonly payload: JsonValue;\n}\n\n// =============================================================================\n// CONSTRAINT NODES\n// =============================================================================\n\n/**\n * Discriminated union of all constraint types.\n * Constraints are set-influencing: they narrow the set of valid values.\n */\nexport type ConstraintNode =\n  | NumericConstraintNode\n  | LengthConstraintNode\n  | PatternConstraintNode\n  | ArrayCardinalityConstraintNode\n  | EnumMemberConstraintNode\n  | ConstConstraintNode\n  | CustomConstraintNode;\n\n/**\n * Numeric constraints: bounds and multipleOf.\n *\n * `minimum` and `maximum` are inclusive; `exclusiveMinimum` and\n * `exclusiveMaximum` are exclusive bounds (matching JSON Schema 2020-12\n * semantics).\n *\n * Type applicability: may only attach to fields with `PrimitiveTypeNode(\"number\")`\n * or a `ReferenceTypeNode` that resolves to one.\n */\nexport interface NumericConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind:\n    | \"minimum\"\n    | \"maximum\"\n    | \"exclusiveMinimum\"\n    | \"exclusiveMaximum\"\n    | \"multipleOf\";\n  readonly value: number;\n  /** If present, targets a nested sub-field rather than the field itself. */\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String length and array item count constraints.\n *\n * `minLength`/`maxLength` apply to strings; `minItems`/`maxItems` apply to\n * arrays. They share the same node shape because the composition rules are\n * identical.\n *\n * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode(\"string\")`;\n * `minItems`/`maxItems` require `ArrayTypeNode`.\n */\nexport interface LengthConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"minLength\" | \"maxLength\" | \"minItems\" | \"maxItems\";\n  readonly value: number;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String pattern constraint (ECMA-262 regex without delimiters).\n *\n * Multiple `pattern` constraints on the same field compose via intersection:\n * all patterns must match simultaneously.\n *\n * Type applicability: requires `PrimitiveTypeNode(\"string\")`.\n */\nexport interface PatternConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"pattern\";\n  /** ECMA-262 regular expression, without delimiters. */\n  readonly pattern: string;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Array uniqueness constraint. */\nexport interface ArrayCardinalityConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"uniqueItems\";\n  readonly value: true;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Enum member subset constraint (refinement — only narrows). */\nexport interface EnumMemberConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"allowedMembers\";\n  readonly members: readonly (string | number)[];\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Literal-value equality constraint. */\nexport interface ConstConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"const\";\n  readonly value: JsonValue;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom constraint. */\nexport interface CustomConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<constraint-name>\"` */\n  readonly constraintId: string;\n  /** JSON-serializable payload defined by the extension. */\n  readonly payload: JsonValue;\n  /** How this constraint composes with others of the same `constraintId`. */\n  readonly compositionRule: \"intersect\" | \"override\";\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// ANNOTATION NODES\n// =============================================================================\n\n/**\n * Discriminated union of all annotation types.\n * Annotations are value-influencing: they describe or present a field\n * but do not affect which values are valid.\n */\nexport type AnnotationNode =\n  | DisplayNameAnnotationNode\n  | DescriptionAnnotationNode\n  | FormatAnnotationNode\n  | PlaceholderAnnotationNode\n  | DefaultValueAnnotationNode\n  | DeprecatedAnnotationNode\n  | FormatHintAnnotationNode\n  | CustomAnnotationNode;\n\nexport interface DisplayNameAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"displayName\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DescriptionAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"description\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/** Schema format annotation (e.g. email/date/uri). */\nexport interface FormatAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"format\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface PlaceholderAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"placeholder\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DefaultValueAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"defaultValue\";\n  /** Must be JSON-serializable and type-compatible (verified during Validate phase). */\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\nexport interface DeprecatedAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"deprecated\";\n  /** Optional deprecation message. */\n  readonly message?: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * UI rendering hint — does not affect schema validation.\n * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.\n */\nexport interface FormatHintAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"formatHint\";\n  /** Renderer-specific format identifier: \"textarea\", \"radio\", \"date\", \"color\", etc. */\n  readonly format: string;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom annotation. */\nexport interface CustomAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<annotation-name>\"` */\n  readonly annotationId: string;\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FIELD NODE\n// =============================================================================\n\n/** A single form field after canonicalization. */\nexport interface FieldNode {\n  readonly kind: \"field\";\n  /** The field's key in the data schema. */\n  readonly name: string;\n  /** The resolved type of this field. */\n  readonly type: TypeNode;\n  /** Whether this field is required in the data schema. */\n  readonly required: boolean;\n  /** Set-influencing constraints, after merging. */\n  readonly constraints: readonly ConstraintNode[];\n  /** Value-influencing annotations, after merging. */\n  readonly annotations: readonly AnnotationNode[];\n  /** Where this field was declared. */\n  readonly provenance: Provenance;\n  /**\n   * Debug only — ordered list of constraint/annotation nodes that participated\n   * in merging, including dominated ones.\n   */\n  readonly mergeHistory?: readonly {\n    readonly node: ConstraintNode | AnnotationNode;\n    readonly dominated: boolean;\n  }[];\n}\n\n// =============================================================================\n// LAYOUT NODES\n// =============================================================================\n\n/** Union of layout node types. */\nexport type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;\n\n/** A visual grouping of form elements. */\nexport interface GroupLayoutNode {\n  readonly kind: \"group\";\n  readonly label: string;\n  /** Elements contained in this group — may be fields or nested groups. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Conditional visibility based on another field's value. */\nexport interface ConditionalLayoutNode {\n  readonly kind: \"conditional\";\n  /** The field whose value triggers visibility. */\n  readonly fieldName: string;\n  /** The value that makes the condition true (SHOW). */\n  readonly value: JsonValue;\n  /** Elements shown when the condition is met. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Union of all IR element types. */\nexport type FormIRElement = FieldNode | LayoutNode;\n\n// =============================================================================\n// TYPE REGISTRY\n// =============================================================================\n\n/** A named type definition stored in the type registry. */\nexport interface TypeDefinition {\n  /** The fully-qualified reference name (key in the registry). */\n  readonly name: string;\n  /** The resolved type node. */\n  readonly type: TypeNode;\n  /** Root-level value metadata for a named type definition. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Where this type was declared. */\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FORM IR (TOP-LEVEL)\n// =============================================================================\n\n/**\n * The complete Canonical Intermediate Representation for a form.\n *\n * Output of the Canonicalize phase; input to Validate, Generate (JSON Schema),\n * and Generate (UI Schema) phases.\n *\n * Serializable to JSON — no live compiler objects.\n */\nexport interface FormIR {\n  readonly kind: \"form-ir\";\n  /**\n   * Schema version for the IR format itself.\n   * Should equal `IR_VERSION`.\n   */\n  readonly irVersion: string;\n  /** Top-level elements of the form: fields and layout nodes. */\n  readonly elements: readonly FormIRElement[];\n  /**\n   * Registry of named types referenced by fields in this form.\n   * Keys are fully-qualified type names matching `ReferenceTypeNode.name`.\n   */\n  readonly typeRegistry: Readonly<Record<string, TypeDefinition>>;\n  /** Root-level metadata for the form itself. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Provenance of the form definition itself. */\n  readonly provenance: Provenance;\n}\n","/**\n * Extension API for registering custom types, constraints, annotations,\n * and vocabulary keywords with FormSpec.\n *\n * Extensions allow third-party packages (e.g., \"Decimal\", \"DateOnly\") to\n * plug into the FormSpec pipeline. The types and factory functions defined\n * here are consumed by the FormSpec build pipeline.\n *\n * @packageDocumentation\n */\n\nimport type { BuiltinConstraintName } from \"../types/constraint-definitions.js\";\nimport type { JsonValue, TypeNode } from \"../types/ir.js\";\n\n// =============================================================================\n// REGISTRATION TYPES\n// =============================================================================\n\n/**\n * Registration for a custom type that maps to a JSON Schema representation.\n *\n * Custom types are referenced via {@link CustomTypeNode} in the IR and\n * resolved to JSON Schema via `toJsonSchema` during generation.\n */\nexport interface CustomTypeRegistration {\n  /** The type name, unique within the extension. */\n  readonly typeName: string;\n  /**\n   * Optional TypeScript surface names that should resolve to this custom type\n   * during TSDoc/class analysis. Defaults to `typeName` when omitted.\n   */\n  readonly tsTypeNames?: readonly string[];\n  /**\n   * Converts the custom type's payload into a JSON Schema fragment.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords (e.g., \"x-stripe\").\n   * @returns A JSON Schema fragment representing this type.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n  /**\n   * Optional broadening of built-in constraint tags so they can apply to this\n   * custom type without modifying the core built-in constraint tables.\n   */\n  readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration[];\n}\n\n/**\n * Registration for a custom constraint that maps to JSON Schema keywords.\n *\n * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.\n */\nexport interface CustomConstraintRegistration {\n  /** The constraint name, unique within the extension. */\n  readonly constraintName: string;\n  /**\n   * How this constraint composes with other constraints of the same kind.\n   * - \"intersect\": combine with logical AND (both must hold)\n   * - \"override\": last writer wins\n   */\n  readonly compositionRule: \"intersect\" | \"override\";\n  /**\n   * TypeNode kinds this constraint is applicable to, or `null` for any type.\n   * Used by the validator to emit TYPE_MISMATCH diagnostics.\n   */\n  readonly applicableTypes: readonly TypeNode[\"kind\"][] | null;\n  /**\n   * Optional precise type predicate used when kind-level applicability is too\n   * broad (for example, constraints that apply to integer-like primitives but\n   * not strings).\n   */\n  readonly isApplicableToType?: (type: TypeNode) => boolean;\n  /**\n   * Optional comparator for payloads belonging to the same custom constraint.\n   * Return values follow the `Array.prototype.sort()` contract.\n   */\n  readonly comparePayloads?: (left: JsonValue, right: JsonValue) => number;\n  /**\n   * Optional semantic family metadata for generic contradiction/broadening\n   * handling across ordered constraints.\n   */\n  readonly semanticRole?: ConstraintSemanticRole;\n  /**\n   * Converts the custom constraint's payload into JSON Schema keywords.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords.\n   * @returns A JSON Schema fragment with the constraint keywords.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom annotation that may produce JSON Schema keywords.\n *\n * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.\n * They describe or present a field but do not affect which values are valid.\n */\nexport interface CustomAnnotationRegistration {\n  /** The annotation name, unique within the extension. */\n  readonly annotationName: string;\n  /**\n   * Optionally converts the annotation value into JSON Schema keywords.\n   * If omitted, the annotation has no JSON Schema representation (UI-only).\n   */\n  readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.\n */\nexport interface VocabularyKeywordRegistration {\n  /** The keyword name (without vendor prefix). */\n  readonly keyword: string;\n  /** JSON Schema that describes the valid values for this keyword. */\n  readonly schema: JsonValue;\n}\n\n/**\n * Declarative authoring-side registration for a custom TSDoc constraint tag.\n */\nexport interface ConstraintTagRegistration {\n  /** Tag name without the `@` prefix, e.g. `\"maxSigFig\"`. */\n  readonly tagName: string;\n  /** The custom constraint that this tag should produce. */\n  readonly constraintName: string;\n  /** Parser from raw TSDoc text to JSON-serializable payload. */\n  readonly parseValue: (raw: string) => JsonValue;\n  /**\n   * Optional precise applicability predicate for the field type being parsed.\n   * When omitted, the target custom constraint registration controls type\n   * applicability during validation.\n   */\n  readonly isApplicableToType?: (type: TypeNode) => boolean;\n}\n\n/**\n * Registration for mapping a built-in TSDoc tag onto a custom constraint when\n * it is used on a particular custom type.\n */\nexport interface BuiltinConstraintBroadeningRegistration {\n  /** The built-in tag being broadened, without the `@` prefix. */\n  readonly tagName: BuiltinConstraintName;\n  /** The custom constraint to emit for this built-in tag. */\n  readonly constraintName: string;\n  /** Parser from raw TSDoc text to extension payload. */\n  readonly parseValue: (raw: string) => JsonValue;\n}\n\n/**\n * Semantic metadata for ordered custom constraints that should participate in\n * the generic contradiction/broadening logic.\n */\nexport interface ConstraintSemanticRole {\n  /**\n   * Logical family identifier shared by related constraints, for example\n   * `\"decimal-bound\"` or `\"date-bound\"`.\n   */\n  readonly family: string;\n  /** Whether this constraint acts as a lower or upper bound. */\n  readonly bound: \"lower\" | \"upper\" | \"exact\";\n  /** Whether equality is allowed when comparing against the bound. */\n  readonly inclusive: boolean;\n}\n\n// =============================================================================\n// EXTENSION DEFINITION\n// =============================================================================\n\n/**\n * A complete extension definition bundling types, constraints, annotations,\n * and vocabulary keywords.\n *\n * @example\n * ```typescript\n * const monetaryExtension = defineExtension({\n *   extensionId: \"x-stripe/monetary\",\n *   types: [\n *     defineCustomType({\n *       typeName: \"Decimal\",\n *       toJsonSchema: (_payload, prefix) => ({\n *         type: \"string\",\n *         [`${prefix}-decimal`]: true,\n *       }),\n *     }),\n *   ],\n * });\n * ```\n */\nexport interface ExtensionDefinition {\n  /** Globally unique extension identifier, e.g., \"x-stripe/monetary\". */\n  readonly extensionId: string;\n  /** Custom type registrations provided by this extension. */\n  readonly types?: readonly CustomTypeRegistration[];\n  /** Custom constraint registrations provided by this extension. */\n  readonly constraints?: readonly CustomConstraintRegistration[];\n  /** Authoring-side TSDoc tag registrations provided by this extension. */\n  readonly constraintTags?: readonly ConstraintTagRegistration[];\n  /** Custom annotation registrations provided by this extension. */\n  readonly annotations?: readonly CustomAnnotationRegistration[];\n  /** Vocabulary keyword registrations provided by this extension. */\n  readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];\n}\n\n// =============================================================================\n// FACTORY FUNCTIONS\n// =============================================================================\n\n/**\n * Defines a complete extension. Currently an identity function that provides\n * type-checking and IDE autocompletion for the definition shape.\n *\n * @param def - The extension definition.\n * @returns The same definition, validated at the type level.\n */\nexport function defineExtension(def: ExtensionDefinition): ExtensionDefinition {\n  return def;\n}\n\n/**\n * Defines a custom type registration. Currently an identity function that\n * provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom type registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom constraint registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom constraint registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom TSDoc constraint tag registration.\n *\n * @param reg - The custom tag registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraintTag(reg: ConstraintTagRegistration): ConstraintTagRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom annotation registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom annotation registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration {\n  return reg;\n}\n","/**\n * Type guards for FormSpec form elements.\n *\n * Each guard narrows a {@link FormElement} to a specific field, group, or conditional type.\n */\n\nimport type {\n  FormElement,\n  AnyField,\n  TextField,\n  NumberField,\n  BooleanField,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  Group,\n  Conditional,\n  EnumOptionValue,\n} from \"./types/elements.js\";\n\n/** Narrows a FormElement to any field type. */\nexport function isField(element: FormElement): element is AnyField {\n  return element._type === \"field\";\n}\n\n/** Narrows a FormElement to a text input field. */\nexport function isTextField(element: FormElement): element is TextField<string> {\n  return element._type === \"field\" && element._field === \"text\";\n}\n\n/** Narrows a FormElement to a numeric input field. */\nexport function isNumberField(element: FormElement): element is NumberField<string> {\n  return element._type === \"field\" && element._field === \"number\";\n}\n\n/** Narrows a FormElement to a boolean checkbox field. */\nexport function isBooleanField(element: FormElement): element is BooleanField<string> {\n  return element._type === \"field\" && element._field === \"boolean\";\n}\n\n/** Narrows a FormElement to a static enum field. */\nexport function isStaticEnumField(\n  element: FormElement\n): element is StaticEnumField<string, readonly EnumOptionValue[]> {\n  return element._type === \"field\" && element._field === \"enum\";\n}\n\n/** Narrows a FormElement to a dynamic enum field. */\nexport function isDynamicEnumField(\n  element: FormElement\n): element is DynamicEnumField<string, string> {\n  return element._type === \"field\" && element._field === \"dynamic_enum\";\n}\n\n/** Narrows a FormElement to a dynamic schema field. */\nexport function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string> {\n  return element._type === \"field\" && element._field === \"dynamic_schema\";\n}\n\n/** Narrows a FormElement to an array field. */\nexport function isArrayField(\n  element: FormElement\n): element is ArrayField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"array\";\n}\n\n/** Narrows a FormElement to an object field. */\nexport function isObjectField(\n  element: FormElement\n): element is ObjectField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"object\";\n}\n\n/** Narrows a FormElement to a visual group. */\nexport function isGroup(element: FormElement): element is Group<readonly FormElement[]> {\n  return element._type === \"group\";\n}\n\n/** Narrows a FormElement to a conditional wrapper. */\nexport function isConditional(\n  element: FormElement\n): element is Conditional<string, unknown, readonly FormElement[]> {\n  return element._type === \"conditional\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;ACxBO,IAAM,iCAAiC;AAAA,EAC5C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,WAAW;AAAA,EACX,UAAU;AAAA,EACV,UAAU;AAAA,EACV,SAAS;AAAA,EACT,aAAa;AAAA,EACb,OAAO;AAAA,EACP,aAAa;AACf;AAgBO,SAAS,2BAA2B,SAAyB;AAClE,SAAO,QAAQ,OAAO,CAAC,EAAE,YAAY,IAAI,QAAQ,MAAM,CAAC;AAC1D;AAWO,SAAS,wBAAwB,SAAmD;AACzF,SAAO,OAAO,OAAO,gCAAgC,OAAO;AAC9D;;;ACvCO,IAAM,aAAa;;;ACkMnB,SAAS,gBAAgB,KAA+C;AAC7E,SAAO;AACT;AASO,SAAS,iBAAiB,KAAqD;AACpF,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;AAQO,SAAS,oBAAoB,KAA2D;AAC7F,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;;;AC7OO,SAAS,QAAQ,SAA2C;AACjE,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,YAAY,SAAoD;AAC9E,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cAAc,SAAsD;AAClF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,eAAe,SAAuD;AACpF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,kBACd,SACgE;AAChE,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,mBACd,SAC6C;AAC7C,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,qBAAqB,SAA6D;AAChG,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,aACd,SACuD;AACvD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cACd,SACwD;AACxD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,QAAQ,SAAgE;AACtF,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,cACd,SACiE;AACjE,SAAO,QAAQ,UAAU;AAC3B;","names":[]}

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  */
 export type { Validity, FieldState, FormState, DataSourceRegistry, DataSourceOption, FetchOptionsResponse, DataSourceValueType, TextField, NumberField, BooleanField, EnumOption, EnumOptionValue, StaticEnumField, DynamicEnumField, DynamicSchemaField, ArrayField, ObjectField, AnyField, Group, Conditional, FormElement, FormSpec, EqualsPredicate, Predicate, BuiltinConstraintName, JsonValue, Provenance, PathTarget, TypeNode, PrimitiveTypeNode, EnumMember, EnumTypeNode, ArrayTypeNode, ObjectProperty, ObjectTypeNode, RecordTypeNode, UnionTypeNode, ReferenceTypeNode, DynamicTypeNode, CustomTypeNode, ConstraintNode, NumericConstraintNode, LengthConstraintNode, PatternConstraintNode, ArrayCardinalityConstraintNode, EnumMemberConstraintNode, ConstConstraintNode, CustomConstraintNode, AnnotationNode, DisplayNameAnnotationNode, DescriptionAnnotationNode, FormatAnnotationNode, PlaceholderAnnotationNode, DefaultValueAnnotationNode, DeprecatedAnnotationNode, FormatHintAnnotationNode, CustomAnnotationNode, FieldNode, LayoutNode, GroupLayoutNode, ConditionalLayoutNode, FormIRElement, TypeDefinition, FormIR, } from "./types/index.js";
 export { createInitialFieldState, BUILTIN_CONSTRAINT_DEFINITIONS, normalizeConstraintTagName, isBuiltinConstraintName, IR_VERSION, } from "./types/index.js";
-export type { ExtensionDefinition, CustomTypeRegistration, CustomConstraintRegistration, CustomAnnotationRegistration, VocabularyKeywordRegistration, } from "./extensions/index.js";
-export { defineExtension, defineCustomType, defineConstraint, defineAnnotation, } from "./extensions/index.js";
+export type { ExtensionDefinition, CustomTypeRegistration, CustomConstraintRegistration, ConstraintTagRegistration, BuiltinConstraintBroadeningRegistration, ConstraintSemanticRole, CustomAnnotationRegistration, VocabularyKeywordRegistration, } from "./extensions/index.js";
+export { defineExtension, defineCustomType, defineConstraint, defineConstraintTag, defineAnnotation, } from "./extensions/index.js";
 export { isField, isTextField, isNumberField, isBooleanField, isStaticEnumField, isDynamicEnumField, isDynamicSchemaField, isArrayField, isObjectField, isGroup, isConditional, } from "./guards.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,YAAY,EAEV,QAAQ,EAGR,UAAU,EAGV,SAAS,EAGT,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EAGnB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EAGR,eAAe,EACf,SAAS,EAGT,qBAAqB,EAGrB,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,0BAA0B,EAC1B,uBAAuB,EACvB,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,OAAO,EACP,WAAW,EACX,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,OAAO,EACP,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,YAAY,EAEV,QAAQ,EAGR,UAAU,EAGV,SAAS,EAGT,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EAGnB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EAGR,eAAe,EACf,SAAS,EAGT,qBAAqB,EAGrB,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,0BAA0B,EAC1B,uBAAuB,EACvB,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,4BAA4B,EAC5B,yBAAyB,EACzB,uCAAuC,EACvC,sBAAsB,EACtB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,OAAO,EACP,WAAW,EACX,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,OAAO,EACP,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -45,6 +45,9 @@ function defineCustomType(reg) {
 function defineConstraint(reg) {
   return reg;
 }
+function defineConstraintTag(reg) {
+  return reg;
+}
 function defineAnnotation(reg) {
   return reg;
 }
@@ -89,6 +92,7 @@ export {
   createInitialFieldState,
   defineAnnotation,
   defineConstraint,
+  defineConstraintTag,
   defineCustomType,
   defineExtension,
   isArrayField,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types/field-state.ts","../src/types/constraint-definitions.ts","../src/types/ir.ts","../src/extensions/index.ts","../src/guards.ts"],"sourcesContent":["import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Built-in constraint definitions for FormSpec constraint validation.\n *\n * This is the single source of truth for which constraints FormSpec\n * recognizes. Both `@formspec/build` (schema generation)\n * and `@formspec/eslint-plugin` (lint-time validation) import from here.\n */\n\n/**\n * Built-in constraint names mapped to their expected value type for parsing.\n * Constraints are surface-agnostic — they manifest as both TSDoc tags\n * (e.g., `@minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).\n *\n * Keys use camelCase matching JSON Schema property names.\n */\nexport const BUILTIN_CONSTRAINT_DEFINITIONS = {\n  minimum: \"number\",\n  maximum: \"number\",\n  exclusiveMinimum: \"number\",\n  exclusiveMaximum: \"number\",\n  multipleOf: \"number\",\n  minLength: \"number\",\n  maxLength: \"number\",\n  minItems: \"number\",\n  maxItems: \"number\",\n  pattern: \"string\",\n  uniqueItems: \"boolean\",\n  const: \"json\",\n  enumOptions: \"json\",\n} as const;\n\n/** Type of a built-in constraint name. */\nexport type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;\n\n/**\n * Normalizes a constraint tag name from PascalCase to camelCase.\n *\n * Lowercases the first character so that e.g. `\"Minimum\"` becomes `\"minimum\"`.\n * Callers must strip the `@` prefix before calling this function.\n *\n * @example\n * normalizeConstraintTagName(\"Minimum\")   // \"minimum\"\n * normalizeConstraintTagName(\"MinLength\") // \"minLength\"\n * normalizeConstraintTagName(\"minimum\")   // \"minimum\" (idempotent)\n */\nexport function normalizeConstraintTagName(tagName: string): string {\n  return tagName.charAt(0).toLowerCase() + tagName.slice(1);\n}\n\n/**\n * Type guard: checks whether a tag name is a known built-in constraint.\n *\n * Uses `Object.hasOwn()` rather than `in` to prevent prototype-chain\n * matches on names like `\"toString\"` or `\"constructor\"`.\n *\n * Callers should normalize with {@link normalizeConstraintTagName} first\n * if the input may be PascalCase.\n */\nexport function isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName {\n  return Object.hasOwn(BUILTIN_CONSTRAINT_DEFINITIONS, tagName);\n}\n","/**\n * Canonical Intermediate Representation (IR) types for FormSpec.\n *\n * The IR is the shared intermediate structure that both authoring surfaces\n * (chain DSL and TSDoc-annotated types) compile to. All downstream operations\n * — JSON Schema generation, UI Schema generation, constraint validation,\n * diagnostics — consume the IR exclusively.\n *\n * All types are plain, serializable objects (no live compiler references).\n *\n * @see {@link https://github.com/stripe/formspec-workspace/blob/main/scratch/design/001-canonical-ir.md}\n */\n\n// =============================================================================\n// IR VERSION\n// =============================================================================\n\n/**\n * The current IR format version. Centralized here so all canonicalizers\n * and consumers reference a single source of truth.\n */\nexport const IR_VERSION = \"0.1.0\" as const;\n\n// =============================================================================\n// UTILITY TYPES\n// =============================================================================\n\n/**\n * A JSON-serializable value. All IR nodes must be representable as JSON.\n */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\n// =============================================================================\n// PROVENANCE\n// =============================================================================\n\n/**\n * Describes the origin of an IR node.\n * Enables diagnostics that point to the source of a contradiction or error.\n */\nexport interface Provenance {\n  /** The authoring surface that produced this node. */\n  readonly surface: \"tsdoc\" | \"chain-dsl\" | \"extension\" | \"inferred\";\n  /** Absolute path to the source file. */\n  readonly file: string;\n  /** 1-based line number in the source file. */\n  readonly line: number;\n  /** 0-based column number in the source file. */\n  readonly column: number;\n  /** Length of the source span in characters (for IDE underline ranges). */\n  readonly length?: number;\n  /**\n   * The specific tag, call, or construct that produced this node.\n   * Examples: `@minimum`, `field.number({ min: 0 })`, `optional`\n   */\n  readonly tagName?: string;\n}\n\n// =============================================================================\n// PATH TARGET\n// =============================================================================\n\n/**\n * A path targeting a sub-field within a complex type.\n * Used by constraints and annotations to target nested properties.\n */\nexport interface PathTarget {\n  /**\n   * Sequence of property names forming a path from the annotated field's type\n   * to the target sub-field.\n   * e.g., `[\"value\"]` or `[\"address\", \"zip\"]`\n   */\n  readonly segments: readonly string[];\n}\n\n// =============================================================================\n// TYPE NODES\n// =============================================================================\n\n/**\n * Discriminated union of all type representations in the IR.\n */\nexport type TypeNode =\n  | PrimitiveTypeNode\n  | EnumTypeNode\n  | ArrayTypeNode\n  | ObjectTypeNode\n  | RecordTypeNode\n  | UnionTypeNode\n  | ReferenceTypeNode\n  | DynamicTypeNode\n  | CustomTypeNode;\n\n/**\n * Primitive types mapping directly to JSON Schema primitives.\n *\n * Note: integer is NOT a primitive kind — integer semantics are expressed\n * via a `multipleOf: 1` constraint on a number type.\n */\nexport interface PrimitiveTypeNode {\n  readonly kind: \"primitive\";\n  readonly primitiveKind: \"string\" | \"number\" | \"boolean\" | \"null\";\n}\n\n/** A member of a static enum type. */\nexport interface EnumMember {\n  /** The serialized value stored in data. */\n  readonly value: string | number;\n  /** Optional per-member display name. */\n  readonly displayName?: string;\n}\n\n/** Static enum type — members known at build time. */\nexport interface EnumTypeNode {\n  readonly kind: \"enum\";\n  readonly members: readonly EnumMember[];\n}\n\n/** Array type with a single items type. */\nexport interface ArrayTypeNode {\n  readonly kind: \"array\";\n  readonly items: TypeNode;\n}\n\n/** A named property within an object type. */\nexport interface ObjectProperty {\n  readonly name: string;\n  readonly type: TypeNode;\n  readonly optional: boolean;\n  /**\n   * Use-site constraints on this property.\n   * Distinct from constraints on the property's type — these are\n   * use-site constraints (e.g., `@minimum :amount 0` targets the\n   * `amount` property of a `MonetaryAmount` field).\n   */\n  readonly constraints: readonly ConstraintNode[];\n  /** Use-site annotations on this property. */\n  readonly annotations: readonly AnnotationNode[];\n  readonly provenance: Provenance;\n}\n\n/** Object type with named properties. */\nexport interface ObjectTypeNode {\n  readonly kind: \"object\";\n  /**\n   * Named properties of this object. Order is preserved from the source\n   * declaration for deterministic output.\n   */\n  readonly properties: readonly ObjectProperty[];\n  /**\n   * Whether additional properties beyond those listed are permitted.\n   * Ordinary static object types default to true under the current spec.\n   * Explicitly closed-object modes may still set this to false.\n   */\n  readonly additionalProperties: boolean;\n}\n\n/**\n * Record (dictionary) type — an object with a string index signature and no\n * named properties. Corresponds to `Record<string, T>` or `{ [k: string]: T }`.\n *\n * Emitted as `{ \"type\": \"object\", \"additionalProperties\": <value schema> }` in\n * JSON Schema per spec 003 §2.5.\n */\nexport interface RecordTypeNode {\n  readonly kind: \"record\";\n  /** The type of each value in the dictionary. */\n  readonly valueType: TypeNode;\n}\n\n/** Union type for non-enum unions. Nullable types are `T | null` using this. */\nexport interface UnionTypeNode {\n  readonly kind: \"union\";\n  readonly members: readonly TypeNode[];\n}\n\n/** Named type reference — preserved as references for `$defs`/`$ref` emission. */\nexport interface ReferenceTypeNode {\n  readonly kind: \"reference\";\n  /**\n   * The fully-qualified name of the referenced type.\n   * For TypeScript interfaces/type aliases: `\"<module>#<TypeName>\"`.\n   * For built-in types: the primitive kind string.\n   */\n  readonly name: string;\n  /**\n   * Type arguments if this is a generic instantiation.\n   * e.g., `Array<string>` → `{ name: \"Array\", typeArguments: [PrimitiveTypeNode(\"string\")] }`\n   */\n  readonly typeArguments: readonly TypeNode[];\n}\n\n/** Dynamic type — schema resolved at runtime from a named data source. */\nexport interface DynamicTypeNode {\n  readonly kind: \"dynamic\";\n  readonly dynamicKind: \"enum\" | \"schema\";\n  /** Key identifying the runtime data source or schema provider. */\n  readonly sourceKey: string;\n  /**\n   * For dynamic enums: field names whose current values are passed as\n   * parameters to the data source resolver.\n   */\n  readonly parameterFields: readonly string[];\n}\n\n/** Custom type registered by an extension. */\nexport interface CustomTypeNode {\n  readonly kind: \"custom\";\n  /**\n   * The extension-qualified type identifier.\n   * Format: `\"<vendor-prefix>/<extension-name>/<type-name>\"`\n   * e.g., `\"x-stripe/monetary/MonetaryAmount\"`\n   */\n  readonly typeId: string;\n  /**\n   * Opaque payload serialized by the extension that registered this type.\n   * Must be JSON-serializable.\n   */\n  readonly payload: JsonValue;\n}\n\n// =============================================================================\n// CONSTRAINT NODES\n// =============================================================================\n\n/**\n * Discriminated union of all constraint types.\n * Constraints are set-influencing: they narrow the set of valid values.\n */\nexport type ConstraintNode =\n  | NumericConstraintNode\n  | LengthConstraintNode\n  | PatternConstraintNode\n  | ArrayCardinalityConstraintNode\n  | EnumMemberConstraintNode\n  | ConstConstraintNode\n  | CustomConstraintNode;\n\n/**\n * Numeric constraints: bounds and multipleOf.\n *\n * `minimum` and `maximum` are inclusive; `exclusiveMinimum` and\n * `exclusiveMaximum` are exclusive bounds (matching JSON Schema 2020-12\n * semantics).\n *\n * Type applicability: may only attach to fields with `PrimitiveTypeNode(\"number\")`\n * or a `ReferenceTypeNode` that resolves to one.\n */\nexport interface NumericConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind:\n    | \"minimum\"\n    | \"maximum\"\n    | \"exclusiveMinimum\"\n    | \"exclusiveMaximum\"\n    | \"multipleOf\";\n  readonly value: number;\n  /** If present, targets a nested sub-field rather than the field itself. */\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String length and array item count constraints.\n *\n * `minLength`/`maxLength` apply to strings; `minItems`/`maxItems` apply to\n * arrays. They share the same node shape because the composition rules are\n * identical.\n *\n * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode(\"string\")`;\n * `minItems`/`maxItems` require `ArrayTypeNode`.\n */\nexport interface LengthConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"minLength\" | \"maxLength\" | \"minItems\" | \"maxItems\";\n  readonly value: number;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String pattern constraint (ECMA-262 regex without delimiters).\n *\n * Multiple `pattern` constraints on the same field compose via intersection:\n * all patterns must match simultaneously.\n *\n * Type applicability: requires `PrimitiveTypeNode(\"string\")`.\n */\nexport interface PatternConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"pattern\";\n  /** ECMA-262 regular expression, without delimiters. */\n  readonly pattern: string;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Array uniqueness constraint. */\nexport interface ArrayCardinalityConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"uniqueItems\";\n  readonly value: true;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Enum member subset constraint (refinement — only narrows). */\nexport interface EnumMemberConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"allowedMembers\";\n  readonly members: readonly (string | number)[];\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Literal-value equality constraint. */\nexport interface ConstConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"const\";\n  readonly value: JsonValue;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom constraint. */\nexport interface CustomConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<constraint-name>\"` */\n  readonly constraintId: string;\n  /** JSON-serializable payload defined by the extension. */\n  readonly payload: JsonValue;\n  /** How this constraint composes with others of the same `constraintId`. */\n  readonly compositionRule: \"intersect\" | \"override\";\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// ANNOTATION NODES\n// =============================================================================\n\n/**\n * Discriminated union of all annotation types.\n * Annotations are value-influencing: they describe or present a field\n * but do not affect which values are valid.\n */\nexport type AnnotationNode =\n  | DisplayNameAnnotationNode\n  | DescriptionAnnotationNode\n  | FormatAnnotationNode\n  | PlaceholderAnnotationNode\n  | DefaultValueAnnotationNode\n  | DeprecatedAnnotationNode\n  | FormatHintAnnotationNode\n  | CustomAnnotationNode;\n\nexport interface DisplayNameAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"displayName\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DescriptionAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"description\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/** Schema format annotation (e.g. email/date/uri). */\nexport interface FormatAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"format\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface PlaceholderAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"placeholder\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DefaultValueAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"defaultValue\";\n  /** Must be JSON-serializable and type-compatible (verified during Validate phase). */\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\nexport interface DeprecatedAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"deprecated\";\n  /** Optional deprecation message. */\n  readonly message?: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * UI rendering hint — does not affect schema validation.\n * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.\n */\nexport interface FormatHintAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"formatHint\";\n  /** Renderer-specific format identifier: \"textarea\", \"radio\", \"date\", \"color\", etc. */\n  readonly format: string;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom annotation. */\nexport interface CustomAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<annotation-name>\"` */\n  readonly annotationId: string;\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FIELD NODE\n// =============================================================================\n\n/** A single form field after canonicalization. */\nexport interface FieldNode {\n  readonly kind: \"field\";\n  /** The field's key in the data schema. */\n  readonly name: string;\n  /** The resolved type of this field. */\n  readonly type: TypeNode;\n  /** Whether this field is required in the data schema. */\n  readonly required: boolean;\n  /** Set-influencing constraints, after merging. */\n  readonly constraints: readonly ConstraintNode[];\n  /** Value-influencing annotations, after merging. */\n  readonly annotations: readonly AnnotationNode[];\n  /** Where this field was declared. */\n  readonly provenance: Provenance;\n  /**\n   * Debug only — ordered list of constraint/annotation nodes that participated\n   * in merging, including dominated ones.\n   */\n  readonly mergeHistory?: readonly {\n    readonly node: ConstraintNode | AnnotationNode;\n    readonly dominated: boolean;\n  }[];\n}\n\n// =============================================================================\n// LAYOUT NODES\n// =============================================================================\n\n/** Union of layout node types. */\nexport type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;\n\n/** A visual grouping of form elements. */\nexport interface GroupLayoutNode {\n  readonly kind: \"group\";\n  readonly label: string;\n  /** Elements contained in this group — may be fields or nested groups. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Conditional visibility based on another field's value. */\nexport interface ConditionalLayoutNode {\n  readonly kind: \"conditional\";\n  /** The field whose value triggers visibility. */\n  readonly fieldName: string;\n  /** The value that makes the condition true (SHOW). */\n  readonly value: JsonValue;\n  /** Elements shown when the condition is met. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Union of all IR element types. */\nexport type FormIRElement = FieldNode | LayoutNode;\n\n// =============================================================================\n// TYPE REGISTRY\n// =============================================================================\n\n/** A named type definition stored in the type registry. */\nexport interface TypeDefinition {\n  /** The fully-qualified reference name (key in the registry). */\n  readonly name: string;\n  /** The resolved type node. */\n  readonly type: TypeNode;\n  /** Root-level value metadata for a named type definition. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Where this type was declared. */\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FORM IR (TOP-LEVEL)\n// =============================================================================\n\n/**\n * The complete Canonical Intermediate Representation for a form.\n *\n * Output of the Canonicalize phase; input to Validate, Generate (JSON Schema),\n * and Generate (UI Schema) phases.\n *\n * Serializable to JSON — no live compiler objects.\n */\nexport interface FormIR {\n  readonly kind: \"form-ir\";\n  /**\n   * Schema version for the IR format itself.\n   * Should equal `IR_VERSION`.\n   */\n  readonly irVersion: string;\n  /** Top-level elements of the form: fields and layout nodes. */\n  readonly elements: readonly FormIRElement[];\n  /**\n   * Registry of named types referenced by fields in this form.\n   * Keys are fully-qualified type names matching `ReferenceTypeNode.name`.\n   */\n  readonly typeRegistry: Readonly<Record<string, TypeDefinition>>;\n  /** Root-level metadata for the form itself. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Provenance of the form definition itself. */\n  readonly provenance: Provenance;\n}\n","/**\n * Extension API for registering custom types, constraints, annotations,\n * and vocabulary keywords with FormSpec.\n *\n * Extensions allow third-party packages (e.g., \"Decimal\", \"DateOnly\") to\n * plug into the FormSpec pipeline. The types and factory functions defined\n * here are consumed by the FormSpec build pipeline.\n *\n * @packageDocumentation\n */\n\nimport type { JsonValue, TypeNode } from \"../types/ir.js\";\n\n// =============================================================================\n// REGISTRATION TYPES\n// =============================================================================\n\n/**\n * Registration for a custom type that maps to a JSON Schema representation.\n *\n * Custom types are referenced via {@link CustomTypeNode} in the IR and\n * resolved to JSON Schema via `toJsonSchema` during generation.\n */\nexport interface CustomTypeRegistration {\n  /** The type name, unique within the extension. */\n  readonly typeName: string;\n  /**\n   * Converts the custom type's payload into a JSON Schema fragment.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords (e.g., \"x-stripe\").\n   * @returns A JSON Schema fragment representing this type.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom constraint that maps to JSON Schema keywords.\n *\n * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.\n */\nexport interface CustomConstraintRegistration {\n  /** The constraint name, unique within the extension. */\n  readonly constraintName: string;\n  /**\n   * How this constraint composes with other constraints of the same kind.\n   * - \"intersect\": combine with logical AND (both must hold)\n   * - \"override\": last writer wins\n   */\n  readonly compositionRule: \"intersect\" | \"override\";\n  /**\n   * TypeNode kinds this constraint is applicable to, or `null` for any type.\n   * Used by the validator to emit TYPE_MISMATCH diagnostics.\n   */\n  readonly applicableTypes: readonly TypeNode[\"kind\"][] | null;\n  /**\n   * Converts the custom constraint's payload into JSON Schema keywords.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords.\n   * @returns A JSON Schema fragment with the constraint keywords.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom annotation that may produce JSON Schema keywords.\n *\n * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.\n * They describe or present a field but do not affect which values are valid.\n */\nexport interface CustomAnnotationRegistration {\n  /** The annotation name, unique within the extension. */\n  readonly annotationName: string;\n  /**\n   * Optionally converts the annotation value into JSON Schema keywords.\n   * If omitted, the annotation has no JSON Schema representation (UI-only).\n   */\n  readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.\n */\nexport interface VocabularyKeywordRegistration {\n  /** The keyword name (without vendor prefix). */\n  readonly keyword: string;\n  /** JSON Schema that describes the valid values for this keyword. */\n  readonly schema: JsonValue;\n}\n\n// =============================================================================\n// EXTENSION DEFINITION\n// =============================================================================\n\n/**\n * A complete extension definition bundling types, constraints, annotations,\n * and vocabulary keywords.\n *\n * @example\n * ```typescript\n * const monetaryExtension = defineExtension({\n *   extensionId: \"x-stripe/monetary\",\n *   types: [\n *     defineCustomType({\n *       typeName: \"Decimal\",\n *       toJsonSchema: (_payload, prefix) => ({\n *         type: \"string\",\n *         [`${prefix}-decimal`]: true,\n *       }),\n *     }),\n *   ],\n * });\n * ```\n */\nexport interface ExtensionDefinition {\n  /** Globally unique extension identifier, e.g., \"x-stripe/monetary\". */\n  readonly extensionId: string;\n  /** Custom type registrations provided by this extension. */\n  readonly types?: readonly CustomTypeRegistration[];\n  /** Custom constraint registrations provided by this extension. */\n  readonly constraints?: readonly CustomConstraintRegistration[];\n  /** Custom annotation registrations provided by this extension. */\n  readonly annotations?: readonly CustomAnnotationRegistration[];\n  /** Vocabulary keyword registrations provided by this extension. */\n  readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];\n}\n\n// =============================================================================\n// FACTORY FUNCTIONS\n// =============================================================================\n\n/**\n * Defines a complete extension. Currently an identity function that provides\n * type-checking and IDE autocompletion for the definition shape.\n *\n * @param def - The extension definition.\n * @returns The same definition, validated at the type level.\n */\nexport function defineExtension(def: ExtensionDefinition): ExtensionDefinition {\n  return def;\n}\n\n/**\n * Defines a custom type registration. Currently an identity function that\n * provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom type registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom constraint registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom constraint registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom annotation registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom annotation registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration {\n  return reg;\n}\n","/**\n * Type guards for FormSpec form elements.\n *\n * Each guard narrows a {@link FormElement} to a specific field, group, or conditional type.\n */\n\nimport type {\n  FormElement,\n  AnyField,\n  TextField,\n  NumberField,\n  BooleanField,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  Group,\n  Conditional,\n  EnumOptionValue,\n} from \"./types/elements.js\";\n\n/** Narrows a FormElement to any field type. */\nexport function isField(element: FormElement): element is AnyField {\n  return element._type === \"field\";\n}\n\n/** Narrows a FormElement to a text input field. */\nexport function isTextField(element: FormElement): element is TextField<string> {\n  return element._type === \"field\" && element._field === \"text\";\n}\n\n/** Narrows a FormElement to a numeric input field. */\nexport function isNumberField(element: FormElement): element is NumberField<string> {\n  return element._type === \"field\" && element._field === \"number\";\n}\n\n/** Narrows a FormElement to a boolean checkbox field. */\nexport function isBooleanField(element: FormElement): element is BooleanField<string> {\n  return element._type === \"field\" && element._field === \"boolean\";\n}\n\n/** Narrows a FormElement to a static enum field. */\nexport function isStaticEnumField(\n  element: FormElement\n): element is StaticEnumField<string, readonly EnumOptionValue[]> {\n  return element._type === \"field\" && element._field === \"enum\";\n}\n\n/** Narrows a FormElement to a dynamic enum field. */\nexport function isDynamicEnumField(\n  element: FormElement\n): element is DynamicEnumField<string, string> {\n  return element._type === \"field\" && element._field === \"dynamic_enum\";\n}\n\n/** Narrows a FormElement to a dynamic schema field. */\nexport function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string> {\n  return element._type === \"field\" && element._field === \"dynamic_schema\";\n}\n\n/** Narrows a FormElement to an array field. */\nexport function isArrayField(\n  element: FormElement\n): element is ArrayField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"array\";\n}\n\n/** Narrows a FormElement to an object field. */\nexport function isObjectField(\n  element: FormElement\n): element is ObjectField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"object\";\n}\n\n/** Narrows a FormElement to a visual group. */\nexport function isGroup(element: FormElement): element is Group<readonly FormElement[]> {\n  return element._type === \"group\";\n}\n\n/** Narrows a FormElement to a conditional wrapper. */\nexport function isConditional(\n  element: FormElement\n): element is Conditional<string, unknown, readonly FormElement[]> {\n  return element._type === \"conditional\";\n}\n"],"mappings":";AA+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;ACxBO,IAAM,iCAAiC;AAAA,EAC5C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,WAAW;AAAA,EACX,UAAU;AAAA,EACV,UAAU;AAAA,EACV,SAAS;AAAA,EACT,aAAa;AAAA,EACb,OAAO;AAAA,EACP,aAAa;AACf;AAgBO,SAAS,2BAA2B,SAAyB;AAClE,SAAO,QAAQ,OAAO,CAAC,EAAE,YAAY,IAAI,QAAQ,MAAM,CAAC;AAC1D;AAWO,SAAS,wBAAwB,SAAmD;AACzF,SAAO,OAAO,OAAO,gCAAgC,OAAO;AAC9D;;;ACvCO,IAAM,aAAa;;;ACsHnB,SAAS,gBAAgB,KAA+C;AAC7E,SAAO;AACT;AASO,SAAS,iBAAiB,KAAqD;AACpF,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;;;ACvJO,SAAS,QAAQ,SAA2C;AACjE,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,YAAY,SAAoD;AAC9E,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cAAc,SAAsD;AAClF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,eAAe,SAAuD;AACpF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,kBACd,SACgE;AAChE,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,mBACd,SAC6C;AAC7C,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,qBAAqB,SAA6D;AAChG,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,aACd,SACuD;AACvD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cACd,SACwD;AACxD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,QAAQ,SAAgE;AACtF,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,cACd,SACiE;AACjE,SAAO,QAAQ,UAAU;AAC3B;","names":[]}
+{"version":3,"sources":["../src/types/field-state.ts","../src/types/constraint-definitions.ts","../src/types/ir.ts","../src/extensions/index.ts","../src/guards.ts"],"sourcesContent":["import type { Validity } from \"./validity.js\";\n\n/**\n * Represents the runtime state of a single form field.\n *\n * @typeParam T - The value type of the field\n */\nexport interface FieldState<T> {\n  /** Current value of the field */\n  readonly value: T;\n\n  /** Whether the field has been modified by the user */\n  readonly dirty: boolean;\n\n  /** Whether the field has been focused and blurred */\n  readonly touched: boolean;\n\n  /** Current validity state */\n  readonly validity: Validity;\n\n  /** Validation error messages, if any */\n  readonly errors: readonly string[];\n}\n\n/**\n * Creates initial field state with default values.\n *\n * @typeParam T - The value type of the field\n * @param value - The initial value for the field\n * @returns Initial field state\n */\nexport function createInitialFieldState<T>(value: T): FieldState<T> {\n  return {\n    value,\n    dirty: false,\n    touched: false,\n    validity: \"unknown\",\n    errors: [],\n  };\n}\n","/**\n * Built-in constraint definitions for FormSpec constraint validation.\n *\n * This is the single source of truth for which constraints FormSpec\n * recognizes. Both `@formspec/build` (schema generation)\n * and `@formspec/eslint-plugin` (lint-time validation) import from here.\n */\n\n/**\n * Built-in constraint names mapped to their expected value type for parsing.\n * Constraints are surface-agnostic — they manifest as both TSDoc tags\n * (e.g., `@minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).\n *\n * Keys use camelCase matching JSON Schema property names.\n */\nexport const BUILTIN_CONSTRAINT_DEFINITIONS = {\n  minimum: \"number\",\n  maximum: \"number\",\n  exclusiveMinimum: \"number\",\n  exclusiveMaximum: \"number\",\n  multipleOf: \"number\",\n  minLength: \"number\",\n  maxLength: \"number\",\n  minItems: \"number\",\n  maxItems: \"number\",\n  pattern: \"string\",\n  uniqueItems: \"boolean\",\n  const: \"json\",\n  enumOptions: \"json\",\n} as const;\n\n/** Type of a built-in constraint name. */\nexport type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;\n\n/**\n * Normalizes a constraint tag name from PascalCase to camelCase.\n *\n * Lowercases the first character so that e.g. `\"Minimum\"` becomes `\"minimum\"`.\n * Callers must strip the `@` prefix before calling this function.\n *\n * @example\n * normalizeConstraintTagName(\"Minimum\")   // \"minimum\"\n * normalizeConstraintTagName(\"MinLength\") // \"minLength\"\n * normalizeConstraintTagName(\"minimum\")   // \"minimum\" (idempotent)\n */\nexport function normalizeConstraintTagName(tagName: string): string {\n  return tagName.charAt(0).toLowerCase() + tagName.slice(1);\n}\n\n/**\n * Type guard: checks whether a tag name is a known built-in constraint.\n *\n * Uses `Object.hasOwn()` rather than `in` to prevent prototype-chain\n * matches on names like `\"toString\"` or `\"constructor\"`.\n *\n * Callers should normalize with {@link normalizeConstraintTagName} first\n * if the input may be PascalCase.\n */\nexport function isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName {\n  return Object.hasOwn(BUILTIN_CONSTRAINT_DEFINITIONS, tagName);\n}\n","/**\n * Canonical Intermediate Representation (IR) types for FormSpec.\n *\n * The IR is the shared intermediate structure that both authoring surfaces\n * (chain DSL and TSDoc-annotated types) compile to. All downstream operations\n * — JSON Schema generation, UI Schema generation, constraint validation,\n * diagnostics — consume the IR exclusively.\n *\n * All types are plain, serializable objects (no live compiler references).\n *\n * @see {@link https://github.com/stripe/formspec-workspace/blob/main/scratch/design/001-canonical-ir.md}\n */\n\n// =============================================================================\n// IR VERSION\n// =============================================================================\n\n/**\n * The current IR format version. Centralized here so all canonicalizers\n * and consumers reference a single source of truth.\n */\nexport const IR_VERSION = \"0.1.0\" as const;\n\n// =============================================================================\n// UTILITY TYPES\n// =============================================================================\n\n/**\n * A JSON-serializable value. All IR nodes must be representable as JSON.\n */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\n// =============================================================================\n// PROVENANCE\n// =============================================================================\n\n/**\n * Describes the origin of an IR node.\n * Enables diagnostics that point to the source of a contradiction or error.\n */\nexport interface Provenance {\n  /** The authoring surface that produced this node. */\n  readonly surface: \"tsdoc\" | \"chain-dsl\" | \"extension\" | \"inferred\";\n  /** Absolute path to the source file. */\n  readonly file: string;\n  /** 1-based line number in the source file. */\n  readonly line: number;\n  /** 0-based column number in the source file. */\n  readonly column: number;\n  /** Length of the source span in characters (for IDE underline ranges). */\n  readonly length?: number;\n  /**\n   * The specific tag, call, or construct that produced this node.\n   * Examples: `@minimum`, `field.number({ min: 0 })`, `optional`\n   */\n  readonly tagName?: string;\n}\n\n// =============================================================================\n// PATH TARGET\n// =============================================================================\n\n/**\n * A path targeting a sub-field within a complex type.\n * Used by constraints and annotations to target nested properties.\n */\nexport interface PathTarget {\n  /**\n   * Sequence of property names forming a path from the annotated field's type\n   * to the target sub-field.\n   * e.g., `[\"value\"]` or `[\"address\", \"zip\"]`\n   */\n  readonly segments: readonly string[];\n}\n\n// =============================================================================\n// TYPE NODES\n// =============================================================================\n\n/**\n * Discriminated union of all type representations in the IR.\n */\nexport type TypeNode =\n  | PrimitiveTypeNode\n  | EnumTypeNode\n  | ArrayTypeNode\n  | ObjectTypeNode\n  | RecordTypeNode\n  | UnionTypeNode\n  | ReferenceTypeNode\n  | DynamicTypeNode\n  | CustomTypeNode;\n\n/**\n * Primitive types mapping directly to JSON Schema primitives.\n *\n * Note: integer is NOT a primitive kind — integer semantics are expressed\n * via a `multipleOf: 1` constraint on a number type.\n */\nexport interface PrimitiveTypeNode {\n  readonly kind: \"primitive\";\n  readonly primitiveKind: \"string\" | \"number\" | \"boolean\" | \"null\";\n}\n\n/** A member of a static enum type. */\nexport interface EnumMember {\n  /** The serialized value stored in data. */\n  readonly value: string | number;\n  /** Optional per-member display name. */\n  readonly displayName?: string;\n}\n\n/** Static enum type — members known at build time. */\nexport interface EnumTypeNode {\n  readonly kind: \"enum\";\n  readonly members: readonly EnumMember[];\n}\n\n/** Array type with a single items type. */\nexport interface ArrayTypeNode {\n  readonly kind: \"array\";\n  readonly items: TypeNode;\n}\n\n/** A named property within an object type. */\nexport interface ObjectProperty {\n  readonly name: string;\n  readonly type: TypeNode;\n  readonly optional: boolean;\n  /**\n   * Use-site constraints on this property.\n   * Distinct from constraints on the property's type — these are\n   * use-site constraints (e.g., `@minimum :amount 0` targets the\n   * `amount` property of a `MonetaryAmount` field).\n   */\n  readonly constraints: readonly ConstraintNode[];\n  /** Use-site annotations on this property. */\n  readonly annotations: readonly AnnotationNode[];\n  readonly provenance: Provenance;\n}\n\n/** Object type with named properties. */\nexport interface ObjectTypeNode {\n  readonly kind: \"object\";\n  /**\n   * Named properties of this object. Order is preserved from the source\n   * declaration for deterministic output.\n   */\n  readonly properties: readonly ObjectProperty[];\n  /**\n   * Whether additional properties beyond those listed are permitted.\n   * Ordinary static object types default to true under the current spec.\n   * Explicitly closed-object modes may still set this to false.\n   */\n  readonly additionalProperties: boolean;\n}\n\n/**\n * Record (dictionary) type — an object with a string index signature and no\n * named properties. Corresponds to `Record<string, T>` or `{ [k: string]: T }`.\n *\n * Emitted as `{ \"type\": \"object\", \"additionalProperties\": <value schema> }` in\n * JSON Schema per spec 003 §2.5.\n */\nexport interface RecordTypeNode {\n  readonly kind: \"record\";\n  /** The type of each value in the dictionary. */\n  readonly valueType: TypeNode;\n}\n\n/** Union type for non-enum unions. Nullable types are `T | null` using this. */\nexport interface UnionTypeNode {\n  readonly kind: \"union\";\n  readonly members: readonly TypeNode[];\n}\n\n/** Named type reference — preserved as references for `$defs`/`$ref` emission. */\nexport interface ReferenceTypeNode {\n  readonly kind: \"reference\";\n  /**\n   * The fully-qualified name of the referenced type.\n   * For TypeScript interfaces/type aliases: `\"<module>#<TypeName>\"`.\n   * For built-in types: the primitive kind string.\n   */\n  readonly name: string;\n  /**\n   * Type arguments if this is a generic instantiation.\n   * e.g., `Array<string>` → `{ name: \"Array\", typeArguments: [PrimitiveTypeNode(\"string\")] }`\n   */\n  readonly typeArguments: readonly TypeNode[];\n}\n\n/** Dynamic type — schema resolved at runtime from a named data source. */\nexport interface DynamicTypeNode {\n  readonly kind: \"dynamic\";\n  readonly dynamicKind: \"enum\" | \"schema\";\n  /** Key identifying the runtime data source or schema provider. */\n  readonly sourceKey: string;\n  /**\n   * For dynamic enums: field names whose current values are passed as\n   * parameters to the data source resolver.\n   */\n  readonly parameterFields: readonly string[];\n}\n\n/** Custom type registered by an extension. */\nexport interface CustomTypeNode {\n  readonly kind: \"custom\";\n  /**\n   * The extension-qualified type identifier.\n   * Format: `\"<vendor-prefix>/<extension-name>/<type-name>\"`\n   * e.g., `\"x-stripe/monetary/MonetaryAmount\"`\n   */\n  readonly typeId: string;\n  /**\n   * Opaque payload serialized by the extension that registered this type.\n   * Must be JSON-serializable.\n   */\n  readonly payload: JsonValue;\n}\n\n// =============================================================================\n// CONSTRAINT NODES\n// =============================================================================\n\n/**\n * Discriminated union of all constraint types.\n * Constraints are set-influencing: they narrow the set of valid values.\n */\nexport type ConstraintNode =\n  | NumericConstraintNode\n  | LengthConstraintNode\n  | PatternConstraintNode\n  | ArrayCardinalityConstraintNode\n  | EnumMemberConstraintNode\n  | ConstConstraintNode\n  | CustomConstraintNode;\n\n/**\n * Numeric constraints: bounds and multipleOf.\n *\n * `minimum` and `maximum` are inclusive; `exclusiveMinimum` and\n * `exclusiveMaximum` are exclusive bounds (matching JSON Schema 2020-12\n * semantics).\n *\n * Type applicability: may only attach to fields with `PrimitiveTypeNode(\"number\")`\n * or a `ReferenceTypeNode` that resolves to one.\n */\nexport interface NumericConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind:\n    | \"minimum\"\n    | \"maximum\"\n    | \"exclusiveMinimum\"\n    | \"exclusiveMaximum\"\n    | \"multipleOf\";\n  readonly value: number;\n  /** If present, targets a nested sub-field rather than the field itself. */\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String length and array item count constraints.\n *\n * `minLength`/`maxLength` apply to strings; `minItems`/`maxItems` apply to\n * arrays. They share the same node shape because the composition rules are\n * identical.\n *\n * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode(\"string\")`;\n * `minItems`/`maxItems` require `ArrayTypeNode`.\n */\nexport interface LengthConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"minLength\" | \"maxLength\" | \"minItems\" | \"maxItems\";\n  readonly value: number;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/**\n * String pattern constraint (ECMA-262 regex without delimiters).\n *\n * Multiple `pattern` constraints on the same field compose via intersection:\n * all patterns must match simultaneously.\n *\n * Type applicability: requires `PrimitiveTypeNode(\"string\")`.\n */\nexport interface PatternConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"pattern\";\n  /** ECMA-262 regular expression, without delimiters. */\n  readonly pattern: string;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Array uniqueness constraint. */\nexport interface ArrayCardinalityConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"uniqueItems\";\n  readonly value: true;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Enum member subset constraint (refinement — only narrows). */\nexport interface EnumMemberConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"allowedMembers\";\n  readonly members: readonly (string | number)[];\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Literal-value equality constraint. */\nexport interface ConstConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"const\";\n  readonly value: JsonValue;\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom constraint. */\nexport interface CustomConstraintNode {\n  readonly kind: \"constraint\";\n  readonly constraintKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<constraint-name>\"` */\n  readonly constraintId: string;\n  /** JSON-serializable payload defined by the extension. */\n  readonly payload: JsonValue;\n  /** How this constraint composes with others of the same `constraintId`. */\n  readonly compositionRule: \"intersect\" | \"override\";\n  readonly path?: PathTarget;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// ANNOTATION NODES\n// =============================================================================\n\n/**\n * Discriminated union of all annotation types.\n * Annotations are value-influencing: they describe or present a field\n * but do not affect which values are valid.\n */\nexport type AnnotationNode =\n  | DisplayNameAnnotationNode\n  | DescriptionAnnotationNode\n  | FormatAnnotationNode\n  | PlaceholderAnnotationNode\n  | DefaultValueAnnotationNode\n  | DeprecatedAnnotationNode\n  | FormatHintAnnotationNode\n  | CustomAnnotationNode;\n\nexport interface DisplayNameAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"displayName\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DescriptionAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"description\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\n/** Schema format annotation (e.g. email/date/uri). */\nexport interface FormatAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"format\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface PlaceholderAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"placeholder\";\n  readonly value: string;\n  readonly provenance: Provenance;\n}\n\nexport interface DefaultValueAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"defaultValue\";\n  /** Must be JSON-serializable and type-compatible (verified during Validate phase). */\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\nexport interface DeprecatedAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"deprecated\";\n  /** Optional deprecation message. */\n  readonly message?: string;\n  readonly provenance: Provenance;\n}\n\n/**\n * UI rendering hint — does not affect schema validation.\n * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.\n */\nexport interface FormatHintAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"formatHint\";\n  /** Renderer-specific format identifier: \"textarea\", \"radio\", \"date\", \"color\", etc. */\n  readonly format: string;\n  readonly provenance: Provenance;\n}\n\n/** Extension-registered custom annotation. */\nexport interface CustomAnnotationNode {\n  readonly kind: \"annotation\";\n  readonly annotationKind: \"custom\";\n  /** Extension-qualified ID: `\"<vendor-prefix>/<extension-name>/<annotation-name>\"` */\n  readonly annotationId: string;\n  readonly value: JsonValue;\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FIELD NODE\n// =============================================================================\n\n/** A single form field after canonicalization. */\nexport interface FieldNode {\n  readonly kind: \"field\";\n  /** The field's key in the data schema. */\n  readonly name: string;\n  /** The resolved type of this field. */\n  readonly type: TypeNode;\n  /** Whether this field is required in the data schema. */\n  readonly required: boolean;\n  /** Set-influencing constraints, after merging. */\n  readonly constraints: readonly ConstraintNode[];\n  /** Value-influencing annotations, after merging. */\n  readonly annotations: readonly AnnotationNode[];\n  /** Where this field was declared. */\n  readonly provenance: Provenance;\n  /**\n   * Debug only — ordered list of constraint/annotation nodes that participated\n   * in merging, including dominated ones.\n   */\n  readonly mergeHistory?: readonly {\n    readonly node: ConstraintNode | AnnotationNode;\n    readonly dominated: boolean;\n  }[];\n}\n\n// =============================================================================\n// LAYOUT NODES\n// =============================================================================\n\n/** Union of layout node types. */\nexport type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;\n\n/** A visual grouping of form elements. */\nexport interface GroupLayoutNode {\n  readonly kind: \"group\";\n  readonly label: string;\n  /** Elements contained in this group — may be fields or nested groups. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Conditional visibility based on another field's value. */\nexport interface ConditionalLayoutNode {\n  readonly kind: \"conditional\";\n  /** The field whose value triggers visibility. */\n  readonly fieldName: string;\n  /** The value that makes the condition true (SHOW). */\n  readonly value: JsonValue;\n  /** Elements shown when the condition is met. */\n  readonly elements: readonly FormIRElement[];\n  readonly provenance: Provenance;\n}\n\n/** Union of all IR element types. */\nexport type FormIRElement = FieldNode | LayoutNode;\n\n// =============================================================================\n// TYPE REGISTRY\n// =============================================================================\n\n/** A named type definition stored in the type registry. */\nexport interface TypeDefinition {\n  /** The fully-qualified reference name (key in the registry). */\n  readonly name: string;\n  /** The resolved type node. */\n  readonly type: TypeNode;\n  /** Root-level value metadata for a named type definition. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Where this type was declared. */\n  readonly provenance: Provenance;\n}\n\n// =============================================================================\n// FORM IR (TOP-LEVEL)\n// =============================================================================\n\n/**\n * The complete Canonical Intermediate Representation for a form.\n *\n * Output of the Canonicalize phase; input to Validate, Generate (JSON Schema),\n * and Generate (UI Schema) phases.\n *\n * Serializable to JSON — no live compiler objects.\n */\nexport interface FormIR {\n  readonly kind: \"form-ir\";\n  /**\n   * Schema version for the IR format itself.\n   * Should equal `IR_VERSION`.\n   */\n  readonly irVersion: string;\n  /** Top-level elements of the form: fields and layout nodes. */\n  readonly elements: readonly FormIRElement[];\n  /**\n   * Registry of named types referenced by fields in this form.\n   * Keys are fully-qualified type names matching `ReferenceTypeNode.name`.\n   */\n  readonly typeRegistry: Readonly<Record<string, TypeDefinition>>;\n  /** Root-level metadata for the form itself. */\n  readonly annotations?: readonly AnnotationNode[];\n  /** Provenance of the form definition itself. */\n  readonly provenance: Provenance;\n}\n","/**\n * Extension API for registering custom types, constraints, annotations,\n * and vocabulary keywords with FormSpec.\n *\n * Extensions allow third-party packages (e.g., \"Decimal\", \"DateOnly\") to\n * plug into the FormSpec pipeline. The types and factory functions defined\n * here are consumed by the FormSpec build pipeline.\n *\n * @packageDocumentation\n */\n\nimport type { BuiltinConstraintName } from \"../types/constraint-definitions.js\";\nimport type { JsonValue, TypeNode } from \"../types/ir.js\";\n\n// =============================================================================\n// REGISTRATION TYPES\n// =============================================================================\n\n/**\n * Registration for a custom type that maps to a JSON Schema representation.\n *\n * Custom types are referenced via {@link CustomTypeNode} in the IR and\n * resolved to JSON Schema via `toJsonSchema` during generation.\n */\nexport interface CustomTypeRegistration {\n  /** The type name, unique within the extension. */\n  readonly typeName: string;\n  /**\n   * Optional TypeScript surface names that should resolve to this custom type\n   * during TSDoc/class analysis. Defaults to `typeName` when omitted.\n   */\n  readonly tsTypeNames?: readonly string[];\n  /**\n   * Converts the custom type's payload into a JSON Schema fragment.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomTypeNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords (e.g., \"x-stripe\").\n   * @returns A JSON Schema fragment representing this type.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n  /**\n   * Optional broadening of built-in constraint tags so they can apply to this\n   * custom type without modifying the core built-in constraint tables.\n   */\n  readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration[];\n}\n\n/**\n * Registration for a custom constraint that maps to JSON Schema keywords.\n *\n * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.\n */\nexport interface CustomConstraintRegistration {\n  /** The constraint name, unique within the extension. */\n  readonly constraintName: string;\n  /**\n   * How this constraint composes with other constraints of the same kind.\n   * - \"intersect\": combine with logical AND (both must hold)\n   * - \"override\": last writer wins\n   */\n  readonly compositionRule: \"intersect\" | \"override\";\n  /**\n   * TypeNode kinds this constraint is applicable to, or `null` for any type.\n   * Used by the validator to emit TYPE_MISMATCH diagnostics.\n   */\n  readonly applicableTypes: readonly TypeNode[\"kind\"][] | null;\n  /**\n   * Optional precise type predicate used when kind-level applicability is too\n   * broad (for example, constraints that apply to integer-like primitives but\n   * not strings).\n   */\n  readonly isApplicableToType?: (type: TypeNode) => boolean;\n  /**\n   * Optional comparator for payloads belonging to the same custom constraint.\n   * Return values follow the `Array.prototype.sort()` contract.\n   */\n  readonly comparePayloads?: (left: JsonValue, right: JsonValue) => number;\n  /**\n   * Optional semantic family metadata for generic contradiction/broadening\n   * handling across ordered constraints.\n   */\n  readonly semanticRole?: ConstraintSemanticRole;\n  /**\n   * Converts the custom constraint's payload into JSON Schema keywords.\n   *\n   * @param payload - The opaque JSON payload from the {@link CustomConstraintNode}.\n   * @param vendorPrefix - The vendor prefix for extension keywords.\n   * @returns A JSON Schema fragment with the constraint keywords.\n   */\n  readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a custom annotation that may produce JSON Schema keywords.\n *\n * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.\n * They describe or present a field but do not affect which values are valid.\n */\nexport interface CustomAnnotationRegistration {\n  /** The annotation name, unique within the extension. */\n  readonly annotationName: string;\n  /**\n   * Optionally converts the annotation value into JSON Schema keywords.\n   * If omitted, the annotation has no JSON Schema representation (UI-only).\n   */\n  readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;\n}\n\n/**\n * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.\n */\nexport interface VocabularyKeywordRegistration {\n  /** The keyword name (without vendor prefix). */\n  readonly keyword: string;\n  /** JSON Schema that describes the valid values for this keyword. */\n  readonly schema: JsonValue;\n}\n\n/**\n * Declarative authoring-side registration for a custom TSDoc constraint tag.\n */\nexport interface ConstraintTagRegistration {\n  /** Tag name without the `@` prefix, e.g. `\"maxSigFig\"`. */\n  readonly tagName: string;\n  /** The custom constraint that this tag should produce. */\n  readonly constraintName: string;\n  /** Parser from raw TSDoc text to JSON-serializable payload. */\n  readonly parseValue: (raw: string) => JsonValue;\n  /**\n   * Optional precise applicability predicate for the field type being parsed.\n   * When omitted, the target custom constraint registration controls type\n   * applicability during validation.\n   */\n  readonly isApplicableToType?: (type: TypeNode) => boolean;\n}\n\n/**\n * Registration for mapping a built-in TSDoc tag onto a custom constraint when\n * it is used on a particular custom type.\n */\nexport interface BuiltinConstraintBroadeningRegistration {\n  /** The built-in tag being broadened, without the `@` prefix. */\n  readonly tagName: BuiltinConstraintName;\n  /** The custom constraint to emit for this built-in tag. */\n  readonly constraintName: string;\n  /** Parser from raw TSDoc text to extension payload. */\n  readonly parseValue: (raw: string) => JsonValue;\n}\n\n/**\n * Semantic metadata for ordered custom constraints that should participate in\n * the generic contradiction/broadening logic.\n */\nexport interface ConstraintSemanticRole {\n  /**\n   * Logical family identifier shared by related constraints, for example\n   * `\"decimal-bound\"` or `\"date-bound\"`.\n   */\n  readonly family: string;\n  /** Whether this constraint acts as a lower or upper bound. */\n  readonly bound: \"lower\" | \"upper\" | \"exact\";\n  /** Whether equality is allowed when comparing against the bound. */\n  readonly inclusive: boolean;\n}\n\n// =============================================================================\n// EXTENSION DEFINITION\n// =============================================================================\n\n/**\n * A complete extension definition bundling types, constraints, annotations,\n * and vocabulary keywords.\n *\n * @example\n * ```typescript\n * const monetaryExtension = defineExtension({\n *   extensionId: \"x-stripe/monetary\",\n *   types: [\n *     defineCustomType({\n *       typeName: \"Decimal\",\n *       toJsonSchema: (_payload, prefix) => ({\n *         type: \"string\",\n *         [`${prefix}-decimal`]: true,\n *       }),\n *     }),\n *   ],\n * });\n * ```\n */\nexport interface ExtensionDefinition {\n  /** Globally unique extension identifier, e.g., \"x-stripe/monetary\". */\n  readonly extensionId: string;\n  /** Custom type registrations provided by this extension. */\n  readonly types?: readonly CustomTypeRegistration[];\n  /** Custom constraint registrations provided by this extension. */\n  readonly constraints?: readonly CustomConstraintRegistration[];\n  /** Authoring-side TSDoc tag registrations provided by this extension. */\n  readonly constraintTags?: readonly ConstraintTagRegistration[];\n  /** Custom annotation registrations provided by this extension. */\n  readonly annotations?: readonly CustomAnnotationRegistration[];\n  /** Vocabulary keyword registrations provided by this extension. */\n  readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];\n}\n\n// =============================================================================\n// FACTORY FUNCTIONS\n// =============================================================================\n\n/**\n * Defines a complete extension. Currently an identity function that provides\n * type-checking and IDE autocompletion for the definition shape.\n *\n * @param def - The extension definition.\n * @returns The same definition, validated at the type level.\n */\nexport function defineExtension(def: ExtensionDefinition): ExtensionDefinition {\n  return def;\n}\n\n/**\n * Defines a custom type registration. Currently an identity function that\n * provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom type registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom constraint registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom constraint registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom TSDoc constraint tag registration.\n *\n * @param reg - The custom tag registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineConstraintTag(reg: ConstraintTagRegistration): ConstraintTagRegistration {\n  return reg;\n}\n\n/**\n * Defines a custom annotation registration. Currently an identity function\n * that provides type-checking and IDE autocompletion.\n *\n * @param reg - The custom annotation registration.\n * @returns The same registration, validated at the type level.\n */\nexport function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration {\n  return reg;\n}\n","/**\n * Type guards for FormSpec form elements.\n *\n * Each guard narrows a {@link FormElement} to a specific field, group, or conditional type.\n */\n\nimport type {\n  FormElement,\n  AnyField,\n  TextField,\n  NumberField,\n  BooleanField,\n  StaticEnumField,\n  DynamicEnumField,\n  DynamicSchemaField,\n  ArrayField,\n  ObjectField,\n  Group,\n  Conditional,\n  EnumOptionValue,\n} from \"./types/elements.js\";\n\n/** Narrows a FormElement to any field type. */\nexport function isField(element: FormElement): element is AnyField {\n  return element._type === \"field\";\n}\n\n/** Narrows a FormElement to a text input field. */\nexport function isTextField(element: FormElement): element is TextField<string> {\n  return element._type === \"field\" && element._field === \"text\";\n}\n\n/** Narrows a FormElement to a numeric input field. */\nexport function isNumberField(element: FormElement): element is NumberField<string> {\n  return element._type === \"field\" && element._field === \"number\";\n}\n\n/** Narrows a FormElement to a boolean checkbox field. */\nexport function isBooleanField(element: FormElement): element is BooleanField<string> {\n  return element._type === \"field\" && element._field === \"boolean\";\n}\n\n/** Narrows a FormElement to a static enum field. */\nexport function isStaticEnumField(\n  element: FormElement\n): element is StaticEnumField<string, readonly EnumOptionValue[]> {\n  return element._type === \"field\" && element._field === \"enum\";\n}\n\n/** Narrows a FormElement to a dynamic enum field. */\nexport function isDynamicEnumField(\n  element: FormElement\n): element is DynamicEnumField<string, string> {\n  return element._type === \"field\" && element._field === \"dynamic_enum\";\n}\n\n/** Narrows a FormElement to a dynamic schema field. */\nexport function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string> {\n  return element._type === \"field\" && element._field === \"dynamic_schema\";\n}\n\n/** Narrows a FormElement to an array field. */\nexport function isArrayField(\n  element: FormElement\n): element is ArrayField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"array\";\n}\n\n/** Narrows a FormElement to an object field. */\nexport function isObjectField(\n  element: FormElement\n): element is ObjectField<string, readonly FormElement[]> {\n  return element._type === \"field\" && element._field === \"object\";\n}\n\n/** Narrows a FormElement to a visual group. */\nexport function isGroup(element: FormElement): element is Group<readonly FormElement[]> {\n  return element._type === \"group\";\n}\n\n/** Narrows a FormElement to a conditional wrapper. */\nexport function isConditional(\n  element: FormElement\n): element is Conditional<string, unknown, readonly FormElement[]> {\n  return element._type === \"conditional\";\n}\n"],"mappings":";AA+BO,SAAS,wBAA2B,OAAyB;AAClE,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ,CAAC;AAAA,EACX;AACF;;;ACxBO,IAAM,iCAAiC;AAAA,EAC5C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,WAAW;AAAA,EACX,UAAU;AAAA,EACV,UAAU;AAAA,EACV,SAAS;AAAA,EACT,aAAa;AAAA,EACb,OAAO;AAAA,EACP,aAAa;AACf;AAgBO,SAAS,2BAA2B,SAAyB;AAClE,SAAO,QAAQ,OAAO,CAAC,EAAE,YAAY,IAAI,QAAQ,MAAM,CAAC;AAC1D;AAWO,SAAS,wBAAwB,SAAmD;AACzF,SAAO,OAAO,OAAO,gCAAgC,OAAO;AAC9D;;;ACvCO,IAAM,aAAa;;;ACkMnB,SAAS,gBAAgB,KAA+C;AAC7E,SAAO;AACT;AASO,SAAS,iBAAiB,KAAqD;AACpF,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;AAQO,SAAS,oBAAoB,KAA2D;AAC7F,SAAO;AACT;AASO,SAAS,iBAAiB,KAAiE;AAChG,SAAO;AACT;;;AC7OO,SAAS,QAAQ,SAA2C;AACjE,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,YAAY,SAAoD;AAC9E,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cAAc,SAAsD;AAClF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,eAAe,SAAuD;AACpF,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,kBACd,SACgE;AAChE,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,mBACd,SAC6C;AAC7C,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,qBAAqB,SAA6D;AAChG,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,aACd,SACuD;AACvD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,cACd,SACwD;AACxD,SAAO,QAAQ,UAAU,WAAW,QAAQ,WAAW;AACzD;AAGO,SAAS,QAAQ,SAAgE;AACtF,SAAO,QAAQ,UAAU;AAC3B;AAGO,SAAS,cACd,SACiE;AACjE,SAAO,QAAQ,UAAU;AAC3B;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formspec/core",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.17",
   "description": "Core utilities for formspec",
   "type": "module",
   "main": "./dist/index.cjs",