praxis-kit 4.0.1 → 4.1.0

package/dist/{merge-refs-CEpa0zK1.d.ts → react-options-XrRof248.d.ts}

@@ -1,8 +1,10 @@
-import { ComponentType, PropsWithChildren, ReactElement, JSX, Ref, ReactNode } from 'react';
-import { Except, RequireAtLeastOne, Simplify, ReadonlyDeep, NonEmptyTuple } from 'type-fest';
+import { Ref, PropsWithChildren, ReactElement, ComponentType, JSX, 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 EmptyRecord = Record<never, never>;
 
 type IntrinsicTag = keyof HTMLElementTagNameMap;
 
@@ -13,7 +15,6 @@ 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;
@@ -23,159 +24,6 @@ type IntrinsicProps = AnyRecord & {
 };
 type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
 
-declare enum DiagnosticCategory {
-    Contract = 0,
-    HTML = 1,
-    ARIA = 2,
-    Composition = 3,
-    Rendering = 4,
-    Accessibility = 5,
-    Performance = 6,
-    Internal = 7,
-    Deprecation = 8,
-    Lint = 9
-}
-
-declare enum DiagnosticCode {
-    MissingRequiredChild = "COMP1001",
-    InvalidParent = "COMP1002",
-    InvalidChild = "COMP1003",
-    UnexpectedChild = "COMP1004",
-    AmbiguousChild = "COMP1005",
-    CardinalityMin = "COMP1006",
-    CardinalityMax = "COMP1007",
-    PositionViolation = "COMP1008",
-    AllowedAsViolation = "COMP1009",
-    SlotExclusive = "SLOT1001",
-    SlotSingleChild = "SLOT1002",
-    SlotDiscardedChildren = "SLOT1003",
-    SlotRenderFn = "SLOT1004",
-    MissingAriaRelationship = "ARIA2001",
-    AriaViolation = "ARIA2002",
-    AriaAttributeInvalid = "ARIA2003",
-    AriaMissingLiveRegion = "ARIA2004",
-    AriaMissingAtomic = "ARIA2005",
-    AriaRelevantInvalidToken = "ARIA2006",
-    AriaRelevantSuperseded = "ARIA2007",
-    AriaInvalidRole = "ARIA2008",
-    AriaMissingAccessibleName = "ARIA2009",
-    AriaAttributeOnPresentational = "ARIA2010",
-    AriaHiddenOnFocusable = "ARIA2011",
-    AriaRequiredProperty = "ARIA2012",
-    AriaInvalidAttributeValue = "ARIA2013",
-    AriaRedundantLevelAttribute = "ARIA2014",
-    InvalidHeadingHierarchy = "HTML3001",
-    HtmlEmptyRole = "HTML3002",
-    HtmlImplicitRoleRedundant = "HTML3003",
-    HtmlImplicitRoleOverride = "HTML3004",
-    HtmlStandaloneRegionOverride = "HTML3005",
-    HtmlLandmarkRoleOverride = "HTML3006",
-    HtmlInvalidChild = "HTML3007",
-    InvalidRenderingTarget = "RENDER4001",
-    LintDeadCompoundKey = "LINT5001",
-    LintDeadCompoundValue = "LINT5002",
-    LintDeadCompoundNonLiteral = "LINT5003",
-    LintMissingStrict = "LINT5004",
-    LintInvalidDefaultKey = "LINT5005",
-    LintInvalidDefaultValue = "LINT5006",
-    LintInvalidDefaultNonLiteral = "LINT5007",
-    LintNegativeMin = "LINT5008",
-    LintNegativeMax = "LINT5009",
-    LintMaxLessThanMin = "LINT5010",
-    LintZeroMax = "LINT5011",
-    LintMultipleFirst = "LINT5012",
-    LintMultipleLast = "LINT5013",
-    LintMinSumExceedsCapacity = "LINT5014",
-    LintCardinalityViolation = "LINT5015",
-    LintAriaTagOverride = "LINT5016",
-    ContractUnknownVariantDim = "COMP1010",
-    ContractUnknownVariantValue = "COMP1011",
-    ContractUnknownRecipeKey = "COMP1012",
-    ContractInvalidVariantValue = "COMP1013",
-    TailwindMultipleDisplayProps = "CSS6001",
-    TailwindReservedLayoutLiteral = "CSS6002",
-    TailwindDeadVariantClass = "CSS6003",
-    PluginInvalidShape = "PLUGIN7001",
-    PluginPipelineReturnType = "PLUGIN7002",
-    InternalError = "INTERNAL9000"
-}
-
-type MetadataMap = AnyRecord;
-type NodeId = string;
-
-interface Diagnostic$1 {
-    code: string;
-    message: string;
-    severity: 'error' | 'warning' | 'info';
-}
-
-type CapabilityMap = StringMap<boolean>;
-
-interface SourcePosition {
-    line: number;
-    col: number;
-}
-interface SourceLocation {
-    file: string;
-    start: SourcePosition;
-    end?: SourcePosition;
-}
-
-declare enum Severity$1 {
-    Debug = 0,
-    Info = 1,
-    Warning = 2,
-    Error = 3,
-    Fatal = 4
-}
-
-interface DiagnosticSuggestion {
-    title: string;
-    description?: string;
-    fix?: string;
-}
-
-type Context = AnyRecord;
-type Metadata = AnyRecord;
-interface Diagnostic {
-    code: DiagnosticCode;
-    severity: Severity$1;
-    category: DiagnosticCategory;
-    message: string;
-    rationale?: string;
-    component?: string;
-    contract?: string;
-    location?: SourceLocation;
-    suggestions?: DiagnosticSuggestion[];
-    context?: Context;
-    metadata?: Metadata;
-}
-
-declare enum Enforcement {
-    Ignore = 0,
-    Report = 1,
-    Throw = 2
-}
-interface DiagnosticPolicy {
-    resolve(diagnostic: Diagnostic): Enforcement;
-}
-
-interface DiagnosticReporter {
-    report(diagnostic: Diagnostic): void;
-}
-
-type DiagnosticInput = Except<Diagnostic, 'severity'>;
-declare class Diagnostics {
-    private readonly reporter;
-    private readonly policy;
-    readonly active: boolean;
-    constructor(reporter: DiagnosticReporter, policy?: DiagnosticPolicy);
-    report(diagnostic: Diagnostic): Diagnostic;
-    warn(input: DiagnosticInput): Diagnostic;
-    error(input: DiagnosticInput): Diagnostic;
-    info(input: DiagnosticInput): Diagnostic;
-}
-
 type MinMax = {
     min: number;
     max: number;
@@ -203,34 +51,16 @@ 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.
  *
@@ -240,14 +70,17 @@ type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof
 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.
  *
@@ -255,7 +88,9 @@ type DefaultVariants<V extends VariantMap> = {
  * 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;
@@ -269,6 +104,29 @@ type AllowedOf<T extends PolymorphicGenerics> = T['allowed'];
 type DefaultOf<T extends PolymorphicGenerics> = T['default'];
 type PropsOf<T extends PolymorphicGenerics> = T['props'];
 
+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;
+}
+
 interface BaseClassOptions {
     baseClassName?: ClassName;
 }
@@ -300,7 +158,11 @@ type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
 }>;
 
 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;
+/** `ClassPluginFactory` with its plugin-owned-props generic erased — the common form used
+ *  wherever a factory's concrete plugin-props shape isn't tracked (factory generics,
+ *  capability wiring). */
+type AnyClassPluginFactory = ClassPluginFactory<AnyRecord> | undefined;
+type ExtractPluginProps<TPlugin extends AnyClassPluginFactory> = TPlugin extends ClassPluginFactory<infer T> ? string extends keyof T ? EmptyRecord : T : EmptyRecord;
 
 type AriaContext = {
     readonly tag: IntrinsicTag;
@@ -360,7 +222,7 @@ type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
     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> = {
+type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = {
     readonly base?: ClassName;
     readonly variants?: V;
     readonly defaults?: Partial<DefaultVariants<V>>;
@@ -374,8 +236,8 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
 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> = {
+type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
+type FactoryOptions<TDefault extends ElementType = ElementType, Props extends AnyRecord = EmptyRecord, V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPreset extends RecipeMap<V> = Readonly<EmptyRecord>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = {
     readonly tag?: TDefault;
     readonly name?: string;
     readonly defaults?: Partial<NoInfer<Props>>;
@@ -384,6 +246,17 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
     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 {
@@ -396,10 +269,15 @@ interface ComponentDefinition {
     identity: ComponentIdentity;
     capabilities: CapabilityMap;
     metadata: MetadataMap;
-    diagnostics: Diagnostic$1[];
+    diagnostics: Diagnostic[];
 }
 
-type UnknownProps = Record<string, unknown>;
+declare function mergeRefs<T>(...refs: (Ref<T> | null | undefined)[]): Ref<T> | null;
+
+type SlottableProps = PropsWithChildren;
+declare function Slottable({ children }: SlottableProps): ReactElement;
+
+type UnknownProps = AnyRecord;
 type SlotComponent = ComponentType<UnknownProps>;
 
 /**
@@ -408,80 +286,96 @@ type SlotComponent = ComponentType<UnknownProps>;
  *
  * 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;
+type RenderCallbackProps = Readonly<AnyRecord>;
 
-/** 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.
+ * Maps a polymorphic element type to the instance type exposed through `ref`.
+ *
+ * Intrinsic HTML elements resolve to their corresponding DOM element type;
+ * custom React components currently fall back to `unknown`.
  */
-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. */
+/**
+ * React's intrinsic JSX props for a given element.
+ *
+ * Custom components intentionally fall back to `UnknownProps`; the component's
+ * own prop model defines their accepted props instead.
+ */
 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.
+ * Removes index signatures while preserving explicitly named properties.
+ *
+ * This prevents generic fallback constraints such as `Record<string, unknown>`
+ * from collapsing `keyof T` to `string`, which would cause
+ * `Omit<IntrinsicJSXProps<T>, keyof ...>` to remove every intrinsic prop.
  */
 type StripIndexSignature<T> = {
     [K in keyof T as string extends K ? never : K]: T[K];
 };
+/** Props explicitly declared by the component. */
 type ComponentProps<G extends PolymorphicGenerics> = StripIndexSignature<PropsOf<G>>;
+/** Variant props generated from the component's variant definitions. */
 type ComponentVariants<G extends PolymorphicGenerics> = StripIndexSignature<VariantProps<VariantsOf<G>>>;
+/**
+ * Props owned by the component itself.
+ *
+ * These take precedence over intrinsic HTML props when names overlap.
+ */
 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.
+ * Polymorphic rendering controls.
+ *
+ * These describe *how* the component renders rather than the data it owns.
  *
- * `asChild` and `children` are excluded — typed separately in the discriminated
- * union below so each render mode can enforce different child constraints.
+ * `children` and `asChild` are intentionally omitted so each render mode
+ * can provide its own stricter contract.
  */
 type PolymorphicControlProps<G extends PolymorphicGenerics, TAs extends ElementType> = {
+    /**
+     * Restrict `as` to `allowedAs` when configured.
+     *
+     * Without `allowedAs`, `AllowedOf<G>` resolves to `ElementType`,
+     * so the intersection becomes `TAs`.
+     */
     as?: TAs & AllowedOf<G>;
+    /**
+     * Explicit `undefined` keeps wrapper components compatible with
+     * `exactOptionalPropertyTypes`.
+     */
     className?: ClassName | undefined;
     recipe?: keyof RecipeOf<G>;
+    /** Ref type follows the resolved element. */
     ref?: Ref<ElementRef<TAs>>;
 };
-/** @internal Full set of props owned by the component — used as the Omit key in IntrinsicPropsWithoutOwned. */
+/**
+ * Complete set of props owned by the component.
+ *
+ * Used primarily as the exclusion list when inheriting intrinsic JSX props.
+ */
 type ControlProps<G extends PolymorphicGenerics, TAs extends ElementType> = OwnedProps<G> & PolymorphicControlProps<G, TAs>;
+/**
+ * Intrinsic JSX props after removing every prop owned by the component.
+ *
+ * Component props always win over intrinsic props with the same name.
+ */
 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. */
+/**
+ * Base props shared by every render mode.
+ *
+ * Render modes contribute only their discriminants (`asChild`, `render`,
+ * `children`, etc.).
+ */
+type BaseProps<G extends PolymorphicGenerics, TAs extends ElementType> = IntrinsicPropsWithoutOwned<G, TAs> & ControlProps<G, TAs>;
+/** Standard rendering (`asChild` absent or false). */
 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.
+ * Slot rendering.
+ *
+ * Requires one or more React elements and forbids `as`, since the child
+ * determines the rendered element.
  */
 type SlotRenderMode = {
     asChild: true;
@@ -489,17 +383,12 @@ type SlotRenderMode = {
     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.
+ * Render callback.
  *
- * 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.
+ * The callback receives fully resolved props (classes, refs, filtered props)
+ * and is responsible for rendering the target element.
  *
- * ```tsx
- * <Button render={(p) => <a href="/home" {...p} />} size="lg" />
- * ```
+ * This provides the flexibility of `asChild` without `cloneElement`.
  */
 type CallbackRenderMode = {
     render: (props: RenderCallbackProps) => ReactElement;
@@ -507,26 +396,29 @@ type CallbackRenderMode = {
     children?: never;
 };
 /**
- * Props for the normal render path. HTML attributes are inferred from `TAs`.
+ * Standard polymorphic props.
  *
- * `Omit + intersection` (not `Merge`) is used so TypeScript can infer `TAs` from
- * the `as` prop value; control props win on key conflicts.
+ * HTML attributes are inferred from `as`.
  */
-type PolymorphicProps<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<SharedProps<G, TAs> & NormalRenderMode>;
+type PolymorphicProps<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<BaseProps<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.
+ * Slot rendering props.
+ *
+ * Requires one or more ReactElement children.
  */
-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>;
+type PolymorphicWithAsChild<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<BaseProps<G, TAs> & SlotRenderMode>;
 /**
- * A polymorphic component that infers HTML attributes and ref type from the `as` prop.
+ * Render callback props.
+ */
+type PolymorphicWithRender<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<BaseProps<G, TAs> & CallbackRenderMode>;
+/**
+ * A polymorphic React component.
+ *
+ * Overloads form a discriminated union:
  *
- * 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
+ * • `render`   → render callback
+ * • `asChild`  → Slot rendering
+ * • otherwise  → normal rendering
  */
 type PolymorphicComponent<G extends PolymorphicGenerics> = {
     <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicWithRender<G, TAs>): ReactElement;
@@ -535,6 +427,29 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
     displayName?: string;
 };
 
-declare function mergeRefs<T>(...refs: (Ref<T> | null | undefined)[]): Ref<T> | null;
+/** 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 AnyClassPluginFactory = AnyClassPluginFactory, 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;
+};
 
-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 };
+export { type AnyClassPluginFactory as A, 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 };