@pyreon/rocketstyle 0.15.0 → 0.16.0

package/lib/index.d.ts

@@ -87,11 +87,47 @@ type ExtractNullableKeys<T> = { [P in keyof T as IsAny<T[P]> extends true ? P :
 type SpreadTwo<L, R> = Id<Pick<L, Exclude<keyof L, keyof R>> & R>;
 type Spread<A extends readonly [...any]> = A extends [infer L, ...infer R] ? SpreadTwo<L, Spread<R>> : unknown;
 type MergeTypes<A extends readonly [...any]> = ExtractNullableKeys<Spread<A>>;
-type ExtractProps<TComponentOrTProps> = TComponentOrTProps extends ComponentFn<infer TProps> ? TProps : TComponentOrTProps;
+/**
+ * Extracts the props type from a Pyreon component function — or passes
+ * through the input unchanged when it's already a props type.
+ *
+ * Multi-overload aware: matches up to 4 call signatures and produces the
+ * UNION of their first-argument types. A single-overload function still
+ * works (the union of 4 copies of the same props type dedupes back to
+ * the single shape).
+ *
+ * **Why this shape**. `T extends (props: infer P) => any ? P : never` only
+ * captures the LAST overload of a multi-overload function — TS's overload-
+ * resolution-against-conditional-types semantics. Iterator / List / Element
+ * are 3-overload primitives where the LAST overload (`ChildrenProps`) is the
+ * loosest; without overload-aware extraction, `ExtractProps<Iterator>`
+ * returned just `ChildrenProps` and lost both `SimpleProps<T>` and
+ * `ObjectProps<T>` — wrapping Iterator through `rocketstyle()` /
+ * `attrs()` silently downgraded the public prop surface.
+ *
+ * The pattern-match shape `T extends { (props: infer P1, ...args: any): any;
+ * (props: infer P2, ...args: any): any; ... }` is the canonical TS trick
+ * for extracting overload sets — see also `Parameters<T>` semantics.
+ *
+ * Mirrors vitus-labs PR #222.
+ */
+type ExtractProps<TComponentOrTProps> = TComponentOrTProps extends {
+  (props: infer P1, ...args: any): any;
+  (props: infer P2, ...args: any): any;
+  (props: infer P3, ...args: any): any;
+  (props: infer P4, ...args: any): any;
+} ? P1 | P2 | P3 | P4 : TComponentOrTProps extends {
+  (props: infer P1, ...args: any): any;
+  (props: infer P2, ...args: any): any;
+  (props: infer P3, ...args: any): any;
+} ? P1 | P2 | P3 : TComponentOrTProps extends {
+  (props: infer P1, ...args: any): any;
+  (props: infer P2, ...args: any): any;
+} ? P1 | P2 : TComponentOrTProps extends ComponentFn<infer TProps> ? TProps : TComponentOrTProps;
 //#endregion
 //#region src/types/styles.d.ts
 interface StylesDefault {}
-type Styles<S = unknown> = StylesDefault;
+type Styles<_S = unknown> = StylesDefault;
 type Css = typeof config.css;
 /**
  * Props available inside `.styles()` interpolation functions.
@@ -226,12 +262,25 @@ type DefaultProps = Partial<PseudoProps> & {
 };
 //#endregion
 //#region src/types/attrs.d.ts
-type AttrsCb<A, T> = (props: Partial<A>, theme: T, helpers: {
+/** Helpers object passed as the 3rd arg to every `.attrs(callback)`. */
+type AttrsHelpers = {
   mode?: ThemeModeKeys;
   isDark?: boolean;
   isLight?: boolean;
   createElement: typeof render;
-}) => Partial<A>;
+};
+/**
+ * Callback signature for `.attrs((props, theme, helpers) => …)`.
+ *
+ * `Partial<A>` on the return is for the strict-typing form when callers
+ * pass `AttrsCb<DFP, Theme<T>>` directly. In the rocketstyle `.attrs()`
+ * callback overload itself we use a different shape that decouples the
+ * props arg (narrow, full DFP) from the return type (loose — only the
+ * user's explicit `<P>` generic is checked, with `Record<string,
+ * unknown>` allowing runtime extras like `_documentProps`). See
+ * `IRocketStyleComponent.attrs` for the call-site shape.
+ */
+type AttrsCb<A, T> = (props: Partial<A>, theme: T, helpers: AttrsHelpers) => Partial<A>;
 //#endregion
 //#region src/types/hoc.d.ts
 type GenericHoc = (component: ElementType) => ElementType;
@@ -250,7 +299,7 @@ type RocketStyleComponent<OA extends TObj = {}, EA extends TObj = {}, T extends
  * @param DKP  Dimensions key props.
  * @param DFP  Calculated final component props
  */
