praxis-kit 0.1.1 → 1.0.2

package/dist/{index-DiPzmjWW.d.ts → index-zJDSXTxL.d.ts}

@@ -1,7 +1,7 @@
 import "clsx";
 import { DiagnosticCode, DiagnosticInput, Diagnostics, DiagnosticsMode } from "./_shared/diagnostics.js";
 import { ComponentType, JSX, PropsWithChildren, ReactElement, ReactNode, Ref } from "react";
-import { NonEmptyTuple, ReadonlyDeep, RequireAtLeastOne, Simplify } from "type-fest";
+import { NonEmptyTuple, OmitIndexSignature, ReadonlyDeep, RequireAtLeastOne, Simplify } from "type-fest";
 //#region ../../lib/foundation/src/string-map.d.ts
 /**
  * A string-keyed object whose values are of type `T`.
@@ -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.
@@ -540,16 +526,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,
@@ -559,7 +535,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`. */
@@ -568,6 +546,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
@@ -622,11 +627,156 @@ 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
-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'];
+/** See this file's own doc comment. */
+type ContractAllowedOf<C extends FactoryOptions> = ContractModelOf<C>['allowed'];
+//#endregion
+//#region ../../lib/primitive/src/types/factory/contract-generics.d.ts
+/**
+ * Same projection as `ContractGenericsOf`, additionally threading `TAllowed` through to
+ * `PolymorphicGenerics`'s own `TAllowed` parameter. Only React's `createContractComponent`
+ * currently uses this variant — every other adapter uses the plain `ContractGenericsOf` above,
+ * matching their current behavior of not narrowing `as` via `enforcement.allowedAs` at the type
+ * level (the ARIA/tag-resolution engine still enforces `allowedAs` identically at runtime for all
+ * adapters regardless of which projection their types use).
+ */
+type ContractGenericsWithAllowedOf<C extends FactoryOptions> = PolymorphicGenerics<ContractTagOf<C>, MergeRecords<ContractPropsOf<C>, ExtractPluginProps<ContractPluginOf<C>>>, ContractVariantsOf<C>, ContractPresetOf<C>, ContractAllowedOf<C>>;
 //#endregion
 //#region ../../lib/pipeline/src/types/primitives.d.ts
 /** Free-form key/value bag a pass may attach to its result for downstream
@@ -674,6 +824,34 @@ declare function Slottable({ children }: SlottableProps): ReactElement;
 type UnknownProps = AnyRecord;
 type SlotComponent = ComponentType<UnknownProps>;
 //#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
@@ -693,26 +871,32 @@ type SlotComponent = ComponentType<UnknownProps>;
  */
 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. 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.
+ * 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.
  *
