praxis-kit 0.1.0 → 1.0.2

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
-import { C as MergeRecords, E as AnyRecord, S as EmptyRecord, T as NoVariants, _ as ExtractPluginProps, a as PolymorphicProps, b as VariantMap, c as RenderCallbackProps, d as SlottableProps, f as mergeRefs, g as AnyClassPluginFactory, h as FactoryOptions, i as PolymorphicComponent, l as UnknownProps, m as AnyFactoryOptions, n as ContractProps, o as PolymorphicWithAsChild, p as defineContractComponent, r as ElementRef, s as PolymorphicWithRender, t as ReactFactoryOptions, u as Slottable, v as PolymorphicGenerics, w as NoPreset, x as ElementType, y as RecipeMap } from "../index-BIBd_iPD.js";
+import { C as RecipeMap, D as MergeRecords, E as EmptyRecord, O as AnyRecord, S as PolymorphicGenerics, T as ElementType, _ as ContractTagOf, a as PolymorphicProps, b as AnyClassPluginFactory, c as RenderCallbackProps, d as SlottableProps, f as mergeRefs, g as ContractPropsOf, h as ContractPresetOf, i as PolymorphicComponent, l as UnknownProps, m as ContractPluginOf, n as ContractProps, o as PolymorphicWithAsChild, p as ContractAllowedOf, r as ElementRef, s as PolymorphicWithRender, t as ReactFactoryOptions, u as Slottable, v as ContractVariantsOf, w as VariantMap, x as ExtractPluginProps, y as FactoryOptions } from "../index-zJDSXTxL.js";
 //#region ../../adapters/react/src/current/create-contract-component.d.ts
 /**
  * Creates a polymorphic React 19 component with praxis-kit contracts applied.
@@ -20,9 +20,18 @@ import { C as MergeRecords, E as AnyRecord, S as EmptyRecord, T as NoVariants, _
  * `ref` is accepted as a plain prop (React 19) and forwarded to the rendered host element or,
  * with `asChild`, to the consumer's own element. Pass `subComponents` to attach named
  * sub-components (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+ *
+ * `TDefault`/`Props`/`Variants`/`TPreset`/`TPlugin`/`TAllowed` are each `ContractXOf<C>`-derived
+ * *defaults* on this function's own type parameter list — not computed inline in the function
+ * body from the still-abstract `C` (an earlier draft did this; confirmed broken, since
+ * `ContractXOf<C>` doesn't simplify to a concrete value for an abstract `C` the way it does once
+ * `C` is resolved at a real call site — the same lesson `defineContract`'s own signature already
+ * encodes). Declaring them as defaults means each resolves once, concretely, at the actual call
+ * site, exactly mirroring how these six dimensions were independently inferred pre-refactor —
+ * `C` is now the single authoritative input; these are its projection, not a fresh inference.
  */
-export declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+export declare function createContractComponent<C extends ReactFactoryOptions, TDefault extends ElementType = ContractTagOf<C>, Props extends UnknownProps = ContractPropsOf<C>, Variants extends Readonly<VariantMap> = ContractVariantsOf<C>, TPreset extends RecipeMap<VariantMap> = ContractPresetOf<C>, TPlugin extends AnyClassPluginFactory = ContractPluginOf<C>, TAllowed extends ElementType = ContractAllowedOf<C>, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: C & {
   readonly subComponents?: TSubComponents;
-}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>>, TSubComponents>;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>, C>, TSubComponents>;
 //#endregion
-export { type AnyFactoryOptions, type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type FactoryOptions, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PolymorphicWithRender, type ReactFactoryOptions, type RenderCallbackProps, Slottable, type SlottableProps, defineContractComponent, mergeRefs };
+export { type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type FactoryOptions, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PolymorphicWithRender, type ReactFactoryOptions, type RenderCallbackProps, Slottable, type SlottableProps, mergeRefs };

package/dist/react/index.js

@@ -1,74 +1,5 @@
-import { _ as invariant, a as getElementRef, c as Slottable, d as finalizeComponent, f as SLOT_NAME, g as defineContractComponent, h as isString, i as makeCloneSlotChild, l as applyDisplayName, m as isObject, n as render, o as getPropsRef, p as isFunction, r as applySlot, s as hasWarningGetter, t as buildRuntime$1, u as mergeRefs } from "../build-runtime-CJ_nQEaZ.js";
+import { a as getElementRef, c as Slottable, d as isReactFactoryOptions, f as finalizeComponent, g as invariant, h as isString, i as makeCloneSlotChild, l as applyDisplayName, m as isFunction, n as render, o as getPropsRef, p as SLOT_NAME, r as applySlot, s as hasWarningGetter, t as buildRuntime$1, u as mergeRefs } from "../build-runtime-cNkW-D62.js";
 import { isValidElement, useCallback, useRef } from "react";