-interface IRocketStyleComponent<OA extends TObj = {}, EA extends TObj = {}, T extends TObj = {}, CSS extends TObj = {}, S extends TObj = {}, HOC extends TObj = {}, D extends Dimensions = Dimensions, UB extends boolean = boolean, DKP extends TDKP = TDKP, DFP = MergeTypes<[OA, EA, DefaultProps, ExtractDimensionProps<D, DKP, UB>]>> {
+interface IRocketStyleComponent<OA extends TObj = {}, EA extends TObj = {}, T extends TObj = {}, CSS extends TObj = {}, S extends TObj = {}, HOC extends TObj = {}, D extends Dimensions = Dimensions, UB extends boolean = boolean, DKP extends TDKP = TDKP, DFP = (OA extends infer O ? Omit<O, keyof EA & keyof O> & Partial<Pick<O, keyof EA & keyof O>> & MergeTypes<[Partial<Omit<EA, keyof O>>, DefaultProps, ExtractDimensionProps<D, DKP, UB>]> : never)> {
   (props: DFP): VNodeChild;
   config: <NC extends ElementType | unknown = unknown>({
     name,
@@ -261,10 +310,16 @@ interface IRocketStyleComponent<OA extends TObj = {}, EA extends TObj = {}, T ex
     inversed,
     passProps
   }: ConfigAttrs<NC, D, DKP, UB>) => NC extends ElementType ? RocketStyleComponent<ExtractProps<NC>, EA, T, CSS, S, HOC, D, UB, DKP> : RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>;
-  attrs: <P extends TObj | unknown = unknown>(param: P extends TObj ? Partial<DFP & P> | ((props: Partial<DFP & P>, theme: Theme<T>, helpers: any) => Partial<P> & Record<string, unknown>) : Partial<DFP> | AttrsCb<DFP, Theme<T>>, config?: Partial<{
-    priority: boolean;
-    filter: P extends TObj ? Partial<keyof (EA & P)>[] : Partial<keyof EA>[];
-  }>) => P extends TObj ? RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP> : RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>;
+  attrs: {
+    <P extends TObj = {}>(param: (props: Partial<DFP & P>, theme: Theme<T>, helpers: AttrsHelpers) => Partial<P> & Record<string, unknown>, config?: Partial<{
+      priority: boolean;
+      filter: (keyof MergeTypes<[EA, P]>)[];
+    }>): RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>;
+    <P extends TObj = {}>(param: P & Partial<NoInfer<DFP>>, config?: Partial<{
+      priority: boolean;
+      filter: (keyof MergeTypes<[EA, P]>)[];
+    }>): RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>;
+  };
   theme: <P extends TObj = TObj>(param: Partial<P> | Partial<Styles<CSS>> | ThemeCb<P, Theme<T>>) => RocketStyleComponent<OA, EA, T, MergeTypes<[CSS, P]>, S, HOC, D, UB, DKP>;
   styles: (param: StylesCb<CSS>) => RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>;
   compose: <P extends ComposeParam>(param: P) => P extends TObj ? RocketStyleComponent<OA, EA, T, CSS, S, MergeTypes<[HOC, P]>, D, UB, DKP> : RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>;
@@ -337,5 +392,5 @@ declare const isRocketComponent: IsRocketComponent;
  */
 declare function resolveTheme<T = Record<string, unknown>>(value: (() => T) | T): T;
 //#endregion
-export { type AttrsCb, type ComponentFn, type ComposeParam, type ConfigAttrs, type ConsumerCb, type ConsumerCtxCBValue, type ConsumerCtxCb, type DefaultProps, type DimensionCallbackParam, type DimensionProps, type DimensionValue, type Dimensions, type ElementType, type ExtractDimensionProps, type ExtractDimensions, type ExtractProps, type GenericHoc, type IRocketStyleComponent, type IsRocketComponent, type MergeTypes, Provider, type RocketComponentType, type RocketProviderState, type RocketStyleComponent, type RocketStyleInterpolationProps, type Rocketstyle, type StylesCb, type StylesDefault, type TDKP, type TObj, type TProvider, type ThemeCb, type ThemeDefault, type ThemeMode, type ThemeModeCallback, type ThemeModeKeys, context, rocketstyle as default, rocketstyle, isRocketComponent, resolveTheme };
+export { type AttrsCb, type AttrsHelpers, type ComponentFn, type ComposeParam, type ConfigAttrs, type ConsumerCb, type ConsumerCtxCBValue, type ConsumerCtxCb, type DefaultProps, type DimensionCallbackParam, type DimensionProps, type DimensionValue, type Dimensions, type ElementType, type ExtractDimensionProps, type ExtractDimensions, type ExtractProps, type GenericHoc, type IRocketStyleComponent, type IsRocketComponent, type MergeTypes, Provider, type RocketComponentType, type RocketProviderState, type RocketStyleComponent, type RocketStyleInterpolationProps, type Rocketstyle, type StylesCb, type StylesDefault, type TDKP, type TObj, type TProvider, type ThemeCb, type ThemeDefault, type ThemeMode, type ThemeModeCallback, type ThemeModeKeys, context, rocketstyle as default, rocketstyle, isRocketComponent, resolveTheme };
 //# sourceMappingURL=index2.d.ts.map

package/lib/index.js

@@ -472,23 +472,38 @@ const getThemeByMode = (object, mode) => Object.keys(object).reduce((acc, key) =
 //#endregion
 //#region src/rocketstyle.ts
 const _countSink = globalThis;
-/** Clones the current configuration and merges new options, returning a fresh rocketComponent. */
-const cloneAndEnhance = (defaultOpts, opts) => rocketComponent({
-	...defaultOpts,
-	attrs: chainOptions(opts.attrs, defaultOpts.attrs),
-	filterAttrs: [...defaultOpts.filterAttrs ?? [], ...opts.filterAttrs ?? []],
-	priorityAttrs: chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
-	statics: {
-		...defaultOpts.statics,
-		...opts.statics
-	},
-	compose: {
-		...defaultOpts.compose,
-		...opts.compose
-	},
-	...chainOrOptions(CONFIG_KEYS, opts, defaultOpts),
-	...chainReservedKeyOptions([...defaultOpts.dimensionKeys, ...STYLING_KEYS], opts, defaultOpts)
-});
+/**
+* Clones the current configuration and merges new options, returning a fresh
+* rocketComponent.
+*
+* Component-swap reset: when `opts.component` is set AND differs from the
+* current `defaultOpts.component`, the prior `attrs`, `priorityAttrs`,
+* `filterAttrs`, and `compose` chains are dropped — they were tailored to the
+* previous component's prop shape, and applying them to a different component
+* silently leaks invalid props through to the DOM (e.g. `disabled` on an
+* `<a>`). Callers who want to preserve them must re-chain explicitly:
+*
+*   const NewBtn = Button.config({ component: 'a' }).attrs(sharedAttrs)
+*/
+const cloneAndEnhance = (defaultOpts, opts) => {
+	const componentChanged = opts.component != null && opts.component !== defaultOpts.component;
+	return rocketComponent({
+		...defaultOpts,
+		attrs: componentChanged ? chainOptions(opts.attrs, []) : chainOptions(opts.attrs, defaultOpts.attrs),
+		filterAttrs: componentChanged ? [...opts.filterAttrs ?? []] : [...defaultOpts.filterAttrs ?? [], ...opts.filterAttrs ?? []],
+		priorityAttrs: componentChanged ? chainOptions(opts.priorityAttrs, []) : chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
+		statics: {
+			...defaultOpts.statics,
+			...opts.statics
+		},
+		compose: componentChanged ? { ...opts.compose } : {
+			...defaultOpts.compose,
+			...opts.compose
+		},
+		...chainOrOptions(CONFIG_KEYS, opts, defaultOpts),
+		...chainReservedKeyOptions([...defaultOpts.dimensionKeys, ...STYLING_KEYS], opts, defaultOpts)
+	});
+};
 const rocketComponent = (options) => {
 	const { component, styles } = options;
 	const { styled } = config;
@@ -548,11 +563,16 @@ const rocketComponent = (options) => {
 		const _resolveRsEntry = () => {
 			const theme = themeAttrs.theme;
 			const mode = themeAttrs.mode;
-			let key = mode;
 			const propsRec = props;
+			const rocketstateRaw = _calculateStylingAttrs({
+				props: pickStyledAttrs(propsRec, reservedPropNames),
+				dimensions
+			});
+			let key = mode;
 			for (const dimName in dimensions) {
-				const v = propsRec[dimName];
-				key += "|" + (typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? String(v) : v === void 0 ? "" : "~" + typeof v);
+				const v = rocketstateRaw[dimName];
+				if (Array.isArray(v)) key += "|" + (v.length === 0 ? "" : v.slice().sort().join(","));
+				else key += "|" + (typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? String(v) : v === void 0 ? "" : "~" + typeof v);
 			}
 			for (const k of ALL_PSEUDO_KEYS) {
 				const propV = propsRec[k];
@@ -583,10 +603,6 @@ const rocketComponent = (options) => {
 				if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
 			} else dimHelper.set(theme, getDimensionThemes(theme, options));
 			const themes = dimHelper.get(theme);
-			const rocketstateRaw = _calculateStylingAttrs({
-				props: pickStyledAttrs(propsRec, reservedPropNames),
-				dimensions
-			});
 			const modeBaseHelper = ThemeManager$1.modeBaseTheme[mode];
 			if (modeBaseHelper.has(baseTheme)) {
 				if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
@@ -715,8 +731,8 @@ const rocketComponent = (options) => {
 			{
 				render,
 				mode,
-				isDark: mode === "light",
-				isLight: mode === "dark"
+				isDark: mode === "dark",
+				isLight: mode === "light"
 			}
 		])
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/rocketstyle",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Multi-dimensional style composition for Pyreon components",
   "license": "MIT",
   "repository": {
@@ -42,19 +42,19 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/test-utils": "^0.13.2",
-    "@pyreon/typescript": "^0.15.0",
-    "@pyreon/ui-core": "^0.15.0",
+    "@pyreon/test-utils": "^0.13.3",
+    "@pyreon/typescript": "^0.16.0",
+    "@pyreon/ui-core": "^0.16.0",
     "@vitest/browser-playwright": "^4.1.4",
     "@vitus-labs/tools-rolldown": "^2.3.0"
   },
-  "peerDependencies": {
-    "@pyreon/core": "^0.15.0",
-    "@pyreon/reactivity": "^0.15.0",
-    "@pyreon/styler": "^0.15.0",
-    "@pyreon/ui-core": "^0.15.0"
-  },
   "engines": {
     "node": ">= 22"
+  },
+  "dependencies": {
+    "@pyreon/core": "^0.16.0",
+    "@pyreon/reactivity": "^0.16.0",
+    "@pyreon/styler": "^0.16.0",
+    "@pyreon/ui-core": "^0.16.0"
   }
 }

package/src/__tests__/attrs-overloads.test.ts

@@ -0,0 +1,97 @@
+import type { ComponentFn } from '@pyreon/core'
+import rocketstyle from '../init'
+
+// Type-level regression tests for the post-#225/#227 `.attrs()` overload
+// split: (a) DFP widening makes `.attrs(obj)` keys optional at JSX call site,
+// (b) callback overload preserves Pyreon's loose-return convention so
+// `_documentProps` / `tag: 'a'` runtime extras still typecheck without
+// per-callsite `as any` casts.
+//
+// These are not bisect-load-bearing at runtime — they're type-level
+// assertions exercised by `tsc --noEmit`. Including them in the suite
+// makes failures show up in the test report (vitest treats type errors
+// as compile failures).
+describe('attrs overloads — type-level contract', () => {
+  // A minimal base component standing in for Text / Button / etc.
+  // We only care about the type-level surface here.
+  type BaseProps = {
+    tag?: 'div' | 'span' | 'p' | 'h1' | 'h2' | 'h3'
+    role?: string
+  }
+  const Base: ComponentFn<BaseProps> = () => null
+
+  describe('object overload — keys become optional at JSX site (PR #225)', () => {
+    it('accepts object with default values', () => {
+      const Comp = rocketstyle()({ name: 'Comp', component: Base }).attrs({
+        tag: 'div',
+      })
+      // The component is callable — at the JSX call site, `tag` is now
+      // optional because `.attrs({ tag: 'div' })` provides a default.
+      // Pre-#225 the type would have required `tag` at the JSX site.
+      // We can't directly assert via `expectTypeOf` without the dep, but
+      // the smoke is: the chain compiles without errors.
+      expect(typeof Comp).toBe('function')
+    })
+
+    it('accepts new keys in attrs object', () => {
+      // The attrs object can introduce new keys beyond the base component's
+      // props (here: `customField`). The keys flow into the returned
+      // component's extended-attrs `EA` and become typed props.
+      const Comp = rocketstyle()({ name: 'Comp', component: Base }).attrs({
+        customField: 'hello',
+      })
+      expect(typeof Comp).toBe('function')
+    })
+  })
+
+  describe('callback overload — Pyreon convention for runtime extras', () => {
+    it('accepts callback returning fields outside the base prop union (no as-cast needed)', () => {
+      // This is the canonical document-primitive pattern: a Text-based
+      // rocketstyle that overrides `tag` to a value outside Text's strict
+      // `tag` union AND adds a runtime-only `_documentProps` marker. The
+      // callback's return type intentionally allows `Record<string, unknown>`
+      // for keys outside the user's explicit `<P>` generic, matching
+      // Pyreon's pre-#225 convention.
+      const Comp = rocketstyle()({ name: 'DocLink', component: Base }).attrs<{
+        href?: string
+      }>((props) => ({
+        tag: 'a', // 'a' is NOT in BaseProps['tag'] — falls through Record<string, unknown>
+        _documentProps: { href: props.href ?? '#' },
+      }))
+      expect(typeof Comp).toBe('function')
+    })
+
+    it('accepts callback returning literal values (contextual narrowing via <P>)', () => {
+      // When the user passes an explicit `<P>` generic, the callback's
+      // return is contextually typed against `Partial<P>`. Writing
+      // `tag: 'h1'` stays narrow at literal `'h1'` — no `as const` needed.
+      // Note: tag is in BaseProps['tag'] union so this typechecks against
+      // BOTH the wildcard arm AND the explicit P-key arm.
+      const Comp = rocketstyle()({ name: 'Heading', component: Base }).attrs<{
+        level?: number
+      }>((props) => ({
+        tag: `h${props.level ?? 1}` as 'h1' | 'h2' | 'h3',
+      }))
+      expect(typeof Comp).toBe('function')
+    })
+
+    it('callback receives full DFP-typed props for narrow reads', () => {
+      // The `props` arg passed to the callback IS strictly typed as
+      // `Partial<DFP & P>` — so reading `props.tag` narrows against the
+      // wrapped component's full surface. This is the "props narrow,
+      // return loose" asymmetry Pyreon settled on.
+      const Comp = rocketstyle()({ name: 'Probe', component: Base }).attrs<{
+        scale?: number
+      }>((props) => {
+        // Type check: `props.scale` is `number | undefined`, `props.tag`
+        // is the narrow BaseProps['tag'] union | undefined.
+        const _scale: number | undefined = props.scale
+        const _tag: 'div' | 'span' | 'p' | 'h1' | 'h2' | 'h3' | undefined = props.tag
+        expect(_scale).toBeUndefined()
+        expect(_tag).toBeUndefined()
+        return { scale: 1 }
+      })
+      expect(typeof Comp).toBe('function')
+    })
+  })
+})

package/src/__tests__/cache-key-boolean-collision.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Bug reproduction: under `useBooleans: true`, `_resolveRsEntry`'s cache
+ * key reads `propsRec[dimName]` directly (e.g. `propsRec.state`). Boolean
+ * shorthand props like `<X primary />` populate `propsRec.primary` (NOT
+ * `propsRec.state`), so the cache key for the `state` slot is `undefined`
+ * → `''` regardless of which boolean variant was passed.
+ *
+ * Result: `<X primary />` and `<X secondary />` produce identical cache
+ * keys and share the cached entry. The first-resolved variant's
+ * `$rocketstyle` wins for all subsequent renders.
+ */
+import { initTestConfig, withThemeContext } from '@pyreon/test-utils'
+import rocketstyle from '../init'
+
+let cleanup: () => void
+beforeAll(() => {
+  cleanup = initTestConfig()
+})
+afterAll(() => cleanup())
+
+const ThemeCapture: any = ({ $rocketstyle, $rocketstate, ...rest }: any) => ({
+  type: 'div',
+  props: rest,
+  $rocketstyle: typeof $rocketstyle === 'function' ? $rocketstyle() : $rocketstyle,
+  $rocketstate: typeof $rocketstate === 'function' ? $rocketstate() : $rocketstate,
+})
+ThemeCapture.displayName = 'ThemeCapture'
+
+describe('rocketstyle — cache-key collision under useBooleans:true', () => {
+  it('different boolean variants produce different $rocketstyle (NOT collide)', () => {
+    const Button: any = rocketstyle({ useBooleans: true })({
+      name: 'BoolButton',
+      component: ThemeCapture,
+    }).states(() => ({
+      primary: { color: 'red' },
+      secondary: { color: 'blue' },
+    }))
+
+    // Render with primary=true. Captures the $rocketstyle resolved
+    // for state='primary'.
+    const a = withThemeContext(() => Button({ primary: true }))
+
+    // Render with secondary=true. Should resolve to state='secondary'
+    // and produce DIFFERENT $rocketstyle.
+    const b = withThemeContext(() => Button({ secondary: true }))
+
+    // Bug: a.$rocketstyle === b.$rocketstyle (same cached entry).
+    // Fix: a.$rocketstyle.color === 'red', b.$rocketstyle.color === 'blue'.
+    expect(a.$rocketstate.state).toBe('primary')
+    expect(b.$rocketstate.state).toBe('secondary')
+    expect(a.$rocketstyle.color).toBe('red')
+    expect(b.$rocketstyle.color).toBe('blue')
+  })
+})

package/src/__tests__/rocketstyle.browser.test.tsx

@@ -95,6 +95,152 @@ describe('@pyreon/rocketstyle in real browser', () => {
     unmount()
   })
 
+  // Bug 3 audit: derivation chain matching the real bokisch.com bug shape.
+  //
+  // Library defines a base `Text` component with `.styles(({css}) => css\`color:
+  // ${$rocketstyle.color}\`)` — the .styles() callback reads $rocketstyle.color.
+  // Library also defines `.theme({color: 'black'})` as the default.
+  //
+  // Consumer derives a sub-component: `Text.theme((t, m) => ({color: m('red',
+  // 'blue')}))` — adds NEW .theme() but does NOT call .styles() again. The
+  // derivation should INHERIT the base's .styles() and have it consume the
+  // new .theme() values, with mode toggling re-rendering correctly.
+  //
+  // The user's report: components in this chain keep stale colors on
+  // theme toggle. Test verifies whether the derivation chain actually
+  // wires up reactively.
+  it('Bug 3 repro: rocketstyle derivation chain — inherited .styles() + new .theme() reacts to mode', async () => {
+    const modeSig = signal<'light' | 'dark'>('light')
+
+    // Library base — has .styles() that reads $rocketstyle.color.
+    const TextBase: any = rocketstyle()({
+      name: 'TextBase',
+      component: Base,
+    })
+      .styles(
+        (css: any) => css`
+          color: ${({ $rocketstyle }: any) => $rocketstyle.color};
+        `,
+      )
+      .theme({ color: 'rgb(0, 128, 0)' }) // green default
+
+    // Consumer derivation — only adds .theme(), no .styles() override.
+    const Text: any = TextBase
+      .theme((_t: any, m: any) => ({
+        color: m('rgb(255, 0, 0)', 'rgb(0, 0, 255)'),
+      }))
+
+    const { container, unmount } = mountInBrowser(
+      h(PyreonUI, { theme: {}, mode: modeSig }, h(Text, { id: 'derive' })),
+    )
+
+    const el = container.querySelector<HTMLElement>('#derive')!
+    const initialColor = getComputedStyle(el).color
+
+    modeSig.set('dark')
+    await new Promise((r) => setTimeout(r, 0))
+    await new Promise((r) => requestAnimationFrame(() => r(undefined)))
+
+    const darkColor = getComputedStyle(el).color
+
+    // Diagnostic: log both colors for clarity, regardless of pass/fail
+    // (helps triage whether the bug is "no .theme() applied at all" vs
+    // "applied but doesn't react to mode toggle").
+    if (initialColor === 'rgb(255, 0, 0)' && darkColor === 'rgb(0, 0, 255)') {
+      // Works correctly — derivation chain wires up reactively
+      expect(darkColor).toBe('rgb(0, 0, 255)')
+    } else {
+      throw new Error(
+        `[bug-3-repro] derivation chain failed. initial=${initialColor}, dark=${darkColor}. ` +
+          `Expected initial=rgb(255, 0, 0), dark=rgb(0, 0, 255). ` +
+          `Possible causes: (a) .theme() override silently dropped, ` +
+          `(b) .styles() not inherited from base, ` +
+          `(c) mode toggle doesn't propagate.`,
+      )
+    }
+    unmount()
+  })
+
+  // Bug 3 audit (continued): derivation chain WITH dimension props.
+  // Real consumer pattern: `<Text base paragraph centered>` uses
+  // dimension-prop values from .sizes()/.variants(). Tests that mode
+  // toggle still propagates when dimension props are active.
+  it('Bug 3 repro: derivation + dimension props + mode toggle', async () => {
+    const modeSig = signal<'light' | 'dark'>('light')
+
+    const TextBase: any = rocketstyle()({ name: 'TextBaseDim', component: Base })
+      .styles(
+        (css: any) => css`
+          color: ${({ $rocketstyle }: any) => $rocketstyle.color};
+          font-size: ${({ $rocketstyle }: any) => $rocketstyle.fontSize};
+        `,
+      )
+      .theme({ color: 'rgb(0, 0, 0)', fontSize: '14px' })
+      .sizes({
+        small: { fontSize: '12px' },
+        large: { fontSize: '20px' },
+      })
+
+    // Consumer derivation: theme override that depends on mode
+    const Text: any = TextBase.theme((_t: any, m: any) => ({
+      color: m('rgb(255, 0, 0)', 'rgb(0, 0, 255)'),
+    }))
+
+    const { container, unmount } = mountInBrowser(
+      h(PyreonUI, { theme: {}, mode: modeSig },
+        h(Text, { id: 'dim', size: 'large' }),
+      ),
+    )
+    const el = container.querySelector<HTMLElement>('#dim')!
+    expect(getComputedStyle(el).color).toBe('rgb(255, 0, 0)')
+    expect(getComputedStyle(el).fontSize).toBe('20px')
+
+    modeSig.set('dark')
+    await new Promise((r) => setTimeout(r, 0))
+    await new Promise((r) => requestAnimationFrame(() => r(undefined)))
+
+    expect(getComputedStyle(el).color).toBe('rgb(0, 0, 255)')
+    expect(getComputedStyle(el).fontSize).toBe('20px') // dimension unchanged
+    unmount()
+  })
+
+  // Bug 3 audit (continued): DOUBLE derivation — Text → TextStyled → consumer.
+  // Tests whether mode reactivity survives a multi-level chain.
+  it('Bug 3 repro: double-derivation chain still reacts to mode', async () => {
+    const modeSig = signal<'light' | 'dark'>('light')
+
+    const TextBase: any = rocketstyle()({ name: 'DoubleTextBase', component: Base })
+      .styles(
+        (css: any) => css`
+          color: ${({ $rocketstyle }: any) => $rocketstyle.color};
+        `,
+      )
+      .theme({ color: 'rgb(0, 0, 0)' })
+
+    // First derivation — adds states (no theme override yet)
+    const TextStyled: any = TextBase.states({
+      muted: { color: 'rgb(128, 128, 128)' },
+    })
+
+    // Second derivation — mode-aware theme
+    const Text: any = TextStyled.theme((_t: any, m: any) => ({
+      color: m('rgb(255, 0, 0)', 'rgb(0, 0, 255)'),
+    }))
+
+    const { container, unmount } = mountInBrowser(
+      h(PyreonUI, { theme: {}, mode: modeSig }, h(Text, { id: 'dbl' })),
+    )
+    const el = container.querySelector<HTMLElement>('#dbl')!
+    expect(getComputedStyle(el).color).toBe('rgb(255, 0, 0)')
+
+    modeSig.set('dark')
+    await new Promise((r) => setTimeout(r, 0))
+    await new Promise((r) => requestAnimationFrame(() => r(undefined)))
+
+    expect(getComputedStyle(el).color).toBe('rgb(0, 0, 255)')
+    unmount()
+  })
+
   it('the `variant` prop layers on top of state', () => {
     const Box: any = rocketstyle()({ name: 'VariantBox', component: Base })
       .styles(
@@ -168,6 +314,81 @@ describe('@pyreon/rocketstyle in real browser', () => {
     dark.unmount()
   })
 
+  // Bug 5 repro: cache-key collision under `useBooleans: true`.
+  //
+  // The user-facing bug shape: `<Btn primary />` and `<Btn secondary />`
+  // both render with the FIRST cached variant's resolved styles. Pre-fix
+  // the dimension-prop memo built its key from raw `propsRec[dimName]`
+  // BEFORE _calculateStylingAttrs resolved the boolean shorthand, so all
+  // boolean variants on the same dimension had `propsRec.state === undefined`
+  // and collided. Real-app symptom: a button group where primary, secondary,
+  // and danger variants all render in the FIRST color the user clicked.
+  //
+  // Real-Chromium proof: mounts both variants in parallel and asserts
+  // `getComputedStyle().color` is different. happy-dom's class-based
+  // assertions wouldn't catch this — only real CSS resolution proves
+  // the styler classCache served different cached styles for each variant.
+  it('Bug 5 repro: useBooleans:true with multiple boolean variants render with distinct computed styles', () => {
+    const Btn: any = rocketstyle({ useBooleans: true })({
+      name: 'BoolBtn',
+      component: Base,
+    })
+      .styles(
+        (css: any) => css`
+          color: ${({ $rocketstyle }: any) => $rocketstyle.color};
+        `,
+      )
+      .theme({ color: 'rgb(0, 0, 0)' })
+      .states({
+        primary: { color: 'rgb(255, 0, 0)' },
+        secondary: { color: 'rgb(0, 255, 0)' },
+        danger: { color: 'rgb(0, 0, 255)' },
+      })
+
+    const primaryMount = mountInBrowser(h(Btn, { id: 'p', primary: true }))
+    const secondaryMount = mountInBrowser(h(Btn, { id: 's', secondary: true }))
+    const dangerMount = mountInBrowser(h(Btn, { id: 'd', danger: true }))
+
+    const primaryEl = primaryMount.container.querySelector<HTMLElement>('#p')!
+    const secondaryEl = secondaryMount.container.querySelector<HTMLElement>('#s')!
+    const dangerEl = dangerMount.container.querySelector<HTMLElement>('#d')!
+
+    // Without the fix: all three resolve to whichever variant was cached
+    // first under the colliding key (mode|undefined|...). With the fix:
+    // each gets its own cache entry keyed off the resolved state value.
+    expect(getComputedStyle(primaryEl).color).toBe('rgb(255, 0, 0)')
+    expect(getComputedStyle(secondaryEl).color).toBe('rgb(0, 255, 0)')
+    expect(getComputedStyle(dangerEl).color).toBe('rgb(0, 0, 255)')
+
+    // Sibling mount under the SAME PyreonUI provider — exercises the
+    // cross-instance shared memo (per-theme WeakMap entry). Pre-fix this
+    // was the actual real-app shape: button group children mounted under
+    // a single provider, all hitting the same colliding key.
+    const groupMount = mountInBrowser(
+      h(PyreonUI, { theme: {}, mode: 'light' },
+        h('div', { id: 'group' },
+          h(Btn, { id: 'g-primary', primary: true }),
+          h(Btn, { id: 'g-secondary', secondary: true }),
+          h(Btn, { id: 'g-danger', danger: true }),
+        ),
+      ),
+    )
+    expect(
+      getComputedStyle(groupMount.container.querySelector<HTMLElement>('#g-primary')!).color,
+    ).toBe('rgb(255, 0, 0)')
+    expect(
+      getComputedStyle(groupMount.container.querySelector<HTMLElement>('#g-secondary')!).color,
+    ).toBe('rgb(0, 255, 0)')
+    expect(
+      getComputedStyle(groupMount.container.querySelector<HTMLElement>('#g-danger')!).color,
+    ).toBe('rgb(0, 0, 255)')
+
+    primaryMount.unmount()
+    secondaryMount.unmount()
+    dangerMount.unmount()
+    groupMount.unmount()
+  })
+
   it('multiple instances share definition-scoped caches (no per-mount rebuild)', () => {
     // Verifies the perf optimization: getDimensionsMap, reservedPropNames keys,
     // and omit Sets are cached at definition time (WeakMap), not rebuilt per mount.

package/src/__tests__/rocketstyleIntegration.test.ts

@@ -214,6 +214,36 @@ describe('chaining methods', () => {
     const result = WithAttrs.getDefaultAttrs({}, {}, 'light')
     expect(result.label).toBe('default')
   })
+
+  it('.getDefaultAttrs() passes isDark/isLight helpers matching the requested mode', () => {
+    // Regression: pre-fix the helpers were inverted in `getDefaultAttrs`
+    // (isDark: mode === 'light', isLight: mode === 'dark') so introspection
+    // callers (rocketstories-style story generators, devtools) saw the
+    // OPPOSITE of what the runtime renders. Runtime via `useTheme` derives
+    // helpers correctly from context (and handles `inversed` by flipping
+    // the mode at the Provider level — see context.test.ts), so the bug
+    // only surfaced for callers that read the helpers via `getDefaultAttrs`.
+    //
+    // Contract: `mode` is the EFFECTIVE mode (post-`inversed` resolution).
+    // Callers wanting "inversed light" pass `'dark'`; this function takes
+    // the resolved value, so testing both light/dark covers both the
+    // un-inversed and inversed cases.
+    const captured: Array<{ mode: any; isDark: any; isLight: any }> = []
+    const Probe = Button.attrs((_props: any, _theme: any, helpers: any) => {
+      captured.push({
+        mode: helpers.mode,
+        isDark: helpers.isDark,
+        isLight: helpers.isLight,
+      })
+      return {}
+    })
+
+    Probe.getDefaultAttrs({}, {}, 'light')
+    Probe.getDefaultAttrs({}, {}, 'dark')
+
+    expect(captured[0]).toEqual({ mode: 'light', isDark: false, isLight: true })
+    expect(captured[1]).toEqual({ mode: 'dark', isDark: true, isLight: false })
+  })
 })
 
 // --------------------------------------------------------
@@ -575,3 +605,107 @@ describe('theme and state injection', () => {
     expect(vnode.$rocketstate.state).toBe('primary')
   })
 })
+
+// --------------------------------------------------------
+// component-swap reset (cloneAndEnhance)
+// --------------------------------------------------------
+// `.config({ component: NewBase })` swaps the underlying renderable. The prior
+// .attrs() / .priorityAttrs() / .filterAttrs() / .compose() chains were
+// tailored to the previous component's prop shape — applying them to a
+// different component silently leaks invalid props through to the DOM (e.g.
+// `disabled` on an `<a>`). vitus-labs's rocketstyle drops those chains on
+// component swap; this regression test locks in matching behavior here.
+describe('component-swap reset', () => {
+  it('drops .attrs() chain when component changes', () => {
+    const ButtonBase: any = ({ children, $rocketstyle, $rocketstate, ...rest }: any) => ({
+      type: 'button',
+      props: rest,
+      children,
+    })
+    ButtonBase.displayName = 'ButtonBase'
+
+    const AnchorBase: any = ({ children, $rocketstyle, $rocketstate, ...rest }: any) => ({
+      type: 'a',
+      props: rest,
+      children,
+    })
+    AnchorBase.displayName = 'AnchorBase'
+
+    const Button: any = rocketstyle()({
+      name: 'Button',
+      component: ButtonBase,
+    }).attrs((() => ({ 'data-button-attr': 'leaked' })) as any)
+
+    const Link: any = Button.config({ component: AnchorBase })
+
+    const result = renderProps(Link)
+    expect(result['data-button-attr']).toBeUndefined()
+  })
+
+  it('preserves .attrs() chain when component is not changed', () => {
+    const Base: any = ({ children, $rocketstyle, $rocketstate, ...rest }: any) => ({
+      type: 'div',
+      props: rest,
+      children,
+    })
+    Base.displayName = 'Base'
+
+    const Button: any = rocketstyle()({
+      name: 'Button',
+      component: Base,
+    }).attrs((() => ({ 'data-keep': 'yes' })) as any)
+
+    const Same: any = Button.config({ DEBUG: false })
+
+    const result = renderProps(Same)
+    expect(result['data-keep']).toBe('yes')
+  })
+
+  it('preserves .attrs() chain when same component is re-passed via config', () => {
+    const Base: any = ({ children, $rocketstyle, $rocketstate, ...rest }: any) => ({
+      type: 'div',
+      props: rest,
+      children,
+    })
+    Base.displayName = 'Base'
+
+    const Button: any = rocketstyle()({
+      name: 'Button',
+      component: Base,
+    }).attrs((() => ({ 'data-keep': 'yes' })) as any)
+
+    const Same: any = Button.config({ component: Base })
+
+    const result = renderProps(Same)
+    expect(result['data-keep']).toBe('yes')
+  })
+
+  it('lets fresh attrs after component swap apply to the new component', () => {
+    const ButtonBase: any = ({ children, $rocketstyle, $rocketstate, ...rest }: any) => ({
+      type: 'button',
+      props: rest,
+      children,
+    })
+    ButtonBase.displayName = 'ButtonBase'
+
+    const AnchorBase: any = ({ children, $rocketstyle, $rocketstate, ...rest }: any) => ({
+      type: 'a',
+      props: rest,
+      children,
+    })
+    AnchorBase.displayName = 'AnchorBase'
+
+    const Button: any = rocketstyle()({
+      name: 'Button',
+      component: ButtonBase,
+    }).attrs((() => ({ 'data-from-button': 'original' })) as any)
+
+    const Link: any = Button.config({ component: AnchorBase }).attrs(
+      (() => ({ 'data-from-link': 'fresh' })) as any,
+    )
+
+    const result = renderProps(Link)
+    expect(result['data-from-button']).toBeUndefined()
+    expect(result['data-from-link']).toBe('fresh')
+  })
+})

package/src/index.ts

@@ -4,7 +4,7 @@ import type { Rocketstyle } from './init'
 import rocketstyle from './init'
 import type { IsRocketComponent } from './isRocketComponent'
 import isRocketComponent from './isRocketComponent'
-import type { AttrsCb } from './types/attrs'
+import type { AttrsCb, AttrsHelpers } from './types/attrs'
 import type {
   ConfigAttrs,
   ConsumerCb,
@@ -37,6 +37,7 @@ import type { ComponentFn, ElementType, ExtractProps, MergeTypes, TObj } from '.
 
 export type {
   AttrsCb,
+  AttrsHelpers,
   ComponentFn,
   ComposeParam,
   ConfigAttrs,

package/src/rocketstyle.ts

@@ -38,18 +38,42 @@ type CloneAndEnhance = (
   opts: Partial<ExtendedConfiguration>,
 ) => ReturnType<typeof rocketComponent>
 
-/** Clones the current configuration and merges new options, returning a fresh rocketComponent. */
-const cloneAndEnhance: CloneAndEnhance = (defaultOpts, opts) =>
-  rocketComponent({
+/**
+ * Clones the current configuration and merges new options, returning a fresh
+ * rocketComponent.
+ *
+ * Component-swap reset: when `opts.component` is set AND differs from the
+ * current `defaultOpts.component`, the prior `attrs`, `priorityAttrs`,
+ * `filterAttrs`, and `compose` chains are dropped — they were tailored to the
+ * previous component's prop shape, and applying them to a different component
+ * silently leaks invalid props through to the DOM (e.g. `disabled` on an
+ * `<a>`). Callers who want to preserve them must re-chain explicitly:
+ *
+ *   const NewBtn = Button.config({ component: 'a' }).attrs(sharedAttrs)
+ */
+const cloneAndEnhance: CloneAndEnhance = (defaultOpts, opts) => {
+  const componentChanged =
+    opts.component != null && opts.component !== defaultOpts.component
+
+  return rocketComponent({
     ...defaultOpts,
-    attrs: chainOptions(opts.attrs, defaultOpts.attrs),
-    filterAttrs: [...(defaultOpts.filterAttrs ?? []), ...(opts.filterAttrs ?? [])],
-    priorityAttrs: chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
+    attrs: componentChanged
+      ? chainOptions(opts.attrs, [])
+      : chainOptions(opts.attrs, defaultOpts.attrs),
+    filterAttrs: componentChanged
+      ? [...(opts.filterAttrs ?? [])]
+      : [...(defaultOpts.filterAttrs ?? []), ...(opts.filterAttrs ?? [])],
+    priorityAttrs: componentChanged
+      ? chainOptions(opts.priorityAttrs, [])
+      : chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
     statics: { ...defaultOpts.statics, ...opts.statics },
-    compose: { ...defaultOpts.compose, ...opts.compose },
+    compose: componentChanged
+      ? { ...opts.compose }
+      : { ...defaultOpts.compose, ...opts.compose },
     ...chainOrOptions(CONFIG_KEYS, opts, defaultOpts),
     ...chainReservedKeyOptions([...defaultOpts.dimensionKeys, ...STYLING_KEYS], opts, defaultOpts),
   } as Parameters<typeof rocketComponent>[0])
+}
 
 // --------------------------------------------------------
 // rocketComponent
@@ -239,23 +263,46 @@ const rocketComponent: RocketComponent = (options) => {
       // Read reactive inputs (tracks theme + mode signals)
       const theme = themeAttrs.theme
       const mode = themeAttrs.mode
+      const propsRec = props as Record<string, unknown>
 
-      // Build key: mode | dimensionProps | pseudoState. Reading dimension
+      // Resolve active dimensions FIRST so the cache key uses the RESOLVED
+      // dimension values, not the raw prop names. Under `useBooleans: true`
+      // the user writes `<X primary />` / `<X secondary />` — both map to
+      // `state="primary"` / `state="secondary"` after _calculateStylingAttrs
+      // resolves the boolean shorthand. Keying off `propsRec[dimName]` would
+      // read `undefined` for both (the dimension prop itself was never set)
+      // and collide every variant onto the first cached entry. Reading
+      // `rocketstateRaw[dimName]` gives the resolved string and partitions
+      // them correctly.
+      // Resolved from props (not localCtx which has pseudo getters).
+      const rocketstateRaw = _calculateStylingAttrs({
+        props: pickStyledAttrs(propsRec, reservedPropNames),
+        dimensions,
+      })
+
+      // Build key: mode | dimensionValues | pseudoState. Reading dimension
       // props + pseudo signals here tracks them in the surrounding computed
       // so any change re-runs us with a different key.
       let key = mode as string
-      const propsRec = props as Record<string, unknown>
       for (const dimName in dimensions) {
-        const v = propsRec[dimName]
-        // String/number/boolean serialize directly. Anything else (including
-        // undefined / objects) gets a typeof tag so we don't collide.
-        key +=
-          '|' +
-          (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
-            ? String(v)
-            : v === undefined
-              ? ''
-              : '~' + typeof v)
+        const v = rocketstateRaw[dimName]
+        // Multi-key dimensions (e.g. variant={['primary', 'rounded']}) are
+        // arrays. Sort + join so equivalent sets hash identically; without
+        // this both `['a','b']` and `['b','a']` would produce different keys.
+        if (Array.isArray(v)) {
+          key +=
+            '|' + (v.length === 0 ? '' : (v as unknown[]).slice().sort().join(','))
+        } else {
+          // String/number/boolean serialize directly. Anything else (including
+          // undefined / objects) gets a typeof tag so we don't collide.
+          key +=
+            '|' +
+            (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
+              ? String(v)
+              : v === undefined
+                ? ''
+                : '~' + typeof v)
+        }
       }
       for (const k of ALL_PSEUDO_KEYS) {
         const propV = propsRec[k]
@@ -307,12 +354,6 @@ const rocketComponent: RocketComponent = (options) => {
       }
       const themes = dimHelper.get(theme)
 
-      // Resolve active dimensions from props (not localCtx which has pseudo getters)
-      const rocketstateRaw = _calculateStylingAttrs({
-        props: pickStyledAttrs(propsRec, reservedPropNames),
-        dimensions,
-      })
-
       // Resolve mode-specific theme
       const modeBaseHelper = ThemeManager.modeBaseTheme[mode]
       if (modeBaseHelper.has(baseTheme)) {
@@ -529,8 +570,8 @@ const rocketComponent: RocketComponent = (options) => {
         {
           render,
           mode,
-          isDark: mode === 'light',
-          isLight: mode === 'dark',
+          isDark: mode === 'dark',
+          isLight: mode === 'light',
         },
       ]),
   })

package/src/types/attrs.ts

@@ -1,13 +1,23 @@
 import type { render } from '@pyreon/ui-core'
 import type { ThemeModeKeys } from './theme'
 
-export type AttrsCb<A, T> = (
-  props: Partial<A>,
-  theme: T,
-  helpers: {
-    mode?: ThemeModeKeys
-    isDark?: boolean
-    isLight?: boolean
-    createElement: typeof render
-  },
-) => Partial<A>
+/** Helpers object passed as the 3rd arg to every `.attrs(callback)`. */
+export type AttrsHelpers = {
+  mode?: ThemeModeKeys
+  isDark?: boolean
+  isLight?: boolean
+  createElement: typeof render
+}
+
+/**
+ * Callback signature for `.attrs((props, theme, helpers) => …)`.
+ *
+ * `Partial<A>` on the return is for the strict-typing form when callers
+ * pass `AttrsCb<DFP, Theme<T>>` directly. In the rocketstyle `.attrs()`
+ * callback overload itself we use a different shape that decouples the
+ * props arg (narrow, full DFP) from the return type (loose — only the
+ * user's explicit `<P>` generic is checked, with `Record<string,
+ * unknown>` allowing runtime extras like `_documentProps`). See
+ * `IRocketStyleComponent.attrs` for the call-site shape.
+ */
+export type AttrsCb<A, T> = (props: Partial<A>, theme: T, helpers: AttrsHelpers) => Partial<A>

package/src/types/rocketstyle.ts

@@ -1,5 +1,5 @@
 import type { VNodeChild } from '@pyreon/core'
-import type { AttrsCb } from './attrs'
+import type { AttrsHelpers } from './attrs'
 import type { ConfigAttrs } from './config'
 import type { DefaultProps } from './configuration'
 import type {
@@ -76,7 +76,27 @@ export interface IRocketStyleComponent<
   // dimension key props
   DKP extends TDKP = TDKP,
   // calculated final props
-  DFP = MergeTypes<[OA, EA, DefaultProps, ExtractDimensionProps<D, DKP, UB>]>,
+  //
+  // `OA extends infer O` distributes over OA's union branches — future-proofs
+  // against the overload-aware `ExtractProps` (follow-up PR); for today's
+  // single-typed OA the distribution collapses to a single branch.
+  //
+  // **OA-overlapping EA keys are widened**. When `.attrs({ tag: 'a' })` sets
+  // a default for `tag` on a wrapper whose OA has `tag: HTMLTags`, we strip
+  // `tag` from OA and re-add it as `Partial<Pick<O, 'tag'>>` — taking O's
+  // WIDER type (`HTMLTags`), not EA's narrow literal `'a'`. The runtime
+  // default is `'a'`; the JSX call site still accepts any `HTMLTags` value
+  // (so `<Btn tag="span" />` is valid). `Partial<Omit<EA, keyof O>>` handles
+  // net-new EA-only keys (no OA conflict) and marks them optional too —
+  // every `.attrs()` value is semantically a default, never required of the
+  // consumer. Mirrors vitus-labs/ui-system PR #225.
+  DFP = OA extends infer O
+    ? Omit<O, keyof EA & keyof O> &
+        Partial<Pick<O, keyof EA & keyof O>> &
+        MergeTypes<
+          [Partial<Omit<EA, keyof O>>, DefaultProps, ExtractDimensionProps<D, DKP, UB>]
+        >
+    : never,
 > {
   // The component is callable — Pyreon components are plain functions
   (props: DFP): VNodeChild
@@ -95,23 +115,52 @@ export interface IRocketStyleComponent<
     : RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>
 
   // ATTRS chaining method
-  attrs: <P extends TObj | unknown = unknown>(
-    param: P extends TObj
-      ?
-          | Partial<DFP & P>
-          | ((
-              props: Partial<DFP & P>,
-              theme: Theme<T>,
-              helpers: any,
-            ) => Partial<P> & Record<string, unknown>)
-      : Partial<DFP> | AttrsCb<DFP, Theme<T>>,
-    config?: Partial<{
-      priority: boolean
-      filter: P extends TObj ? Partial<keyof (EA & P)>[] : Partial<keyof EA>[]
-    }>,
-  ) => P extends TObj
-    ? RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>
-    : RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>
+  //
+  // Two overloads. TS resolves in declaration order; the callback form is
+  // listed FIRST so a function argument matches it before falling through to
+  // the object form. Mirrors vitus-labs/ui-system PR #227 Issue 2 (callback
+  // overload split).
+  //
+  // **Callback overload — asymmetric props/return**: the `props` arg is
+  // typed strictly as `Partial<DFP & P>` (so reading `props.x` narrows
+  // against the wrapped component's full surface), while the RETURN is
+  // `Partial<P> & Record<string, unknown>` — only the user's explicit `<P>`
+  // generic is checked, with a wildcard for runtime extras. This preserves
+  // Pyreon's documented convention where `.attrs(callback)` returns can
+  // carry runtime-only fields (`_documentProps` markers for the document-
+  // export pipeline, `tag: 'a'` overrides on Text-based components where
+  // the rendered DOM tag is outside the component's narrow `tag` union,
+  // etc.). The runtime is loose by design — `.attrs(cb, { filter })`
+  // strips keys before forwarding to the DOM. Consumers wanting strict
+  // typed extras pass `<P>` with the precise keys they expect.
+  //
+  // **Object overload — `P & Partial<NoInfer<DFP>>`**: TS infers P from
+  // the param's keys. `NoInfer<DFP>` (TS 5.4+) prevents DFP from
+  // contributing to P inference. Combined with DFP widening above, this
+  // makes `.attrs({ tag: 'a' })` keys optional at the JSX call site —
+  // every `.attrs()` value is a default, not a required prop. Mirrors
+  // vitus-labs PR #225.
+  attrs: {
+    <P extends TObj = {}>(
+      param: (
+        props: Partial<DFP & P>,
+        theme: Theme<T>,
+        helpers: AttrsHelpers,
+      ) => Partial<P> & Record<string, unknown>,
+      config?: Partial<{
+        priority: boolean
+        filter: (keyof MergeTypes<[EA, P]>)[]
+      }>,
+    ): RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>
+
+    <P extends TObj = {}>(
+      param: P & Partial<NoInfer<DFP>>,
+      config?: Partial<{
+        priority: boolean
+        filter: (keyof MergeTypes<[EA, P]>)[]
+      }>,
+    ): RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>
+  }
 
   // THEME chaining method
   theme: <P extends TObj = TObj>(

package/src/types/styles.ts

@@ -4,7 +4,7 @@ import type { TObj } from './utils'
 
 export interface StylesDefault {}
 
-export type Styles<S = unknown> = StylesDefault
+export type Styles<_S = unknown> = StylesDefault
 
 export type Css = typeof config.css
 export type Style = ReturnType<Css>

package/src/types/utils.ts

@@ -51,5 +51,48 @@ export type Spread<A extends readonly [...any]> = A extends [infer L, ...infer R
 export type MergeTypes<A extends readonly [...any]> = ExtractNullableKeys<Spread<A>>
 
 // ─── ExtractProps ─────────────────────────────────────────────
-export type ExtractProps<TComponentOrTProps> =
-  TComponentOrTProps extends ComponentFn<infer TProps> ? TProps : TComponentOrTProps
+/**
+ * Extracts the props type from a Pyreon component function — or passes
+ * through the input unchanged when it's already a props type.
+ *
+ * Multi-overload aware: matches up to 4 call signatures and produces the
+ * UNION of their first-argument types. A single-overload function still
+ * works (the union of 4 copies of the same props type dedupes back to
+ * the single shape).
+ *
+ * **Why this shape**. `T extends (props: infer P) => any ? P : never` only
+ * captures the LAST overload of a multi-overload function — TS's overload-
+ * resolution-against-conditional-types semantics. Iterator / List / Element
+ * are 3-overload primitives where the LAST overload (`ChildrenProps`) is the
+ * loosest; without overload-aware extraction, `ExtractProps<Iterator>`
+ * returned just `ChildrenProps` and lost both `SimpleProps<T>` and
+ * `ObjectProps<T>` — wrapping Iterator through `rocketstyle()` /
+ * `attrs()` silently downgraded the public prop surface.
+ *
+ * The pattern-match shape `T extends { (props: infer P1, ...args: any): any;
+ * (props: infer P2, ...args: any): any; ... }` is the canonical TS trick
+ * for extracting overload sets — see also `Parameters<T>` semantics.
+ *
+ * Mirrors vitus-labs PR #222.
+ */
+export type ExtractProps<TComponentOrTProps> = TComponentOrTProps extends {
+  (props: infer P1, ...args: any): any
+  (props: infer P2, ...args: any): any
+  (props: infer P3, ...args: any): any
+  (props: infer P4, ...args: any): any
+}
+  ? P1 | P2 | P3 | P4
+  : TComponentOrTProps extends {
+        (props: infer P1, ...args: any): any
+        (props: infer P2, ...args: any): any
+        (props: infer P3, ...args: any): any
+      }
+    ? P1 | P2 | P3
+    : TComponentOrTProps extends {
+          (props: infer P1, ...args: any): any
+          (props: infer P2, ...args: any): any
+        }
+      ? P1 | P2
+      : TComponentOrTProps extends ComponentFn<infer TProps>
+        ? TProps
+        : TComponentOrTProps