@pyreon/rocketstyle 0.14.0 → 0.16.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import * as _pyreon_core0 from "@pyreon/core";
+import * as _$_pyreon_core0 from "@pyreon/core";
 import { VNodeChild } from "@pyreon/core";
 import { config, context, render } from "@pyreon/ui-core";
 
@@ -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.
@@ -222,16 +258,29 @@ type Configuration<C = ElementType | unknown, D extends Dimensions = Dimensions>
   statics: Record<string, any>;
 } & Record<string, any>;
 type DefaultProps = Partial<PseudoProps> & {
-  children?: _pyreon_core0.VNodeChild;
+  children?: _$_pyreon_core0.VNodeChild;
 };
 //#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

@@ -1,10 +1,10 @@
-import { createContext, provide, useContext } from "@pyreon/core";
+import { createContext, nativeCompat, provide, useContext } from "@pyreon/core";
 import { Provider as Provider$1, compose, config, context, get, hoistNonReactStatics, isEmpty, merge, omit, pick, render, set } from "@pyreon/ui-core";
 import { signal } from "@pyreon/reactivity";
 
 //#region src/constants/index.ts
 /** Tree-shakeable dev-mode flag. `true` in dev, `false` (dead code eliminated) in prod. */
-const __DEV__ = import.meta.env?.DEV === true;
+const __DEV__ = process.env.NODE_ENV !== "production";
 /** Default theme mode used when no mode is provided via context. */
 const MODE_DEFAULT = "light";
 /** Pseudo-state interaction keys tracked for styling (hover, active, focus, pressed). */
@@ -74,6 +74,7 @@ const Provider = ({ provider = Provider$1, inversed, ...props }) => {
 		children
 	}) ?? null;
 };
+nativeCompat(Provider);
 
 //#endregion
 //#region src/constants/defaultDimensions.ts
@@ -471,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;
@@ -510,6 +526,8 @@ const rocketComponent = (options) => {
 		...options.filterAttrs ?? []
 	];
 	const _omitSetCache = /* @__PURE__ */ new WeakMap();
