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

package/dist/core.d.ts

@@ -14,15 +14,23 @@
  * Discriminated union of all annotation types.
  * Annotations are value-influencing: they describe or present a field
  * but do not affect which values are valid.
+ *
+ * @public
  */
-export declare type AnnotationNode = DisplayNameAnnotationNode | DescriptionAnnotationNode | FormatAnnotationNode | PlaceholderAnnotationNode | DefaultValueAnnotationNode | DeprecatedAnnotationNode | FormatHintAnnotationNode | CustomAnnotationNode;
+export declare type AnnotationNode = DisplayNameAnnotationNode | DescriptionAnnotationNode | RemarksAnnotationNode | FormatAnnotationNode | PlaceholderAnnotationNode | DefaultValueAnnotationNode | DeprecatedAnnotationNode | FormatHintAnnotationNode | CustomAnnotationNode;
 
 /**
  * Union of all field types.
+ *
+ * @public
  */
 export declare type AnyField = TextField<string> | NumberField<string> | BooleanField<string> | StaticEnumField<string, readonly EnumOptionValue[]> | DynamicEnumField<string, string> | DynamicSchemaField<string> | ArrayField<string, readonly FormElement[]> | ObjectField<string, readonly FormElement[]>;
 
-/** Array uniqueness constraint. */
+/**
+ * Array uniqueness constraint.
+ *
+ * @public
+ */
 export declare interface ArrayCardinalityConstraintNode {
     readonly kind: "constraint";
     readonly constraintKind: "uniqueItems";
@@ -38,6 +46,8 @@ export declare interface ArrayCardinalityConstraintNode {
  *
  * @typeParam N - The field name (string literal type)
  * @typeParam Items - The form elements that define each array item
+ *
+ * @public
  */
 export declare interface ArrayField<N extends string, Items extends readonly FormElement[]> {
     /** Type discriminator for form elements */
@@ -58,7 +68,11 @@ export declare interface ArrayField<N extends string, Items extends readonly For
     readonly maxItems?: number;
 }
 
-/** Array type with a single items type. */
+/**
+ * Array type with a single items type.
+ *
+ * @public
+ */
 export declare interface ArrayTypeNode {
     readonly kind: "array";
     readonly items: TypeNode;
@@ -68,6 +82,8 @@ export declare interface ArrayTypeNode {
  * A boolean checkbox field.
  *
  * @typeParam N - The field name (string literal type)
+ *
+ * @public
  */
 export declare interface BooleanField<N extends string> {
     /** Type discriminator for form elements */
@@ -88,6 +104,8 @@ export declare interface BooleanField<N extends string> {
  * (e.g., `@minimum 0`) and chain DSL options (e.g., `{ minimum: 0 }`).
  *
  * Keys use camelCase matching JSON Schema property names.
+ *
+ * @public
  */
 export declare const BUILTIN_CONSTRAINT_DEFINITIONS: {
     readonly minimum: "number";
@@ -108,6 +126,8 @@ export declare const BUILTIN_CONSTRAINT_DEFINITIONS: {
 /**
  * Registration for mapping a built-in TSDoc tag onto a custom constraint when
  * it is used on a particular custom type.
+ *
+ * @public
  */
 export declare interface BuiltinConstraintBroadeningRegistration {
     /** The built-in tag being broadened, without the `@` prefix. */
@@ -118,7 +138,11 @@ export declare interface BuiltinConstraintBroadeningRegistration {
     readonly parseValue: (raw: string) => JsonValue;
 }
 
-/** Type of a built-in constraint name. */
+/**
+ * Type of a built-in constraint name.
+ *
+ * @public
+ */
 export declare type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFINITIONS;
 
 /**
@@ -127,6 +151,8 @@ export declare type BuiltinConstraintName = keyof typeof BUILTIN_CONSTRAINT_DEFI
  * @typeParam FieldName - The field to check
  * @typeParam Value - The value that triggers the condition
  * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
  */
 export declare interface Conditional<FieldName extends string, Value, Elements extends readonly FormElement[]> {
     /** Type discriminator - identifies this as a conditional element */
@@ -139,7 +165,11 @@ export declare interface Conditional<FieldName extends string, Value, Elements e
     readonly elements: Elements;
 }
 
-/** Conditional visibility based on another field's value. */
+/**
+ * Conditional visibility based on another field's value.
+ *
+ * @public
+ */
 export declare interface ConditionalLayoutNode {
     readonly kind: "conditional";
     /** The field whose value triggers visibility. */
@@ -151,7 +181,11 @@ export declare interface ConditionalLayoutNode {
     readonly provenance: Provenance;
 }
 
-/** Literal-value equality constraint. */
+/**
+ * Literal-value equality constraint.
+ *
+ * @public
+ */
 export declare interface ConstConstraintNode {
     readonly kind: "constraint";
     readonly constraintKind: "const";
@@ -163,12 +197,16 @@ export declare interface ConstConstraintNode {
 /**
  * Discriminated union of all constraint types.
  * Constraints are set-influencing: they narrow the set of valid values.
+ *
+ * @public
  */
 export declare type ConstraintNode = NumericConstraintNode | LengthConstraintNode | PatternConstraintNode | ArrayCardinalityConstraintNode | EnumMemberConstraintNode | ConstConstraintNode | CustomConstraintNode;
 
 /**
  * Semantic metadata for ordered custom constraints that should participate in
  * the generic contradiction/broadening logic.
+ *
+ * @public
  */
 export declare interface ConstraintSemanticRole {
     /**
@@ -184,6 +222,8 @@ export declare interface ConstraintSemanticRole {
 
 /**
  * Declarative authoring-side registration for a custom TSDoc constraint tag.
+ *
+ * @public
  */
 export declare interface ConstraintTagRegistration {
     /** Tag name without the `@` prefix, e.g. `"maxSigFig"`. */
@@ -206,10 +246,16 @@ export declare interface ConstraintTagRegistration {
  * @typeParam T - The value type of the field
  * @param value - The initial value for the field
  * @returns Initial field state
+ *
+ * @public
  */
 export declare function createInitialFieldState<T>(value: T): FieldState<T>;
 
-/** Extension-registered custom annotation. */
+/**
+ * Extension-registered custom annotation.
+ *
+ * @public
+ */
 export declare interface CustomAnnotationNode {
     readonly kind: "annotation";
     readonly annotationKind: "custom";
@@ -224,6 +270,8 @@ export declare interface CustomAnnotationNode {
  *
  * Custom annotations are referenced via {@link CustomAnnotationNode} in the IR.
  * They describe or present a field but do not affect which values are valid.
+ *
+ * @public
  */
 export declare interface CustomAnnotationRegistration {
     /** The annotation name, unique within the extension. */
@@ -235,7 +283,11 @@ export declare interface CustomAnnotationRegistration {
     readonly toJsonSchema?: (value: JsonValue, vendorPrefix: string) => Record<string, unknown>;
 }
 
-/** Extension-registered custom constraint. */
+/**
+ * Extension-registered custom constraint.
+ *
+ * @public
+ */
 export declare interface CustomConstraintNode {
     readonly kind: "constraint";
     readonly constraintKind: "custom";
@@ -253,6 +305,8 @@ export declare interface CustomConstraintNode {
  * Registration for a custom constraint that maps to JSON Schema keywords.
  *
  * Custom constraints are referenced via {@link CustomConstraintNode} in the IR.
+ *
+ * @public
  */
 export declare interface CustomConstraintRegistration {
     /** The constraint name, unique within the extension. */
@@ -294,7 +348,11 @@ export declare interface CustomConstraintRegistration {
     readonly toJsonSchema: (payload: JsonValue, vendorPrefix: string) => Record<string, unknown>;
 }
 
-/** Custom type registered by an extension. */
+/**
+ * Custom type registered by an extension.
+ *
+ * @public
+ */
 export declare interface CustomTypeNode {
     readonly kind: "custom";
     /**
@@ -315,6 +373,8 @@ export declare interface CustomTypeNode {
  *
  * Custom types are referenced via {@link CustomTypeNode} in the IR and
  * resolved to JSON Schema via `toJsonSchema` during generation.
+ *
+ * @public
  */
 export declare interface CustomTypeRegistration {
     /** The type name, unique within the extension. */
@@ -343,6 +403,8 @@ export declare interface CustomTypeRegistration {
  * A single option returned by a data source resolver.
  *
  * @typeParam T - The data type for additional option metadata
+ *
+ * @public
  */
 export declare interface DataSourceOption<T = unknown> {
     /** The value stored when this option is selected */
@@ -367,6 +429,8 @@ export declare interface DataSourceOption<T = unknown> {
  *   }
  * }
  * ```
+ *
+ * @public
  */
 export declare interface DataSourceRegistry {
 }
@@ -376,11 +440,18 @@ export declare interface DataSourceRegistry {
  *
  * If the source has an `id` property, that becomes the value type.
  * Otherwise, defaults to `string`.
+ *
+ * @public
  */
 export declare type DataSourceValueType<Source extends string> = Source extends keyof DataSourceRegistry ? DataSourceRegistry[Source] extends {
     id: infer ID;
 } ? ID : string : string;
 
+/**
+ * Default-value annotation.
+ *
+ * @public
+ */
 export declare interface DefaultValueAnnotationNode {
     readonly kind: "annotation";
     readonly annotationKind: "defaultValue";
@@ -395,6 +466,8 @@ export declare interface DefaultValueAnnotationNode {
  *
  * @param reg - The custom annotation registration.
  * @returns The same registration, validated at the type level.
+ *
+ * @public
  */
 export declare function defineAnnotation(reg: CustomAnnotationRegistration): CustomAnnotationRegistration;
 
@@ -404,6 +477,8 @@ export declare function defineAnnotation(reg: CustomAnnotationRegistration): Cus
  *
  * @param reg - The custom constraint registration.
  * @returns The same registration, validated at the type level.
+ *
+ * @public
  */
 export declare function defineConstraint(reg: CustomConstraintRegistration): CustomConstraintRegistration;
 
@@ -412,6 +487,8 @@ export declare function defineConstraint(reg: CustomConstraintRegistration): Cus
  *
  * @param reg - The custom tag registration.
  * @returns The same registration, validated at the type level.
+ *
+ * @public
  */
 export declare function defineConstraintTag(reg: ConstraintTagRegistration): ConstraintTagRegistration;
 
@@ -421,6 +498,8 @@ export declare function defineConstraintTag(reg: ConstraintTagRegistration): Con
  *
  * @param reg - The custom type registration.
  * @returns The same registration, validated at the type level.
+ *
+ * @public
  */
 export declare function defineCustomType(reg: CustomTypeRegistration): CustomTypeRegistration;
 
@@ -430,9 +509,16 @@ export declare function defineCustomType(reg: CustomTypeRegistration): CustomTyp
  *
  * @param def - The extension definition.
  * @returns The same definition, validated at the type level.
+ *
+ * @public
  */
 export declare function defineExtension(def: ExtensionDefinition): ExtensionDefinition;
 
+/**
+ * Deprecated annotation.
+ *
+ * @public
+ */
 export declare interface DeprecatedAnnotationNode {
     readonly kind: "annotation";
     readonly annotationKind: "deprecated";
@@ -441,6 +527,11 @@ export declare interface DeprecatedAnnotationNode {
     readonly provenance: Provenance;
 }
 
+/**
+ * Description annotation.
+ *
+ * @public
+ */
 export declare interface DescriptionAnnotationNode {
     readonly kind: "annotation";
     readonly annotationKind: "description";
@@ -448,6 +539,11 @@ export declare interface DescriptionAnnotationNode {
     readonly provenance: Provenance;
 }
 
+/**
+ * Display-name annotation.
+ *
+ * @public
+ */
 export declare interface DisplayNameAnnotationNode {
     readonly kind: "annotation";
     readonly annotationKind: "displayName";
@@ -460,6 +556,8 @@ export declare interface DisplayNameAnnotationNode {
  *
  * @typeParam N - The field name (string literal type)
  * @typeParam Source - The data source key (from DataSourceRegistry)
+ *
+ * @public
  */
 export declare interface DynamicEnumField<N extends string, Source extends string> {
     /** Type discriminator for form elements */
@@ -482,6 +580,8 @@ export declare interface DynamicEnumField<N extends string, Source extends strin
  * A field that loads its schema dynamically (e.g., from an extension).
  *
  * @typeParam N - The field name (string literal type)
+ *
+ * @public
  */
 export declare interface DynamicSchemaField<N extends string> {
     /** Type discriminator for form elements */
@@ -500,7 +600,11 @@ export declare interface DynamicSchemaField<N extends string> {
     readonly params?: readonly string[];
 }
 
-/** Dynamic type — schema resolved at runtime from a named data source. */
+/**
+ * Dynamic type whose schema is resolved at runtime from a named data source.
+ *
+ * @public
+ */
 export declare interface DynamicTypeNode {
     readonly kind: "dynamic";
     readonly dynamicKind: "enum" | "schema";
@@ -513,7 +617,11 @@ export declare interface DynamicTypeNode {
     readonly parameterFields: readonly string[];
 }
 
-/** A member of a static enum type. */
+/**
+ * A member of a static enum type.
+ *
+ * @public
+ */
 export declare interface EnumMember {
     /** The serialized value stored in data. */
     readonly value: string | number;
@@ -521,7 +629,11 @@ export declare interface EnumMember {
     readonly displayName?: string;
 }
 
-/** Enum member subset constraint (refinement — only narrows). */
+/**
+ * Enum member subset constraint that only narrows the allowed member set.
+ *
+ * @public
+ */
 export declare interface EnumMemberConstraintNode {
     readonly kind: "constraint";
     readonly constraintKind: "allowedMembers";
@@ -534,6 +646,8 @@ export declare interface EnumMemberConstraintNode {
  * An enum option with a separate ID and display label.
  *
  * Use this when the stored value (id) should differ from the display text (label).
+ *
+ * @public
  */
 export declare interface EnumOption {
     readonly id: string;
@@ -542,10 +656,16 @@ export declare interface EnumOption {
 
 /**
  * Valid enum option types: either plain strings or objects with id/label.
+ *
+ * @public
  */
 export declare type EnumOptionValue = string | EnumOption;
 
-/** Static enum type — members known at build time. */
+/**
+ * Static enum type with members known at build time.
+ *
+ * @public
+ */
 export declare interface EnumTypeNode {
     readonly kind: "enum";
     readonly members: readonly EnumMember[];
@@ -561,6 +681,8 @@ export declare interface EnumTypeNode {
  *
  * @typeParam K - The field name to check
  * @typeParam V - The value to compare against
+ *
+ * @public
  */
 export declare interface EqualsPredicate<K extends string, V> {
     /** Predicate type discriminator */
@@ -590,6 +712,8 @@ export declare interface EqualsPredicate<K extends string, V> {
  *   ],
  * });
  * ```
+ *
+ * @public
  */
 export declare interface ExtensionDefinition {
     /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
@@ -610,6 +734,8 @@ export declare interface ExtensionDefinition {
  * Response from a data source resolver function.
  *
  * @typeParam T - The data type for option metadata
+ *
+ * @public
  */
 export declare interface FetchOptionsResponse<T = unknown> {
     /** The available options */
@@ -620,7 +746,11 @@ export declare interface FetchOptionsResponse<T = unknown> {
     readonly message?: string;
 }
 
-/** A single form field after canonicalization. */
+/**
+ * A single form field after canonicalization.
+ *
+ * @public
+ */
 export declare interface FieldNode {
     readonly kind: "field";
     /** The field's key in the data schema. */
@@ -649,6 +779,8 @@ export declare interface FieldNode {
  * Represents the runtime state of a single form field.
  *
  * @typeParam T - The value type of the field
+ *
+ * @public
  */
 export declare interface FieldState<T> {
     /** Current value of the field */
@@ -663,7 +795,11 @@ export declare interface FieldState<T> {
     readonly errors: readonly string[];
 }
 
-/** Schema format annotation (e.g. email/date/uri). */
+/**
+ * Schema format annotation, for example `email`, `date`, or `uri`.
+ *
+ * @public
+ */
 export declare interface FormatAnnotationNode {
     readonly kind: "annotation";
     readonly annotationKind: "format";
@@ -674,6 +810,8 @@ export declare interface FormatAnnotationNode {
 /**
  * UI rendering hint — does not affect schema validation.
  * Unlike FormatAnnotationNode, this never emits a JSON Schema `format`.
+ *
+ * @public
  */
 export declare interface FormatHintAnnotationNode {
     readonly kind: "annotation";
@@ -685,6 +823,8 @@ export declare interface FormatHintAnnotationNode {
 
 /**
  * Union of all form element types (fields and structural elements).
+ *
+ * @public
  */
 export declare type FormElement = AnyField | Group<readonly FormElement[]> | Conditional<string, unknown, readonly FormElement[]>;
 
@@ -695,6 +835,8 @@ export declare type FormElement = AnyField | Group<readonly FormElement[]> | Con
  * and Generate (UI Schema) phases.
  *
  * Serializable to JSON — no live compiler objects.
+ *
+ * @public
  */
 export declare interface FormIR {
     readonly kind: "form-ir";
@@ -718,13 +860,19 @@ export declare interface FormIR {
     readonly provenance: Provenance;
 }
 
-/** Union of all IR element types. */
+/**
+ * Union of all IR element types.
+ *
+ * @public
+ */
 export declare type FormIRElement = FieldNode | LayoutNode;
 
 /**
  * A complete form specification.
  *
  * @typeParam Elements - Tuple of top-level form elements
+ *
+ * @public
  */
 export declare interface FormSpec<Elements extends readonly FormElement[]> {
     /** Top-level form elements */
@@ -735,6 +883,8 @@ export declare interface FormSpec<Elements extends readonly FormElement[]> {
  * Represents the runtime state of an entire form.
  *
  * @typeParam Schema - The form schema type (maps field names to value types)
+ *
+ * @public
  */
 export declare interface FormState<Schema extends Record<string, unknown>> {
     /** State for each field, keyed by field name */
@@ -755,6 +905,8 @@ export declare interface FormState<Schema extends Record<string, unknown>> {
  * Groups provide visual organization and can be rendered as fieldsets or sections.
  *
  * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
  */
 export declare interface Group<Elements extends readonly FormElement[]> {
     /** Type discriminator - identifies this as a group element */
@@ -765,7 +917,11 @@ export declare interface Group<Elements extends readonly FormElement[]> {
     readonly elements: Elements;
 }
 
-/** A visual grouping of form elements. */
+/**
+ * A visual grouping of form elements.
+ *
+ * @public
+ */
 export declare interface GroupLayoutNode {
     readonly kind: "group";
     readonly label: string;
@@ -777,13 +933,23 @@ export declare interface GroupLayoutNode {
 /**
  * The current IR format version. Centralized here so all canonicalizers
  * and consumers reference a single source of truth.
+ *
+ * @public
  */
 export declare const IR_VERSION: "0.1.0";
 
-/** Narrows a FormElement to an array field. */
+/**
+ * Narrows a `FormElement` to an array field.
+ *
+ * @public
+ */
 export declare function isArrayField(element: FormElement): element is ArrayField<string, readonly FormElement[]>;
 
-/** Narrows a FormElement to a boolean checkbox field. */
+/**
+ * Narrows a `FormElement` to a boolean checkbox field.
+ *
+ * @public
+ */
 export declare function isBooleanField(element: FormElement): element is BooleanField<string>;
 
 /**
@@ -794,44 +960,88 @@ export declare function isBooleanField(element: FormElement): element is Boolean
  *
  * Callers should normalize with {@link normalizeConstraintTagName} first
  * if the input may be PascalCase.
+ *
+ * @public
  */
 export declare function isBuiltinConstraintName(tagName: string): tagName is BuiltinConstraintName;
 
-/** Narrows a FormElement to a conditional wrapper. */
+/**
+ * Narrows a `FormElement` to a conditional wrapper.
+ *
+ * @public
+ */
 export declare function isConditional(element: FormElement): element is Conditional<string, unknown, readonly FormElement[]>;
 
-/** Narrows a FormElement to a dynamic enum field. */
+/**
+ * Narrows a `FormElement` to a dynamic enum field.
+ *
+ * @public
+ */
 export declare function isDynamicEnumField(element: FormElement): element is DynamicEnumField<string, string>;
 
-/** Narrows a FormElement to a dynamic schema field. */
+/**
+ * Narrows a `FormElement` to a dynamic schema field.
+ *
+ * @public
+ */
 export declare function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string>;
 
-/** Narrows a FormElement to any field type. */
+/**
+ * Narrows a `FormElement` to any field type.
+ *
+ * @public
+ */
 export declare function isField(element: FormElement): element is AnyField;
 
-/** Narrows a FormElement to a visual group. */
+/**
+ * Narrows a `FormElement` to a visual group.
+ *
+ * @public
+ */
 export declare function isGroup(element: FormElement): element is Group<readonly FormElement[]>;
 
-/** Narrows a FormElement to a numeric input field. */
+/**
+ * Narrows a `FormElement` to a numeric input field.
+ *
+ * @public
+ */
 export declare function isNumberField(element: FormElement): element is NumberField<string>;
 
-/** Narrows a FormElement to an object field. */
+/**
+ * Narrows a `FormElement` to an object field.
+ *
+ * @public
+ */
 export declare function isObjectField(element: FormElement): element is ObjectField<string, readonly FormElement[]>;
 
-/** Narrows a FormElement to a static enum field. */
+/**
+ * Narrows a `FormElement` to a static enum field.
+ *
+ * @public
+ */
 export declare function isStaticEnumField(element: FormElement): element is StaticEnumField<string, readonly EnumOptionValue[]>;
 
-/** Narrows a FormElement to a text input field. */
+/**
+ * Narrows a `FormElement` to a text input field.
+ *
+ * @public
+ */
 export declare function isTextField(element: FormElement): element is TextField<string>;
 
 /**
  * A JSON-serializable value. All IR nodes must be representable as JSON.
+ *
+ * @public
  */
 export declare type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
 
-/** Union of layout node types. */
+/**
+ * Union of layout node types.
+ *
+ * @public
+ */
 export declare type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;
 
 /**
@@ -843,6 +1053,8 @@ export declare type LayoutNode = GroupLayoutNode | ConditionalLayoutNode;
  *
  * Type applicability: `minLength`/`maxLength` require `PrimitiveTypeNode("string")`;
  * `minItems`/`maxItems` require `ArrayTypeNode`.
+ *
+ * @public
  */
 export declare interface LengthConstraintNode {
     readonly kind: "constraint";
@@ -862,6 +1074,8 @@ export declare interface LengthConstraintNode {
  * normalizeConstraintTagName("Minimum")   // "minimum"
  * normalizeConstraintTagName("MinLength") // "minLength"
  * normalizeConstraintTagName("minimum")   // "minimum" (idempotent)
+ *
+ * @public
  */
 export declare function normalizeConstraintTagName(tagName: string): string;
 
@@ -869,6 +1083,8 @@ export declare function normalizeConstraintTagName(tagName: string): string;
  * A numeric input field.
  *
  * @typeParam N - The field name (string literal type)
+ *
+ * @public
  */
 export declare interface NumberField<N extends string> {
     /** Type discriminator for form elements */
@@ -898,6 +1114,8 @@ export declare interface NumberField<N extends string> {
  *
  * Type applicability: may only attach to fields with `PrimitiveTypeNode("number")`
  * or a `ReferenceTypeNode` that resolves to one.
+ *
+ * @public
  */
 export declare interface NumericConstraintNode {
     readonly kind: "constraint";
@@ -915,6 +1133,8 @@ export declare interface NumericConstraintNode {
  *
  * @typeParam N - The field name (string literal type)
  * @typeParam Properties - The form elements that define the object's properties
+ *
+ * @public
  */
 export declare interface ObjectField<N extends string, Properties extends readonly FormElement[]> {
     /** Type discriminator for form elements */
@@ -931,7 +1151,11 @@ export declare interface ObjectField<N extends string, Properties extends readon
     readonly required?: boolean;
 }
 
-/** A named property within an object type. */
+/**
+ * A named property within an object type.
+ *
+ * @public
+ */
 export declare interface ObjectProperty {
     readonly name: string;
     readonly type: TypeNode;
@@ -948,7 +1172,11 @@ export declare interface ObjectProperty {
     readonly provenance: Provenance;
 }
 
-/** Object type with named properties. */
+/**
+ * Object type with named properties.
+ *
+ * @public
+ */
 export declare interface ObjectTypeNode {
     readonly kind: "object";
     /**
@@ -967,6 +1195,8 @@ export declare interface ObjectTypeNode {
 /**
  * A path targeting a sub-field within a complex type.
  * Used by constraints and annotations to target nested properties.
+ *
+ * @public
  */
 export declare interface PathTarget {
     /**
@@ -984,6 +1214,8 @@ export declare interface PathTarget {
  * all patterns must match simultaneously.
  *
  * Type applicability: requires `PrimitiveTypeNode("string")`.
+ *
+ * @public
  */
 export declare interface PatternConstraintNode {
     readonly kind: "constraint";
@@ -994,6 +1226,11 @@ export declare interface PatternConstraintNode {
     readonly provenance: Provenance;
 }
 
+/**
+ * Placeholder annotation.
+ *
+ * @public
+ */
 export declare interface PlaceholderAnnotationNode {
     readonly kind: "annotation";
     readonly annotationKind: "placeholder";
@@ -1008,6 +1245,8 @@ export declare interface PlaceholderAnnotationNode {
  * - `OneOfPredicate` - field value is one of several options
  * - `NotPredicate` - negation of another predicate
  * - `AndPredicate` / `OrPredicate` - logical combinations
+ *
+ * @public
  */
 export declare type Predicate<K extends string = string, V = unknown> = EqualsPredicate<K, V>;
 
@@ -1016,6 +1255,8 @@ export declare type Predicate<K extends string = string, V = unknown> = EqualsPr
  *
  * Note: integer is NOT a primitive kind — integer semantics are expressed
  * via a `multipleOf: 1` constraint on a number type.
+ *
+ * @public
  */
 export declare interface PrimitiveTypeNode {
     readonly kind: "primitive";
@@ -1025,6 +1266,8 @@ export declare interface PrimitiveTypeNode {
 /**
  * Describes the origin of an IR node.
  * Enables diagnostics that point to the source of a contradiction or error.
+ *
+ * @public
  */
 export declare interface Provenance {
     /** The authoring surface that produced this node. */
@@ -1050,6 +1293,8 @@ export declare interface Provenance {
  *
  * Emitted as `{ "type": "object", "additionalProperties": <value schema> }` in
  * JSON Schema per spec 003 §2.5.
+ *
+ * @public
  */
 export declare interface RecordTypeNode {
     readonly kind: "record";
@@ -1057,7 +1302,11 @@ export declare interface RecordTypeNode {
     readonly valueType: TypeNode;
 }
 
-/** Named type reference — preserved as references for `$defs`/`$ref` emission. */
+/**
+ * Named type reference preserved for `$defs` and `$ref` emission.
+ *
+ * @public
+ */
 export declare interface ReferenceTypeNode {
     readonly kind: "reference";
     /**
@@ -1073,6 +1322,23 @@ export declare interface ReferenceTypeNode {
     readonly typeArguments: readonly TypeNode[];
 }
 
+/**
+ * Remarks annotation — programmatic-persona documentation carried via
+ * the `x-<vendor>-remarks` JSON Schema extension keyword.
+ *
+ * Populated from `@remarks` TSDoc tag content. SDK codegen can include
+ * this in doc comments; API Documenter renders the source `@remarks`
+ * natively in a dedicated Remarks section.
+ *
+ * @public
+ */
+export declare interface RemarksAnnotationNode {
+    readonly kind: "annotation";
+    readonly annotationKind: "remarks";
+    readonly value: string;
+    readonly provenance: Provenance;
+}
+
 /**
  * A field with static enum options (known at compile time).
  *
@@ -1080,6 +1346,8 @@ export declare interface ReferenceTypeNode {
  *
  * @typeParam N - The field name (string literal type)
  * @typeParam O - Tuple of option values (strings or EnumOption objects)
+ *
+ * @public
  */
 export declare interface StaticEnumField<N extends string, O extends readonly EnumOptionValue[]> {
     /** Type discriminator for form elements */
@@ -1106,6 +1374,8 @@ export declare interface StaticEnumField<N extends string, O extends readonly En
  * A text input field.
  *
  * @typeParam N - The field name (string literal type)
+ *
+ * @public
  */
 export declare interface TextField<N extends string> {
     /** Type discriminator for form elements */
@@ -1128,7 +1398,11 @@ export declare interface TextField<N extends string> {
     readonly pattern?: string;
 }
 
-/** A named type definition stored in the type registry. */
+/**
+ * A named type definition stored in the type registry.
+ *
+ * @public
+ */
 export declare interface TypeDefinition {
     /** The fully-qualified reference name (key in the registry). */
     readonly name: string;
@@ -1144,10 +1418,16 @@ export declare interface TypeDefinition {
 
 /**
  * Discriminated union of all type representations in the IR.
+ *
+ * @public
  */
 export declare type TypeNode = PrimitiveTypeNode | EnumTypeNode | ArrayTypeNode | ObjectTypeNode | RecordTypeNode | UnionTypeNode | ReferenceTypeNode | DynamicTypeNode | CustomTypeNode;
 
-/** Union type for non-enum unions. Nullable types are `T | null` using this. */
+/**
+ * Union type for non-enum unions. Nullable types are represented as `T | null`.
+ *
+ * @public
+ */
 export declare interface UnionTypeNode {
     readonly kind: "union";
     readonly members: readonly TypeNode[];
@@ -1159,11 +1439,15 @@ export declare interface UnionTypeNode {
  * - `"valid"` - All validations pass
  * - `"invalid"` - One or more validations failed
  * - `"unknown"` - Validation state not yet determined (e.g., async validation pending)
+ *
+ * @public
  */
 export declare type Validity = "valid" | "invalid" | "unknown";
 
 /**
  * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
+ *
+ * @public
  */
 export declare interface VocabularyKeywordRegistration {
     /** The keyword name (without vendor prefix). */