praxis-kit 4.0.0 → 4.0.3

package/dist/merge-refs-B0YcfdtP.d.ts

@@ -0,0 +1,399 @@
+import { ComponentType, PropsWithChildren, ReactElement, JSX, Ref, ReactNode } from 'react';
+import { RequireAtLeastOne, Simplify, ReadonlyDeep, NonEmptyTuple } from 'type-fest';
+import { Diagnostics, DiagnosticInput } from './_shared/diagnostics.js';
+
+type StringMap<T = unknown> = Record<string, T>;
+type AnyRecord = StringMap<unknown>;
+
+type IntrinsicTag = keyof HTMLElementTagNameMap;
+
+type ElementType = IntrinsicTag | (string & {});
+
+declare const KNOWN_ARIA_ROLES: readonly ["alert", "alertdialog", "application", "article", "banner", "blockquote", "button", "caption", "cell", "checkbox", "code", "columnheader", "combobox", "complementary", "contentinfo", "definition", "deletion", "dialog", "document", "emphasis", "feed", "figure", "form", "generic", "grid", "gridcell", "group", "heading", "img", "insertion", "link", "list", "listbox", "listitem", "log", "main", "marquee", "math", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "meter", "navigation", "none", "note", "option", "paragraph", "presentation", "progressbar", "radio", "radiogroup", "region", "row", "rowgroup", "rowheader", "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton", "status", "strong", "subscript", "superscript", "switch", "tab", "table", "tablist", "tabpanel", "term", "textbox", "time", "timer", "toolbar", "tooltip", "tree", "treegrid", "treeitem"];
+type KnownAriaRole = (typeof KNOWN_ARIA_ROLES)[number];
+
+type Booleanish = boolean | 'true' | 'false';
+type ClassName = string | string[];
+type EmptyRecord = Record<never, never>;
+type NonEmptyArray<T> = [T, ...T[]];
+type Numberish = number | `${number}`;
+type Primitive = string | number | boolean;
+type AriaRole = KnownAriaRole | (string & {});
+type IntrinsicProps = AnyRecord & {
+    role?: AriaRole;
+};
+type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
+
+type MinMax = {
+    min: number;
+    max: number;
+};
+type CardinalityInput = Partial<MinMax>;
+
+type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
+
+type ChildRulePosition = 'first' | 'last' | 'any';
+
+type ChildRuleInput<T = unknown, U extends T = T> = {
+    name: string;
+    match: ChildRuleMatch<T, U>;
+    cardinality?: CardinalityInput;
+    position?: ChildRulePosition;
+    /**
+     * Optional component-type reference for O(1) dispatch index.
+     * When provided for every rule, the matcher reads child.type instead of
+     * calling every match function on every child (O(n×m) → O(n+m)).
+     */
+    type?: unknown;
+};
+
+type ValidResult = {
+    valid: true;
+};
+
+type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
+type CompoundVariantConditionValue<V extends VariantMap, K extends keyof V> = VariantKey<V, K> | NonEmptyArray<VariantKey<V, K>>;
+type CompoundVariantConditions<V extends VariantMap> = Simplify<{
+    [K in keyof V]: CompoundVariantConditionValue<V, K>;
+}>;
+type CompoundVariantRequiredConditions<V extends VariantMap> = RequireAtLeastOneIfNotEmpty<CompoundVariantConditions<V>>;
+type CompoundVariantBase<V extends VariantMap> = keyof V extends never ? EmptyRecord : CompoundVariantRequiredConditions<V>;
+type CompoundVariant<V extends VariantMap> = CompoundVariantBase<V> & {
+    class: VariantValue;
+};
+
+interface CVACompounds<V extends VariantMap> {
+    compoundVariants?: readonly CompoundVariant<V>[];
+}
+
+interface CVADefaults<V extends VariantMap> {
+    defaultVariants?: DefaultVariants<V>;
+}
+
+interface CVAVariants<V extends VariantMap> {
+    variants?: V;
+}
+
+type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;
+type VariantValue = string | string[];
+type VariantStates<K extends string = string> = Record<K, VariantValue>;
+type VariantMap<V extends string = string, K extends string = string> = Record<V, VariantStates<K>>;
+type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof V[K] & string>;
+/**
+ * A partial selection of variant states authored at factory definition time.
+ *
+ * Uses `keyof V[K]` directly (not `VariantKey`) so TypeScript can eagerly
+ * resolve the union at constraint-check time without deferred conditional types.
+ */
+type VariantSelection<V extends VariantMap> = {
+    [K in keyof V]?: keyof V[K];
+};
+/** The full optional prop surface exposed to callers for a given variant map. */
+type VariantProps<V extends VariantMap> = {
+    [K in keyof V]?: VariantKey<V, K>;
+};
+type NormalizedVariantValue<K extends string> = string extends K ? Primitive : K extends 'true' | 'false' ? Booleanish : K extends `${number}` ? Numberish : K;
+type DefaultVariants<V extends VariantMap> = {
+    [K in keyof V]?: NormalizedVariantValue<keyof V[K] & string>;
+};
+/**
+ * A static, immutable map of named presets to partial variant selections.
+ *
+ * Presets are named bundles of variant props that callers activate by key,
+ * avoiding the need to repeat variant combinations at each call site.
+ */
+type RecipeMap<V extends VariantMap = VariantMap> = Readonly<Record<string, VariantSelection<V>>>;
+type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TAllowed extends ElementType = ElementType> {
+    default: TDefault;
+    props: Props;
+    variants: Variants;
+    preset: TPreset;
+    allowed: TAllowed;
+}
+type VariantsOf<T extends PolymorphicGenerics> = T['variants'];
+type RecipeOf<T extends PolymorphicGenerics> = T['preset'];
+type AllowedOf<T extends PolymorphicGenerics> = T['allowed'];
+type DefaultOf<T extends PolymorphicGenerics> = T['default'];
+type PropsOf<T extends PolymorphicGenerics> = T['props'];
+
+interface BaseClassOptions {
+    baseClassName?: ClassName;
+}
+
+type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string;
+
+interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
+    recipeMap?: Record<string, RecipeTarget<TVariants>>;
+}
+
+interface TagMapOptions {
+    tagMap?: TagMap;
+}
+
+type CompositionOptions<TVariants extends VariantMap = VariantMap> = Simplify<TagMapOptions & RecipeOptions<TVariants>>;
+
+type CVASystemOptions<TVariants extends VariantMap = VariantMap> = Simplify<CVAVariants<TVariants> & CVADefaults<TVariants> & CVACompounds<TVariants>>;
+
+type StyleOptions<TVariants extends VariantMap = VariantMap> = Simplify<BaseClassOptions & CVASystemOptions<TVariants>>;
+
+type ClassPipelineOptions<TVariants extends VariantMap = VariantMap> = Simplify<StyleOptions<TVariants> & CompositionOptions<TVariants>>;
+
+type OwnedPropKeys = ReadonlySet<string>;
+
+type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
+    pipeline: ClassPipelineFn;
+    ownedKeys?: OwnedPropKeys;
+    readonly _pluginProps?: TProps;
+}>;
+
+type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends VariantMap>(options: ClassPipelineOptions<V>, diagnostics: Diagnostics) => ClassPlugin<TProps>;
+type ExtractPluginProps<TPlugin extends ClassPluginFactory<AnyRecord> | undefined> = TPlugin extends ClassPluginFactory<infer T> ? string extends keyof T ? EmptyRecord : T : EmptyRecord;
+
+type AriaContext = {
+    readonly tag: IntrinsicTag;
+    readonly implicitRole: AriaRole | undefined;
+    readonly effectiveRole: string | undefined;
+    readonly props: ReadonlyDeep<IntrinsicProps>;
+};
+
+type RemoveAttributeFixKind = `removeAttribute:${string}`;
+type InjectLiveFixKind = `injectLive:${string}`;
+type FixKind = 'removeRole' | 'setRole' | 'normalizeRelevantAll' | RemoveAttributeFixKind | InjectLiveFixKind;
+
+type AriaFixResult = {
+    applied: false;
+    next: ReadonlyDeep<IntrinsicProps>;
+} | {
+    applied: true;
+    next: ReadonlyDeep<IntrinsicProps>;
+    previous: ReadonlyDeep<IntrinsicProps>;
+};
+type AriaFix = {
+    readonly kind: FixKind;
+    readonly priority?: number;
+    readonly source?: string;
+    readonly apply: (context: AriaContext) => AriaFixResult;
+};
+
+type Severity = 'error' | 'warning' | (string & {});
+
+type AriaInvalidBase<M extends string = string> = {
+    valid: false;
+    severity: Severity;
+    message?: M;
+    attribute?: string;
+    diagnostic?: DiagnosticInput;
+};
+type AriaInvalidWithFix<M extends string = string> = AriaInvalidBase<M> & {
+    fixable: true;
+    fix: AriaFix;
+};
+type AriaInvalidWithoutFix<M extends string = string> = AriaInvalidBase<M> & {
+    fixable: false;
+};
+type AriaInvalidResult<M extends string = string> = AriaInvalidWithFix<M> | AriaInvalidWithoutFix<M>;
+type AriaResult = ValidResult | AriaInvalidResult;
+
+type AriaRule<C extends AriaContext = AriaContext> = (context: C) => readonly AriaResult[];
+
+type PropNormalizer = (props: Readonly<AnyRecord & IntrinsicProps>) => Partial<AnyRecord & IntrinsicProps>;
+
+type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
+    readonly diagnostics?: Diagnostics;
+    readonly aria?: readonly AriaRule[];
+    readonly children?: readonly ChildRuleInput[];
+    readonly props?: readonly PropNormalizer[];
+    /** Restricts the `as` prop to this set of tags. Violations route through diagnostics. */
+    readonly allowedAs?: readonly TAllowed[];
+};
+
+type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined> = {
+    readonly base?: ClassName;
+    readonly variants?: V;
+    readonly defaults?: Partial<DefaultVariants<V>>;
+    readonly compounds?: readonly CompoundVariant<V>[];
+    readonly presets?: TPreset;
+    readonly tags?: Readonly<TagMap>;
+    readonly plugin?: TPlugin;
+    readonly precomputedClasses?: Readonly<Record<string, string>>;
+};
+
+type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
+    normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
+}['normalize'];
+type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, ClassPluginFactory<AnyRecord> | undefined>;
+type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined, TAllowed extends ElementType = ElementType> = {
+    readonly tag?: TDefault;
+    readonly name?: string;
+    readonly defaults?: Partial<NoInfer<Props>>;
+    readonly normalize?: NormalizeFn<NoInfer<Props>>;
+    readonly styling?: StylingOptions<V, TPreset, TPlugin>;
+    readonly enforcement?: EnforcementOptions<TAllowed>;
+};
+
+type MetadataMap = AnyRecord;
+type NodeId = string;
+
+interface Diagnostic {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+}
+
+type CapabilityMap = StringMap<boolean>;
+
+declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
+
+interface ComponentIdentity {
+    id: NodeId;
+    name: string;
+    tag: string;
+}
+
+interface ComponentDefinition {
+    identity: ComponentIdentity;
+    capabilities: CapabilityMap;
+    metadata: MetadataMap;
+    diagnostics: Diagnostic[];
+}
+
+type UnknownProps = Record<string, unknown>;
+type SlotComponent = ComponentType<UnknownProps>;
+
+/**
+ * Props passed to the `render` callback — the component's resolved className,
+ * filtered own props, and ref. Spread these onto the target element.
+ *
+ * Typed loosely to accommodate any element tag the user chooses.
+ */
+type RenderCallbackProps = Readonly<Record<string, unknown>>;
+
+type SlottableProps = PropsWithChildren;
+declare function Slottable({ children }: SlottableProps): ReactElement;
+
+/** Structural subset of `CompiledComponentArtifact` consumed by the React adapter. */
+interface CompiledArtifact {
+    readonly definition: ComponentDefinition;
+    readonly precomputed?: {
+        readonly variantLookup?: Record<string, string>;
+    };
+}
+/**
+ * Extends FactoryOptions with React-specific configuration.
+ * slotComponent is intentionally not in core — it is a React rendering concern.
+ */
+type ReactFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined, TAllowed extends ElementType = ElementType> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+    /** Component used to render the asChild slot. Defaults to the built-in Slot. */
+    slotComponent?: SlotComponent;
+    /**
+     * Return true for any prop key that should be consumed but not forwarded to the DOM.
+     * The adapter strips nothing by default — implementations decide what is safe to drop.
+     * Receives `runtime.options.variantKeys` as a convenience if needed.
+     */
+    filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
+    /** Pre-compiled artifact from `@praxis-kit/runtime`'s compiler. When provided, replaces the stub
+     *  definition and enables the precomputed variant lookup fast path. */
+    artifact?: CompiledArtifact;
+};
+
+/** Maps a core ElementType to its DOM instance type for ref inference. */
+type ElementRef<T extends ElementType> = T extends IntrinsicTag ? HTMLElementTagNameMap[T] : unknown;
+/** @internal React JSX intrinsic props for a given element type. */
+type IntrinsicJSXProps<T extends ElementType> = T extends IntrinsicTag ? JSX.IntrinsicElements[T] : UnknownProps;
+/**
+ * @internal
+ * Removes index signatures (e.g. `[key: string]: T`) from a type, keeping only
+ * explicitly named properties. Used to prevent fallback-to-constraint generics
+ * like `Record<string, unknown>` or `Readonly<VariantMap>` from producing a
+ * `[key: string]: T` member that makes `keyof` resolve to `string` — which
+ * would cause `Omit<IntrinsicJSXProps<TAs>, string>` to remove all HTML props.
+ */
+type StripIndexSignature<T> = {
+    [K in keyof T as string extends K ? never : K]: T[K];
+};
+type ComponentProps<G extends PolymorphicGenerics> = StripIndexSignature<PropsOf<G>>;
+type ComponentVariants<G extends PolymorphicGenerics> = StripIndexSignature<VariantProps<VariantsOf<G>>>;
+type OwnedProps<G extends PolymorphicGenerics> = ComponentProps<G> & ComponentVariants<G>;
+/**
+ * @internal
+ * Polymorphic machinery props. Separated from `OwnedProps` so the two concerns
+ * are distinct: user-defined props vs. the tag/ref/class system.
+ *
+ * `asChild` and `children` are excluded — typed separately in the discriminated
+ * union below so each render mode can enforce different child constraints.
+ */
+type PolymorphicControlProps<G extends PolymorphicGenerics, TAs extends ElementType> = {
+    as?: TAs & AllowedOf<G>;
+    className?: ClassName | undefined;
+    recipe?: keyof RecipeOf<G>;
+    ref?: Ref<ElementRef<TAs>>;
+};
+/** @internal Full set of props owned by the component — used as the Omit key in IntrinsicPropsWithoutOwned. */
+type ControlProps<G extends PolymorphicGenerics, TAs extends ElementType> = OwnedProps<G> & PolymorphicControlProps<G, TAs>;
+type IntrinsicPropsWithoutOwned<G extends PolymorphicGenerics, TAs extends ElementType> = Omit<IntrinsicJSXProps<TAs>, keyof ControlProps<G, TAs> | 'children'>;
+type SharedProps<G extends PolymorphicGenerics, TAs extends ElementType> = IntrinsicPropsWithoutOwned<G, TAs> & ControlProps<G, TAs>;
+/** Discriminant for the normal render path: `asChild` absent or false, any children. */
+type NormalRenderMode = {
+    asChild?: false;
+    children?: ReactNode | undefined;
+};
+/**
+ * Discriminant for the slot render path. One or more `ReactElement` children required.
+ * `as` is forbidden — combining `as` with `asChild` is a runtime invariant violation.
+ */
+type SlotRenderMode = {
+    asChild: true;
+    as?: never;
+    children: ReactElement | NonEmptyTuple<ReactElement>;
+};
+/**
+ * Discriminant for the render-prop path. The callback receives all resolved props
+ * (className, ref, filtered component props) and returns the target element.
+ *
+ * This is the output form for the compile-time `asChild` transform: keeps the same
+ * rendering flexibility as `asChild` without the `cloneElement` cost at runtime.
+ * Unlike `asChild`, the render callback does not auto-merge conflicting event
+ * handlers — spread position determines precedence.
+ *
+ * ```tsx
+ * <Button render={(p) => <a href="/home" {...p} />} size="lg" />
+ * ```
+ */
+type CallbackRenderMode = {
+    render: (props: RenderCallbackProps) => ReactElement;
+    asChild?: never;
+    children?: never;
+};
+/**
+ * Props for the normal render path. HTML attributes are inferred from `TAs`.
+ *
+ * `Omit + intersection` (not `Merge`) is used so TypeScript can infer `TAs` from
+ * the `as` prop value; control props win on key conflicts.
+ */
+type PolymorphicProps<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<SharedProps<G, TAs> & NormalRenderMode>;
+/**
+ * Props for the slot render path (`asChild: true`). One or more `ReactElement`
+ * children are required. Multiple children are permitted for the Slottable
+ * sibling pattern where one child is a `<Slottable>` wrapper.
+ */
+type PolymorphicWithAsChild<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<SharedProps<G, TAs> & SlotRenderMode>;
+type PolymorphicWithRender<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<SharedProps<G, TAs> & CallbackRenderMode>;
+/**
+ * A polymorphic component that infers HTML attributes and ref type from the `as` prop.
+ *
+ * Three call signatures form a discriminated union:
+ * - `render` present       → render-prop path; no Slot or cloneElement at runtime
+ * - `asChild: true`        → slot path; exactly one `ReactElement` child required
+ * - `asChild?: false`      → normal path; any `ReactNode` children accepted
+ */
+type PolymorphicComponent<G extends PolymorphicGenerics> = {
+    <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicWithRender<G, TAs>): ReactElement;
+    <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicWithAsChild<G, TAs>): ReactElement;
+    <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicProps<G, TAs>): ReactElement;
+    displayName?: string;
+};
+
+declare function mergeRefs<T>(...refs: (Ref<T> | null | undefined)[]): Ref<T> | null;
+
+export { type AnyRecord as A, type ClassPluginFactory as C, type ElementType as E, type FactoryOptions as F, type PolymorphicComponent as P, type RecipeMap as R, Slottable as S, type UnknownProps as U, type VariantMap as V, type EmptyRecord as a, type ReactFactoryOptions as b, type PolymorphicGenerics as c, type ExtractPluginProps as d, type AnyFactoryOptions as e, type ElementRef as f, type PolymorphicProps as g, type PolymorphicWithAsChild as h, type PolymorphicWithRender as i, type RenderCallbackProps as j, type SlottableProps as k, defineContractComponent as l, mergeRefs as m };

