praxis-kit 0.1.1 → 1.0.2

package/dist/preact/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,11 +624,158 @@ 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/preact/src/slot/Slottable.d.ts
 type SlottableProps = {
@@ -637,7 +789,14 @@ type SlotComponent = ComponentType<UnknownProps>;
 type AnyVNode = VNode<any>;
 //#endregion
 //#region ../../adapters/preact/src/preact-options.d.ts
-type PreactFactoryOptions<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 `PreactFactoryOptions` can be used bare, as `createContractComponent`'s single
+ * `C extends PreactFactoryOptions` constraint — see `ReactFactoryOptions`'s identical fix for the
+ * same reason.
+ */
+type PreactFactoryOptions<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> & {
   /** Component used to render the asChild slot. Defaults to the built-in Slot. */
   slotComponent?: SlotComponent;
   /**
@@ -647,6 +806,34 @@ type PreactFactoryOptions<TDefault extends ElementType, Props extends UnknownPro
   filterProps?: (key: string, variantKeys: ReadonlySet<string>) => boolean;
 };
 //#endregion
+//#region ../../lib/tailwind/src/layout-keys.d.ts
+/**
+ * Canonical list of reserved layout prop names.
+ *
+ * This array is the single source of truth for every supported CSS `display`
+ * value exposed as a boolean prop. The `LayoutKey` type is derived directly
+ * from this list.
+ *
+ * To add a new display mode:
+ *   1. Add the display value here.
+ *   2. Register its layout family in `LAYOUT_FAMILY_MAP`.
+ *
+ * Prop names intentionally match the corresponding Tailwind/CSS display
+ * utilities, so no additional prop-to-class mapping is required.
+ */
+declare const layoutKeys: readonly ["flex", "inline-flex", "grid", "inline-grid", "block", "inline-block", "inline", "hidden", "contents", "flow-root", "list-item", "table", "inline-table", "table-caption", "table-cell", "table-column", "table-column-group", "table-footer-group", "table-header-group", "table-row-group", "table-row"];
+/**
+ * The concrete union of layout prop names — the pre-resolved form of
+ * `LayoutKey<typeof layoutKeys>`, colocated with the tuple it derives from.
+ *
+ * For code that needs to *name* the layout keys in a type without also importing the runtime
+ * tuple. A framework adapter uses it to collapse the mutually-exclusive `LayoutProps` union back
+ * out of an *extracted* prop type (`ContractProps<typeof Component>`): there a caller wants "the
+ * layout props exist and are optional `true`s", not the ~22-member discriminated union that the
+ * component's own call signature carries — where "only one may be `true`" is a useful error.
+ */
+type LayoutKeyName = (typeof layoutKeys)[number];
+//#endregion
 //#region ../../lib/contract-props/src/mode.d.ts
 /**
  * The three render modes a praxis-kit component's props can be typed for, shared across every
@@ -666,26 +853,32 @@ type PreactFactoryOptions<TDefault extends ElementType, Props extends UnknownPro
  */
 type Mode = 'normal' | 'asChild' | 'render';
 //#endregion
-//#region ../../lib/contract-props/src/has-generics.d.ts
+//#region ../../lib/contract-props/src/has-contract.d.ts
 /**
- * The phantom-marker shape read back via `T extends HasGenerics<infer G> ? G : never`. See the
- * README for why this exists.
+ * 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.
  *
- * Type-only: never assigned at runtime. In React's `PolymorphicComponent<G>`, declaring `readonly
- * __generics?: G` inline (structurally matching this shape) rather than writing `HasGenerics<G> &
- * { ...call signatures... }` was necessary to keep `PolymorphicComponent<any>`-typed test helpers
- * assignable — confirmed directly against that adapter's own real component type (see
- * `adapters/react/src/shared/types/polymorphic-props.test.ts`), not reproducible in an isolated
- * minimal mock (see this file's own `has-generics.test.ts`), so treat "inline, not intersected"
- * as an adapter-level implementation detail this package's marker shape must stay compatible
- * with, not a property `HasGenerics<G>` itself enforces.
+ * 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: the whole point is that
- * an adapter's real callable component type structurally satisfies this shape by declaring the
- * same optional string-keyed field inline. Nominal purity here would break that compatibility.
+ * 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 HasGenerics<G> {
-  readonly __generics?: G;
+interface HasContract<C> {
+  readonly __contract?: C;
 }
 //#endregion
 //#region ../../lib/contract-props/src/pick-mode.d.ts
@@ -723,7 +916,36 @@ type PolymorphicWithAsChild<G extends PolymorphicGenerics, TAs extends ElementTy
   as?: never;
   children: AnyVNode | AnyVNode[];
 }>;
-type PolymorphicComponent<G extends PolymorphicGenerics> = {
+/**
+ * The layout keys a prop-union actually carries as the tailwind plugin's mutually-exclusive
+ * shape: distributed over every member of `P`, a key counts when its value there is exactly
+ * `true` or `never` — the two shapes `ExclusiveTrueProp` produces. `[M[K]] extends [true]`
+ * matches both and rejects `boolean`, so a component's own same-named prop and the intrinsic
+ * `hidden` attribute are not counted, and a plugin-less component yields `never`.
+ */
+type LayoutPluginKeys<P> = { [K in LayoutKeyName]-?: P extends (infer M) ? K extends keyof M ? [M[K]] extends [true] ? K : never : never : never; }[LayoutKeyName];
+/**
+ * Collapses the mutually-exclusive `LayoutProps` union down to one flat shape — every layout key
+ * an optional `true` — for the **type-extraction** path (`ContractProps<T>`) only. Mirrors the
+ * React adapter's `FlattenLayout` (`adapters/react/src/shared/types/polymorphic-props.ts`), where
+ * the full rationale lives.
+ *
+ * `styling.plugin: createTailwindPipeline` contributes `ExclusiveTrueProp<LayoutKey>` — a ~22-way
+ * union (`{ flex: true } | { grid: true } | …`) that distributes through `PropsOf<G>` and
+ * everything built from it, so a `ContractProps<T>` built from it becomes a ~22-member union
+ * whose members share no common layout key: hostile to a spread (matches no member), to
+ * `Omit`/`Pick`/`Merge` (`TS2590 union too complex`) and to a rest-destructure (`TS2700`). A
+ * consumer extracting props for a wrapper wants "the layout props exist and are optional", not
+ * the discriminated union. The strict union stays on `PolymorphicComponent<G>`'s call overloads.
+ * See finding #44 / `praxis-kit-0.1.x-contractprops-regression.md` item #2.
+ *
+ * `Omit<P, LayoutKeyName>` (a static key set) drops every layout key from every member so the
+ * union dedupes to one; the flat `{ flex?: true; … }` is added back from just the keys the union
+ * really had. The `LayoutPluginKeys<P> extends never` fast-path returns `P` untouched for a
+ * plugin-less component, so the `Omit` never runs on its large intrinsic-prop object.
+ */
+type FlattenLayout<P> = [P] extends [never] ? never : [LayoutPluginKeys<P>] extends [never] ? P : Simplify<Omit<P, LayoutKeyName> & { [K in LayoutPluginKeys<P>]?: true; }>;
+type PolymorphicComponent<G extends PolymorphicGenerics, C extends FactoryOptions = FactoryOptions> = {
   <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicWithAsChild<G, TAs>): AnyVNode;
   <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicProps<G, TAs>): AnyVNode;
   /**
@@ -736,14 +958,30 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
    */
   (props: PolymorphicProps<G, DefaultOf<G>>): AnyVNode;
   /**
-   * Type-only; never assigned at runtime. See `HasGenerics<G>` for
+   * Type-only; never assigned at runtime. See `HasGenerics<G>` (`@praxis-kit/contract-props`) for
    * the full rationale — kept as an inline field rather than `HasGenerics<G> & {...}` because
    * intersecting it onto this callable type changes how `PolymorphicComponent<any>` resolves
    * against concrete instantiations (confirmed for React's identical shape,
    * `adapters/react/src/shared/types/polymorphic-props.test.ts`); structurally identical to
-   * `HasGenerics<G>` either way, which is what lets `ContractProps` constrain against it.
+   * `HasGenerics<G>` either way.
+   *
+   * `ContractProps` no longer reads this field directly (it projects `G` from the retained
+   * `__contract` below instead, mirroring React's identical Phase 4 rewire) — kept per the same
+   * migration policy: added alongside `__contract`, not replaced by it, until every adapter and
+   * test proves the new relationship out, and because other code may still constrain against
+   * `HasGenerics<G>` directly.
    */
   readonly __generics?: G;
+  /**
+   * Type-only; never assigned at runtime — same rationale as `__generics` above. Carries the
+   * *complete* contract this component was built from (`C`, the argument
+   * `createContractComponent<C extends PreactFactoryOptions>` was actually called with) —
+   * deliberately a second, separate marker from `__generics`, not `__generics` broadened to do
+   * both jobs: `G` answers "what does the adapter need to implement this component," `C` answers
+   * "what was this component configured with." Defaults to the widest `FactoryOptions` so every
+   * existing two-argument `PolymorphicComponent<G>` reference keeps resolving exactly as before.
+   */
+  readonly __contract?: C;
   displayName?: string;
 };
 /**
@@ -765,7 +1003,7 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
  * type ContainerAsChildProps = ContractProps<typeof Container, 'asChild'>
  * ```
  */
