@formspec/build 0.1.0-alpha.5 → 0.1.0-alpha.50

package/dist/build.d.ts

@@ -2,7 +2,7 @@
  * `@formspec/build` - Build tools for FormSpec
  *
  * This package provides generators to compile FormSpec forms into:
- * - JSON Schema (for validation)
+ * - JSON Schema 2020-12 (for validation)
  * - JSON Forms UI Schema (for rendering)
  *
  * @example
@@ -23,8 +23,37 @@
  * @packageDocumentation
  */
 
-import type { FormElement } from '@formspec/core';
-import type { FormSpec } from '@formspec/core';
+import { AnyField } from '@formspec/core';
+import { ArrayField } from '@formspec/core';
+import { BooleanField } from '@formspec/core';
+import { BuiltinConstraintBroadeningRegistration } from '@formspec/core';
+import { Conditional } from '@formspec/core';
+import { ConstraintTagRegistration } from '@formspec/core';
+import { CustomAnnotationRegistration } from '@formspec/core';
+import { CustomConstraintRegistration } from '@formspec/core';
+import { CustomTypeRegistration } from '@formspec/core';
+import { DynamicEnumField } from '@formspec/core';
+import { DynamicSchemaField } from '@formspec/core';
+import { EnumOption } from '@formspec/core';
+import { EnumOptionValue } from '@formspec/core';
+import { ExtensionDefinition } from '@formspec/core';
+import { FormElement } from '@formspec/core';
+import { FormSpec } from '@formspec/core';
+import { Group } from '@formspec/core';
+import type { MetadataPolicyInput } from '@formspec/core';
+import { NumberField } from '@formspec/core';
+import { ObjectField } from '@formspec/core';
+import type { ResolvedMetadata } from '@formspec/core';
+import { StaticEnumField } from '@formspec/core';
+import { TextField } from '@formspec/core';
+import * as ts from 'typescript';
+import { z } from 'zod';
+
+export { AnyField }
+
+export { ArrayField }
+
+export { BooleanField }
 
 /**
  * Builds both JSON Schema and UI Schema from a FormSpec.
@@ -52,246 +81,2269 @@ import type { FormSpec } from '@formspec/core';
  *
  * @param form - The FormSpec to build schemas from
  * @returns Object containing both jsonSchema and uiSchema
+ *
+ * @public
+ */
+export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options?: BuildFormSchemasOptions): BuildResult;
+
+/**
+ * Options for building schemas from a FormSpec.
+ *
+ * Currently identical to `GenerateJsonSchemaOptions`. Defined separately so the
+ * Chain DSL surface can grow independently in the future if needed.
+ *
+ * @public
+ */
+export declare interface BuildFormSchemasOptions extends GenerateJsonSchemaOptions, GenerateUiSchemaOptions {
+}
+
+/**
+ * Builds JSON Schema and UI Schema from a TSDoc-derived model with ChainDSL
+ * field overlays.
+ *
+ * Overlays are matched by field name. The static model wins for structure,
+ * ordering, and constraints; ChainDSL overlays may contribute dynamic runtime
+ * field metadata such as dynamic enum or dynamic schema keywords, and may fill
+ * in missing annotations.
+ *
+ * @public
+ */
+export declare function buildMixedAuthoringSchemas(options: BuildMixedAuthoringSchemasOptions): MixedAuthoringSchemas;
+
+/**
+ * Options for generating mixed-authoring schemas.
+ *
+ * The `typeName` can resolve to a class, interface, or object type alias, just
+ * like `generateSchemas()`.
+ *
+ * @public
+ */
+export declare interface BuildMixedAuthoringSchemasOptions extends StaticSchemaGenerationOptions {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the class, interface, or type alias to analyze. */
+    readonly typeName: string;
+    /** ChainDSL overlays to apply to the static model. Groups and conditionals are flattened by field name. */
+    readonly overlays: FormSpec<readonly FormElement[]>;
+}
+
+/**
+ * Result of building form schemas.
+ *
+ * @public
+ */
+export declare interface BuildResult {
+    /** JSON Schema 2020-12 for validation */
+    readonly jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    readonly uiSchema: UISchema;
+}
+
+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).
+ *
+ * @public
+ */
+export declare interface Categorization {
+    /** Discriminator identifying a categorization layout. */
+    readonly type: "Categorization";
+    /** Categories rendered as tabs or steps. */
+    readonly elements: Category[];
+    /** Optional label for the overall categorization container. */
+    readonly label?: string | undefined;
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific categorization options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+/**
+ * A Category element, used inside a Categorization layout.
+ *
+ * @public
+ */
+export declare interface Category {
+    /** Discriminator identifying a category inside a categorization layout. */
+    readonly type: "Category";
+    /** Category label shown in tabs or step navigation. */
+    readonly label: string;
+    /** Child elements rendered inside the category. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific category options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+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.
+ *
+ * @public
+ */
+export declare interface ControlElement {
+    /** Discriminator identifying a JSON Forms control element. */
+    readonly type: "Control";
+    /** JSON Pointer scope that this control binds to. */
+    readonly scope: string;
+    /** Optional label override, or `false` to suppress the label. */
+    readonly label?: string | false | undefined;
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific control options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    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.
+ *
+ * The registry indexes all types, constraints, and annotations by their
+ * fully-qualified IDs (`<extensionId>/<name>`) for O(1) lookup during
+ * generation and validation.
+ *
+ * @param extensions - The extension definitions to register.
+ * @returns An {@link ExtensionRegistry} instance.
+ * @throws If duplicate type/constraint/annotation IDs are detected across extensions.
+ *
+ * @public
+ */
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): MutableExtensionRegistry;
+
+/**
+ * Creates a supported static build context for a source file.
+ *
+ * @param filePath - Entry TypeScript source file used for export resolution
+ * @returns Reusable build context containing the program, checker, and source file
+ *
+ * @public
+ */
+export declare function createStaticBuildContext(filePath: string): StaticBuildContext;
+
+/**
+ * Creates a supported static build context from an existing host-owned program.
+ *
+ * @param program - Existing TypeScript program supplied by the caller
+ * @param filePath - Entry TypeScript source file used for export resolution
+ * @returns Reusable build context containing the program, checker, and source file
+ *
+ * @public
+ */
+export declare function createStaticBuildContextFromProgram(program: ts.Program, filePath: string): StaticBuildContext;
+
+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.
+     * @deprecated Prefer `brand` for structural detection or type parameters
+     * on `defineCustomType<T>()` for symbol-based detection. String name
+     * matching will be removed in a future major version.
+     */
+    readonly tsTypeNames?: readonly string[];
+    /**
+     * Optional brand identifier for structural type detection.
+     *
+     * When provided, the type resolver checks `type.getProperties()` for a
+     * computed property whose name matches this identifier. This is more
+     * reliable than `tsTypeNames` for aliased branded types because it does not
+     * depend on the local type name.
+     *
+     * Brand detection is attempted after name-based resolution (`tsTypeNames`)
+     * as a structural fallback. If both match, name-based resolution wins.
+     *
+     * The value should match the identifier text of a `unique symbol` declaration
+     * used as a computed property key on the branded type. For example, if the
+     * type is `string & { readonly [__decimalBrand]: true }`, the brand is
+     * `"__decimalBrand"`.
+     *
+     * Brand identifiers are stored as plain strings in the extension registry, so
+     * they must be unique across the extensions loaded into the same build.
+     *
+     * Note: `"__integerBrand"` is reserved for the builtin Integer type.
+     */
+    readonly brand?: 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.
+ *
+ * @public
+ */
+export declare interface DetailedClassSchemasResult {
+    /** Whether schema generation completed without error-severity diagnostics. */
+    readonly ok: boolean;
+    /** Collected analysis and validation diagnostics for this target. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** JSON Schema 2020-12 for validation, when generation succeeds. */
+    readonly jsonSchema?: JsonSchema2020 | undefined;
+    /** JSON Forms UI Schema for rendering, when generation succeeds. */
+    readonly uiSchema?: UISchema | undefined;
+}
+
+/**
+ * Result for a single target in a batch generation request.
+ *
+ * @public
+ */
+export declare interface DetailedSchemaGenerationTargetResult extends DetailedClassSchemasResult {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias that was analyzed. */
+    readonly typeName: string;
+}
+
+/**
+ * Generated schemas for a discovered declaration or signature type.
+ *
+ * `uiSchema` is `null` when the discovered type does not have an object-shaped
+ * root that can be represented as a JSON Forms layout.
+ *
+ * @public
+ */
+export declare interface DiscoveredTypeSchemas {
+    /** JSON Schema 2020-12 for the resolved type. */
+    readonly jsonSchema: JsonSchema2020;
+    /** UI Schema for object-shaped roots, or `null` when not applicable. */
+    readonly uiSchema: UISchema | null;
+    /**
+     * Resolved type-level metadata used during generation, when available.
+     *
+     * This preserves explicit and inferred naming metadata such as singular and
+     * plural API/display names for consumers that need the resolved values in
+     * addition to the emitted schema artifacts.
+     */
+    readonly resolvedMetadata?: ResolvedMetadata | undefined;
+}
+
+/**
+ * Discriminator-specific schema generation options.
+ *
+ * @public
+ */
+export declare interface DiscriminatorResolutionOptions {
+    /**
+     * Optional prefix applied only to metadata-derived discriminator values.
+     *
+     * Literal discriminator identities taken directly from a bound type remain
+     * unchanged.
+     */
+    readonly apiNamePrefix?: string | undefined;
+}
+
+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 }
+
+/**
+ * JSON Schema with FormSpec extension properties for arbitrary `x-formspec-*` keys.
+ *
+ * @public
+ */
+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.
+ *
+ * Type IDs follow the format: `<extensionId>/<typeName>`
+ * Constraint IDs follow the format: `<extensionId>/<constraintName>`
+ * Annotation IDs follow the format: `<extensionId>/<annotationName>`
+ *
+ * @public
+ */
+export declare interface ExtensionRegistry {
+    /** The extensions registered in this registry (in registration order). */
+    readonly extensions: readonly ExtensionDefinition[];
+    /**
+     * Look up a custom type registration by its fully-qualified type ID.
+     *
+     * @param typeId - The fully-qualified type ID (e.g., "x-stripe/monetary/Decimal").
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findType(typeId: string): CustomTypeRegistration | undefined;
+    /**
+     * Look up a custom type registration by a TypeScript-facing type name.
+     *
+     * This is used during TSDoc/class analysis to resolve extension-defined
+     * custom types from source-level declarations.
+     */
+    findTypeByName(typeName: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type registration by a brand identifier.
+     *
+     * This is used during class analysis to resolve extension-defined custom types
+     * via structural brand detection (`unique symbol` computed property keys).
+     * Brand identifiers are stored as plain strings, so they must be unique
+     * across all extensions loaded into the registry.
+     *
+     * @param brand - The identifier text of the `unique symbol` brand variable.
+     */
+    findTypeByBrand(brand: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type by its TypeScript symbol identity.
+     *
+     * Built from `defineCustomType<T>()` type parameter extraction in the config file.
+     * This is the most precise detection path — it uses `ts.Symbol` identity, which is
+     * immune to import aliases and name collisions.
+     *
+     * Returns `undefined` until {@link MutableExtensionRegistry.setSymbolMap} has been
+     * called (i.e., before the TypeScript program is available), or when the symbol is
+     * not registered via a type parameter.
+     *
+     * @param symbol - The canonical TypeScript symbol to look up.
+     */
+    findTypeBySymbol(symbol: ts.Symbol): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom constraint registration by its fully-qualified constraint ID.
+     *
+     * @param constraintId - The fully-qualified constraint ID.
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findConstraint(constraintId: string): CustomConstraintRegistration | undefined;
+    /**
+     * Look up a TSDoc custom constraint-tag registration by tag name.
+     */
+    findConstraintTag(tagName: string): {
+        readonly extensionId: string;
+        readonly registration: ConstraintTagRegistration;
+    } | undefined;
+    /**
+     * Look up built-in tag broadening for a given custom type ID.
+     */
+    findBuiltinConstraintBroadening(typeId: string, tagName: string): {
+        readonly extensionId: string;
+        readonly registration: BuiltinConstraintBroadeningRegistration;
+    } | undefined;
+    /**
+     * Look up a custom annotation registration by its fully-qualified annotation ID.
+     *
+     * @param annotationId - The fully-qualified annotation ID.
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    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";
+
+/**
+ * The result of a successful extension type lookup.
+ *
+ * Returned by {@link ExtensionRegistry.findTypeByName},
+ * {@link ExtensionRegistry.findTypeByBrand}, and
+ * {@link ExtensionRegistry.findTypeBySymbol}.
+ *
+ * @public
+ */
+export declare interface ExtensionTypeLookupResult {
+    /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
+    readonly extensionId: string;
+    /** The custom type registration matched by this lookup. */
+    readonly registration: CustomTypeRegistration;
+}
+
+/**
+ * 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.
+ *
+ * @public
+ */
+export declare type FormSpecSchemaExtensions = Record<`x-formspec-${string}`, unknown>;
+
+/**
+ * Options for generating schemas from a decorated class.
+ *
+ * @public
+ */
+export declare interface GenerateFromClassOptions extends StaticSchemaGenerationOptions {
+    /** Path to the TypeScript source file */
+    filePath: string;
+    /** Class name to analyze */
+    className: string;
+}
+
+/**
+ * Result of generating schemas from a decorated class.
+ *
+ * @public
+ */
+export declare interface GenerateFromClassResult {
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+
+/**
+ * Generates a JSON Schema 2020-12 from a FormSpec.
+ *
+ * All generation routes through the canonical IR. The chain DSL is first
+ * canonicalized to a FormIR, then the IR-based generator produces the schema.
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   field.text("name", { label: "Name", required: true }),
+ *   field.number("age", { min: 0 }),
+ * );
+ *
+ * const schema = generateJsonSchema(form);
+ * // {
+ * //   $schema: "https://json-schema.org/draft/2020-12/schema",
+ * //   type: "object",
+ * //   properties: {
+ * //     name: { type: "string", title: "Name" },
+ * //     age: { type: "number", minimum: 0 }
+ * //   },
+ * //   required: ["name"]
+ * // }
+ * ```
+ *
+ * @param form - The FormSpec to convert
+ * @returns A JSON Schema 2020-12 object
+ *
+ * @public
+ */
+export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>, options?: GenerateJsonSchemaOptions): JsonSchema2020;
+
+/**
+ * Options for generating JSON Schema from a Chain DSL form.
+ *
+ * @public
+ */
+export declare interface GenerateJsonSchemaOptions {
+    /**
+     * Vendor prefix for emitted extension keywords.
+     * @defaultValue "x-formspec"
+     */
+    readonly vendorPrefix?: string | undefined;
+    /**
+     * JSON Schema representation to use for static enums.
+     * @defaultValue "enum"
+     */
+    readonly enumSerialization?: "enum" | "oneOf";
+    /** Metadata resolution policy for chain DSL generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named TypeScript
+ * type — a decorated class, an interface with TSDoc tags, or a type alias.
+ *
+ * This is the recommended entry point. It automatically detects whether
+ * the name resolves to a class, interface, or type alias and uses the
+ * appropriate IR analysis pipeline.
+ *
+ * @example
+ * ```typescript
+ * const result = generateSchemas({
+ *   filePath: "./src/config.ts",
+ *   typeName: "DiscountConfig",
+ *   errorReporting: "throw",
+ * });
+ * ```
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type and throws when
+ * generation reports error-severity diagnostics.
+ *
+ * @param options - File path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
+ *
+ * @param options - File path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
+ * @param options - File path and type name
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemas(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates schemas for many targets and returns per-target diagnostics instead
+ * of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatch(options: GenerateSchemasBatchOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Generates schemas for many targets from an existing TypeScript program and
+ * returns per-target diagnostics instead of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatchFromProgram(options: GenerateSchemasBatchFromProgramOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Batch options for non-throwing schema generation using an existing program.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Batch options for non-throwing schema generation.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchOptions extends StaticSchemaGenerationOptions {
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
+ * @deprecated Use `generateSchemas({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasDetailed(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a decorated TypeScript class.
+ *
+ * This is a high-level entry point that handles the entire pipeline:
+ * creating a TypeScript program, finding the class, analyzing it to IR,
+ * and generating schemas — all in one call.
+ *
+ * @example
+ * ```typescript
+ * const result = generateSchemasFromClass({
+ *   filePath: "./src/forms.ts",
+ *   className: "UserForm",
+ * });
+ * console.log(result.jsonSchema);
+ * ```
+ *
+ * @param options - File path, class name, and optional compiler options
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromClass(options: GenerateFromClassOptions): GenerateFromClassResult;
+
+/**
+ * Generates schemas from a resolved declaration using the supported public
+ * static-build workflow.
+ *
+ * Named declarations reuse the same analyzer semantics as FormSpec's existing
+ * top-level generation APIs. Non-object type aliases fall back to the generic
+ * resolved-type entry point.
+ *
+ * @public
+ */
+export declare function generateSchemasFromDeclaration(options: GenerateSchemasFromDeclarationOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a resolved declaration.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromDeclarationOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration to turn into schemas. */
+    readonly declaration: SchemaSourceDeclaration;
+}
+
+/**
+ * Generates schemas for a method or function parameter type.
+ *
+ * @public
+ */
+export declare function generateSchemasFromParameter(options: GenerateSchemasFromParameterOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a method or function parameter type.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromParameterOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Parameter declaration whose type should be converted into schemas. */
+    readonly parameter: ts.ParameterDeclaration;
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program supplied by the caller.
+ *
+ * This low-level entry point lets downstream tooling reuse a host-owned
+ * `Program` for both FormSpec extraction and other TypeScript analysis.
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and throws when generation reports error-severity diagnostics.
+ *
+ * @param options - Host program, file path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ *
+ * @param options - Host program, file path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
+ * @param options - Host program, file path, and type name
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ * @deprecated Use `generateSchemasFromProgram({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgramDetailed(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
+
+/**
+ * Options for generating schemas from a named type inside an existing TypeScript program.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Path to the TypeScript source file */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze */
+    readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
+}
+
+/**
+ * Generates schemas for a method or function return type.
+ *
+ * Awaited `Promise<T>`-style return types are unwrapped before generation.
+ *
+ * @public
+ */
+export declare function generateSchemasFromReturnType(options: GenerateSchemasFromReturnTypeOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a method or function return type.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromReturnTypeOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Signature declaration whose return type should be converted into schemas. */
+    readonly declaration: ts.SignatureDeclaration;
+}
+
+/**
+ * Generates schemas from a resolved TypeScript type.
+ *
+ * This is the advanced public entry point for build tooling that already uses
+ * the TypeScript compiler API to discover types before handing them to
+ * FormSpec.
+ *
+ * @public
+ */
+export declare function generateSchemasFromType(options: GenerateSchemasFromTypeOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a resolved TypeScript type.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromTypeOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** TypeScript type to turn into schemas. */
+    readonly type: ts.Type;
+    /**
+     * Optional source node associated with the type.
+     *
+     * When provided, FormSpec uses it as the source location for provenance and
+     * inline-type analysis.
+     */
+    readonly sourceNode?: ts.Node | undefined;
+    /** Optional logical name used for anonymous roots. */
+    readonly name?: string | undefined;
+}
+
+/**
+ * Options for generating schemas from a named type (class, interface, or type alias).
+ *
+ * @public
+ */
+export declare interface GenerateSchemasOptions extends StaticSchemaGenerationOptions {
+    /** Path to the TypeScript source file */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze */
+    readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
+}
+
+/**
+ * Generates a JSON Forms UI Schema from a FormSpec.
+ *
+ * All generation routes through the canonical IR. The chain DSL is first
+ * canonicalized to a FormIR, then the IR-based generator produces the schema.
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   group("Customer",
+ *     field.text("name", { label: "Name" }),
+ *   ),
+ *   when("status", "draft",
+ *     field.text("notes", { label: "Notes" }),
+ *   ),
+ * );
+ *
+ * const uiSchema = generateUiSchema(form);
+ * // {
+ * //   type: "VerticalLayout",
+ * //   elements: [
+ * //     {
+ * //       type: "Group",
+ * //       label: "Customer",
+ * //       elements: [
+ * //         { type: "Control", scope: "#/properties/name", label: "Name" }
+ * //       ]
+ * //     },
+ * //     {
+ * //       type: "Control",
+ * //       scope: "#/properties/notes",
+ * //       label: "Notes",
+ * //       rule: {
+ * //         effect: "SHOW",
+ * //         condition: { scope: "#/properties/status", schema: { const: "draft" } }
+ * //       }
+ * //     }
+ * //   ]
+ * // }
+ * ```
+ *
+ * @param form - The FormSpec to convert
+ * @returns A JSON Forms UI Schema
+ *
+ * @public
+ */
+export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>, options?: GenerateUiSchemaOptions): UISchema;
+
+/**
+ * Options for generating a UI Schema from a Chain DSL form.
+ *
+ * @public
+ */
+export declare interface GenerateUiSchemaOptions {
+    /** Metadata resolution policy for chain DSL UI generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
+}
+
+export { Group }
+
+/**
+ * A group element with a label.
+ *
+ * @public
+ */
+export declare interface GroupLayout {
+    /** Discriminator identifying a labeled group container. */
+    readonly type: "Group";
+    /** Group label shown by compatible renderers. */
+    readonly label: string;
+    /** Child elements rendered inside the group. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific group options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+/**
+ * A horizontal layout element.
+ *
+ * @public
+ */
+export declare interface HorizontalLayout {
+    /** Discriminator identifying a horizontal layout container. */
+    readonly type: "HorizontalLayout";
+    /** Child elements rendered side by side. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific layout options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+/**
+ * A JSON Schema 2020-12 document, sub-schema, or keyword collection.
+ *
+ * This interface covers the subset of JSON Schema 2020-12 that this generator
+ * emits, plus an index signature for custom `x-formspec-*` extension keywords.
+ *
+ * @public
+ */
+export declare interface JsonSchema2020 {
+    /** Declared JSON Schema dialect URI for the document root. */
+    $schema?: string;
+    /** Reference to another schema location. */
+    $ref?: string;
+    /** Named reusable schema definitions keyed by definition name. */
+    $defs?: Record<string, JsonSchema2020>;
+    /** JSON Schema type keyword for the current node. */
+    type?: string;
+    /** Object properties keyed by property name. */
+    properties?: Record<string, JsonSchema2020>;
+    /** Property names that must be present on object values. */
+    required?: string[];
+    /** Item schema applied to array elements. */
+    items?: JsonSchema2020;
+    /** Whether, or how, additional object properties are allowed. */
+    additionalProperties?: boolean | JsonSchema2020;
+    /** Closed set of allowed scalar values. */
+    enum?: readonly (string | number)[];
+    /** Literal value the instance must equal. */
+    const?: unknown;
+    /** Schemas that must all validate successfully. */
+    allOf?: readonly JsonSchema2020[];
+    /** Schemas of which exactly one should validate successfully. */
+    oneOf?: readonly JsonSchema2020[];
+    /** Schemas of which at least one may validate successfully. */
+    anyOf?: readonly JsonSchema2020[];
+    /** Inclusive numeric lower bound. */
+    minimum?: number;
+    /** Inclusive numeric upper bound. */
+    maximum?: number;
+    /** Exclusive numeric lower bound. */
+    exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound. */
+    exclusiveMaximum?: number;
+    /** Required numeric step interval. */
+    multipleOf?: number;
+    /** Inclusive minimum string length. */
+    minLength?: number;
+    /** Inclusive maximum string length. */
+    maxLength?: number;
+    /** Inclusive minimum array length. */
+    minItems?: number;
+    /** Inclusive maximum array length. */
+    maxItems?: number;
+    /** Regular expression pattern applied to string values. */
+    pattern?: string;
+    /** Whether array elements must be unique. */
+    uniqueItems?: boolean;
+    /** Format hint for downstream validators and tooling. */
+    format?: string;
+    /** Human-readable title for the schema node. */
+    title?: string;
+    /** Human-readable description for the schema node. */
+    description?: string;
+    /** Default value suggested for the schema node. */
+    default?: unknown;
+    /** Whether the schema node is deprecated. */
+    deprecated?: boolean;
+    /** Additional vendor-prefixed extension keywords. */
+    [key: `x-${string}`]: unknown;
+}
+
+/**
+ * A JSON Schema definition (legacy subset used by Zod validator and types.ts).
+ *
+ * @public
+ */
+export declare interface JSONSchema7 {
+    /** Declared JSON Schema dialect URI for the document root. */
+    $schema?: string;
+    /** Stable identifier for the schema document or sub-schema. */
+    $id?: string;
+    /** Reference to another schema location. */
+    $ref?: string;
+    /** Human-readable title for the schema node. */
+    title?: string;
+    /** Human-readable description for the schema node. */
+    description?: string;
+    /** Whether the schema node is deprecated. */
+    deprecated?: boolean;
+    /** JSON Schema type keyword for the current node. */
+    type?: JSONSchemaType | JSONSchemaType[];
+    /** Inclusive minimum string length. */
+    minLength?: number;
+    /** Inclusive maximum string length. */
+    maxLength?: number;
+    /** Regular expression pattern applied to string values. */
+    pattern?: string;
+    /** Inclusive numeric lower bound. */
+    minimum?: number;
+    /** Inclusive numeric upper bound. */
+    maximum?: number;
+    /** Exclusive numeric lower bound. */
+    exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound. */
+    exclusiveMaximum?: number;
+    /** Closed set of allowed scalar values. */
+    enum?: readonly (string | number | boolean | null)[];
+    /** Literal value the instance must equal. */
+    const?: string | number | boolean | null;
+    /** Object properties keyed by property name. */
+    properties?: Record<string, JSONSchema7>;
+    /** Property names that must be present on object values. */
+    required?: string[];
+    /** Whether, or how, additional object properties are allowed. */
+    additionalProperties?: boolean | JSONSchema7;
+    /** Item schema or tuple schemas applied to array elements. */
+    items?: JSONSchema7 | JSONSchema7[];
+    /** Inclusive minimum array length. */
+    minItems?: number;
+    /** Inclusive maximum array length. */
+    maxItems?: number;
+    /** Schemas that must all validate successfully. */
+    allOf?: JSONSchema7[];
+    /** Schemas of which at least one may validate successfully. */
+    anyOf?: JSONSchema7[];
+    /** Schemas of which exactly one should validate successfully. */
+    oneOf?: JSONSchema7[];
+    /** Schema that must not validate successfully. */
+    not?: JSONSchema7;
+    /** Conditional branch predicate schema. */
+    if?: JSONSchema7;
+    /** Schema applied when the `if` branch matches. */
+    then?: JSONSchema7;
+    /** Schema applied when the `if` branch does not match. */
+    else?: JSONSchema7;
+    /** Format hint for downstream validators and tooling. */
+    format?: string;
+    /** Default value suggested for the schema node. */
+    default?: unknown;
+    /**
+     * Data source key for dynamic enum fields.
+     * Indicates that options should be fetched from a registered resolver.
+     */
+    "x-formspec-source"?: string;
+    /**
+     * Field names whose values are needed to fetch dynamic enum options.
+     * Used for dependent/cascading dropdowns.
+     */
+    "x-formspec-params"?: readonly string[];
+    /**
+     * Schema source identifier for dynamic schema fields.
+     * Indicates that the schema should be loaded dynamically at runtime.
+     */
+    "x-formspec-schemaSource"?: string;
+}
+
+/**
+ * Zod schema for the legacy JSON Schema 7 subset used by `@formspec/build`.
+ *
+ * @public
+ */
+export declare const jsonSchema7Schema: z.ZodType<JSONSchema7>;
+
+/**
+ * JSON Schema type definitions.
+ *
+ * These types are a subset of JSON Schema sufficient for form generation.
+ */
+/**
+ * JSON Schema primitive types.
+ *
+ * @public
+ */
+export declare type JSONSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+
+/**
+ * A Label element for displaying static text.
+ *
+ * @public
+ */
+export declare interface LabelElement {
+    /** Discriminator identifying a static text label element. */
+    readonly type: "Label";
+    /** Static text content rendered by the label element. */
+    readonly text: string;
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific label options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    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
  */
-export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>): BuildResult;
+declare type MetadataSlotId = string;
 
 /**
- * Result of building form schemas.
+ * Context passed to extensible metadata inference hooks.
+ *
+ * @public
  */
-export declare interface BuildResult {
-    /** JSON Schema for validation */
-    readonly jsonSchema: JSONSchema7;
-    /** JSON Forms UI Schema for rendering */
-    readonly uiSchema: UISchema;
+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;
 }
 
 /**
- * A Control element that binds to a JSON Schema property.
+ * Callback used to infer an extensible metadata slot value.
+ *
+ * @public
  */
-export declare interface ControlElement extends UISchemaElementBase {
-    type: "Control";
-    scope: string;
-    label?: string;
-}
+declare type MetadataSlotInferenceFn = (context: MetadataSlotInferenceContext) => string;
 
 /**
- * Generates a JSON Schema from a FormSpec.
+ * Extensible metadata slot definition shared across build- and lint-time analysis.
  *
- * @example
- * ```typescript
- * const form = formspec(
- *   field.text("name", { label: "Name", required: true }),
- *   field.number("age", { min: 0 }),
- * );
+ * @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.
  *
- * const schema = generateJsonSchema(form);
- * // {
- * //   $schema: "https://json-schema.org/draft-07/schema#",
- * //   type: "object",
- * //   properties: {
- * //     name: { type: "string", title: "Name" },
- * //     age: { type: "number", minimum: 0 }
- * //   },
- * //   required: ["name"]
- * // }
- * ```
+ * This helper is intentionally limited to named type declarations,
+ * methods/functions, and object-like properties. It does not currently expose
+ * parameter or variable metadata resolution on the public build surface.
  *
- * @param form - The FormSpec to convert
- * @returns A JSON Schema object
+ * @public
  */
-export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>): JSONSchema7;
+export declare type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
 
 /**
- * Generates a JSON Forms UI Schema from a FormSpec.
+ * Scalar metadata disabled unless provided explicitly elsewhere.
  *
- * @example
- * ```typescript
- * const form = formspec(
- *   group("Customer",
- *     field.text("name", { label: "Name" }),
- *   ),
- *   when("status", "draft",
- *     field.text("notes", { label: "Notes" }),
- *   ),
- * );
+ * @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.
  *
- * const uiSchema = generateUiSchema(form);
- * // {
- * //   type: "VerticalLayout",
- * //   elements: [
- * //     {
- * //       type: "Group",
- * //       label: "Customer",
- * //       elements: [
- * //         { type: "Control", scope: "#/properties/name", label: "Name" }
- * //       ]
- * //     },
- * //     {
- * //       type: "Control",
- * //       scope: "#/properties/notes",
- * //       label: "Notes",
- * //       rule: {
- * //         effect: "SHOW",
- * //         condition: { scope: "#/properties/status", schema: { const: "draft" } }
- * //       }
- * //     }
- * //   ]
- * // }
- * ```
+ * @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.
  *
- * @param form - The FormSpec to convert
- * @returns A JSON Forms UI Schema
+ * @public
  */
-export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>): UISchema;
+declare type MetadataValuePolicyInput = MetadataValueDisabledPolicyInput | MetadataValueRequireExplicitPolicyInput | MetadataValueInferIfMissingPolicyInput;
 
 /**
- * A group element with a label.
+ * Scalar metadata must be authored explicitly.
+ *
+ * @public
  */
-export declare interface GroupLayout extends UISchemaElementBase {
-    type: "Group";
-    label: string;
-    elements: UISchemaElement[];
+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;
 }
 
 /**
- * A horizontal layout element.
+ * Result of generating schemas from a mixed-authoring composition.
+ *
+ * @public
  */
-export declare interface HorizontalLayout extends UISchemaElementBase {
-    type: "HorizontalLayout";
-    elements: UISchemaElement[];
+export declare interface MixedAuthoringSchemas {
+    /** JSON Schema 2020-12 for validation. */
+    readonly jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering. */
+    readonly uiSchema: UISchema;
 }
 
 /**
- * A JSON Schema definition (draft-07 subset).
+ * Mutable extension registry used internally by the build pipeline.
+ *
+ * Extends {@link ExtensionRegistry} with `setSymbolMap`, which must be called
+ * after the TypeScript program is created. Consumer code should accept only
+ * the read-only {@link ExtensionRegistry} interface.
+ *
+ * @public
  */
-export declare interface JSONSchema7 {
-    $schema?: string;
-    $id?: string;
-    $ref?: string;
-    title?: string;
-    description?: string;
-    type?: JSONSchemaType | JSONSchemaType[];
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    minimum?: number;
-    maximum?: number;
-    exclusiveMinimum?: number;
-    exclusiveMaximum?: number;
-    enum?: readonly (string | number | boolean | null)[];
-    const?: string | number | boolean | null;
-    properties?: Record<string, JSONSchema7>;
-    required?: string[];
-    additionalProperties?: boolean | JSONSchema7;
-    items?: JSONSchema7 | JSONSchema7[];
-    minItems?: number;
-    maxItems?: number;
-    allOf?: JSONSchema7[];
-    anyOf?: JSONSchema7[];
-    oneOf?: JSONSchema7[];
-    not?: JSONSchema7;
-    if?: JSONSchema7;
-    then?: JSONSchema7;
-    else?: JSONSchema7;
-    format?: string;
-    default?: unknown;
-    /**
-     * Data source key for dynamic enum fields.
-     * Indicates that options should be fetched from a registered resolver.
-     */
-    "x-formspec-source"?: string;
-    /**
-     * Field names whose values are needed to fetch dynamic enum options.
-     * Used for dependent/cascading dropdowns.
-     */
-    "x-formspec-params"?: readonly string[];
+export declare interface MutableExtensionRegistry extends ExtensionRegistry {
     /**
-     * Schema source identifier for dynamic schema fields.
-     * Indicates that the schema should be loaded dynamically at runtime.
+     * Sets the symbol map built from config AST analysis.
+     *
+     * Called after the TypeScript program is created and the config file is analyzed.
+     * Prior to this call, {@link ExtensionRegistry.findTypeBySymbol} always returns
+     * `undefined`.
+     *
+     * @param map - A map from canonical `ts.Symbol` to the matching registry entry.
      */
-    "x-formspec-schemaSource"?: string;
+    setSymbolMap(map: Map<ts.Symbol, ExtensionTypeLookupResult>): void;
+}
+
+export { NumberField }
+
+export { ObjectField }
+
+/**
+ * Resolves metadata from a declaration using FormSpec's configured metadata
+ * policy for the matching declaration kind.
+ *
+ * @public
+ */
+export declare function resolveDeclarationMetadata(options: ResolveDeclarationMetadataOptions): ResolvedMetadata | undefined;
+
+/**
+ * Options for resolving metadata from a declaration against the active
+ * metadata policy.
+ *
+ * @public
+ */
+export declare interface ResolveDeclarationMetadataOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration whose metadata should be resolved. */
+    readonly declaration: MetadataSourceDeclaration;
 }
 
 /**
- * JSON Schema Draft-07 type definitions.
+ * Resolves an export from the context source file, following aliases and re-exports.
  *
- * These types are a subset of JSON Schema sufficient for form generation.
+ * @param context - Static build context created for the entry source file
+ * @param exportName - Export name to resolve. Defaults to `"default"`.
+ * @returns Resolved symbol for the export, or `null` when it cannot be found
+ *
+ * @public
  */
+export declare function resolveModuleExport(context: StaticBuildContext, exportName?: string): ts.Symbol | null;
+
 /**
- * JSON Schema primitive types.
+ * Resolves the declaration behind an export from the context source file,
+ * following aliases and re-exports. This helper is intentionally limited to
+ * declaration kinds accepted by declaration-driven schema generation.
+ *
+ * @param context - Static build context created for the entry source file
+ * @param exportName - Export name to resolve. Defaults to `"default"`.
+ * @returns Resolved class, interface, or type-alias declaration for the export,
+ * or `null` when the export does not resolve to one of those schema-source kinds
+ *
+ * @public
  */
-export declare type JSONSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+export declare function resolveModuleExportDeclaration(context: StaticBuildContext, exportName?: string): ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration | null;
 
 /**
  * Rule for conditional element visibility/enablement.
+ *
+ * @public
  */
 export declare interface Rule {
-    effect: RuleEffect;
-    condition: SchemaBasedCondition;
+    /** UI effect to apply when the rule condition matches. */
+    readonly effect: RuleEffect;
+    /** Predicate that controls when the UI effect applies. */
+    readonly condition: SchemaBasedCondition;
 }
 
 /**
- * JSON Schema subset for rule conditions.
+ * JSON Schema subset used in rule conditions.
+ *
+ * @public
  */
-declare interface RuleConditionSchema {
+export declare interface RuleConditionSchema {
+    /** Literal value the condition schema must equal. */
     const?: unknown;
+    /** Allowed values for the condition schema. */
     enum?: readonly unknown[];
+    /** JSON Schema type required by the condition schema. */
     type?: string;
+    /** Negated branch of the condition schema. */
+    not?: RuleConditionSchema;
+    /** Inclusive numeric lower bound in the condition schema. */
     minimum?: number;
+    /** Inclusive numeric upper bound in the condition schema. */
     maximum?: number;
+    /** Exclusive numeric lower bound in the condition schema. */
+    exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound in the condition schema. */
+    exclusiveMaximum?: number;
+    /** Inclusive minimum string length in the condition schema. */
+    minLength?: number;
+    /** Nested property conditions keyed by property name. */
     properties?: Record<string, RuleConditionSchema>;
+    /** Property names that must be present for the condition to match. */
+    required?: string[];
+    /** Schemas that must all match for the condition to succeed. */
     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.
+ *
+ * These are the consumer-facing TypeScript shapes. Runtime validation remains
+ * defined separately in `./schema.ts`.
+ *
+ * See: https://jsonforms.io/docs/uischema/
+ */
 /**
  * Rule effect types for conditional visibility.
+ *
+ * @public
  */
 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.
+ *
+ * @public
  */
 export declare interface SchemaBasedCondition {
-    scope: string;
-    schema: RuleConditionSchema;
+    /** JSON Pointer scope the rule evaluates against. */
+    readonly scope: string;
+    /** JSON Schema fragment evaluated at the scoped location. */
+    readonly schema: RuleConditionSchema;
+}
+
+/**
+ * A batch target for non-throwing schema generation.
+ *
+ * @public
+ */
+export declare interface SchemaGenerationTarget {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze. */
+    readonly typeName: string;
+}
+
+/**
+ * Supported declaration kinds for declaration-driven schema generation.
+ *
+ * @public
+ */
+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.
+ *
+ * This context gives consumers access to the TypeScript program, checker, and
+ * source file used to discover declarations before invoking FormSpec schema
+ * generation helpers.
+ *
+ * @public
+ */
+export declare interface StaticBuildContext {
+    /** Host-owned or FormSpec-created TypeScript program. */
+    readonly program: ts.Program;
+    /** TypeScript checker for symbol and type analysis. */
+    readonly checker: ts.TypeChecker;
+    /** Source file used as the entry module for export resolution. */
+    readonly sourceFile: ts.SourceFile;
+}
+
+export { StaticEnumField }
+
+/**
+ * Shared options for schema generation flows that support custom extensions.
+ *
+ * @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.
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
+     */
+    readonly metadata?: MetadataPolicyInput | undefined;
+    /** Discriminator-specific schema generation behavior. */
+    readonly discriminator?: DiscriminatorResolutionOptions | undefined;
+    /**
+     * Absolute path to the FormSpec config file (e.g., `formspec.config.ts`).
+     *
+     * When provided alongside a `config` that includes extensions, the build
+     * pipeline includes the config file in the TypeScript program and extracts
+     * `defineCustomType<T>()` type parameters. This enables symbol-based custom
+     * type detection — the most precise resolution path, immune to import aliases
+     * and name collisions.
+     *
+     * Obtain this from `loadFormSpecConfig()`:
+     * ```typescript
+     * const { config, configPath } = await loadFormSpecConfig();
+     * await generateSchemas({ filePath, typeName, config, configPath, errorReporting: "throw" });
+     * ```
+     */
+    readonly configPath?: string | undefined;
 }
 
+export { TextField }
+
+/**
+ * Root UI Schema (always a layout — not a Control, Category, or Label).
+ *
+ * @public
+ */
+export declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout | Categorization;
+
 /**
- * Root UI Schema (always a layout).
+ * UI Schema feature constraints - control JSONForms-specific features.
+ *
+ * @public
  */
-export declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout;
+declare interface UISchemaConstraints {
+    /** Layout type constraints */
+    layouts?: LayoutTypeConstraints;
+    /** Rule (conditional) constraints */
+    rules?: RuleConstraints;
+}
 
 /**
  * Union of all UI Schema element types.
+ *
+ * @public
  */
-export declare type UISchemaElement = ControlElement | VerticalLayout | HorizontalLayout | GroupLayout;
+export declare type UISchemaElement = ControlElement | VerticalLayout | HorizontalLayout | GroupLayout | Categorization | Category | LabelElement;
 
 /**
  * Base interface for all UI Schema elements.
+ *
+ * This is a manually maintained interface representing the common shape
+ * shared by all element types. It is kept as an interface (rather than
+ * derived from Zod) because it is the base of a discriminated union, not
+ * a union member itself.
+ *
+ * @public
  */
-declare interface UISchemaElementBase {
+export declare interface UISchemaElementBase {
+    /** Discriminator for the concrete JSON Forms element type. */
     type: UISchemaElementType;
+    /** Optional rule controlling visibility or enablement. */
     rule?: Rule;
+    /** Renderer-specific options shared by UI schema elements. */
     options?: Record<string, unknown>;
 }
 
 /**
- * JSON Forms UI Schema type definitions.
+ * UI Schema element types.
  *
- * These types define the UI layout structure for JSON Forms.
- * See: https://jsonforms.io/docs/uischema/
+ * @public
  */
+export declare type UISchemaElementType = "Control" | "VerticalLayout" | "HorizontalLayout" | "Group" | "Categorization" | "Category" | "Label";
+
 /**
- * UI Schema element types.
+ * Zod schema for the root UI Schema (layout types only).
+ *
+ * @public
+ */
+export declare const uiSchemaSchema: z.ZodType<UISchema>;
+
+/**
+ * Options for validating canonical FormIR.
+ *
+ * @public
+ */
+export declare interface ValidateIROptions {
+    /** Vendor prefix used when resolving extension-backed keywords. */
+    readonly vendorPrefix?: string;
+    /** Extension registry used to resolve custom constraints and types. */
+    readonly extensionRegistry?: ExtensionRegistry;
+}
+
+/**
+ * A machine-readable validation diagnostic returned by static schema analysis.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnostic {
+    /** Stable machine-readable diagnostic code. */
+    readonly code: string;
+    /** Human-readable explanation of the validation problem. */
+    readonly message: string;
+    /** Severity of the reported validation problem. */
+    readonly severity: ValidationDiagnosticSeverity;
+    /** Primary source location associated with the diagnostic. */
+    readonly primaryLocation: ValidationDiagnosticLocation;
+    /** Related source locations that add context to the diagnostic. */
+    readonly relatedLocations: readonly ValidationDiagnosticLocation[];
+}
+
+/**
+ * Public source-location shape attached to validation diagnostics.
+ *
+ * This mirrors the provenance information surfaced by the shared analysis
+ * layer without exposing `@formspec/core/internals` through the public API.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnosticLocation {
+    /** Authoring surface that produced the diagnostic location. */
+    readonly surface: "tsdoc" | "chain-dsl" | "extension" | "inferred";
+    /** Absolute path to the source file. */
+    readonly file: string;
+    /** 1-based line number in the source file. */
+    readonly line: number;
+    /** 0-based column number in the source file. */
+    readonly column: number;
+    /** Optional span length in characters. */
+    readonly length?: number;
+    /** Optional tag or construct associated with the location. */
+    readonly tagName?: string;
+}
+
+/**
+ * Supported severity levels returned by static build validation.
+ *
+ * @public
+ */
+export declare type ValidationDiagnosticSeverity = "error" | "warning";
+
+/**
+ * Result of validating canonical FormIR before schema emission.
+ *
+ * @public
  */
-export declare type UISchemaElementType = "Control" | "VerticalLayout" | "HorizontalLayout" | "Group" | "Categorization" | "Category";
+export declare interface ValidationResult {
+    /** Diagnostics produced during validation. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** Whether any error-severity diagnostics were produced. */
+    readonly valid: boolean;
+}
 
 /**
  * A vertical layout element.
+ *
+ * @public
  */
-export declare interface VerticalLayout extends UISchemaElementBase {
-    type: "VerticalLayout";
-    elements: UISchemaElement[];
+export declare interface VerticalLayout {
+    /** Discriminator identifying a vertical layout container. */
+    readonly type: "VerticalLayout";
+    /** Child elements rendered in vertical order. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific layout options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    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;
 }
 
 /**
@@ -322,13 +2374,17 @@ export declare interface VerticalLayout extends UISchemaElementBase {
  * @param form - The FormSpec to build schemas from
  * @param options - Output options (directory, file name, indentation)
  * @returns Object containing paths to the generated files
+ *
+ * @public
  */
 export declare function writeSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options: WriteSchemasOptions): WriteSchemasResult;
 
 /**
  * Options for writing schemas to disk.
+ *
+ * @public
  */
-export declare interface WriteSchemasOptions {
+export declare interface WriteSchemasOptions extends GenerateJsonSchemaOptions {
     /** Output directory for the schema files */
     readonly outDir: string;
     /** Base name for the output files (without extension). Defaults to "schema" */
@@ -339,6 +2395,8 @@ export declare interface WriteSchemasOptions {
 
 /**
  * Result of writing schemas to disk.
+ *
+ * @public
  */
 export declare interface WriteSchemasResult {
     /** Path to the generated JSON Schema file */