package/dist/preact/index.d.ts

@@ -1,8 +1,237 @@
-import { ElementType, VariantMap, RecipeMap, EmptyRecord, ClassPluginFactory, AnyRecord, FactoryOptions, IntrinsicTag, PolymorphicGenerics, DefaultOf, PropsOf, VariantProps, VariantsOf, ClassName, RecipeOf, ExtractPluginProps } from '@praxis-kit/core';
-export { AnyFactoryOptions, ElementType, EmptyRecord, PolymorphicGenerics } from '@praxis-kit/core';
+import { RequireAtLeastOne, Simplify, ReadonlyDeep, OmitIndexSignature } from 'type-fest';
+import { Diagnostics, DiagnosticInput } from '../_shared/diagnostics.js';
 import { ComponentChildren, VNode, ComponentType, JSX, Ref } from 'preact';
-import { Simplify, OmitIndexSignature } from 'type-fest';
-export { defineContractComponent } from '@praxis-kit/adapter-utils';
+
+type StringMap<T = unknown> = Record<string, T>;
+type AnyRecord = StringMap<unknown>;
+
+type IntrinsicTag = keyof HTMLElementTagNameMap;
+
+type ElementType = IntrinsicTag | (string & {});
+
+declare const KNOWN_ARIA_ROLES: readonly ["alert", "alertdialog", "application", "article", "banner", "blockquote", "button", "caption", "cell", "checkbox", "code", "columnheader", "combobox", "complementary", "contentinfo", "definition", "deletion", "dialog", "document", "emphasis", "feed", "figure", "form", "generic", "grid", "gridcell", "group", "heading", "img", "insertion", "link", "list", "listbox", "listitem", "log", "main", "marquee", "math", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "meter", "navigation", "none", "note", "option", "paragraph", "presentation", "progressbar", "radio", "radiogroup", "region", "row", "rowgroup", "rowheader", "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton", "status", "strong", "subscript", "superscript", "switch", "tab", "table", "tablist", "tabpanel", "term", "textbox", "time", "timer", "toolbar", "tooltip", "tree", "treegrid", "treeitem"];
+type KnownAriaRole = (typeof KNOWN_ARIA_ROLES)[number];
+
+type Booleanish = boolean | 'true' | 'false';
+type ClassName = string | string[];
+type EmptyRecord = Record<never, never>;
+type NonEmptyArray<T> = [T, ...T[]];
+type Numberish = number | `${number}`;
+type Primitive = string | number | boolean;
+type AriaRole = KnownAriaRole | (string & {});
+type IntrinsicProps = AnyRecord & {
+    role?: AriaRole;
+};
+type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
+
+type MinMax = {
+    min: number;
+    max: number;
+};
+type CardinalityInput = Partial<MinMax>;
+
+type ChildRuleMatch<T, U extends T = T> = (child: T) => child is U;
+
+type ChildRulePosition = 'first' | 'last' | 'any';
+
+type ChildRuleInput<T = unknown, U extends T = T> = {
+    name: string;
+    match: ChildRuleMatch<T, U>;
+    cardinality?: CardinalityInput;
+    position?: ChildRulePosition;
+    /**
+     * Optional component-type reference for O(1) dispatch index.
+     * When provided for every rule, the matcher reads child.type instead of
+     * calling every match function on every child (O(n×m) → O(n+m)).
+     */
+    type?: unknown;
+};
+
+type ValidResult = {
+    valid: true;
+};
+
+type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
+type CompoundVariantConditionValue<V extends VariantMap, K extends keyof V> = VariantKey<V, K> | NonEmptyArray<VariantKey<V, K>>;
+type CompoundVariantConditions<V extends VariantMap> = Simplify<{
+    [K in keyof V]: CompoundVariantConditionValue<V, K>;
+}>;
+type CompoundVariantRequiredConditions<V extends VariantMap> = RequireAtLeastOneIfNotEmpty<CompoundVariantConditions<V>>;
+type CompoundVariantBase<V extends VariantMap> = keyof V extends never ? EmptyRecord : CompoundVariantRequiredConditions<V>;
+type CompoundVariant<V extends VariantMap> = CompoundVariantBase<V> & {
+    class: VariantValue;
+};
+
+interface CVACompounds<V extends VariantMap> {
+    compoundVariants?: readonly CompoundVariant<V>[];
+}
+
+interface CVADefaults<V extends VariantMap> {
+    defaultVariants?: DefaultVariants<V>;
+}
+
+interface CVAVariants<V extends VariantMap> {
+    variants?: V;
+}
+
+type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;
+type VariantValue = string | string[];
+type VariantStates<K extends string = string> = Record<K, VariantValue>;
+type VariantMap<V extends string = string, K extends string = string> = Record<V, VariantStates<K>>;
+type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof V[K] & string>;
+/**
+ * A partial selection of variant states authored at factory definition time.
+ *
+ * Uses `keyof V[K]` directly (not `VariantKey`) so TypeScript can eagerly
+ * resolve the union at constraint-check time without deferred conditional types.
+ */
+type VariantSelection<V extends VariantMap> = {
+    [K in keyof V]?: keyof V[K];
+};
+/** The full optional prop surface exposed to callers for a given variant map. */
+type VariantProps<V extends VariantMap> = {
+    [K in keyof V]?: VariantKey<V, K>;
+};
+type NormalizedVariantValue<K extends string> = string extends K ? Primitive : K extends 'true' | 'false' ? Booleanish : K extends `${number}` ? Numberish : K;
+type DefaultVariants<V extends VariantMap> = {
+    [K in keyof V]?: NormalizedVariantValue<keyof V[K] & string>;
+};
+/**
+ * A static, immutable map of named presets to partial variant selections.
+ *
+ * Presets are named bundles of variant props that callers activate by key,
+ * avoiding the need to repeat variant combinations at each call site.
+ */
+type RecipeMap<V extends VariantMap = VariantMap> = Readonly<Record<string, VariantSelection<V>>>;
+type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+interface PolymorphicGenerics<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TAllowed extends ElementType = ElementType> {
+    default: TDefault;
+    props: Props;
+    variants: Variants;
+    preset: TPreset;
+    allowed: TAllowed;
+}
+type VariantsOf<T extends PolymorphicGenerics> = T['variants'];
+type RecipeOf<T extends PolymorphicGenerics> = T['preset'];
+type DefaultOf<T extends PolymorphicGenerics> = T['default'];
+type PropsOf<T extends PolymorphicGenerics> = T['props'];
+
+interface BaseClassOptions {
+    baseClassName?: ClassName;
+}
+
+type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string;
+
+interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
+    recipeMap?: Record<string, RecipeTarget<TVariants>>;
+}
+
+interface TagMapOptions {
+    tagMap?: TagMap;
+}
+
+type CompositionOptions<TVariants extends VariantMap = VariantMap> = Simplify<TagMapOptions & RecipeOptions<TVariants>>;
+
+type CVASystemOptions<TVariants extends VariantMap = VariantMap> = Simplify<CVAVariants<TVariants> & CVADefaults<TVariants> & CVACompounds<TVariants>>;
+
+type StyleOptions<TVariants extends VariantMap = VariantMap> = Simplify<BaseClassOptions & CVASystemOptions<TVariants>>;
+
+type ClassPipelineOptions<TVariants extends VariantMap = VariantMap> = Simplify<StyleOptions<TVariants> & CompositionOptions<TVariants>>;
+
+type OwnedPropKeys = ReadonlySet<string>;
+
+type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
+    pipeline: ClassPipelineFn;
+    ownedKeys?: OwnedPropKeys;
+    readonly _pluginProps?: TProps;
+}>;
+
+type ClassPluginFactory<TProps extends AnyRecord = EmptyRecord> = <V extends VariantMap>(options: ClassPipelineOptions<V>, diagnostics: Diagnostics) => ClassPlugin<TProps>;
+type ExtractPluginProps<TPlugin extends ClassPluginFactory<AnyRecord> | undefined> = TPlugin extends ClassPluginFactory<infer T> ? string extends keyof T ? EmptyRecord : T : EmptyRecord;
+
+type AriaContext = {
+    readonly tag: IntrinsicTag;
+    readonly implicitRole: AriaRole | undefined;
+    readonly effectiveRole: string | undefined;
+    readonly props: ReadonlyDeep<IntrinsicProps>;
+};
+
+type RemoveAttributeFixKind = `removeAttribute:${string}`;
+type InjectLiveFixKind = `injectLive:${string}`;
+type FixKind = 'removeRole' | 'setRole' | 'normalizeRelevantAll' | RemoveAttributeFixKind | InjectLiveFixKind;
+
+type AriaFixResult = {
+    applied: false;
+    next: ReadonlyDeep<IntrinsicProps>;
+} | {
+    applied: true;
+    next: ReadonlyDeep<IntrinsicProps>;
+    previous: ReadonlyDeep<IntrinsicProps>;
+};
+type AriaFix = {
+    readonly kind: FixKind;
+    readonly priority?: number;
+    readonly source?: string;
+    readonly apply: (context: AriaContext) => AriaFixResult;
+};
+
+type Severity = 'error' | 'warning' | (string & {});
+
+type AriaInvalidBase<M extends string = string> = {
+    valid: false;
+    severity: Severity;
+    message?: M;
+    attribute?: string;
+    diagnostic?: DiagnosticInput;
+};
+type AriaInvalidWithFix<M extends string = string> = AriaInvalidBase<M> & {
+    fixable: true;
+    fix: AriaFix;
+};
+type AriaInvalidWithoutFix<M extends string = string> = AriaInvalidBase<M> & {
+    fixable: false;
+};
+type AriaInvalidResult<M extends string = string> = AriaInvalidWithFix<M> | AriaInvalidWithoutFix<M>;
+type AriaResult = ValidResult | AriaInvalidResult;
+
+type AriaRule<C extends AriaContext = AriaContext> = (context: C) => readonly AriaResult[];
+
+type PropNormalizer = (props: Readonly<AnyRecord & IntrinsicProps>) => Partial<AnyRecord & IntrinsicProps>;
+
+type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
+    readonly diagnostics?: Diagnostics;
+    readonly aria?: readonly AriaRule[];
+    readonly children?: readonly ChildRuleInput[];
+    readonly props?: readonly PropNormalizer[];
+    /** Restricts the `as` prop to this set of tags. Violations route through diagnostics. */
+    readonly allowedAs?: readonly TAllowed[];
+};
+
+type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined> = {
+    readonly base?: ClassName;
+    readonly variants?: V;
+    readonly defaults?: Partial<DefaultVariants<V>>;
+    readonly compounds?: readonly CompoundVariant<V>[];
+    readonly presets?: TPreset;
+    readonly tags?: Readonly<TagMap>;
+    readonly plugin?: TPlugin;
+    readonly precomputedClasses?: Readonly<Record<string, string>>;
+};
+
+type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
+    normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
+}['normalize'];
+type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, ClassPluginFactory<AnyRecord> | undefined>;
+type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined, TAllowed extends ElementType = ElementType> = {
+    readonly tag?: TDefault;
+    readonly name?: string;
+    readonly defaults?: Partial<NoInfer<Props>>;
+    readonly normalize?: NormalizeFn<NoInfer<Props>>;
+    readonly styling?: StylingOptions<V, TPreset, TPlugin>;
+    readonly enforcement?: EnforcementOptions<TAllowed>;
+};
+
+declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
 
 type SlottableProps = {
     children?: ComponentChildren;
@@ -49,4 +278,4 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
 
 declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<Variants> = Readonly<EmptyRecord>, TPlugin extends ClassPluginFactory<AnyRecord> | undefined = ClassPluginFactory<AnyRecord> | undefined>(options: PreactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin>): PolymorphicComponent<PolymorphicGenerics<TDefault, Props & ExtractPluginProps<TPlugin>, Variants, TPreset>>;
 
-export { type ElementRef, type PolymorphicComponent, type PolymorphicProps, type PolymorphicWithAsChild, type PreactFactoryOptions, Slottable, createContractComponent };
+export { type AnyFactoryOptions, type ElementRef, type ElementType, type EmptyRecord, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PreactFactoryOptions, Slottable, createContractComponent, defineContractComponent };