-type ContractProps<T extends HasGenerics<PolymorphicGenerics>, M extends Exclude<Mode, 'render'> = 'normal'> = T extends HasGenerics<infer G extends PolymorphicGenerics> ? PickMode<M, PolymorphicProps<G, DefaultOf<G>>, PolymorphicWithAsChild<G, DefaultOf<G>>, never> : never;
+type ContractProps<T extends HasContract<FactoryOptions>, M extends Exclude<Mode, 'render'> = 'normal'> = T extends HasContract<infer C extends FactoryOptions> ? ContractGenericsOf<C> extends (infer G extends PolymorphicGenerics) ? PickMode<M, FlattenLayout<PolymorphicProps<G, DefaultOf<G>>>, FlattenLayout<PolymorphicWithAsChild<G, DefaultOf<G>>>, never> : never : never;
 //#endregion
 //#region ../../adapters/preact/src/create-contract-component.d.ts
 /**
@@ -788,9 +1026,15 @@ type ContractProps<T extends HasGenerics<PolymorphicGenerics>, M extends Exclude
  * Returns a `forwardRef` component — `ref` is forwarded to the rendered host 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` 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 — Preact 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: PreactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin> & {
+export declare function createContractComponent<C extends PreactFactoryOptions, 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, PolymorphicWithAsChild, PreactFactoryOptions };
+export type { ContractProps, ElementRef, ElementType, EmptyRecord, FactoryOptions, PolymorphicComponent, PolymorphicGenerics, PolymorphicProps, PolymorphicWithAsChild, PreactFactoryOptions };