-//#region ../../lib/adapter-utils/src/runtime/is-factory-options-like.ts
-/**
-* Loosely validates one recognized `FactoryOptions` field's runtime shape.
-* "Loosely" because the field's declared type is itself parameterized by a
-* generic (Props, Variants, TPlugin, ...) that's erased at runtime — these
-* checks confirm the field is the right *kind* of value (object, function,
-* string), not that it satisfies its exact generic instantiation, which no
-* runtime check can ever do.
-*
-* Covers every field `FactoryOptions` itself declares — identical across
-* every adapter, since they all extend the same core type. Adapter-specific
-* additions (React's `slotComponent`/`artifact`, every adapter's own
-* `filterProps`, etc.) are passed in by the caller as extra entries.
-*/
-const FACTORY_OPTIONS_FIELD_VALIDATORS = {
-	tag: (v) => v === void 0 || isString(v),
-	name: (v) => v === void 0 || isString(v),
-	defaults: (v) => v === void 0 || isObject(v),
-	normalize: (v) => v === void 0 || isFunction(v),
-	styling: (v) => v === void 0 || isObject(v),
-	enforcement: (v) => v === void 0 || isObject(v),
-	diagnostics: (v) => v === void 0 || isObject(v),
-	subComponents: (v) => v === void 0 || isObject(v),
-	onElement: (v) => v === void 0 || isFunction(v)
-};
-/**
-* Type guard narrowing the generic `FactoryOptions` shape down to an
-* adapter-specific factory options type `T` — the type each adapter's
-* `buildRuntime` is declared against.
-*
-* Walks every own enumerable property on `options` and checks it against
-* `FACTORY_OPTIONS_FIELD_VALIDATORS` plus `extraFieldValidators` (the
-* adapter's own additions on top of `FactoryOptions`): an unrecognized key,
-* or a recognized key holding a value of the wrong kind, fails the guard.
-* This is a genuine structural check, not a relabeled assertion — though it
-* necessarily stops at each field's runtime *kind*, since the field's actual
-* generic instantiation is erased at runtime and no guard can validate it.
-* That part remains the caller's responsibility, same as with any other
-* generic function in TypeScript.
-*/
-function isFactoryOptionsLike(options, extraFieldValidators) {
-	if (!isObject(options)) return false;
-	const validators = {
-		...FACTORY_OPTIONS_FIELD_VALIDATORS,
-		...extraFieldValidators
-	};
-	for (const [key, value] of Object.entries(options)) {
-		const validate = validators[key];
-		if (!validate || !validate(value)) return false;
-	}
-	return true;
-}
-//#endregion
-//#region ../../adapters/react/src/shared/to-react-factory-options.ts
-/** React-specific additions on top of `FactoryOptions`. */
-const REACT_FIELD_VALIDATORS = {
-	slotComponent: (v) => v === void 0 || isFunction(v) || isObject(v),
-	filterProps: (v) => v === void 0 || isFunction(v),
-	artifact: (v) => v === void 0 || isObject(v)
-};
-/**
-* Type guard narrowing the generic `FactoryOptions` shape down to
-* `ReactFactoryOptions` — the type `buildRuntime` is declared against. See
-* `isFactoryOptionsLike` for what this does and doesn't validate.
-*/
-function isReactFactoryOptions(options) {
-	return isFactoryOptionsLike(options, REACT_FIELD_VALIDATORS);
-}
-//#endregion
 //#region ../../adapters/react/src/shared/is-polymorphic-component.ts
 /**
 * Type guard narrowing a generated component's real (framework-specific)
@@ -137,9 +68,26 @@ function buildRuntime(options) {
 * `ref` is accepted as a plain prop (React 19) and forwarded to the rendered host element or,
 * with `asChild`, to the consumer's own element. Pass `subComponents` to attach named
 * sub-components (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+*
+* `TDefault`/`Props`/`Variants`/`TPreset`/`TPlugin`/`TAllowed` are each `ContractXOf<C>`-derived
+* *defaults* on this function's own type parameter list — not computed inline in the function
+* body from the still-abstract `C` (an earlier draft did this; confirmed broken, since
+* `ContractXOf<C>` doesn't simplify to a concrete value for an abstract `C` the way it does once
+* `C` is resolved at a real call site — the same lesson `defineContract`'s own signature already
+* encodes). Declaring them as defaults means each resolves once, concretely, at the actual call
+* site, exactly mirroring how these six dimensions were independently inferred pre-refactor —
+* `C` is now the single authoritative input; these are its projection, not a fresh inference.
 */
 function createContractComponent(options) {
 	invariant(isReactFactoryOptions(options), "options is not a valid ReactFactoryOptions object");
+	/**
+	* `C` and `TDefault`/`Props`/`Variants`/`TPreset`/`TAllowed` are formally independent type
+	* parameters to the checker — `TDefault = ContractTagOf<C>` is a *default value*, used only
+	* when nothing else is inferred, not a provable relationship the checker can use inside this
+	* body. The `invariant` above is what actually guarantees `options` is `ReactFactoryOptions`
+	* shaped; this assertion bridges the gap in the compiler's reasoning the same way the return
+	* statement below already does.
+	*/
 	const bundle = buildRuntime(options);
 	/** Captured once from the factory options so the callback ref below can remain stable. */
 	const { onElement } = options;
@@ -197,9 +145,11 @@ function createContractComponent(options) {
 	* prove that the assembled value satisfies the same conditional expression used by the
 	* declared return type. Once the generics are instantiated at a call site, the conditional
 	* simplifies correctly. The invariant above validates the runtime shape; this assertion
-	* bridges the gap in the compiler's type reasoning.
+	* bridges the gap in the compiler's type reasoning. Also where `__contract`'s `C` is attached —
+	* type-only, matching `__generics`: `assembled` never actually gains a `__contract` property at
+	* runtime, only in the type this assertion claims.
 	*/
 	return assembled;
 }
 //#endregion
-export { Slottable, createContractComponent, defineContractComponent, mergeRefs };
+export { Slottable, createContractComponent, mergeRefs };

package/dist/react/legacy.d.ts

@@ -1,4 +1,4 @@
-import { C as MergeRecords, E as AnyRecord, S as EmptyRecord, T as NoVariants, _ as ExtractPluginProps, a as PolymorphicProps, b as VariantMap, c as RenderCallbackProps, d as SlottableProps, f as mergeRefs, g as AnyClassPluginFactory, h as FactoryOptions, i as PolymorphicComponent, l as UnknownProps, m as AnyFactoryOptions, n as ContractProps, o as PolymorphicWithAsChild, p as defineContractComponent, r as ElementRef, s as PolymorphicWithRender, t as ReactFactoryOptions, u as Slottable, v as PolymorphicGenerics, w as NoPreset, x as ElementType, y as RecipeMap } from "../index-BIBd_iPD.js";
+import { C as RecipeMap, D as MergeRecords, E as EmptyRecord, O as AnyRecord, S as PolymorphicGenerics, T as ElementType, _ as ContractTagOf, a as PolymorphicProps, b as AnyClassPluginFactory, c as RenderCallbackProps, d as SlottableProps, f as mergeRefs, g as ContractPropsOf, h as ContractPresetOf, i as PolymorphicComponent, l as UnknownProps, m as ContractPluginOf, n as ContractProps, o as PolymorphicWithAsChild, p as ContractAllowedOf, r as ElementRef, s as PolymorphicWithRender, t as ReactFactoryOptions, u as Slottable, v as ContractVariantsOf, w as VariantMap, x as ExtractPluginProps, y as FactoryOptions } from "../index-zJDSXTxL.js";
 //#region ../../adapters/react/src/legacy/create-contract-component.d.ts
 /**
  * Creates a polymorphic React component with praxis-kit contracts applied, for React 18 and
@@ -21,9 +21,14 @@ import { C as MergeRecords, E as AnyRecord, S as EmptyRecord, T as NoVariants, _
  * Returns a `forwardRef` component — `ref` is forwarded to the rendered host element the same
  * way it works in `praxis-kit/react`. Pass `subComponents` to attach named sub-components
  * (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+ *
+ * `TDefault`/`Props`/`Variants`/`TPreset`/`TPlugin`/`TAllowed` are each `ContractXOf<C>`-derived
+ * *defaults* on this function's own type parameter list, mirroring `current/create-contract-component.ts`
+ * exactly — see that file's own doc comment for why (computed as function type-parameter defaults,
+ * not inline body computations, which doesn't resolve for a still-abstract `C`).
  */
-export declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+export declare function createContractComponent<C extends ReactFactoryOptions, TDefault extends ElementType = ContractTagOf<C>, Props extends UnknownProps = ContractPropsOf<C>, Variants extends Readonly<VariantMap> = ContractVariantsOf<C>, TPreset extends RecipeMap<VariantMap> = ContractPresetOf<C>, TPlugin extends AnyClassPluginFactory = ContractPluginOf<C>, TAllowed extends ElementType = ContractAllowedOf<C>, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: C & {
   readonly subComponents?: TSubComponents;
-}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>>, TSubComponents>;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>, C>, TSubComponents>;
 //#endregion
-export { type AnyFactoryOptions, type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type FactoryOptions, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PolymorphicWithRender, type ReactFactoryOptions, type RenderCallbackProps, Slottable, type SlottableProps, defineContractComponent, mergeRefs };
+export { type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type FactoryOptions, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PolymorphicWithRender, type ReactFactoryOptions, type RenderCallbackProps, Slottable, type SlottableProps, mergeRefs };

package/dist/react/legacy.js

@@ -1,4 +1,4 @@
-import { a as getElementRef, c as Slottable, d as finalizeComponent, f as SLOT_NAME, g as defineContractComponent, i as makeCloneSlotChild, l as applyDisplayName, n as render, o as getPropsRef, r as applySlot, s as hasWarningGetter, t as buildRuntime$1, u as mergeRefs } from "../build-runtime-CJ_nQEaZ.js";
+import { a as getElementRef, c as Slottable, d as isReactFactoryOptions, f as finalizeComponent, g as invariant, i as makeCloneSlotChild, l as applyDisplayName, n as render, o as getPropsRef, p as SLOT_NAME, r as applySlot, s as hasWarningGetter, t as buildRuntime$1, u as mergeRefs } from "../build-runtime-cNkW-D62.js";
 import { Children, forwardRef, isValidElement, useCallback, useRef } from "react";
 //#region ../../adapters/react/src/legacy/slot/composeRefs.ts
 function getChildRef(element) {
@@ -47,8 +47,20 @@ function buildRuntime(options) {
 * Returns a `forwardRef` component — `ref` is forwarded to the rendered host element the same
 * way it works in `praxis-kit/react`. Pass `subComponents` to attach named sub-components
 * (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+*
+* `TDefault`/`Props`/`Variants`/`TPreset`/`TPlugin`/`TAllowed` are each `ContractXOf<C>`-derived
+* *defaults* on this function's own type parameter list, mirroring `current/create-contract-component.ts`
+* exactly — see that file's own doc comment for why (computed as function type-parameter defaults,
+* not inline body computations, which doesn't resolve for a still-abstract `C`).
 */
 function createContractComponent(options) {
+	invariant(isReactFactoryOptions(options), "options is not a valid ReactFactoryOptions object");
+	/**
+	* `C` and `TDefault`/`Props`/`Variants`/`TPreset`/`TAllowed` are formally independent type
+	* parameters to the checker — see `current/create-contract-component.ts`'s identical comment
+	* for the full explanation. The `invariant` above is what actually guarantees `options` is
+	* `ReactFactoryOptions` shaped; this assertion bridges the gap in the compiler's reasoning.
+	*/
 	const bundle = buildRuntime(options);
 	const { onElement } = options;
 	const Component = forwardRef(function Component(props, ref) {
@@ -77,4 +89,4 @@ function createContractComponent(options) {
 	return finalizeComponent(Component, bundle.runtime.options.defaultTag, options.subComponents);
 }
 //#endregion
-export { Slottable, createContractComponent, defineContractComponent, mergeRefs };
+export { Slottable, createContractComponent, mergeRefs };

package/dist/solid/index.d.ts

@@ -25,20 +25,6 @@ type EmptyRecord = Record<never, never>;
  * `{ Header, Content, Footer }`.
  */
 type SubComponentMap = Readonly<AnyRecord>;
-/**
- * Default `Variants` type for components that declare no variants.
- *
- * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
- * editor hovers remain self-descriptive.
- */
-type NoVariants = Readonly<EmptyRecord>;
-/**
- * Default `TPreset` type for components that declare no named presets.
- *
- * Structurally identical to `Readonly<EmptyRecord>`, but named separately so
- * editor hovers remain self-descriptive.
- */
-type NoPreset = Readonly<EmptyRecord>;
 /**
  * Fallback for `ExtractPluginProps<TPlugin>` when a plugin contributes no
  * props, including the no-plugin case.
@@ -537,16 +523,6 @@ type StylingOptions<V extends Readonly<VariantMap> = Readonly<EmptyRecord>, TPre
 type NormalizeFn<Props extends AnyRecord = AnyRecord> = {
   normalize(props: Readonly<Props & IntrinsicProps>): Props & IntrinsicProps;
 }['normalize'];
-/**
- * The type-erased shape of {@link FactoryOptions} — every generic parameter widened to its bound.
- *
- * Use it for a value that must hold *any* factory config (a registry, a generic wrapper). It
- * cannot check `styling.compounds` conditions against the real variant keys/values, because it
- * has forgotten what they are — for that, annotate against `FactoryOptions<...>` with the concrete
- * generics (or `satisfies FactoryOptions<'button', Props, typeof variants>`), which keeps an
- * invalid compound condition a type error rather than a silent no-op.
- */
-type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, RecipeMap<VariantMap>, AnyClassPluginFactory>;
 /**
  * The framework-neutral component-authoring config passed to `createContractComponent` in every
  * adapter: default tag + name, own-prop defaults, a `normalize` transform, `styling` (variants,
@@ -556,7 +532,9 @@ type AnyFactoryOptions = FactoryOptions<ElementType, AnyRecord, VariantMap, Reci
  * `satisfies FactoryOptions<TDefault, Props, typeof variants, ...>` on a config object narrows
  * `styling.compounds` conditions to the real per-variant-key shape — including resolving a
  * boolean-shaped axis (`{ true, false }`) to a real `boolean` — so a condition naming a variant or
- * value that does not exist is a compile error. `AnyFactoryOptions` cannot do this.
+ * value that does not exist is a compile error. Leaving `V` at the bare `VariantMap` instead
+ * (whether via `FactoryOptions`'s own default or an explicit erased instantiation) forgets that
+ * shape entirely, so the same invalid condition becomes a silent no-op instead.
  */
 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> = {
   /** The intrinsic tag the component renders by default. Overridable per instance via `as`. */
@@ -565,6 +543,33 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
   readonly name?: string;
   /** Values used for the component's own (non-variant) props when the consumer omits them. */
   readonly defaults?: Partial<NoInfer<Props>>;
+  /**
+   * Optional, type-only declaration of this component's complete own-prop shape — present purely
+   * for type recovery, never read at runtime (see `declareProps` in `@praxis-kit/adapter-utils`).
+   *
+   * `defaults` alone can only prove a prop *has a default*, not that it's the complete prop model
+   * a component accepts — a `defaults: { size: 'md' }` component may still take `onClick`,
+   * `disabled`, and other props with no default at all, none of which a `defaults`-only recovery
+   * can see (see `ContractPropsFrom`'s own doc comment for the general shape of this problem).
+   * `props` closes that gap: when present, `ContractPropsOf<C>` / `ContractProps<typeof Component>`
+   * recover this declared type directly and exactly, in place of the necessarily-partial,
+   * literal-widened recovery `defaults` alone allows.
+   *
+   * Typed as `object | undefined`, not `NoInfer<Props> | undefined` like `defaults`/`onElement` —
+   * deliberately decoupled from this interface's own `Props` generic, unlike those two fields.
+   * `defaults`/`onElement` are tied to `Props` because real runtime code reads them against a
+   * concretely-resolved `Props` for a real call; `props` is never read at runtime at all (see
+   * above), so it has no such need, and tying it to `Props extends AnyRecord` would force every
+   * hand-declared prop `interface`/`type` an author passes through `declareProps<Props>()` to
+   * structurally satisfy `Record<string, unknown>` — a real TypeScript limitation (a named type
+   * without an index signature never satisfies that, even via plain assignment, only a fresh
+   * object literal does) that would make this field far more awkward to use for its one real job:
+   * carrying an author's own already-precise prop type through untouched. `ContractPropsFrom`
+   * (`contract-model.ts`) recovers the real value here structurally, straight off `O`'s own
+   * literal type — independent of this field's declared type, same as every other `Contract*From`
+   * derivation in that file.
+   */
+  readonly props?: object | undefined;
   /**
    * A pure `(props) => props` transform run on every render, after `enforcement.props`'s
    * normalizers see the same input. Use this for component-specific prop shaping — anything
@@ -619,18 +624,172 @@ type FactoryOptions<TDefault extends ElementType = ElementType, Props extends An
    *
    * Return a cleanup function to run when the instance unmounts.
    */
-  readonly onElement?: (element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>) => void | (() => void);
+  readonly onElement?: {
+    onElement(element: ElementForTag<TDefault | TAllowed>, getProps: () => Readonly<Props>): void | (() => void);
+  }['onElement'];
 };
 //#endregion
-//#region ../../lib/adapter-utils/src/runtime/define-component.d.ts
-export declare function defineContractComponent<O extends FactoryOptions>(options: O): <R>(factory: (options: O) => R) => R;
+//#region ../../lib/primitive/src/types/factory/contract-model.d.ts
+/**
+ * The pipeline this file implements:
+ *
+ * ```text
+ * O (a raw contract literal)
+ *   → Contract*From<O>        one derivation per dimension, straight off O's own shape
+ *   → ContractDimensions<O>   the six derivations, assembled
+ *   → ContractModel<...>      the same six values, as a required-field carrier
+ *   → ContractModelOf<C>      resolves an already-`defineContract`-ed C's real model,
+ *                             or reconstructs one from a raw C via ContractModelFrom
+ * ```
+ *
+ * See `DECISIONS.md`'s `defineContract` entry for the TypeScript limitations that shaped the
+ * derivations below.
+ */
+/**
+ * Canonical type-level representation of a contract's dimensions — the contract-level counterpart
+ * to `PolymorphicGenerics`. Every field is required, so a field's presence is never ambiguous the
+ * way it is on an optional `FactoryOptions` field.
+ */
+interface ContractModel<TDefault extends ElementType = ElementType, Props extends AnyRecord = AnyRecord, V extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<VariantMap> = RecipeMap<VariantMap>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> {
+  readonly tag: TDefault;
+  readonly props: Props;
+  readonly variants: V;
+  readonly preset: TPreset;
+  readonly plugin: TPlugin;
+  readonly allowed: TAllowed;
+}
+/**
+ * The phantom-marker shape read back via `T extends HasContractModel<infer M> ? M : ...` — the
+ * contract-level counterpart to `lib/contract-props`'s `HasGenerics<G>`. Type-only: never assigned
+ * at runtime.
+ *
+ * `__model` is **required**, not optional like `HasGenerics<G>`'s `__generics?` — an optional field
+ * would make `C extends HasContractModel<infer M>` trivially succeed for any `C`, defeating the
+ * one thing this marker exists to answer: did `C` really go through `defineContract`?
+ */
+interface HasContractModel<M extends ContractModel = ContractModel> {
+  readonly __model: M;
+}
+type ContractTagFrom<O> = O extends {
+  tag: infer TDefault extends ElementType;
+} ? TDefault : ElementType;
+/** `'img'` → `string`, `1` → `number`, `true` → `boolean` — undoes `defineContract`'s `const O`
+ *  literal narrowing so a `defaults` value doesn't become the only value a caller may pass. */
+type WidenLiteral<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+type WidenShallow<T> = { [K in keyof T]: WidenLiteral<T[K]>; };
+/** What the author explicitly declared, via `props: declareProps<Props>()`
+ *  (`@praxis-kit/adapter-utils`) — used exactly as declared, no `Partial`/widening/`data-*`
+ *  stripping (see `DefaultPropsFrom` for why those exist there but not here). */
+type DeclaredPropsFrom<O> = O extends {
+  props: infer Props extends object | undefined;
+} ? [NonNullable<Props>] extends [never] ? never : NonNullable<Props> & AnyRecord : never;
+/** What can be inferred from `defaults` — partial at best, since a default only proves a prop
+ *  *has* one, not that it's the complete prop set. `Partial`: a defaulted prop is optional to the
+ *  caller by definition. `data-*` keys are dropped — every adapter has its own passthrough for
+ *  those already (finding #43). */
+type DefaultPropsFrom<O> = O extends {
+  defaults: infer Props extends AnyRecord;
+} ? Partial<WidenShallow<Omit<Props, Extract<keyof Props, `data-${string}`>>>> : never;
+/** Declared beats defaulted beats nothing. `[X] extends [never]`, not bare `X extends never` —
+ *  tuple-wrapped so the check doesn't distribute if `X` is ever a union containing `never`. */
+type ContractPropsFrom<O> = [DeclaredPropsFrom<O>] extends [never] ? [DefaultPropsFrom<O>] extends [never] ? EmptyRecord : DefaultPropsFrom<O> : DeclaredPropsFrom<O>;
+type ContractVariantsFrom<O> = O extends {
+  styling: {
+    variants: infer V extends Readonly<VariantMap>;
+  };
+} ? V : Readonly<EmptyRecord>;
+type ContractPresetFrom<O> = O extends {
+  styling: {
+    presets: infer TPreset extends RecipeMap<VariantMap>;
+  };
+} ? TPreset : Readonly<EmptyRecord>;
+type ContractPluginFrom<O> = O extends {
+  styling: {
+    plugin: infer TPlugin extends AnyClassPluginFactory;
+  };
+} ? TPlugin : AnyClassPluginFactory;
+type ContractAllowedFrom<O> = O extends {
+  enforcement: {
+    allowedAs: readonly (infer TAllowed extends ElementType)[];
+  };
+} ? TAllowed : ElementType;
+/** The six derivations above, assembled — the direct input to `ContractModel`. */
+type ContractDimensions<O> = {
+  readonly tag: ContractTagFrom<O>;
+  readonly props: ContractPropsFrom<O>;
+  readonly variants: ContractVariantsFrom<O>;
+  readonly preset: ContractPresetFrom<O>;
+  readonly plugin: ContractPluginFrom<O>;
+  readonly allowed: ContractAllowedFrom<O>;
+};
+/**
+ * Builds a `ContractModel` from a raw literal `O` — the fallback path `ContractModelOf<C>` uses
+ * when `C` never went through `defineContract` (no `__model` marker to read directly), and what
+ * `defineContract` itself attaches as that marker for a `C` that did.
+ */
+type ContractModelFrom<O> = ContractDimensions<O> extends (infer D extends ContractDimensions<O>) ? ContractModel<D['tag'], D['props'], D['variants'], D['preset'], D['plugin'], D['allowed']> : never;
+/**
+ * Resolves "does `C` carry a real `ContractModel` already, or do we need to build one from its raw
+ * shape" — every `Contract*Of` accessor (`contract-of.ts`) is a one-line projection off this.
+ */
+type ContractModelOf<C> = C extends HasContractModel<infer M> ? M : ContractModelFrom<C>;
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-of.d.ts
+/**
+ * `FactoryOptions`-level accessor family, mirroring `polymorphic-generics.ts`'s `*Of<T>`
+ * convention (`DefaultOf<G>`, `PropsOf<G>`, etc.) but applied one layer up, to a contract itself
+ * rather than to the `PolymorphicGenerics` an adapter derives from it.
+ *
+ * Named with a `Contract` prefix specifically to avoid colliding with `polymorphic-generics.ts`'s
+ * own `PropsOf`/`VariantsOf`/`RecipeOf`/`AllowedOf`/`DefaultOf` — both families are re-exported
+ * from `@praxis-kit/core`, so a name clash would be a real conflict, not a style nit.
+ *
+ * Each accessor is a trivial projection off `ContractModelOf<C>` (`contract-model.ts`) — the one
+ * place that resolves "does `C` carry a real `ContractModel` (via `defineContract`) or does one
+ * need reconstructing from `C`'s raw shape," so every accessor shares one implementation of that
+ * resolution rather than repeating it. See `contract-model.ts`'s own doc comments for the
+ * `ContractXFrom<O>` derivation each of these ultimately reads through, and `DECISIONS.md`'s
+ * `defineContract` entry for the design history behind the required-pattern-match technique.
+ */
+type ContractTagOf<C extends FactoryOptions> = ContractModelOf<C>['tag'];
+/** See this file's own doc comment. Best-effort when `C` has no `ContractModel` marker — see
+ *  `ContractPropsFrom`'s own doc comment for why. */
+type ContractPropsOf<C extends FactoryOptions> = ContractModelOf<C>['props'];
+/** See this file's own doc comment. */
+type ContractVariantsOf<C extends FactoryOptions> = ContractModelOf<C>['variants'];
+/** See this file's own doc comment. */
+type ContractPresetOf<C extends FactoryOptions> = ContractModelOf<C>['preset'];
+/** See this file's own doc comment. */
+type ContractPluginOf<C extends FactoryOptions> = ContractModelOf<C>['plugin'];
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-generics.d.ts
+/**
+ * The canonical projection from a defined contract `C` to the `PolymorphicGenerics` shape every
+ * adapter's prop types are built from — the one place "G" gets computed, so it can no longer
+ * silently drift per adapter the way today's hand-assembled `PolymorphicGenerics<...>` instantiation
+ * at each `createContractComponent` call site can (see `ContractGenericsWithAllowedOf` below for
+ * the one confirmed instance of that drift).
+ *
+ * Folds the class-resolution plugin's own contributed props (`ExtractPluginProps<TPlugin>`) into
+ * `props` here, once, rather than leaving each adapter's `ContractProps` to re-derive that merge
+ * via its own distributive conditional type on every read — the root cause of the ~22-member
+ * layout-union bug PR #95 patched per-adapter (see `DECISIONS.md`'s `defineContract` entry).
+ */
+type ContractGenericsOf<C extends FactoryOptions> = PolymorphicGenerics<ContractTagOf<C>, MergeRecords<ContractPropsOf<C>, ExtractPluginProps<ContractPluginOf<C>>>, ContractVariantsOf<C>, ContractPresetOf<C>>;
 //#endregion
 //#region ../../adapters/solid/src/types/primitives.d.ts
 type UnknownProps = AnyRecord;
 type SolidElement = JSX.Element;
 //#endregion
 //#region ../../adapters/solid/src/solid-options.d.ts
-type SolidFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+/**
+ * Every generic parameter has a default (widened to that parameter's own *bound*, matching
+ * a wide-bound, type-erased philosophy, not `FactoryOptions`'s own narrower `EmptyRecord`-style
+ * defaults) so `SolidFactoryOptions` can be used bare, as `createContractComponent`'s single
+ * `C extends SolidFactoryOptions` constraint — see `ReactFactoryOptions`'s identical fix for the
+ * same reason.
+ */
+type SolidFactoryOptions<TDefault extends ElementType = ElementType, Props extends UnknownProps = UnknownProps, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = RecipeMap<Variants>, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
   /**
    * Return true for any prop key that should be consumed but not forwarded to the DOM.
    * Receives `runtime.options.variantKeys` as a convenience if needed.
@@ -638,6 +797,34 @@ type SolidFactoryOptions<TDefault extends ElementType, Props extends UnknownProp
   filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
 };
 //#endregion
+//#region ../../lib/contract-props/src/has-contract.d.ts
+/**
+ * The phantom-marker shape read back via `T extends HasContract<infer C> ? C : never` — the
+ * contract-retention counterpart to `HasGenerics<G>` in this same package. Where `HasGenerics<G>`
+ * lets a built component recover the `PolymorphicGenerics` an adapter derived for it,
+ * `HasContract<C>` lets it recover the *complete, authoritative contract* (`C`, the argument
+ * `createContractComponent<C extends XFactoryOptions>` was actually called with) it was derived
+ * from — the two are deliberately separate markers, not one broadened to do both jobs: `G` is
+ * "what the adapter needs to implement the component," `C` is "what the component was configured
+ * with" (see `DECISIONS.md`'s `defineContract` entry). A component carries both.
+ *
+ * Type-only: never assigned at runtime, same rationale as `HasGenerics<G>` (see that type's own
+ * doc comment) — a `createContractComponent` return value gets this shape via a type assertion,
+ * not a real property write.
+ *
+ * Unconstrained (no `C extends FactoryOptions` bound), matching `HasGenerics<G>`'s own choice —
+ * this package has no dependency on `@praxis-kit/core`/`@praxis-kit/primitive`, and adding one
+ * just to write a bound here isn't worth it: the accessor types that actually consume `C`
+ * (`ContractTagOf<C>`, etc., in `@praxis-kit/primitive`) already declare their own constraint.
+ *
+ * Do **not** "harden" this with a `unique symbol` or other nominal brand, for the same reason
+ * `HasGenerics<G>` doesn't: a real component's callable type needs to structurally satisfy this
+ * shape by declaring the same inline optional field, not by importing a nominal brand.
+ */
+interface HasContract<C> {
+  readonly __contract?: C;
+}
+//#endregion
 //#region ../../adapters/solid/src/types/polymorphic-props.d.ts
 type ElementRef<T extends ElementType> = T extends IntrinsicTag ? HTMLElementTagNameMap[T] : unknown;
 type IntrinsicJSXProps<T extends ElementType> = T extends IntrinsicTag ? JSX.IntrinsicElements[T] : UnknownProps;
@@ -677,7 +864,7 @@ type PolymorphicProps<G extends PolymorphicGenerics, TAs extends ElementType = D
   asChild?: false;
   children?: unknown;
 }) | AsChildProps<G>>;
-type PolymorphicComponent<G extends PolymorphicGenerics> = {
+type PolymorphicComponent<G extends PolymorphicGenerics, C extends FactoryOptions = FactoryOptions> = {
   <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicProps<G, TAs>): JSX.Element;
   /**
    * Non-generic fallback overload used for type extraction.
@@ -688,17 +875,37 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
    * inference for tools such as Storybook and `ComponentProps`.
    */
   (props: PolymorphicProps<G, DefaultOf<G>>): JSX.Element;
+  /**
+   * Type-only; never assigned at runtime — same rationale as React's/Preact's `__contract` (see
+   * `HasContract<C>`, `@praxis-kit/contract-props`). Carries the *complete* contract this
+   * component was built from (`C`, the argument `createContractComponent<C extends
+   * SolidFactoryOptions>` was actually called with). Unlike React's/Preact's `__generics` (which
+   * this adapter never needed — `PolymorphicProps<G, TAs>` already folds both render modes into
+   * one type, with no overload-resolution ceiling forcing a marker for `G` the way those two
+   * adapters need), `C` still needs one: nothing else on this type exposes the *complete*
+   * contract, only its `PolymorphicGenerics` projection. Defaults to the widest `FactoryOptions`
+   * so every existing one-argument `PolymorphicComponent<G>` reference keeps resolving exactly as
+   * before.
+   */
+  readonly __contract?: C;
   displayName?: string;
 };
 /**
- * A component's full prop contract — naming symmetry with React's/Preact's `ContractProps<T,
- * Mode>`, not a fix for a gap: Solid has no version of the
- * overload-resolution ceiling those two adapters need a marker to work around. `PolymorphicProps<G,
- * TAs>` already folds both render modes into one unioned type (rather than two separate types the
- * way React/Preact split them), and `PolymorphicComponent<G>`'s fallback overload already returns
- * that whole union — so this alias is just `PolymorphicProps<G>` under a familiar name.
+ * A component's full prop contract — `PolymorphicProps<G, TAs>` already folds both render modes
+ * into one unioned type (rather than two separate types the way React/Preact split them), and
+ * `PolymorphicComponent<G>`'s fallback overload already returns that whole union, so this is that
+ * same shape, projected from the component's retained `__contract` rather than a bare `G` the
+ * caller must already have in hand — `ContractProps<typeof Box>`, matching every other adapter,
+ * not `ContractProps<SomeG>`.
+ *
+ * An earlier version of this type took `G` directly (`ContractProps<G extends
+ * PolymorphicGenerics>`) — a genuinely different public shape, not a bug fix here: Solid's
+ * `PolymorphicProps<G, TAs>` never had React's/Preact's overload-resolution ceiling, so there was
+ * no *forced* reason for a marker. Unified to `ContractProps<typeof Component>` now that
+ * `__contract` exists anyway (Phase 3 retention, needed regardless of this decision), mirroring
+ * Vue's identical Phase 4 decision for the identical reason.
  */
-type ContractProps<G extends PolymorphicGenerics> = PolymorphicProps<G>;
+type ContractProps<T extends HasContract<FactoryOptions>> = T extends HasContract<infer C extends FactoryOptions> ? ContractGenericsOf<C> extends (infer G extends PolymorphicGenerics) ? PolymorphicProps<G> : never : never;
 //#endregion
 //#region ../../adapters/solid/src/create-contract-component.d.ts
 /**
@@ -720,9 +927,15 @@ type ContractProps<G extends PolymorphicGenerics> = PolymorphicProps<G>;
  *
  * `ref` is forwarded as an ordinary Solid ref callback. Pass `subComponents` to attach named
  * sub-components (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+ *
+ * `TDefault`/`Props`/`Variants`/`TPreset`/`TPlugin` are each `ContractXOf<C>`-derived *defaults*
+ * on this function's own type parameter list, mirroring `@praxis-kit/react`'s identical fix — see
+ * that adapter's own doc comment for why (computed as function type-parameter defaults, not inline
+ * body computations, which doesn't resolve for a still-abstract `C`). No `TAllowed` here, matching
+ * this adapter's pre-refactor behavior — Solid never threaded it as its own generic.
  */
-export declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: SolidFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+export declare function createContractComponent<C extends SolidFactoryOptions, TDefault extends ElementType = ContractTagOf<C>, Props extends UnknownProps = ContractPropsOf<C>, Variants extends Readonly<VariantMap> = ContractVariantsOf<C>, TPreset extends RecipeMap<VariantMap> = ContractPresetOf<C>, TPlugin extends AnyClassPluginFactory = ContractPluginOf<C>, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: C & {
   readonly subComponents?: TSubComponents;
-}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>>, TSubComponents>;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset>, C>, TSubComponents>;
 //#endregion
-export type { AnyFactoryOptions, ContractProps, ElementRef, ElementType, EmptyRecord, FactoryOptions, PolymorphicComponent, PolymorphicGenerics, PolymorphicProps, ResolvedSlotProps, SlotRenderFn, SolidFactoryOptions };
+export type { ContractProps, ElementRef, ElementType, EmptyRecord, FactoryOptions, PolymorphicComponent, PolymorphicGenerics, PolymorphicProps, ResolvedSlotProps, SlotRenderFn, SolidFactoryOptions };