- * 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.
+ * 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 HasGenerics<G> {
-  readonly __generics?: G;
+interface HasContract<C> {
+  readonly __contract?: C;
 }
 //#endregion
 //#region ../../lib/contract-props/src/pick-mode.d.ts
@@ -756,19 +940,15 @@ type ElementRef<T extends ElementType> = T extends IntrinsicTag ? HTMLElementTag
  * prop definitions determine the accepted props.
  */
 type IntrinsicJSXProps<T extends ElementType> = T extends IntrinsicTag ? JSX.IntrinsicElements[T] : UnknownProps;
-/**
- * Removes index signatures while preserving explicitly declared
- * properties.
+/** Props explicitly declared by the component.
  *
- * Prevents broad index signatures (for example `Record<string, unknown>`)
- * from causing `keyof T` to become `string`, which would otherwise erase
- * every intrinsic prop during `Omit`.
- */
-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>>;
+ * `OmitIndexSignature` (type-fest) — not a hand-rolled version — matches every other adapter's
+ * own `polymorphic-props.ts` (Preact/Vue/Solid all import the same utility for this exact
+ * purpose): strips a broad index signature (e.g. `Record<string, unknown>`) so `keyof T` doesn't
+ * become `string`, which would otherwise erase every intrinsic prop during the `Omit` below. */
+type ComponentProps<G extends PolymorphicGenerics> = OmitIndexSignature<PropsOf<G>>;
 /** Variant props generated from the component's variant definitions. */
-type ComponentVariants<G extends PolymorphicGenerics> = StripIndexSignature<VariantProps<VariantsOf<G>>>;
+type ComponentVariants<G extends PolymorphicGenerics> = OmitIndexSignature<VariantProps<VariantsOf<G>>>;
 /**
  * Props defined by the component itself.
  *
@@ -881,6 +1061,60 @@ type PolymorphicWithAsChild<G extends PolymorphicGenerics, TAs extends ElementTy
  * Render callback props.
  */
 type PolymorphicWithRender<G extends PolymorphicGenerics, TAs extends ElementType = DefaultOf<G>> = Simplify<BaseProps<G, TAs> & CallbackRenderMode>;
+/**
+ * Whether a single (already-distributed) union member `M` declares `K` as exactly `true` — the
+ * "this key is the active one *on this member*" check `KeyTrueInAnyMember` runs once per member.
+ * `K extends keyof M` first, so a member that doesn't declare `K` at all (not even `?: never`)
+ * answers `false` rather than erroring on the indexed access. `[M[K]] extends [true]` (not a bare
+ * `M[K] extends true`) rejects plain `boolean` — a component's *own* same-named prop or the
+ * intrinsic `hidden` attribute — so only the literal `true` `ExclusiveTrueProp` itself produces
+ * counts, matching `LayoutPluginKeys`'s own contract.
+ */
+type IsKeyTrueOn<M, K extends PropertyKey> = K extends keyof M ? [M[K]] extends [true] ? true : false : false;
+/**
+ * Whether *any* member of the (possibly still-union) `P` sets `K` to `true` — `K` itself if so,
+ * `never` otherwise. `P extends infer M ? ... : never` distributes the check across each member
+ * of `P` individually via `IsKeyTrueOn`, rather than computing `keyof`/an indexed access over the
+ * union as a whole (which only sees keys common to *every* member, via `keyof`'s intersection
+ * rule for unions — confirmed empirically: a union with one member that omits a key entirely,
+ * rather than declaring it `?: never`, silently loses that key everywhere if checked against
+ * `keyof P` directly). `ExclusiveTrueProp` (`@praxis-kit/tailwind`) happens to declare every
+ * layout key on every member today, so that particular gap isn't live — but per-member
+ * distribution costs nothing extra and doesn't depend on that continuing to hold.
+ */
+type KeyTrueInAnyMember<P, K extends PropertyKey> = P extends (infer M) ? IsKeyTrueOn<M, K> extends true ? K : never : never;
+/**
+ * The layout keys a prop-union actually carries as the tailwind plugin's mutually-exclusive
+ * shape: for each known layout key, keep it only if `KeyTrueInAnyMember` finds it `true`
+ * somewhere in `P`. A component with no `styling.plugin` yields `never` (no member of a
+ * plugin-less `P` ever sets a layout key `true`).
+ */
+type LayoutPluginKeys<P> = { [K in LayoutKeyName]-?: KeyTrueInAnyMember<P, K>; }[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.
+ *
+ * `styling.plugin: createTailwindPipeline` contributes `ExclusiveTrueProp<LayoutKey>` — a ~22-way
+ * union (`{ flex: true } | { grid: true } | …`) that distributes through every downstream type,
+ * so `PolymorphicProps<G>` (and a `ContractProps<T>` built from it) becomes a ~22-member union
+ * whose members share no common layout key. That makes the extracted type hostile to every
+ * structural operation a consumer does with it: a spread matches no member on any extra/missing
+ * key (`not assignable to '… | … 20 more … | …'`), `Omit`/`Pick`/`Merge` trips `TS2590 union too
+ * complex`, a rest-destructure trips `TS2700`.
+ *
+ * A consumer extracting props to build a wrapper wants "the layout props exist and are optional",
+ * not the discriminated union — so flatten it here. The strict union stays on
+ * `PolymorphicComponent<G>`'s call overloads, where "only one display prop may be `true`" is the
+ * whole point of the compile error. See finding #44 /
+ * `praxis-kit-0.1.x-contractprops-regression.md` item #2.
+ *
+ * `Omit<P, LayoutKeyName>` (a static key set, so cheap) drops every layout key from every member
+ * — the members only ever differed there — 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 expensive `Omit` never runs on the (large) intrinsic-prop object there.
+ */
+type FlattenLayout<P> = [P] extends [never] ? never : [LayoutPluginKeys<P>] extends [never] ? P : Simplify<Omit<P, LayoutKeyName> & { [K in LayoutPluginKeys<P>]?: true; }>;
 /**
  * A polymorphic React component.
  *
@@ -890,7 +1124,7 @@ type PolymorphicWithRender<G extends PolymorphicGenerics, TAs extends ElementTyp
  * - `asChild`  — slot rendering
  * - default    — standard polymorphic rendering
  */
-type PolymorphicComponent<G extends PolymorphicGenerics> = {
+type PolymorphicComponent<G extends PolymorphicGenerics, C extends FactoryOptions = FactoryOptions> = {
   <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicWithRender<G, TAs>): ReactElement;
   <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicWithAsChild<G, TAs>): ReactElement;
   <TAs extends ElementType = DefaultOf<G>>(props: PolymorphicProps<G, TAs>): ReactElement;
@@ -902,6 +1136,13 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
    * overload. Anchoring that overload to the default element preserves
    * correct prop inference for tools such as Storybook and
    * `React.ComponentProps`.
+   *
+   * Deliberately *not* run through `FlattenLayout`: this overload is still a
+   * real call signature (it catches calls the three generic overloads reject),
+   * so flattening it here would make `<Component flex grid />` — two
+   * mutually-exclusive layout props — compile. `ContractProps<T>` does the
+   * flattening instead, on the pure type-extraction path. `React.ComponentProps`
+   * keeps the strict union it already had.
    */
   (props: PolymorphicProps<G, DefaultOf<G>>): ReactElement;
   /**
@@ -909,13 +1150,30 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
    * the full rationale — kept as an inline field rather than `HasGenerics<G> & {...}` because
    * intersecting it onto this callable type changes how `PolymorphicComponent<any>` (used by
    * test helpers like `box()`) resolves against concrete instantiations; structurally identical
-   * to `HasGenerics<G>` either way, which is what lets `ContractProps` constrain against it.
+   * to `HasGenerics<G>` either way.
+   *
+   * `ContractProps` no longer reads this field directly (Phase 4: it projects `G` from the
+   * retained `__contract` below instead) — kept per Phase 3's 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, and the same
+   * "inline field, not intersected" reason (see `HasContract<C>`, `@praxis-kit/contract-props`).
+   * Carries the *complete* contract this component was built from (`C`, the argument
+   * `createContractComponent<C extends ReactFactoryOptions>` 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" — related questions, different answers (see
+   * `DECISIONS.md`'s `defineContract` entry). Defaults to the widest `FactoryOptions` so every
+   * existing two-argument `PolymorphicComponent<G>` reference keeps resolving exactly as before.
+   */
+  readonly __contract?: C;
   displayName?: string;
 };
 /**
- * Recovers a built `PolymorphicComponent<G>`'s prop shape for a specific render mode, from
+ * Recovers a built `PolymorphicComponent<G, C>`'s prop shape for a specific render mode, from
  * outside the file that built it — the missing piece `React.ComponentProps<typeof Component>`
  * can't provide, since it always resolves against `PolymorphicComponent`'s normal-mode fallback
  * overload (see that type's own doc comment).
@@ -931,10 +1189,21 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
  * type ContainerAsChildProps = ContractProps<typeof Container, 'asChild'>
  * ```
  *
- * `T` accepts any built component value (`PolymorphicComponent<G>` or `CompoundComponent<G, S>` —
- * the latter's sub-component intersection doesn't disturb `__generics`, which lives on the root
- * call signature) via its own `__generics` marker; the `never` branch below only fires for a
- * non-praxis-kit component, which has no `__generics` field to infer from at all.
+ * Projects off the component's retained `__contract` (`C`, via `HasContract<C>` —
+ * `@praxis-kit/contract-props`), not `__generics` (`G`) — a deliberate Phase 4 rewire, not a new
+ * mechanism: `G` is *derived* from `C` (`ContractGenericsWithAllowedOf<C>`, the same canonical
+ * projection `createContractComponent`'s own return type already uses), so reading `C` and
+ * projecting `G` from it recovers exactly the same `G` `__generics` would have, without needing a
+ * second, independently-populated marker to stay in sync with the first. `FlattenLayout`,
+ * `PickMode`, `Mode`, and the three `Polymorphic*` prop-shape types below are unchanged — only
+ * where `G` comes from moved. `__generics` itself is untouched (Phase 3's migration policy: added
+ * alongside `__contract`, not replaced by it, until every adapter and test proves the new
+ * relationship out — see that field's own doc comment).
+ *
+ * `T` accepts any built component value (`PolymorphicComponent<G, C>` or `CompoundComponent<G, S>`
+ * — the latter's sub-component intersection doesn't disturb `__contract`, which lives on the root
+ * call signature) via its own `__contract` marker; the `never` branch below only fires for a
+ * non-praxis-kit component, which has no `__contract` field to infer from at all.
  *
  * Always resolves against the component's *default* element (`PolymorphicWithAsChild<G,
  * DefaultOf<G>>`, etc.) — the same ceiling `React.ComponentProps<typeof Component>` already has
@@ -943,7 +1212,7 @@ type PolymorphicComponent<G extends PolymorphicGenerics> = {
  * `PolymorphicProps<G, 'a'>` when a caller needs a specific non-default `as` — those remain two
  * different questions with two different answers.
  */
-type ContractProps<T extends HasGenerics<PolymorphicGenerics>, M extends Mode = 'normal'> = T extends HasGenerics<infer G extends PolymorphicGenerics> ? PickMode<M, PolymorphicProps<G, DefaultOf<G>>, PolymorphicWithAsChild<G, DefaultOf<G>>, PolymorphicWithRender<G, DefaultOf<G>>> : never;
+type ContractProps<T extends HasContract<FactoryOptions>, M extends Mode = 'normal'> = T extends HasContract<infer C extends FactoryOptions> ? ContractGenericsWithAllowedOf<C> extends (infer G extends PolymorphicGenerics) ? PickMode<M, FlattenLayout<PolymorphicProps<G, DefaultOf<G>>>, FlattenLayout<PolymorphicWithAsChild<G, DefaultOf<G>>>, FlattenLayout<PolymorphicWithRender<G, DefaultOf<G>>>> : never : never;
 //#endregion
 //#region ../../adapters/react/src/shared/react-options.d.ts
 /** Structural subset of `CompiledComponentArtifact` consumed by the React adapter. */
@@ -956,8 +1225,15 @@ interface CompiledArtifact {
 /**
  * Extends FactoryOptions with React-specific configuration.
  * slotComponent is intentionally not in core — it is a React rendering concern.
+ *
+ * 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 `ReactFactoryOptions` can be used bare, as `createContractComponent`'s single
+ * `C extends ReactFactoryOptions` constraint — a real contract's non-empty `variants`/`presets`
+ * must structurally satisfy that bound, which narrow defaults would reject (confirmed while
+ * building `ContractInput`, the same fix applied there for the same reason).
  */
-type ReactFactoryOptions<TDefault extends ElementType, Props extends UnknownProps, Variants extends Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType> = FactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+type ReactFactoryOptions<TDefault extends ElementType = ElementType, Props extends UnknownProps = UnknownProps, Variants extends Readonly<VariantMap> = Readonly<VariantMap>, TPreset extends RecipeMap<Variants> = RecipeMap<Variants>, 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;
   /**
@@ -971,4 +1247,4 @@ type ReactFactoryOptions<TDefault extends ElementType, Props extends UnknownProp
   artifact?: CompiledArtifact;
 };
 //#endregion
-export { MergeRecords as C, AnyRecord as E, EmptyRecord as S, NoVariants as T, ExtractPluginProps as _, PolymorphicProps as a, VariantMap as b, RenderCallbackProps as c, SlottableProps as d, mergeRefs as f, AnyClassPluginFactory as g, FactoryOptions as h, PolymorphicComponent as i, UnknownProps as l, AnyFactoryOptions as m, ContractProps as n, PolymorphicWithAsChild as o, defineContractComponent as p, ElementRef as r, PolymorphicWithRender as s, ReactFactoryOptions as t, Slottable as u, PolymorphicGenerics as v, NoPreset as w, ElementType as x, RecipeMap as y };
+export { RecipeMap as C, MergeRecords as D, EmptyRecord as E, AnyRecord as O, PolymorphicGenerics as S, ElementType as T, ContractTagOf as _, PolymorphicProps as a, AnyClassPluginFactory as b, RenderCallbackProps as c, SlottableProps as d, mergeRefs as f, ContractPropsOf as g, ContractPresetOf as h, PolymorphicComponent as i, UnknownProps as l, ContractPluginOf as m, ContractProps as n, PolymorphicWithAsChild as o, ContractAllowedOf as p, ElementRef as r, PolymorphicWithRender as s, ReactFactoryOptions as t, Slottable as u, ContractVariantsOf as v, VariantMap as w, ExtractPluginProps as x, FactoryOptions as y };