@codeleap/styles 6.3.0 → 6.8.0

package/src/classes/StaleControl.ts

@@ -6,7 +6,7 @@
  * Developed for potential future need of time-based cache invalidation.
  */
  export class StaleControl {
-  private wiperId: Timer | null = null
+  private wiperId: ReturnType<typeof setInterval> | null = null
 
   /**
    * @param staleTime - Expiration time in minutes (default: 60 minutes)

package/src/classes/StyleCache.ts

@@ -5,12 +5,18 @@ import { CacheType } from '../types/cache'
 import { StateStorage } from '../types/store'
 
 /**
- * StyleCache manages multiple cache instances for different style-related data.
- * Provides centralized caching functionality with compression and key generation.
+ * Aggregates the six typed `Cache` buckets used by the style registry.
+ * Three buckets (`styles`, `compositions`, `responsive`) are in-memory only.
+ * Three buckets (`variants`, `common`, `components`) are backed by the
+ * provided `StateStorage` and survive page reloads until the stale window expires.
+ *
+ * All keys are derived from a `baseKey` that encodes the active color scheme,
+ * theme snapshot, and common variants — so switching color scheme automatically
+ * invalidates all cached values without an explicit `wipeCache` call.
  */
 export class StyleCache {
   /** Base key used for cache key generation */
-  baseKey: string
+  baseKey!: string
 
   /** Cache for style data */
   styles = new Cache('styles')

package/src/classes/StylePersistor.ts

@@ -2,12 +2,23 @@ import { StateStorage } from '../types/store'
 import { minifier } from '../tools'
 import { StyleConstants } from '../constants'
 
+/**
+ * Platform-specific storage adapter required by `StylePersistor`.
+ * Implementations exist for MMKV (mobile) and localStorage (web).
+ * Note the method names (`set`/`get`/`del`) differ from the `StateStorage` interface
+ * (`setItem`/`getItem`/`removeItem`) — `StylePersistor` bridges the two.
+ */
 export type StoragePersistor = {
   set: (key: string, value: any) => void
   get: (key: string) => any
   del: (key: string) => void
 }
 
+/**
+ * Adapts a platform `StoragePersistor` to the `StateStorage` interface expected by
+ * `StyleCache`. All values are LZ-compressed on write and decompressed on read,
+ * substantially reducing storage footprint for large serialised style caches.
+ */
 export class StylePersistor implements StateStorage {
   /**
    * Creates a new StylePersistor instance with compression capabilities

package/src/classes/StyleRegistry.ts

@@ -1,5 +1,5 @@
 /* eslint-disable dot-notation */
-import type { AnyRecord, AnyStyledComponent, ICSS, ITheme, StyleAggregator, StyleProp, VariantStyleSheet } from '../types'
+import type { AnyStyledComponent, ComponentContext, ICSS, ITheme, StyleAggregator, StyleProp, VariantStyleSheet } from '../types'
 import type { StateStorage } from '../types/store'
 import type { MultiplierFunction } from '../variants'
 import { themeStore } from '../theme'
@@ -7,7 +7,22 @@ import { defaultVariants, dynamicVariants } from '../variants'
 import { capitalize, ignoredStyleKeys, isSpacingKey } from '../utils'
 import { StyleCache } from './StyleCache'
 import { minifier, deepClone, deepmerge } from '../tools'
-
+import { CONTEXT_FACTORY_SYMBOL } from '../lib/createStyles'
+
+/**
+ * Central style resolution engine for the `@codeleap/styles` system.
+ *
+ * Responsibilities:
+ * - Stores compressed variant stylesheets per component (`stylesheets`).
+ * - Maintains the merged common-variant map (`defaultVariants + appVariants + dynamicVariants + spacing`).
+ * - Resolves `StyleProp` values into flat `ICSS` objects for each composition element.
+ * - Caches every resolution step in the six `StyleCache` buckets for performance.
+ * - Provides `createStyle` as an abstract hook for platform-specific style flattening
+ *   (web passes through; RN uses `StyleSheet.flatten`).
+ *
+ * Instantiated once per platform registry (not per component). Platform packages
+ * subclass or configure this to provide the appropriate `createStyle` implementation.
+ */
 export class CodeleapStyleRegistry {
   stylesheets: Record<string, VariantStyleSheet> = {}
 
@@ -17,6 +32,9 @@ export class CodeleapStyleRegistry {
 
   components: Record<string, AnyStyledComponent> = {}
 
+  /** Per-component map of variant names to context-aware factory functions. Populated during `registerVariants`. */
+  variantFactories: Record<string, Record<string, (theme: ITheme, context: ComponentContext) => any>> = {}
+
   private styleCache: StyleCache
 
   constructor(storage: StateStorage) {
@@ -24,42 +42,47 @@ export class CodeleapStyleRegistry {
 
     this.registerCommonVariants()
 
-    const currentColorScheme = themeStore.theme?.['currentColorScheme']?.() ?? themeStore.colorScheme ?? 'default'
+    const currentColorScheme = themeStore.themeTyped?.currentColorScheme?.() ?? themeStore.colorScheme ?? 'default'
 
     this.styleCache.registerBaseKey([currentColorScheme, themeStore.theme, this.commonVariants])
   }
 
-  computeCommonVariantStyle(componentName: string, variant: string, component = null) {
+  /**
+   * Resolves a single common-variant string (e.g., `"flex"`, `"padding:2"`, `"xl:flex"`)
+   * into a composition-keyed style object. Handles breakpoint-prefixed variants by wrapping
+   * the result in a `@media` key. Returns `null` if the variant is not found in `commonVariants`.
+   */
+  computeCommonVariantStyle(componentName: string, variant: string, component: string | undefined = undefined) {
     const cache = this.styleCache.keyFor('common', variant)
 
     if (!!cache.value) {
       return {
-        [component]: this.createStyle(cache.value),
+        [component as string]: this.createStyle(cache.value),
       }
     }
 
     const theme = themeStore.theme
 
-    let mediaQuery = null
+    let mediaQuery: string | null = null
 
-    let [variantName, value] = variant?.includes(':') ? variant?.split(':') : [variant, null]
+    let [variantName, value] = variant?.includes(':') ? variant?.split(':') : [variant, null as string | null]
 
-    // @ts-expect-error
+    // @ts-ignore the not yet augmented/defined
     if (!!theme?.breakpoints[variantName]) {
       const [breakpoint, _variantName, _value] = variant?.split(':')?.length == 2 ? [...variant?.split(':'), null] : variant?.split(':')
 
       // @ts-expect-error
       mediaQuery = theme.media.down(breakpoint)
-      value = _value
-      variantName = _variantName
+      value = _value as string | null
+      variantName = _variantName as string
     }
 
     const variantStyle = this.commonVariants[variantName] ?? this.commonVariants[variant]
 
-    let style = null
+    let style: any = null
 
     if (typeof variantStyle == 'function') {
-      style = isSpacingKey(variantName) ? variantStyle(value) : variantStyle(theme, value)
+      style = isSpacingKey(variantName) ? variantStyle(value as any) : (variantStyle as any)(theme, value)
     } else {
       style = variantStyle
     }
@@ -73,7 +96,7 @@ export class CodeleapStyleRegistry {
     }
 
     const commonStyles = {
-      [component]: this.createStyle(style),
+      [component as string]: this.createStyle(style),
     }
 
     this.styleCache.cacheFor('common', cache.key, style)
@@ -81,15 +104,23 @@ export class CodeleapStyleRegistry {
     return commonStyles
   }
 
-  computeVariantStyle(componentName: string, variants: string[], _component = null): ICSS {
+  /**
+   * Resolves an array of variant strings for a component into a single merged `ICSS`.
+   * Checks component-level variant stylesheet first, then falls back to common variants.
+   * Context-aware factories (registered via `CONTEXT_FACTORY_SYMBOL`) are called with
+   * the current theme and the provided `context` object.
+   */
+  computeVariantStyle(componentName: string, variants: string[], _component: string | undefined = undefined, context?: ComponentContext): ICSS {
     const { rootElement } = this.getRegisteredComponent(componentName)
 
     const component = _component ?? rootElement
 
-    const stylesheet = minifier.decompress(this.stylesheets[componentName])
+    const stylesheet = minifier.decompress(this.stylesheets[componentName]) ?? {}
+
+    
     const aggregator = this.aggregators[componentName]
 
-    const cache = this.styleCache.keyFor('variants', { componentName, component, stylesheet, variants, aggregator })
+    const cache = this.styleCache.keyFor('variants', { componentName, component, stylesheet, variants, aggregator, context })
 
     if (!!cache.value) {
       return cache.value
@@ -98,6 +129,12 @@ export class CodeleapStyleRegistry {
     const theme = themeStore.theme
 
     const variantStyles = variants.map((variant) => {
+      const factory = context && theme && this.variantFactories?.[componentName]?.[variant]
+
+      if (factory) {
+        return factory(theme, context)
+      }
+      
       if (!!stylesheet[variant]) {
 
         return stylesheet[variant]
@@ -123,7 +160,7 @@ export class CodeleapStyleRegistry {
     let variantStyle = deepmerge({ all: true })(...variantStyles)
 
     if (!!aggregator) {
-      variantStyle = aggregator(theme, variantStyle)
+      variantStyle = aggregator(theme as ITheme, variantStyle)
     }
 
     this.styleCache.cacheFor('variants', cache.key, variantStyle)
@@ -131,8 +168,14 @@ export class CodeleapStyleRegistry {
     return variantStyle
   }
 
+  /**
+   * Determines whether a style object contains composition keys for a given component.
+   * A key is a composition key if it starts with one of the component's `elements` strings
+   * and is not in `ignoredStyleKeys`. Returns both a boolean flag and the extracted
+   * composition sub-record so callers can avoid a second pass.
+   */
   isCompositionStyle(component: AnyStyledComponent, style: any) {
-    const composition = {}
+    const composition: Record<string, any> = {}
 
     if (!style) {
       return {
@@ -143,9 +186,9 @@ export class CodeleapStyleRegistry {
 
     const styleKeys = Object.keys(style)
 
-    let elements = []
+    let elements: string[] = []
 
-    for (const element of component?.elements) {
+    for (const element of component?.elements ?? []) {
       const componentElements = styleKeys?.filter(k => k?.startsWith(element) && !ignoredStyleKeys?.includes(k))
 
       if (componentElements?.length >= 1) {
@@ -163,6 +206,12 @@ export class CodeleapStyleRegistry {
     }
   }
 
+  /**
+   * Checks whether a style object contains a `breakpoints` key, indicating it uses
+   * the responsive style API. Returns the key name alongside the boolean so the caller
+   * can use it to read and delete the breakpoints entry without a repeated `'breakpoints'`
+   * string literal.
+   */
   isResponsiveStyle(style: any) {
     const responsiveStyleKey = 'breakpoints'
 
@@ -214,7 +263,7 @@ export class CodeleapStyleRegistry {
     }
   }
 
-  getResponsiveStyle(componentName: string, responsiveStyleKey: string, style: object) {
+  getResponsiveStyle(componentName: string, responsiveStyleKey: string, style: Record<string, any>) {
     const responsiveStyles = style[responsiveStyleKey]
 
     if (!responsiveStyles) return {}
@@ -227,14 +276,14 @@ export class CodeleapStyleRegistry {
       return cache.value
     }
 
-    const styles = {}
+    const styles: Record<string, any> = {}
 
     for (const responsiveStyle in responsiveStyles) {
       const mediaQuery = this.getMediaQuery(responsiveStyle)
 
       const breakpointStyle = responsiveStyles[responsiveStyle]
 
-      const componentStyles = this.styleFor(componentName, breakpointStyle, false)
+      const componentStyles = this.styleFor(componentName, breakpointStyle, false) as Record<string, any>
 
       // @ts-ignore
       for (const composition in componentStyles) {
@@ -272,7 +321,7 @@ export class CodeleapStyleRegistry {
           component,
         )
 
-        styles = deepmerge({ all: true })(styles, computedVariantStyle[component])
+        styles = deepmerge({ all: true })(styles, (computedVariantStyle as any)[component])
       }
     } else if (typeof style === 'object') {
       styles = !!predicateObj ? predicateObj(style) : style
@@ -283,8 +332,7 @@ export class CodeleapStyleRegistry {
 
   private getMediaQuery(responsiveKey: string) {
     const [breakpoint, query] = responsiveKey?.includes(':') ? responsiveKey?.split(':') : [responsiveKey, 'down']
-
-    // @ts-expect-error - media not has type
+    // @ts-ignore
     const mediaQuery = themeStore.theme?.media?.[query]?.(breakpoint)
 
     return mediaQuery
@@ -345,8 +393,8 @@ export class CodeleapStyleRegistry {
     return styles
   }
 
-  styleFor<T = unknown>(componentName: string, componentStyle: StyleProp<T>, mergeWithDefaultStyle = true): T {
-    const cache = this.styleCache.keyFor('components', { componentName, componentStyle, stylesheet: this.stylesheets[componentName] })
+  styleFor<T = unknown>(componentName: string, componentStyle: StyleProp<T & string>, mergeWithDefaultStyle = true, context?: ComponentContext): T {
+    const cache = this.styleCache.keyFor('components', { componentName, componentStyle, stylesheet: this.stylesheets[componentName], context })
 
     if (!!cache.value) {
       return cache.value as T
@@ -364,7 +412,7 @@ export class CodeleapStyleRegistry {
     }
 
     if (typeof style === 'string') {
-      const computedVariantStyle = this.computeVariantStyle(componentName, [style])
+      const computedVariantStyle = this.computeVariantStyle(componentName, [style], undefined, context)
 
       return this.mergeStylesWithCache(
         [defaultStyle, computedVariantStyle],
@@ -418,7 +466,7 @@ export class CodeleapStyleRegistry {
         const isObj = typeof s === 'object'
 
         if (variants.length > 0 && (idx === filteredStyle.length - 1 || isObj)) {
-          const computedVariantStyle = this.computeVariantStyle(componentName, variants)
+          const computedVariantStyle = this.computeVariantStyle(componentName, variants, undefined, context)
 
           styles.push(computedVariantStyle)
 
@@ -461,10 +509,15 @@ export class CodeleapStyleRegistry {
     return {} as T
   }
 
+  /**
+   * Rebuilds `commonVariants` by merging (in ascending priority order):
+   * `defaultVariants` → `appVariants` → `dynamicVariants` → `spacingVariants` → `insetVariants`.
+   * Called once in the constructor; must be re-called (via `update`) if app variants change.
+   */
   registerCommonVariants() {
-    const spacingVariants = themeStore.theme?.['spacing']
+    const spacingVariants = themeStore.themeTyped?.spacing
 
-    const insetVariants = themeStore.theme?.['inset']
+    const insetVariants = themeStore.themeTyped?.inset
 
     const appVariants = themeStore.variants
 
@@ -476,18 +529,41 @@ export class CodeleapStyleRegistry {
       insetVariants,
     )
 
-    this.commonVariants = commonVariants
+    this.commonVariants = commonVariants as Record<string, ICSS | MultiplierFunction>
   }
 
+  /**
+   * Registers a component's variant stylesheet. No-ops if the component is already
+   * registered (variants are immutable after first registration). Extracts any
+   * `CONTEXT_FACTORY_SYMBOL`-tagged entries into `variantFactories` for context-aware
+   * resolution, then compresses and stores the remaining variants.
+   */
   registerVariants<Composition extends string = any>(componentName: string, variants: VariantStyleSheet, aggregator?: StyleAggregator<Composition>) {
     if (this.stylesheets[componentName]) {
-      throw new Error(`Variants for ${componentName} already registered`)
+      return
+    }
+
+    const factories: Record<string, (theme: ITheme, context: ComponentContext) => any> = {}
+    for (const [variantName, variant] of Object.entries(variants)) {
+      const factory = (variant as any)?.[CONTEXT_FACTORY_SYMBOL]
+      if (typeof factory === 'function') factories[variantName] = factory
+    }
+    if (Object.keys(factories).length > 0) {
+      this.variantFactories[componentName] = factories
+    }
+
+    if (aggregator) {
+      this.aggregators[componentName] = aggregator as StyleAggregator
     }
-    this.aggregators[componentName] = aggregator
 
     this.stylesheets[componentName] = minifier.compress(variants)
   }
 
+  /**
+   * Records the minimal component metadata (`styleRegistryName`, `elements`,
+   * `rootElement`) needed for composition and style resolution. Only the metadata
+   * is stored — the component function itself is not retained.
+   */
   registerComponent(component: AnyStyledComponent) {
     const componentData = {
       styleRegistryName: component?.styleRegistryName,
@@ -495,7 +571,7 @@ export class CodeleapStyleRegistry {
       rootElement: component?.rootElement,
     }
 
-    this.components[component.styleRegistryName] = componentData as any
+    this.components[component.styleRegistryName!] = componentData as any
   }
 
   /**
@@ -506,8 +582,13 @@ export class CodeleapStyleRegistry {
     throw new Error('createStyle: Not implemented')
   }
 
+  /**
+   * Must be called after the active color scheme changes so that the `StyleCache`
+   * base key is regenerated. Without this call, cached values from the previous
+   * scheme would be returned for the new scheme.
+   */
   update() {
-    const currentColorScheme = themeStore.theme?.['currentColorScheme']?.() ?? themeStore.colorScheme ?? 'default'
+    const currentColorScheme = themeStore.themeTyped?.currentColorScheme?.() ?? themeStore.colorScheme ?? 'default'
 
     this.styleCache.registerBaseKey([currentColorScheme, themeStore.theme, this.commonVariants])
   }
@@ -516,11 +597,11 @@ export class CodeleapStyleRegistry {
     return deepClone(style)
   }
 
-  createStyles<K extends string = string>(styles: Record<K, StyleProp<AnyRecord, ''>> | ((theme: ITheme) => Record<K, StyleProp<AnyRecord, ''>>)): Record<K, ICSS> {
+  createStyles<K extends string = string>(styles: Record<K, StyleProp<string, ''>> | ((theme: ITheme) => Record<K, StyleProp<string, ''>>)): Record<K, ICSS> {
     const compute = () => {
       const current = themeStore.theme
 
-      const stylesObj = typeof styles === 'function' ? styles(current) : styles
+      const stylesObj = typeof styles === 'function' ? styles(current as ITheme) : styles
 
       const cache = this.styleCache.keyFor('styles', stylesObj)
 
@@ -531,7 +612,7 @@ export class CodeleapStyleRegistry {
       const createdStyles = {} as Record<K, any>
 
       for (const key in stylesObj) {
-        const style = this.styleFor('MyComponent', stylesObj[key], false)
+        const style = this.styleFor('MyComponent', stylesObj[key], false) as any
 
         createdStyles[key] = style?.wrapper ?? style
       }
@@ -551,12 +632,12 @@ export class CodeleapStyleRegistry {
   prefixStyle(prefix: string, style: any) {
     const entries = Object.entries(style).map(e => {
       const [key, value] = e
-      
+
       const elementKey = capitalize(key)
-      
+
       return [`${prefix}${elementKey}`, value]
     })
-  
+
     return Object.fromEntries(entries)
   }
 }

package/src/classes/tests/StyleRegistry.spec.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, beforeEach } from 'bun:test'
+import { CodeleapStyleRegistry } from '../StyleRegistry'
+import { createStyles, createStylesWithContext, CONTEXT_FACTORY_SYMBOL } from '../../lib/createStyles'
+import { mockTheme, MockedTheme } from '../../tests/theme'
+import { themeStore } from '../../theme'
+import type { ICSS, ITheme } from '../../types'
+
+class MockStateStorage {
+  private storage = new Map<string, any>()
+
+  getItem(key: string): any {
+    return this.storage.get(key) || null
+  }
+
+  setItem(key: string, value: any): void {
+    this.storage.set(key, value)
+  }
+
+  removeItem(key: string): void {
+    this.storage.delete(key)
+  }
+}
+
+class TestStyleRegistry extends CodeleapStyleRegistry {
+  constructor() {
+    super(new MockStateStorage() as any)
+  }
+
+  createStyle(css: ICSS): ICSS {
+    return css
+  }
+}
+
+const TEST_COMPONENT = 'TestComponent'
+
+const testComponent = {
+  styleRegistryName: TEST_COMPONENT,
+  elements: ['wrapper', 'text'],
+  rootElement: 'wrapper',
+}
+
+describe('StyleRegistry — context threading', () => {
+  let registry: TestStyleRegistry
+  let currentTheme: MockedTheme
+
+  beforeEach(() => {
+    mockTheme()
+    currentTheme = themeStore.theme as unknown as MockedTheme
+    registry = new TestStyleRegistry()
+    registry.registerComponent(testComponent as any)
+  })
+
+  describe('registerVariants — factory extraction', () => {
+    it('stores factory for variants created with createStylesWithContext', () => {
+      const factory = (_theme: ITheme, context: { isActive: boolean }) => ({
+        wrapper: { opacity: context.isActive ? 1 : 0.5 },
+      })
+
+      const variants = {
+        active: createStylesWithContext(factory as any),
+      }
+
+      registry.registerVariants(TEST_COMPONENT, variants)
+
+      expect(registry.variantFactories[TEST_COMPONENT]?.active).toBe(factory as any)
+    })
+
+    it('does not store factory for plain createStyles variants', () => {
+      const variants = {
+        default: createStyles((_theme: ITheme) => ({
+          wrapper: { opacity: 1 },
+        })),
+      }
+
+      registry.registerVariants(TEST_COMPONENT, variants)
+
+      expect(registry.variantFactories[TEST_COMPONENT]).toBeUndefined()
+    })
+
+    it('stores only context-aware factories in mixed registrations', () => {
+      const factory = (_theme: ITheme, context: { isActive: boolean }) => ({
+        wrapper: { opacity: context.isActive ? 1 : 0.5 },
+      })
+
+      const variants = {
+        default: createStyles((_theme: ITheme) => ({ wrapper: { opacity: 1 } })),
+        active: createStylesWithContext(factory as any),
+      }
+
+      registry.registerVariants(TEST_COMPONENT, variants)
+
+      const factories = registry.variantFactories[TEST_COMPONENT]
+      expect(factories?.default).toBeUndefined()
+      expect(factories?.active).toBe(factory as any)
+    })
+  })
+
+  describe('computeVariantStyle — context path', () => {
+    beforeEach(() => {
+      const factory = (_theme: ITheme, context: { isActive: boolean }) => ({
+        wrapper: { opacity: context.isActive ? 1 : 0.5 },
+      })
+
+      const variants = {
+        default: createStyles((_theme: ITheme) => ({ wrapper: { color: 'black' } })),
+        active: createStylesWithContext(factory as any),
+      }
+
+      registry.registerVariants(TEST_COMPONENT, variants)
+    })
+
+    it('uses pre-computed stylesheet when no context is provided', () => {
+      const result = registry.computeVariantStyle(TEST_COMPONENT, ['default']) as any
+      expect(result?.['wrapper']?.['color']).toBe('black')
+    })
+
+    it('calls factory with context when context is provided', () => {
+      const result = registry.computeVariantStyle(TEST_COMPONENT, ['active'], undefined, { isActive: 1 }) as any
+      expect(result?.['wrapper']?.['opacity']).toBe(1)
+    })
+
+    it('produces different output for different context values', () => {
+      const active = registry.computeVariantStyle(TEST_COMPONENT, ['active'], undefined, { isActive: 1 }) as any
+      const inactive = registry.computeVariantStyle(TEST_COMPONENT, ['active'], undefined, { isActive: 0 }) as any
+
+      expect(active?.['wrapper']?.['opacity']).toBe(1)
+      expect(inactive?.['wrapper']?.['opacity']).toBe(0.5)
+    })
+
+    it('caches separately for different context values', () => {
+      const resultA = registry.computeVariantStyle(TEST_COMPONENT, ['active'], undefined, { isActive: 1 })
+      const resultB = registry.computeVariantStyle(TEST_COMPONENT, ['active'], undefined, { isActive: 0 })
+
+      expect(resultA).not.toEqual(resultB)
+    })
+  })
+
+  describe('styleFor — context threading', () => {
+    beforeEach(() => {
+      const factory = (_theme: ITheme, context: { isActive: boolean }) => ({
+        wrapper: { opacity: context.isActive ? 1 : 0.5 },
+      })
+
+      const variants = {
+        default: createStyles((_theme: ITheme) => ({ wrapper: { color: 'black' } })),
+        active: createStylesWithContext(factory as any),
+      }
+
+      registry.registerVariants(TEST_COMPONENT, variants)
+    })
+
+    it('threads context into computeVariantStyle when style is a string', () => {
+      const result = registry.styleFor(TEST_COMPONENT, 'active', true, { isActive: 1 }) as any
+      expect(result?.['wrapper']?.['opacity']).toBe(1)
+    })
+
+    it('threads context into computeVariantStyle when style is an array', () => {
+      const result = registry.styleFor(TEST_COMPONENT, ['active'], true, { isActive: 0 }) as any
+      expect(result?.['wrapper']?.['opacity']).toBe(0.5)
+    })
+
+    it('produces different results for different contexts via styleFor', () => {
+      const active = registry.styleFor(TEST_COMPONENT, 'active', true, { isActive: 1 }) as any
+      const inactive = registry.styleFor(TEST_COMPONENT, 'active', true, { isActive: 0 }) as any
+
+      expect(active?.['wrapper']?.['opacity']).not.toBe(inactive?.['wrapper']?.['opacity'])
+    })
+  })
+})

package/src/constants.ts

@@ -1,6 +1,20 @@
 // @ts-ignore
 const isBrowser = ():boolean => typeof document !== 'undefined'
 
+/**
+ * Package-wide feature flags and runtime constants. These are read once at module
+ * load time and are not reactive.
+ *
+ * - `STORES_PERSIST_VERSION` — bumping this value invalidates all persisted caches
+ *   on the next load (because it is included in every `hashKey` call via `registerBaseKey`).
+ * - `STORE_CACHE_ENABLED` — when `false`, the persistent `Cache` instances skip
+ *   loading from and writing to `StateStorage`.
+ * - `CACHE_ENABLED` — when `false`, `StyleCache.cacheFor` returns values without
+ *   writing to any cache bucket, effectively disabling all in-memory caching.
+ * - `IS_BROWSER` — sniffed at load time via `typeof document`; used as a fast guard
+ *   before any DOM access.
+ * - `LOG` — enables verbose `console.log` tracing inside `Cache` and `StylePersistor`.
+ */
 export const StyleConstants = {
   STORES_PERSIST_VERSION: 1,
   STORE_CACHE_ENABLED: true,

package/src/hooks/useCompositionStyles.ts

@@ -3,11 +3,13 @@ import { ICSS } from '../types'
 import { getNestedStylesByKey } from '../utils'
 
 /**
- * Hook that processes composition styles based on component styles.
- * 
- * @param {T | Array<T>} composition - Composition element(s)
- * @param {Partial<Record<C, ICSS>>} componentStyles - Component styles object
- * @returns {Partial<Record<T, ICSS>>} Mapped styles for each composition element
+ * Slices a flat component-style record into per-element sub-records, memoised to
+ * avoid unnecessary re-renders. For each element name in `composition`, it calls
+ * `getNestedStylesByKey(element, componentStyles)` to collect all keys that start
+ * with that element name. Accepts either a single element string or an array.
+ *
+ * Useful when a parent component receives a merged `componentStyles` object and
+ * needs to distribute the correct slice to each child element.
  */
 export function useCompositionStyles<T extends string, C extends string>(
   composition: (T | Array<T>),
@@ -18,7 +20,7 @@ export function useCompositionStyles<T extends string, C extends string>(
   }
 
   return useMemo(() => {
-    const compositionStyles = {}
+    const compositionStyles: Record<string, ICSS> = {}
 
     if (Array.isArray(composition)) {
       for (const element of composition) {
@@ -28,6 +30,6 @@ export function useCompositionStyles<T extends string, C extends string>(
       compositionStyles[composition as string] = getNestedStylesByKey(composition, styles)
     }
 
-    return compositionStyles
+    return compositionStyles as Partial<Record<T, ICSS>>
   }, [styles])
 }