@formspec/build 0.1.0-alpha.42 → 0.1.0-alpha.43

package/dist/build-beta.d.ts

@@ -141,6 +141,28 @@ export declare interface BuildResult {
 
 export { BuiltinConstraintBroadeningRegistration }
 
+/**
+ * Registration for mapping a built-in TSDoc tag onto a custom constraint when
+ * it is used on a particular custom type.
+ *
+ * @public
+ */
+declare interface BuiltinConstraintBroadeningRegistration_2 {
+    /** 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) => ExtensionPayloadValue;
+}
+
+/**
+ * Type of a built-in constraint name.
+ *
+ * @public
+ */
+declare type BuiltinConstraintName = "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "minItems" | "maxItems" | "uniqueItems" | "pattern" | "const" | "enumOptions";
+
 /**
  * A Categorization element (tab-based layout).
  *
@@ -183,8 +205,64 @@ export declare interface Category {
 
 export { Conditional }
 
+/**
+ * Complete constraint configuration for a FormSpec project.
+ *
+ * @public
+ */
+declare interface ConstraintConfig {
+    /** Field type constraints */
+    fieldTypes?: FieldTypeConstraints;
+    /** Layout and structure constraints */
+    layout?: LayoutConstraints;
+    /** UI Schema feature constraints */
+    uiSchema?: UISchemaConstraints;
+    /** Field configuration option constraints */
+    fieldOptions?: FieldOptionConstraints;
+    /** Control options constraints */
+    controlOptions?: ControlOptionConstraints;
+}
+
+/**
+ * Semantic metadata for ordered custom constraints that should participate in
+ * the generic contradiction/broadening logic.
+ *
+ * @public
+ */
+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;
+}
+
 export { ConstraintTagRegistration }
 
+/**
+ * Declarative authoring-side registration for a custom TSDoc constraint tag.
+ *
+ * @public
+ */
+declare interface ConstraintTagRegistration_2 {
+    /** 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) => ExtensionPayloadValue;
+    /**
+     * 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: ExtensionApplicableType) => boolean;
+}
+
 /**
  * A Control element that binds to a JSON Schema property.
  *
@@ -205,6 +283,27 @@ export declare interface ControlElement {
     readonly [k: string]: unknown;
 }
 
+/**
+ * Control options constraints - control which JSONForms Control.options are allowed.
+ * These are renderer-specific options that may not be universally supported.
+ *
+ * @public
+ */
+declare interface ControlOptionConstraints {
+    /** format - renderer format hint (e.g., "radio", "textarea") */
+    format?: Severity;
+    /** readonly - read-only mode */
+    readonly?: Severity;
+    /** multi - multi-select for enums */
+    multi?: Severity;
+    /** showUnfocusedDescription - show description when unfocused */
+    showUnfocusedDescription?: Severity;
+    /** hideRequiredAsterisk - hide required indicator */
+    hideRequiredAsterisk?: Severity;
+    /** Custom control options (extensible dictionary) */
+    custom?: Record<string, Severity>;
+}
+
 /**
  * Creates an extension registry from a list of extension definitions.
  *
@@ -243,10 +342,129 @@ export declare function createStaticBuildContextFromProgram(program: ts.Program,
 
 export { CustomAnnotationRegistration }
 
+/**
+ * Registration for a custom annotation that may produce JSON Schema keywords.
+ *
+ * Custom annotations are referenced by FormSpec's internal custom-annotation nodes.
+ * They describe or present a field but do not affect which values are valid.
+ *
+ * @public
+ */
+declare interface CustomAnnotationRegistration_2 {
+    /** The annotation name, unique within the extension. */
+    readonly annotationName: string;
+    /**
+     * Optionally converts the annotation value into JSON Schema keywords.
+     * If omitted, the annotation has no JSON Schema representation (UI-only).
+     */
+    readonly toJsonSchema?: (value: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
+}
+
 export { CustomConstraintRegistration }
 
+/**
+ * Registration for a custom constraint that maps to JSON Schema keywords.
+ *
+ * Custom constraints are referenced by FormSpec's internal custom-constraint nodes.
+ *
+ * @public
+ */
+declare interface CustomConstraintRegistration_2 {
+    /** The constraint name, unique within the extension. */
+    readonly constraintName: string;
+    /**
+     * How this constraint composes with other constraints of the same kind.
+     * - "intersect": combine with logical AND (both must hold)
+     * - "override": last writer wins
+     */
+    readonly compositionRule: "intersect" | "override";
+    /**
+     * TypeNode kinds this constraint is applicable to, or `null` for any type.
+     * Used by the validator to emit TYPE_MISMATCH diagnostics.
+     */
+    readonly applicableTypes: readonly ExtensionApplicableType["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: ExtensionApplicableType) => boolean;
+    /**
+     * Optional comparator for payloads belonging to the same custom constraint.
+     * Return values follow the `Array.prototype.sort()` contract.
+     */
+    readonly comparePayloads?: (left: ExtensionPayloadValue, right: ExtensionPayloadValue) => number;
+    /**
+     * Optional semantic family metadata for generic contradiction/broadening
+     * handling across ordered constraints.
+     */
+    readonly semanticRole?: ConstraintSemanticRole;
+    /**
+     * Converts the custom constraint's payload into JSON Schema keywords.
+     *
+     * @param payload - The opaque JSON payload stored on the custom constraint node.
+     * @param vendorPrefix - The vendor prefix for extension keywords.
+     * @returns A JSON Schema fragment with the constraint keywords.
+     */
+    readonly toJsonSchema: (payload: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
+    /**
+     * When true, `toJsonSchema` may emit vocabulary keywords that do not carry
+     * the vendor prefix. By default, all keys returned from `toJsonSchema` must
+     * start with `${vendorPrefix}-`; setting this flag relaxes that check so
+     * the constraint can produce standard or custom vocabulary keywords such as
+     * `decimalMinimum`.
+     *
+     * Use this for constraints that define their own JSON Schema vocabulary
+     * rather than namespacing under the vendor prefix.
+     */
+    readonly emitsVocabularyKeywords?: boolean;
+}
+
 export { CustomTypeRegistration }
 
+/**
+ * Registration for a custom type that maps to a JSON Schema representation.
+ *
+ * Custom types are referenced by FormSpec's internal custom-type IR nodes and
+ * resolved to JSON Schema via `toJsonSchema` during generation.
+ *
+ * @public
+ */
+declare interface CustomTypeRegistration_2 {
+    /** The type name, unique within the extension. */
+    readonly typeName: string;
+    /**
+     * Optional TypeScript surface names that should resolve to this custom type
+     * during TSDoc/class analysis. Defaults to `typeName` when omitted.
+     */
+    readonly tsTypeNames?: readonly string[];
+    /**
+     * Converts the custom type's payload into a JSON Schema fragment.
+     *
+     * @param payload - The opaque JSON payload stored on the custom type node.
+     * @param vendorPrefix - The vendor prefix for extension keywords (e.g., "x-stripe").
+     * @returns A JSON Schema fragment representing this type.
+     */
+    readonly toJsonSchema: (payload: ExtensionPayloadValue, 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_2[];
+}
+
+/**
+ * Per-declaration metadata policy input.
+ *
+ * @public
+ */
+declare interface DeclarationMetadataPolicyInput {
+    /** Policy for JSON-facing serialized names. */
+    readonly apiName?: MetadataValuePolicyInput | undefined;
+    /** Policy for human-facing labels and titles. */
+    readonly displayName?: MetadataValuePolicyInput | undefined;
+}
+
 /**
  * Non-throwing schema generation result with structured diagnostics.
  *
@@ -317,6 +535,82 @@ export { DynamicEnumField }
 
 export { DynamicSchemaField }
 
+/**
+ * Enum-member display names remain unset unless authored explicitly.
+ *
+ * @public
+ */
+declare interface EnumMemberDisplayNameDisabledPolicyInput {
+    /** Leaves missing enum-member display names unresolved. */
+    readonly mode: "disabled";
+}
+
+/**
+ * Missing enum-member display names may be inferred.
+ *
+ * @public
+ */
+declare interface EnumMemberDisplayNameInferIfMissingPolicyInput {
+    /** Infers an enum-member display name when it is not authored explicitly. */
+    readonly mode: "infer-if-missing";
+    /** Callback used to infer the missing display name. */
+    readonly infer: EnumMemberMetadataInferenceFn;
+}
+
+/**
+ * Enum-member display-name policy input.
+ *
+ * @public
+ */
+declare type EnumMemberDisplayNamePolicyInput = EnumMemberDisplayNameDisabledPolicyInput | EnumMemberDisplayNameRequireExplicitPolicyInput | EnumMemberDisplayNameInferIfMissingPolicyInput;
+
+/**
+ * Enum members must declare display names explicitly.
+ *
+ * @public
+ */
+declare interface EnumMemberDisplayNameRequireExplicitPolicyInput {
+    /** Fails when an enum member has no authored display name. */
+    readonly mode: "require-explicit";
+}
+
+/**
+ * Build-facing context passed to enum-member metadata inference callbacks.
+ *
+ * Enum members are resolved separately from declaration-level metadata so they
+ * do not participate in the shared declaration-kind model used by TSDoc and
+ * extension metadata slots.
+ *
+ * @public
+ */
+declare interface EnumMemberMetadataInferenceContext {
+    /** Authoring surface the enum originated from. */
+    readonly surface: MetadataAuthoringSurface;
+    /** Logical member identifier used for policy inference. */
+    readonly logicalName: string;
+    /** Underlying enum value before stringification. */
+    readonly memberValue: string | number;
+    /** Optional build-only context supplied by the resolver. */
+    readonly buildContext?: unknown;
+}
+
+/**
+ * Callback used to infer enum-member display names.
+ *
+ * @public
+ */
+declare type EnumMemberMetadataInferenceFn = (context: EnumMemberMetadataInferenceContext) => string;
+
+/**
+ * User-facing enum-member metadata policy input.
+ *
+ * @public
+ */
+declare interface EnumMemberMetadataPolicyInput {
+    /** Policy for human-facing enum-member labels. */
+    readonly displayName?: EnumMemberDisplayNamePolicyInput | undefined;
+}
+
 export { EnumOption }
 
 export { EnumOptionValue }
@@ -328,8 +622,75 @@ export { EnumOptionValue }
  */
 export declare type ExtendedJSONSchema7 = JSONSchema7 & FormSpecSchemaExtensions;
 
+/**
+ * A curated type shape exposed to extension applicability hooks.
+ *
+ * This intentionally exposes only the fields needed to determine tag/type
+ * applicability without committing the entire canonical IR as public API.
+ *
+ * @public
+ */
+declare type ExtensionApplicableType = {
+    readonly kind: "primitive";
+    readonly primitiveKind: "string" | "number" | "integer" | "bigint" | "boolean" | "null";
+} | {
+    readonly kind: "custom";
+    readonly typeId: string;
+    readonly payload: ExtensionPayloadValue;
+} | {
+    readonly kind: Exclude<ExtensionTypeKind, "primitive" | "custom">;
+};
+
 export { ExtensionDefinition }
 
+/**
+ * A complete extension definition bundling types, constraints, annotations,
+ * and vocabulary keywords.
+ *
+ * @example
+ * ```typescript
+ * const monetaryExtension = defineExtension({
+ *   extensionId: "x-stripe/monetary",
+ *   types: [
+ *     defineCustomType({
+ *       typeName: "Decimal",
+ *       toJsonSchema: (_payload, prefix) => ({
+ *         type: "string",
+ *         [`${prefix}-decimal`]: true,
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare interface ExtensionDefinition_2 {
+    /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
+    readonly extensionId: string;
+    /** Custom type registrations provided by this extension. */
+    readonly types?: readonly CustomTypeRegistration_2[];
+    /** Custom constraint registrations provided by this extension. */
+    readonly constraints?: readonly CustomConstraintRegistration_2[];
+    /** Authoring-side TSDoc tag registrations provided by this extension. */
+    readonly constraintTags?: readonly ConstraintTagRegistration_2[];
+    /** Metadata-slot registrations shared by build- and lint-time analysis. */
+    readonly metadataSlots?: readonly MetadataSlotRegistration[];
+    /** Custom annotation registrations provided by this extension. */
+    readonly annotations?: readonly CustomAnnotationRegistration_2[];
+    /** Vocabulary keyword registrations provided by this extension. */
+    readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];
+}
+
+/**
+ * A JSON-serializable payload value used by extension registration hooks.
+ *
+ * @public
+ */
+declare type ExtensionPayloadValue = null | boolean | number | string | readonly ExtensionPayloadValue[] | {
+    readonly [key: string]: ExtensionPayloadValue;
+};
+
 /**
  * A registry of extensions that provides lookup by fully-qualified ID.
  *
@@ -389,10 +750,120 @@ export declare interface ExtensionRegistry {
     findAnnotation(annotationId: string): CustomAnnotationRegistration | undefined;
 }
 
+/**
+ * Top-level type kinds that extension applicability hooks may inspect.
+ *
+ * @public
+ */
+declare type ExtensionTypeKind = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
+
+/**
+ * Field configuration option constraints - control which field options are allowed.
+ *
+ * @public
+ */
+declare interface FieldOptionConstraints {
+    /** label - field label text */
+    label?: Severity;
+    /** placeholder - input placeholder text */
+    placeholder?: Severity;
+    /** required - whether field is required */
+    required?: Severity;
+    /** minValue - minimum value for numbers */
+    minValue?: Severity;
+    /** maxValue - maximum value for numbers */
+    maxValue?: Severity;
+    /** minItems - minimum array length */
+    minItems?: Severity;
+    /** maxItems - maximum array length */
+    maxItems?: Severity;
+}
+
+/**
+ * Field type constraints - control which field types are allowed.
+ * Fine-grained control over each DSL field builder.
+ *
+ * @public
+ */
+declare interface FieldTypeConstraints {
+    /** field.text() - basic text input */
+    text?: Severity;
+    /** field.number() - numeric input */
+    number?: Severity;
+    /** field.boolean() - checkbox/toggle */
+    boolean?: Severity;
+    /** field.enum() with literal options */
+    staticEnum?: Severity;
+    /** field.dynamicEnum() - runtime-fetched options */
+    dynamicEnum?: Severity;
+    /** field.dynamicSchema() - runtime-fetched schema */
+    dynamicSchema?: Severity;
+    /** field.array() / field.arrayWithConfig() */
+    array?: Severity;
+    /** field.object() / field.objectWithConfig() */
+    object?: Severity;
+}
+
 export { FormElement }
 
 export { FormSpec }
 
+/**
+ * Top-level FormSpec configuration file structure.
+ * The .formspec.yml file uses this structure.
+ *
+ * @public
+ */
+export declare interface FormSpecConfig {
+    /**
+     * Extension definitions providing custom types, constraints,
+     * annotations, and vocabulary keywords.
+     */
+    readonly extensions?: readonly ExtensionDefinition_2[];
+    /** Constraint surface configuration — controls which field types,
+     * layouts, UI features, and field/control options are allowed. */
+    readonly constraints?: ConstraintConfig;
+    /**
+     * Metadata inference and naming policy. Controls how apiName,
+     * displayName, and plural forms are derived when not authored.
+     */
+    readonly metadata?: MetadataPolicyInput_2;
+    /**
+     * Vendor prefix for extension-emitted JSON Schema keywords.
+     * Must start with "x-".
+     * @defaultValue "x-formspec"
+     */
+    readonly vendorPrefix?: string;
+    /**
+     * JSON Schema representation for static enums.
+     * - "enum": flat { "enum": ["a", "b"] }
+     * - "oneOf": { "oneOf": [{ "const": "a" }, ...] }
+     * @defaultValue "enum"
+     */
+    readonly enumSerialization?: "enum" | "oneOf";
+    /**
+     * Per-package configuration overrides for monorepos.
+     * Keys are glob patterns matched against file paths relative to
+     * the config file's directory. Values merge with root settings.
+     */
+    readonly packages?: Readonly<Record<string, FormSpecPackageOverride>>;
+}
+
+/**
+ * Per-package overrides that merge with the root config.
+ * Only settings that genuinely vary per package are overridable.
+ *
+ * @public
+ */
+declare interface FormSpecPackageOverride {
+    /** Override constraint surface for this package. */
+    readonly constraints?: ConstraintConfig;
+    /** Override enum serialization for this package. */
+    readonly enumSerialization?: "enum" | "oneOf";
+    /** Override metadata policy for this package. */
+    readonly metadata?: MetadataPolicyInput_2;
+}
+
 /**
  * Extension properties for custom FormSpec constraint tags.
  *
@@ -1091,6 +1562,222 @@ export declare interface LabelElement {
     readonly [k: string]: unknown;
 }
 
+/**
+ * Layout and structure constraints - control grouping, conditionals, nesting.
+ *
+ * @public
+ */
+declare interface LayoutConstraints {
+    /** group() - visual grouping of fields */
+    group?: Severity;
+    /** when() - conditional field visibility */
+    conditionals?: Severity;
+    /** Maximum nesting depth for objects/arrays (0 = flat only) */
+    maxNestingDepth?: number;
+}
+
+/**
+ * JSONForms layout type constraints.
+ *
+ * @public
+ */
+declare interface LayoutTypeConstraints {
+    /** VerticalLayout - stack elements vertically */
+    VerticalLayout?: Severity;
+    /** HorizontalLayout - arrange elements horizontally */
+    HorizontalLayout?: Severity;
+    /** Group - visual grouping with label */
+    Group?: Severity;
+    /** Categorization - tabbed/wizard interface */
+    Categorization?: Severity;
+    /** Category - individual tab/step in Categorization */
+    Category?: Severity;
+}
+
+/**
+ * Authoring surfaces that can contribute metadata.
+ *
+ * @public
+ */
+declare type MetadataAuthoringSurface = "tsdoc" | "chain-dsl";
+
+/**
+ * Declaration categories that metadata policy can target.
+ *
+ * @public
+ */
+declare type MetadataDeclarationKind = "type" | "field" | "method";
+
+/**
+ * Build-facing context passed to metadata inference callbacks.
+ *
+ * `buildContext` is intentionally opaque so browser/runtime packages do not
+ * need to depend on TypeScript compiler types.
+ *
+ * @public
+ */
+declare interface MetadataInferenceContext {
+    /** Authoring surface the metadata is being resolved for. */
+    readonly surface: MetadataAuthoringSurface;
+    /** Declaration kind currently being resolved. */
+    readonly declarationKind: MetadataDeclarationKind;
+    /** Logical identifier before any metadata policy is applied. */
+    readonly logicalName: string;
+    /** Optional build-only context supplied by the resolver. */
+    readonly buildContext?: unknown;
+}
+
+/**
+ * Callback used to infer a scalar metadata value.
+ *
+ * @public
+ */
+declare type MetadataInferenceFn = (context: MetadataInferenceContext) => string;
+
+/**
+ * Context passed to pluralization callbacks.
+ *
+ * @public
+ */
+declare interface MetadataPluralizationContext extends MetadataInferenceContext {
+    /** Singular value that pluralization should derive from. */
+    readonly singular: string;
+}
+
+/**
+ * Pluralization disabled.
+ *
+ * @public
+ */
+declare interface MetadataPluralizationDisabledPolicyInput {
+    /** Disables automatic plural-value generation. */
+    readonly mode?: "disabled" | undefined;
+}
+
+/**
+ * Callback used to derive plural metadata from a singular value.
+ *
+ * @public
+ */
+declare type MetadataPluralizationFn = (context: MetadataPluralizationContext) => string;
+
+/**
+ * Pluralization may be inferred when absent.
+ *
+ * @public
+ */
+declare interface MetadataPluralizationInferIfMissingPolicyInput {
+    /** Infers plural values whenever no explicit plural is present. */
+    readonly mode: "infer-if-missing";
+    /** Callback that derives a plural form from the resolved singular value. */
+    readonly inflect: MetadataPluralizationFn;
+}
+
+/**
+ * Pluralization policy input.
+ *
+ * @public
+ */
+declare type MetadataPluralizationPolicyInput = MetadataPluralizationDisabledPolicyInput | MetadataPluralizationRequireExplicitPolicyInput | MetadataPluralizationInferIfMissingPolicyInput;
+
+/**
+ * Pluralization must be authored explicitly.
+ *
+ * @public
+ */
+declare interface MetadataPluralizationRequireExplicitPolicyInput {
+    /** Requires plural values to be authored directly. */
+    readonly mode: "require-explicit";
+}
+
+/**
+ * User-facing metadata policy configuration.
+ *
+ * @public
+ */
+declare interface MetadataPolicyInput_2 {
+    /** Policy applied to named types and the analyzed root declaration. */
+    readonly type?: DeclarationMetadataPolicyInput | undefined;
+    /** Policy applied to fields and object properties. */
+    readonly field?: DeclarationMetadataPolicyInput | undefined;
+    /** Policy applied to callable/method declarations. */
+    readonly method?: DeclarationMetadataPolicyInput | undefined;
+    /** Policy applied to enum-member display names during build-time IR resolution. */
+    readonly enumMember?: EnumMemberMetadataPolicyInput | undefined;
+}
+
+/**
+ * Supported qualifier registration for an extensible metadata slot.
+ *
+ * @public
+ */
+declare interface MetadataQualifierRegistration {
+    /** Qualifier text without the leading colon. */
+    readonly qualifier: string;
+    /**
+     * Optional source qualifier to use as the base input for this qualifier's
+     * inference hook. Defaults to the slot's bare/default value when omitted.
+     */
+    readonly sourceQualifier?: string | undefined;
+    /** Optional inference hook for this qualified value. */
+    readonly inferValue?: MetadataSlotInferenceFn | undefined;
+}
+
+/**
+ * Stable slot identifier for extensible metadata analysis.
+ *
+ * @public
+ */
+declare type MetadataSlotId = string;
+
+/**
+ * Context passed to extensible metadata inference hooks.
+ *
+ * @public
+ */
+declare interface MetadataSlotInferenceContext extends MetadataInferenceContext {
+    /** Stable logical slot identifier. */
+    readonly slotId: MetadataSlotId;
+    /** Tag name associated with the slot, without the `@` prefix. */
+    readonly tagName: string;
+    /** Optional qualifier being inferred (for example `plural`). */
+    readonly qualifier?: string | undefined;
+    /** Resolved bare/default value used as the base input for derived qualifiers. */
+    readonly baseValue?: string | undefined;
+}
+
+/**
+ * Callback used to infer an extensible metadata slot value.
+ *
+ * @public
+ */
+declare type MetadataSlotInferenceFn = (context: MetadataSlotInferenceContext) => string;
+
+/**
+ * Extensible metadata slot definition shared across build- and lint-time analysis.
+ *
+ * @public
+ */
+declare interface MetadataSlotRegistration {
+    /** Stable logical slot identifier. */
+    readonly slotId: MetadataSlotId;
+    /** Tag name associated with this slot, without the `@` prefix. */
+    readonly tagName: string;
+    /** Declaration kinds where the slot is meaningful. */
+    readonly declarationKinds: readonly MetadataDeclarationKind[];
+    /** Whether a bare tag without a qualifier is supported. Defaults to true. */
+    readonly allowBare?: boolean | undefined;
+    /** Supported qualifiers for this slot. */
+    readonly qualifiers?: readonly MetadataQualifierRegistration[] | undefined;
+    /** Optional inference hook for the bare/default slot value. */
+    readonly inferValue?: MetadataSlotInferenceFn | undefined;
+    /**
+     * Optional applicability hook for declaration-specific rules beyond
+     * declaration kind. `buildContext` may carry compiler objects.
+     */
+    readonly isApplicable?: ((context: MetadataInferenceContext) => boolean) | undefined;
+}
+
 /**
  * Supported declaration kinds for standalone metadata resolution.
  *
@@ -1102,6 +1789,51 @@ export declare interface LabelElement {
  */
 export declare type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
 
+/**
+ * Scalar metadata disabled unless provided explicitly elsewhere.
+ *
+ * @public
+ */
+declare interface MetadataValueDisabledPolicyInput {
+    /** Disables inference for this scalar metadata value. */
+    readonly mode?: "disabled" | undefined;
+    /** Optional policy controlling plural forms of this scalar value. */
+    readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
+}
+
+/**
+ * Scalar metadata may be inferred when missing.
+ *
+ * @public
+ */
+declare interface MetadataValueInferIfMissingPolicyInput {
+    /** Infers this scalar metadata value when it is not authored explicitly. */
+    readonly mode: "infer-if-missing";
+    /** Callback used to infer the missing singular value. */
+    readonly infer: MetadataInferenceFn;
+    /** Optional policy controlling plural forms of this scalar value. */
+    readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
+}
+
+/**
+ * Scalar metadata policy input.
+ *
+ * @public
+ */
+declare type MetadataValuePolicyInput = MetadataValueDisabledPolicyInput | MetadataValueRequireExplicitPolicyInput | MetadataValueInferIfMissingPolicyInput;
+
+/**
+ * Scalar metadata must be authored explicitly.
+ *
+ * @public
+ */
+declare interface MetadataValueRequireExplicitPolicyInput {
+    /** Requires this scalar metadata value to be authored directly. */
+    readonly mode: "require-explicit";
+    /** Optional policy controlling plural forms of this scalar value. */
+    readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
+}
+
 /**
  * Result of generating schemas from a mixed-authoring composition.
  *
@@ -1208,6 +1940,18 @@ export declare interface RuleConditionSchema {
     allOf?: RuleConditionSchema[];
 }
 
+/**
+ * JSONForms rule constraints.
+ *
+ * @public
+ */
+declare interface RuleConstraints {
+    /** Whether rules are enabled at all */
+    enabled?: Severity;
+    /** Fine-grained control over rule effects */
+    effects?: RuleEffectConstraints;
+}
+
 /**
  * JSON Forms UI Schema type definitions.
  *
@@ -1223,6 +1967,22 @@ export declare interface RuleConditionSchema {
  */
 export declare type RuleEffect = "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
 
+/**
+ * JSONForms rule effect constraints.
+ *
+ * @public
+ */
+declare interface RuleEffectConstraints {
+    /** SHOW - show element when condition is true */
+    SHOW?: Severity;
+    /** HIDE - hide element when condition is true */
+    HIDE?: Severity;
+    /** ENABLE - enable element when condition is true */
+    ENABLE?: Severity;
+    /** DISABLE - disable element when condition is true */
+    DISABLE?: Severity;
+}
+
 /**
  * Condition for a rule.
  *
@@ -1254,6 +2014,16 @@ export declare interface SchemaGenerationTarget {
  */
 export declare type SchemaSourceDeclaration = ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
 
+/**
+ * Severity level for constraint violations.
+ * - "error": Violation fails validation
+ * - "warn": Violation emits warning but passes
+ * - "off": Feature is allowed (no violation)
+ *
+ * @public
+ */
+declare type Severity = "error" | "warn" | "off";
+
 /**
  * Supported compiler context for static build-time analysis workflows.
  *
@@ -1280,21 +2050,33 @@ export { StaticEnumField }
  * @public
  */
 export declare interface StaticSchemaGenerationOptions {
+    /**
+     * FormSpec project configuration. When provided, resolves `extensionRegistry`,
+     * `vendorPrefix`, `enumSerialization`, and `metadata` from the config object.
+     * Direct options take precedence over config values.
+     */
+    readonly config?: FormSpecConfig | undefined;
     /**
      * Registry used to resolve custom types, constraints, and annotations.
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
      */
     readonly extensionRegistry?: ExtensionRegistry | undefined;
     /**
      * Vendor prefix for emitted extension keywords.
      * @defaultValue "x-formspec"
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
      */
     readonly vendorPrefix?: string | undefined;
     /**
      * JSON Schema representation to use for static enums.
      * @defaultValue "enum"
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
      */
     readonly enumSerialization?: "enum" | "oneOf";
-    /** Metadata resolution policy for static schema generation. */
+    /**
+     * Metadata resolution policy for static schema generation.
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
+     */
     readonly metadata?: MetadataPolicyInput | undefined;
     /** Discriminator-specific schema generation behavior. */
     readonly discriminator?: DiscriminatorResolutionOptions | undefined;
@@ -1309,6 +2091,18 @@ export { TextField }
  */
 export declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout | Categorization;
 
+/**
+ * UI Schema feature constraints - control JSONForms-specific features.
+ *
+ * @public
+ */
+declare interface UISchemaConstraints {
+    /** Layout type constraints */
+    layouts?: LayoutTypeConstraints;
+    /** Rule (conditional) constraints */
+    rules?: RuleConstraints;
+}
+
 /**
  * Union of all UI Schema element types.
  *
@@ -1439,6 +2233,18 @@ export declare interface VerticalLayout {
     readonly [k: string]: unknown;
 }
 
+/**
+ * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
+ *
+ * @public
+ */
+declare interface VocabularyKeywordRegistration {
+    /** The keyword name (without vendor prefix). */
+    readonly keyword: string;
+    /** JSON Schema that describes the valid values for this keyword. */
+    readonly schema: ExtensionPayloadValue;
+}
+
 /**
  * Builds and writes both JSON Schema and UI Schema files to disk.
  *