@pyreon/rocketstyle 0.13.0 → 0.14.0

package/src/constants/index.ts

@@ -1,3 +1,13 @@
+// `import.meta.env.DEV` is provided by Vite/Rolldown at build time and
+// literal-replaced so prod bundles tree-shake the dev branch to zero bytes.
+// Typed through a narrowing interface so downstream packages don't need
+// `vite/client` in their tsconfigs to type-check this file transitively.
+interface ViteMeta {
+  readonly env?: { readonly DEV?: boolean }
+}
+/** Tree-shakeable dev-mode flag. `true` in dev, `false` (dead code eliminated) in prod. */
+export const __DEV__: boolean = (import.meta as ViteMeta).env?.DEV === true
+
 /** Default theme mode used when no mode is provided via context. */
 export const MODE_DEFAULT = 'light'
 

package/src/init.ts

@@ -1,5 +1,5 @@
 import { isEmpty } from '@pyreon/ui-core'
-import { ALL_RESERVED_KEYS } from './constants'
+import { ALL_RESERVED_KEYS, __DEV__ } from './constants'
 import defaultDimensions from './constants/defaultDimensions'
 import rocketComponent from './rocketstyle'
 import type { DefaultDimensions, Dimensions } from './types/dimensions'
@@ -73,7 +73,7 @@ const validateInit = (name: string, component: unknown, dimensions: Dimensions)
 
 const rocketstyle = (({ dimensions = defaultDimensions, useBooleans = false } = {}) =>
   ({ name, component }: { name: string; component: any }) => {
-    if (process.env.NODE_ENV !== 'production') {
+    if (__DEV__) {
       validateInit(name, component, dimensions)
     }
 

package/src/rocketstyle.ts

@@ -1,6 +1,6 @@
 import { compose, config, hoistNonReactStatics, omit, pick, render } from '@pyreon/ui-core'
 import { LocalThemeManager } from './cache'
-import { CONFIG_KEYS, PSEUDO_KEYS, PSEUDO_META_KEYS, STYLING_KEYS } from './constants'
+import { CONFIG_KEYS, PSEUDO_KEYS, PSEUDO_META_KEYS, STYLING_KEYS, __DEV__ } from './constants'
 import createLocalProvider from './context/createLocalProvider'
 import { useLocalContext } from './context/localContext'
 import { rocketstyleAttrsHoc } from './hoc'
@@ -17,6 +17,12 @@ import { createStaticsChainingEnhancers, createStaticsEnhancers } from './utils/
 import { calculateStyles } from './utils/styles'
 import { getDimensionThemes, getTheme, getThemeByMode, getThemeFromChain } from './utils/theme'
 
+// Dev-time counter sink — see packages/internals/perf-harness for contract.
+interface ViteMeta {
+  readonly env?: { readonly DEV?: boolean }
+}
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
+
 /**
  * Core rocketstyle component factory. Creates a fully-featured Pyreon component
  * that integrates theme management (with light/dark mode support), multi-tier
@@ -87,6 +93,27 @@ const rocketComponent: RocketComponent = (options) => {
   // --------------------------------------------------------
   const ThemeManager = new LocalThemeManager()
 
+  // ── Per-definition caches (shared across all instances) ──────────────
+  // getDimensionsMap + Object.keys(reservedPropNames) are theme-independent
+  // (dimension structure comes from .sizes()/.states()/.variants() chain,
+  // not from runtime theme values). Cache them so 50 instances of the same
+  // component definition skip the rebuild entirely.
+  const _dimensionsCache = new WeakMap<
+    object,
+    { keysMap: Record<string, unknown>; keywords: Record<string, true | undefined> }
+  >()
+  const _reservedKeysCache = new WeakMap<object, string[]>()
+
+  // Pre-compute merged key arrays once per definition (not per mount)
+  const ALL_PSEUDO_KEYS = [...PSEUDO_KEYS, ...PSEUDO_META_KEYS]
+  // Static portion of omit keys — PSEUDO_KEYS + filterAttrs + 'pseudo' are definition-scoped.
+  // RESERVED_STYLING_PROPS_KEYS is dimension-dependent but also cached per definition.
+  // 'pseudo' is included here so we can skip the destructuring spread of mergeProps.
+  const STATIC_OMIT_KEYS = ['pseudo', ...PSEUDO_KEYS, ...(options.filterAttrs ?? [])]
+  // Pre-built Set for omit() — avoids per-call Set allocation. Built once the
+  // dimension-dependent reserved keys are known (first mount), then reused.
+  const _omitSetCache = new WeakMap<string[], Set<string>>()
+
   // --------------------------------------------------------
   // COMPOSE - high-order components
   // --------------------------------------------------------
@@ -140,12 +167,27 @@ const rocketComponent: RocketComponent = (options) => {
       return helper.get(initialTheme)
     })()
 
-    const { keysMap: dimensions, keywords: reservedPropNames } = getDimensionsMap({
-      themes: initialDimensionThemes,
-      useBooleans: options.useBooleans,
-    })
+    // Cache getDimensionsMap per dimension-themes identity — all instances
+    // of the same component definition share the same dimension structure.
+    let dimResult = _dimensionsCache.get(initialDimensionThemes as object)
+    if (dimResult) {
+      if ((import.meta as ViteMeta).env?.DEV === true)
+        _countSink.__pyreon_count__?.('rocketstyle.dimensionsMap.hit')
+    } else {
+      dimResult = getDimensionsMap({
+        themes: initialDimensionThemes,
+        useBooleans: options.useBooleans,
+      })
+      _dimensionsCache.set(initialDimensionThemes as object, dimResult)
+    }
+    const { keysMap: dimensions, keywords: reservedPropNames } = dimResult
 
-    const RESERVED_STYLING_PROPS_KEYS = Object.keys(reservedPropNames)
+    // Cache Object.keys() result — same dimension structure = same keys
+    let RESERVED_STYLING_PROPS_KEYS = _reservedKeysCache.get(reservedPropNames as object)
+    if (!RESERVED_STYLING_PROPS_KEYS) {
+      RESERVED_STYLING_PROPS_KEYS = Object.keys(reservedPropNames)
+      _reservedKeysCache.set(reservedPropNames as object, RESERVED_STYLING_PROPS_KEYS)
+    }
 
     // --------------------------------------------------
     // $rocketstyle as a FUNCTION ACCESSOR — fully reactive.
@@ -154,6 +196,8 @@ const rocketComponent: RocketComponent = (options) => {
     // (signals, getters) produce updated dimension values.
     // --------------------------------------------------
     const $rocketstyleAccessor = () => {
+      if ((import.meta as ViteMeta).env?.DEV === true)
+        _countSink.__pyreon_count__?.('rocketstyle.getTheme')
       // Read theme + mode LAZILY via the getter-backed themeAttrs object.
       // Both reads are tracked when this accessor runs inside a reactive
       // scope (styler's effect), so theme swap / mode toggle re-runs the
@@ -165,13 +209,19 @@ const rocketComponent: RocketComponent = (options) => {
       // keyed on theme identity — stable-theme renders hit cache in O(1),
       // theme swaps fall through to recompute (once per new theme).
       const baseThemeHelper = ThemeManager.baseTheme
-      if (!baseThemeHelper.has(theme)) {
+      if (baseThemeHelper.has(theme)) {
+        if ((import.meta as ViteMeta).env?.DEV === true)
+          _countSink.__pyreon_count__?.('rocketstyle.localThemeManager.hit')
+      } else {
         baseThemeHelper.set(theme, getThemeFromChain(options.theme, theme))
       }
       const baseTheme = baseThemeHelper.get(theme)
 
       const dimHelper = ThemeManager.dimensionsThemes
-      if (!dimHelper.has(theme)) {
+      if (dimHelper.has(theme)) {
+        if ((import.meta as ViteMeta).env?.DEV === true)
+          _countSink.__pyreon_count__?.('rocketstyle.localThemeManager.hit')
+      } else {
         dimHelper.set(theme, getDimensionThemes(theme, options))
       }
       const themes = dimHelper.get(theme)
@@ -184,13 +234,19 @@ const rocketComponent: RocketComponent = (options) => {
 
       // Resolve mode-specific theme
       const modeBaseHelper = ThemeManager.modeBaseTheme[mode]
-      if (!modeBaseHelper.has(baseTheme)) {
+      if (modeBaseHelper.has(baseTheme)) {
+        if ((import.meta as ViteMeta).env?.DEV === true)
+          _countSink.__pyreon_count__?.('rocketstyle.localThemeManager.hit')
+      } else {
         modeBaseHelper.set(baseTheme, getThemeByMode(baseTheme, mode))
       }
       const currentModeBaseTheme = modeBaseHelper.get(baseTheme)
 
       const modeDimHelper = ThemeManager.modeDimensionTheme[mode]
-      if (!modeDimHelper.has(themes)) {
+      if (modeDimHelper.has(themes)) {
+        if ((import.meta as ViteMeta).env?.DEV === true)
+          _countSink.__pyreon_count__?.('rocketstyle.localThemeManager.hit')
+      } else {
         modeDimHelper.set(themes, getThemeByMode(themes, mode))
       }
       const currentModeThemes = modeDimHelper.get(themes)
@@ -228,7 +284,7 @@ const rocketComponent: RocketComponent = (options) => {
       // Read pseudo props fresh each call — props may have reactive getters
       // from _rp() wrapping. Reading inside the accessor (which runs in an
       // effect) ensures changes to pseudo props like active={isDark()} are tracked.
-      const propPseudo = pick(props, [...PSEUDO_KEYS, ...PSEUDO_META_KEYS])
+      const propPseudo = pick(props, ALL_PSEUDO_KEYS)
 
       return {
         ...rocketstate,
@@ -237,34 +293,42 @@ const rocketComponent: RocketComponent = (options) => {
     }
 
     // --------------------------------------------------
-    // Static mergeProps for final prop filtering (non-dimension props)
+    // final props passed to WrappedComponent
     // --------------------------------------------------
-    const { pseudo: _pseudo, ...mergeProps } = {
-      ...localCtx,
-      ...props,
+    // Cache a pre-built Set for omit() — avoids building a new Set from
+    // the key array on every mount. Same dimension structure = same Set.
+    let omitSet = _omitSetCache.get(RESERVED_STYLING_PROPS_KEYS)
+    if (omitSet) {
+      if ((import.meta as ViteMeta).env?.DEV === true)
+        _countSink.__pyreon_count__?.('rocketstyle.omitSet.hit')
+    } else {
+      omitSet = new Set([...RESERVED_STYLING_PROPS_KEYS, ...STATIC_OMIT_KEYS])
+      _omitSetCache.set(RESERVED_STYLING_PROPS_KEYS, omitSet)
     }
 
-    // --------------------------------------------------
-    // final props passed to WrappedComponent
-    // --------------------------------------------------
-    const finalProps: Record<string, any> = {
-      ...omit(mergeProps, [
-        ...RESERVED_STYLING_PROPS_KEYS,
-        ...PSEUDO_KEYS,
-        ...options.filterAttrs,
-      ]),
-      ...(options.passProps ? pick(mergeProps, options.passProps) : {}),
-      ref: props.ref,
-      // Function accessors — DynamicStyled wraps them in a computed() so
-      // mode/dimension changes produce a new CSS class reactively. The
-      // computed tracks only these two accessors; the resolve itself runs
-      // untracked to prevent exponential cascade from theme deep-reads.
-      $rocketstyle: $rocketstyleAccessor,
-      $rocketstate: $rocketstateAccessor,
+    // Merge localCtx + props without an intermediate spread object.
+    // omit() handles 'pseudo' removal (included in STATIC_OMIT_KEYS).
+    const mergeProps = localCtx ? { ...localCtx, ...props } : props
+
+    // omit() already returns a fresh object — assign directly onto it
+    // instead of spreading into another {} (saves one object allocation).
+    const finalProps = omit(mergeProps as Record<string, unknown>, omitSet) as Record<string, any>
+
+    if (options.passProps) {
+      const passed = pick(mergeProps, options.passProps)
+      for (const k in passed) finalProps[k] = passed[k]
     }
 
-    // development debugging
-    if (process.env.NODE_ENV !== 'production') {
+    finalProps.ref = props.ref
+    // Function accessors — DynamicStyled wraps them in a computed() so
+    // mode/dimension changes produce a new CSS class reactively. The
+    // computed tracks only these two accessors; the resolve itself runs
+    // untracked to prevent exponential cascade from theme deep-reads.
+    finalProps.$rocketstyle = $rocketstyleAccessor
+    finalProps.$rocketstate = $rocketstateAccessor
+
+    // development debugging — tree-shaken in production via import.meta.env.DEV
+    if (__DEV__) {
       finalProps['data-rocketstyle'] = componentName
 
       if (options.DEBUG) {
@@ -326,6 +390,26 @@ const rocketComponent: RocketComponent = (options) => {
     options: options.statics,
   })
 
+  // ─── Hoisted attrs chain (T3.1) ──────────────────────────────────────
+  //
+  // Expose the accumulated `.attrs()` callback chain on the component so
+  // external inspectors (notably `extractDocumentTree` from
+  // `@pyreon/connector-document`) can compute the post-attrs props
+  // without invoking the full component. The previous Path B workaround
+  // had to run the entire styled wrapper — JSX tree creation, dimension
+  // resolution, the lot — just to read `_documentProps` off the result.
+  //
+  // Typed surface: `RocketStyleComponent.__rs_attrs` is a `readonly
+  // ReadonlyArray<(props) => Record<string, unknown>>`. Empty when
+  // no `.attrs()` was ever called. `chain.reduce(Object.assign, {})`
+  // produces the post-attrs result for a given props bag.
+  //
+  // The `readonly` modifier guards external CONSUMERS — internal
+  // assignment from the factory itself is the only legitimate write,
+  // hence the cast. Do not drop the readonly on the type.
+  ;(FinalComponent as unknown as { __rs_attrs: typeof options.attrs }).__rs_attrs =
+    options.attrs ?? []
+
   Object.assign(FinalComponent, {
     attrs: (attrs: any, { priority, filter }: any = {}) => {
       const result: Record<string, any> = {}

package/src/types/rocketstyle.ts

@@ -153,4 +153,19 @@ export interface IRocketStyleComponent<
 
   IS_ROCKETSTYLE: true
   displayName: string
+
+  /**
+   * The accumulated `.attrs()` callback chain — hoisted at component-creation
+   * time so external inspectors (notably `extractDocumentTree` from
+   * `@pyreon/connector-document`) can compute post-attrs props without
+   * invoking the full styled wrapper. Each callback maps user props to a
+   * partial props object; `chain.reduce(Object.assign, {})` produces the
+   * post-attrs result.
+   *
+   * Stable contract — consumers can rely on this property being present on
+   * every rocketstyle-wrapped component. Empty array when no `.attrs()`
+   * was ever called on the chain. Treat as read-only; mutating breaks
+   * `extractDocumentTree` and any other inspector consuming the hoist.
+   */
+  readonly __rs_attrs: ReadonlyArray<(props: Record<string, unknown>) => Record<string, unknown>>
 }

package/src/utils/attrs.ts

@@ -80,53 +80,49 @@ export const calculateStylingAttrs: CalculateStylingAttrs =
     const result: Record<string, any> = {}
 
     // (1) find dimension keys values & initialize
-    // object with possible options
-    Object.keys(dimensions).forEach((item) => {
+    for (const item in dimensions) {
       const pickedProp = props[item]
       const t = typeof pickedProp
 
-      // if the property is multi key, allow assign array as well
       if (multiKeys?.[item] && Array.isArray(pickedProp)) {
         result[item] = pickedProp
-      }
-      // assign when it's only a string or number otherwise it's considered
-      // as invalid param
-      else if (t === 'string' || t === 'number') {
+      } else if (t === 'string' || t === 'number') {
         result[item] = pickedProp
       } else {
         result[item] = undefined
       }
-    })
+    }
 
     // (2) if booleans are being used let's find the rest
+    // Use `in` operator on the dimension map instead of allocating
+    // a new Set per dimension — the map is already an object with
+    // the keywords as keys.
     if (useBooleans) {
-      const propsKeys = Object.keys(props)
+      for (const key in result) {
+        if (result[key]) continue // already assigned
 
-      Object.entries(result).forEach(([key, value]) => {
+        const dimensionMap = dimensions[key] as Record<string, unknown>
         const isMultiKey = multiKeys?.[key]
+        let newDimensionValue: string | string[] | undefined
 
-        // when value in result is not assigned yet
-        if (!value) {
-          let newDimensionValue: string | string[] | undefined
-          const keywordSet = new Set(Object.keys(dimensions[key] as Record<string, unknown>))
-
-          if (isMultiKey) {
-            newDimensionValue = propsKeys.filter((propKey) => keywordSet.has(propKey))
-          } else {
-            // iterate backwards to guarantee the last one will have
-            // a priority over previous ones
-            for (let i = propsKeys.length - 1; i >= 0; i--) {
-              const k = propsKeys[i] as string
-              if (keywordSet.has(k) && props[k]) {
-                newDimensionValue = k
-                break
-              }
+        if (isMultiKey) {
+          const matches: string[] = []
+          for (const propKey in props) {
+            if (propKey in dimensionMap) matches.push(propKey)
+          }
+          newDimensionValue = matches.length > 0 ? matches : undefined
+        } else {
+          // Iterate props to find last matching keyword
+          // (last wins for priority)
+          for (const k in props) {
+            if (k in dimensionMap && props[k]) {
+              newDimensionValue = k
             }
           }
-
-          result[key] = newDimensionValue
         }
-      })
+
+        result[key] = newDimensionValue
+      }
     }
 
     return result

package/src/utils/theme.ts

@@ -60,26 +60,21 @@ type GetDimensionThemes = (
 ) => Record<string, any>
 
 export const getDimensionThemes: GetDimensionThemes = (theme, options) => {
-  const result = {}
-
-  if (isEmpty(options.dimensions)) return result
-
-  return Object.entries(options.dimensions).reduce(
-    (acc, [key, value]) => {
-      const [, dimension] = isMultiKey(value as string | Record<string, unknown>)
+  const dims = options.dimensions
+  if (isEmpty(dims)) return {}
 
-      const helper = options[key]
+  const result: Record<string, any> = {}
 
-      if (Array.isArray(helper) && helper.length > 0) {
-        const finalDimensionThemes = getThemeFromChain(helper, theme)
+  for (const key in dims) {
+    const [, dimension] = isMultiKey(dims[key] as string | Record<string, unknown>)
+    const helper = options[key]
 
-        acc[dimension] = removeNullableValues(finalDimensionThemes)
-      }
+    if (Array.isArray(helper) && helper.length > 0) {
+      result[dimension] = removeNullableValues(getThemeFromChain(helper, theme))
+    }
+  }
 
-      return acc
-    },
-    result as Record<string, any>,
-  )
+  return result
 }
 
 // --------------------------------------------------------
@@ -119,54 +114,62 @@ export type GetTheme = (params: {
   appTheme?: Record<string, any>
 }) => Record<string, unknown>
 
+// Shared empty object for pseudo-state defaults — allocated once, reused by
+// every getTheme call. Frozen to prevent accidental mutation.
+const EMPTY_PSEUDO: Record<string, never> = Object.freeze({}) as Record<string, never>
+
 export const getTheme: GetTheme = ({ rocketstate, themes, baseTheme, transformKeys, appTheme }) => {
-  let finalTheme = { ...baseTheme }
-  const deferredTransforms: Array<
-    (
-      currentTheme: Record<string, any>,
-      currentAppTheme: Record<string, any>,
-      mode: typeof themeModeCallback,
-      cssFn: typeof config.css,
-    ) => Record<string, any>
-  > = []
-
-  Object.entries(rocketstate).forEach(([key, value]: [string, string | string[]]) => {
+  // Spread baseTheme into result — this is unavoidable (we must not mutate
+  // the cached baseTheme). But we merge dimension slices in-place onto
+  // finalTheme instead of creating a new {} target each merge() call.
+  const finalTheme: Record<string, any> = { ...baseTheme }
+  type TransformFn = (
+    currentTheme: Record<string, any>,
+    currentAppTheme: Record<string, any>,
+    mode: typeof themeModeCallback,
+    cssFn: typeof config.css,
+  ) => Record<string, any>
+  const deferredTransforms: TransformFn[] = []
+
+  for (const key in rocketstate) {
+    const value = rocketstate[key]
+    if (value == null) continue
     const keyTheme: Record<string, any> = themes[key] ?? {}
     const isTransform = transformKeys?.[key]
 
     const mergeValue = (item: string) => {
       const val = keyTheme[item]
+      if (val == null) return
       if (isTransform && typeof val === 'function') {
-        deferredTransforms.push(val)
+        deferredTransforms.push(val as TransformFn)
       } else {
-        finalTheme = merge({}, finalTheme, val)
+        // Merge in-place onto finalTheme — avoids allocating a fresh {}
+        // as merge target on every dimension slice.
+        merge(finalTheme, val)
       }
     }
 
     if (Array.isArray(value)) {
-      value.forEach(mergeValue)
+      for (let i = 0; i < value.length; i++) mergeValue(value[i] as string)
     } else {
-      mergeValue(value)
+      mergeValue(value as string)
     }
-  })
+  }
 
   // Apply transform dimension values last with the fully accumulated theme
-  for (const transform of deferredTransforms) {
-    finalTheme = merge(
-      {},
-      finalTheme,
-      transform(finalTheme, appTheme ?? {}, themeModeCallback, config.css),
-    )
+  for (let i = 0; i < deferredTransforms.length; i++) {
+    merge(finalTheme, deferredTransforms[i]!(finalTheme, appTheme ?? {}, themeModeCallback, config.css))
   }
 
   // Ensure pseudo-state keys always exist as objects so .styles() can
   // destructure without defaults: const { hover, focus, ... } = $rocketstyle
-  finalTheme.hover ??= {}
-  finalTheme.focus ??= {}
-  finalTheme.active ??= {}
-  finalTheme.disabled ??= {}
-  finalTheme.pressed ??= {}
-  finalTheme.readOnly ??= {}
+  // Uses a frozen shared empty object instead of allocating 6 new {} per call.
+  finalTheme.hover ??= EMPTY_PSEUDO
+  finalTheme.focus ??= EMPTY_PSEUDO
+  finalTheme.active ??= EMPTY_PSEUDO
+  finalTheme.disabled ??= EMPTY_PSEUDO
+  finalTheme.pressed ??= EMPTY_PSEUDO
+  finalTheme.readOnly ??= EMPTY_PSEUDO
 
   return finalTheme
 }