+	const _rsMemo = /* @__PURE__ */ new WeakMap();
+	const RS_MEMO_CAP = 32;
 	const hocsFuncs = [rocketStyleHOC(options), ...calculateHocsFuncs(options.compose)];
 	const EnhancedComponent = (props) => {
 		const localCtx = useLocalContext(options.consumer);
@@ -527,7 +545,7 @@ const rocketComponent = (options) => {
 		})();
 		let dimResult = _dimensionsCache.get(initialDimensionThemes);
 		if (dimResult) {
-			if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("rocketstyle.dimensionsMap.hit");
+			if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.dimensionsMap.hit");
 		} else {
 			dimResult = getDimensionsMap({
 				themes: initialDimensionThemes,
@@ -541,59 +559,90 @@ const rocketComponent = (options) => {
 			RESERVED_STYLING_PROPS_KEYS = Object.keys(reservedPropNames);
 			_reservedKeysCache.set(reservedPropNames, RESERVED_STYLING_PROPS_KEYS);
 		}
-		const $rocketstyleAccessor = () => {
-			if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("rocketstyle.getTheme");
+		const localPseudo = localCtx?.pseudo;
+		const _resolveRsEntry = () => {
 			const theme = themeAttrs.theme;
 			const mode = themeAttrs.mode;
+			const propsRec = props;
+			const rocketstateRaw = _calculateStylingAttrs({
+				props: pickStyledAttrs(propsRec, reservedPropNames),
+				dimensions
+			});
+			let key = mode;
+			for (const dimName in dimensions) {
+				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];
+				const localV = localPseudo?.[k];
+				const v = propV !== void 0 ? propV : localV;
+				key += "|" + (v === void 0 ? "" : v ? "1" : "0");
+			}
+			let themeMemo = _rsMemo.get(theme);
+			if (!themeMemo) {
+				themeMemo = /* @__PURE__ */ new Map();
+				_rsMemo.set(theme, themeMemo);
+			}
+			const cached = themeMemo.get(key);
+			if (cached) {
+				if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.dimensionMemo.hit");
+				themeMemo.delete(key);
+				themeMemo.set(key, cached);
+				return cached;
+			}
+			if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.getTheme");
 			const baseThemeHelper = ThemeManager$1.baseTheme;
 			if (baseThemeHelper.has(theme)) {
-				if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
+				if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
 			} else baseThemeHelper.set(theme, getThemeFromChain(options.theme, theme));
 			const baseTheme = baseThemeHelper.get(theme);
 			const dimHelper = ThemeManager$1.dimensionsThemes;
 			if (dimHelper.has(theme)) {
-				if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
+				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 rocketstate = _calculateStylingAttrs({
-				props: pickStyledAttrs(props, reservedPropNames),
-				dimensions
-			});
 			const modeBaseHelper = ThemeManager$1.modeBaseTheme[mode];
 			if (modeBaseHelper.has(baseTheme)) {
-				if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
+				if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
 			} else modeBaseHelper.set(baseTheme, getThemeByMode(baseTheme, mode));
 			const currentModeBaseTheme = modeBaseHelper.get(baseTheme);
 			const modeDimHelper = ThemeManager$1.modeDimensionTheme[mode];
 			if (modeDimHelper.has(themes)) {
-				if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
+				if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.localThemeManager.hit");
 			} else modeDimHelper.set(themes, getThemeByMode(themes, mode));
-			return getTheme({
-				rocketstate,
+			const rocketstyle = getTheme({
+				rocketstate: rocketstateRaw,
 				themes: modeDimHelper.get(themes),
 				baseTheme: currentModeBaseTheme,
 				transformKeys: options.transformKeys,
 				appTheme: theme
 			});
-		};
-		const localPseudo = localCtx?.pseudo;
-		const $rocketstateAccessor = () => {
-			const rocketstate = _calculateStylingAttrs({
-				props: pickStyledAttrs(props, reservedPropNames),
-				dimensions
-			});
-			const propPseudo = pick(props, ALL_PSEUDO_KEYS);
-			return {
-				...rocketstate,
+			const propPseudo = pick(propsRec, ALL_PSEUDO_KEYS);
+			const rocketstate = {
+				...rocketstateRaw,
 				pseudo: {
 					...localPseudo,
 					...propPseudo
 				}
 			};
+			if (themeMemo.size >= RS_MEMO_CAP) {
+				const oldestKey = themeMemo.keys().next().value;
+				if (oldestKey !== void 0) themeMemo.delete(oldestKey);
+			}
+			const entry = {
+				rocketstyle,
+				rocketstate
+			};
+			themeMemo.set(key, entry);
+			return entry;
 		};
+		const $rocketstyleAccessor = () => _resolveRsEntry().rocketstyle;
+		const $rocketstateAccessor = () => _resolveRsEntry().rocketstate;
 		let omitSet = _omitSetCache.get(RESERVED_STYLING_PROPS_KEYS);
 		if (omitSet) {
-			if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("rocketstyle.omitSet.hit");
+			if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("rocketstyle.omitSet.hit");
 		} else {
 			omitSet = new Set([...RESERVED_STYLING_PROPS_KEYS, ...STATIC_OMIT_KEYS]);
 			_omitSetCache.set(RESERVED_STYLING_PROPS_KEYS, omitSet);
@@ -682,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.14.0",
+  "version": "0.16.0",
   "description": "Multi-dimensional style composition for Pyreon components",
   "license": "MIT",
   "repository": {
@@ -10,6 +10,7 @@
   },
   "files": [
     "lib",
+    "!lib/**/*.map",
     "!lib/analysis",
     "README.md",
     "LICENSE",
@@ -41,19 +42,19 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/test-utils": "^0.13.2",
-    "@pyreon/typescript": "^0.14.0",
-    "@pyreon/ui-core": "^0.14.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": "^1.15.3"
-  },
-  "peerDependencies": {
-    "@pyreon/core": "^0.14.0",
-    "@pyreon/reactivity": "^0.14.0",
-    "@pyreon/styler": "^0.14.0",
-    "@pyreon/ui-core": "^0.14.0"
+    "@vitus-labs/tools-rolldown": "^2.3.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__/native-marker.test.ts

@@ -0,0 +1,9 @@
+import { isNativeCompat } from '@pyreon/core'
+import { describe, expect, it } from 'vitest'
+import RocketstyleProvider from '../context/context'
+
+describe('native-compat marker — @pyreon/rocketstyle', () => {
+  it('Provider is marked native', () => {
+    expect(isNativeCompat(RocketstyleProvider)).toBe(true)
+  })
+})