@pyreon/rocketstyle 0.22.0 → 0.24.0

package/README.md

@@ -1,36 +1,22 @@
 # @pyreon/rocketstyle
 
-Multi-dimensional styling system for Pyreon.
+Multi-dimensional component styling — states, sizes, variants, themes, light/dark, all cached.
 
-Organize component styles by dimensions — states, sizes, variants — instead of flat props. Chain theme values, attach CSS via `@pyreon/styler`, and get full TypeScript inference. Built-in pseudo-state handling, light/dark mode, and provider/consumer patterns for parent-child state propagation.
+`@pyreon/rocketstyle` is the styling layer Pyreon's UI system builds on. Organize styles by named DIMENSIONS — `state` (`primary` / `danger` / `success`), `size` (`sm` / `md` / `lg`), `variant`, plus any custom dimension you declare — instead of flat boolean props. Each dimension is a chainable method (`.states({...})`, `.sizes({...})`); per-dimension values are themed via `.theme()` callbacks that receive `(theme, mode, css)`, with light/dark mode threaded through and pseudo-states (`hover` / `focus` / `pressed` / `active` / `disabled`) auto-detected. Built on `@pyreon/attrs` + `@pyreon/styler`. Per-definition WeakMap caches make per-mount cost near zero for same-definition components — verified 73% reduction in `styler.resolve` calls on real-app benchmarks.
 
-## Features
-
-- **Dimension-based theming** — define style variations as named dimensions (states, sizes, variants)
-- **Immutable chaining** — `.attrs()`, `.theme()`, `.states()`, `.sizes()`, `.styles()` and more
-- **Boolean shorthand** — `Button({ primary: true, lg: true })` instead of `Button({ state: 'primary', size: 'lg' })`
-- **Pseudo-state detection** — hover, focus, pressed tracked via signals and context
-- **Light/dark mode** — theme callbacks receive a mode parameter
-- **Provider/Consumer** — propagate parent state to children through context
-- **Multi-tier WeakMap caching** — dimension maps, reserved keys, omit Sets, and theme results cached per component definition (shared across all instances). Per-mount allocations near zero for same-definition components
-- **TypeScript inference** — dimension values and prop types inferred through the chain
-
-## Installation
+## Install
 
 ```bash
-bun add @pyreon/rocketstyle
+bun add @pyreon/rocketstyle @pyreon/core @pyreon/reactivity @pyreon/ui-core @pyreon/styler
 ```
 
-## Quick Start
+## Quick start
 
-```ts
+```tsx
 import rocketstyle from '@pyreon/rocketstyle'
 import { Element } from '@pyreon/elements'
 
-const Button = rocketstyle()({
-  name: 'Button',
-  component: Element,
-})
+const Button = rocketstyle()({ name: 'Button', component: Element })
   .attrs({ tag: 'button' })
   .theme({
     fontSize: 16,
@@ -39,238 +25,178 @@ const Button = rocketstyle()({
     borderRadius: 4,
     color: '#fff',
     backgroundColor: '#0d6efd',
-    hover: {
-      backgroundColor: '#0b5ed7',
-    },
+    hover: { backgroundColor: '#0b5ed7' },
   })
   .states({
-    primary: {
-      backgroundColor: '#0d6efd',
-      hover: { backgroundColor: '#0b5ed7' },
-    },
-    danger: {
-      backgroundColor: '#dc3545',
-      hover: { backgroundColor: '#bb2d3b' },
-    },
-    success: {
-      backgroundColor: '#198754',
-      hover: { backgroundColor: '#157347' },
-    },
+    primary: { backgroundColor: '#0d6efd', hover: { backgroundColor: '#0b5ed7' } },
+    danger:  { backgroundColor: '#dc3545', hover: { backgroundColor: '#bb2d3b' } },
+    success: { backgroundColor: '#198754', hover: { backgroundColor: '#157347' } },
   })
   .sizes({
     sm: { fontSize: 14, paddingX: 12, paddingY: 6 },
     md: { fontSize: 16, paddingX: 16, paddingY: 8 },
     lg: { fontSize: 18, paddingX: 20, paddingY: 10 },
   })
-```
 
-```ts
-// Named props
-Button({ state: 'danger', size: 'lg', label: 'Delete' })
-
-// Boolean shorthand (when useBooleans is enabled)
-Button({ danger: true, lg: true, label: 'Delete' })
+<Button state="danger" size="lg">Delete</Button>
 ```
 
-## Core Concepts
+## Core concepts
 
 ### Dimensions
 
-A dimension is a named axis of style variation. The factory ships with four defaults:
+A dimension is a named axis of style variation. Defaults ship four:
 
-| Dimension  | Prop name | Multi | Example                        |
-| ---------- | --------- | ----- | ------------------------------ |
-| `states`   | `state`   | no    | `primary`, `danger`, `success` |
-| `sizes`    | `size`    | no    | `sm`, `md`, `lg`               |
-| `variants` | `variant` | no    | `outlined`, `filled`           |
-| `multiple` | —         | yes   | `rounded`, `shadow`            |
+| Dimension  | Prop name | Multi? | Example                        |
+| ---------- | --------- | ------ | ------------------------------ |
+| `states`   | `state`   | no     | `primary`, `danger`, `success` |
+| `sizes`    | `size`    | no     | `sm`, `md`, `lg`               |
+| `variants` | `variant` | no     | `outlined`, `filled`           |
+| `multiple` | —         | yes    | `rounded`, `shadow`            |
 
-Each dimension creates a chain method (`.states()`, `.sizes()`, etc.) and a corresponding prop on the component.
+Each declared dimension creates a chain method AND a corresponding prop on the component. Multi-dimensions accept multiple active values at once.
 
-**Multi dimensions** allow multiple values at once: `Button({ rounded: true, shadow: true })`.
+### Default: `useBooleans: false` (string prop values)
 
-### Theme Object
+```tsx
+<Button state="primary" size="lg">Save</Button>
+```
 
-The `.theme()` method defines base CSS property values. Values are processed by `@pyreon/unistyle` — numbers convert to rem, shorthand properties expand automatically.
+Boolean shorthand (`<Button primary lg>Save</Button>`) is opt-in via `rocketstyle({ useBooleans: true })`. **Important**: before April 2026 the type default was `true` but the runtime was `false` — boolean props typechecked but were silently dropped at runtime. Fixed in `rocketstyle/init.ts`; new code should not rely on the historical behaviour.
 
-Pseudo-state keys nest directly in the theme object:
+### Theme + pseudo-states
 
 ```ts
 .theme({
   color: '#333',
   fontSize: 16,
-  hover: { color: '#000' },
-  focus: { outline: '2px solid blue' },
-  active: { transform: 'scale(0.98)' },
+  hover:    { color: '#000' },
+  focus:    { outline: '2px solid blue' },
+  active:   { transform: 'scale(0.98)' },
+  disabled: { opacity: 0.5 },
 })
 ```
 
-### Styles Function
+Pseudo-state keys nest directly. Bases (`@pyreon/elements`) generate `:hover` / `:focus-visible` / `:active` / `:disabled` CSS from the nested objects. `:hover` is unconditional — applied to EVERY component with hover theme; only `cursor: pointer` is gated on `onClick` / `href`.
 
-The `.styles()` method defines the CSS template that receives the computed theme:
+### Styles callback
 
 ```ts
 .styles((css) => css`
+  cursor: pointer;
+  border: none;
+  transition: all 0.2s;
+
   ${({ $rocketstyle, $rocketstate }) => {
-    // $rocketstyle — computed theme values (base + active dimension values merged)
+    // $rocketstyle — computed theme (base + active dimension values merged)
     // $rocketstate — { hover, focus, pressed, active, disabled, pseudo }
-    return css`...`
+    return /* css string */
   }}
 `)
 ```
 
+`$rocketstyle` is identity-cached — same dimension-prop combo produces the same object identity, which lets the styler's `classCache` skip resolve work entirely on cache hits.
+
 ## API
 
-### rocketstyle(options?)
+### `rocketstyle(options?)({ name, component })`
 
 Factory initializer. Returns a function that accepts component configuration.
 
 ```ts
 const factory = rocketstyle({
-  dimensions: {
-    /* custom dimensions */
-  },
+  dimensions: { /* custom dimensions */ },
   useBooleans: true,
 })
 
-const Component = factory({
-  name: 'ComponentName',
-  component: BaseComponent,
-})
+const Button = factory({ name: 'Button', component: Element })
 ```
 
-### .attrs(props | callback, options?)
-
-Same API as `@pyreon/attrs`. Define default props with optional priority and filter.
+### `.attrs(props | callback, options?)`
 
-```ts
-Button.attrs({ tag: 'button', role: 'button' })
-Button.attrs((props) => ({ 'aria-label': props.label }))
-```
+Same as `@pyreon/attrs` — accumulate defaults, supports callback / priority / filter.
 
-### .theme(values | callback)
+### `.theme(values | callback)`
 
-Base theme values applied to every instance.
+Base theme applied to every instance.
 
 ```ts
-// Object form
-Button.theme({
-  fontSize: 16,
-  color: '#fff',
-  hover: { opacity: 0.9 },
-})
-
-// Callback form — receives the theme context and mode
-Button.theme((theme, mode, css) => ({
+.theme({ fontSize: 16, color: '#fff', hover: { opacity: 0.9 } })
+.theme((theme, mode, css) => ({
   fontSize: 16,
   color: mode === 'dark' ? '#fff' : '#333',
 }))
 ```
 
-### .states() / .sizes() / .variants() / .multiple()
+### `.states()` / `.sizes()` / `.variants()` / `.multiple()`
 
-Define values for each dimension. Each key becomes a selectable option.
+Define per-dimension values.
 
 ```ts
-Button.states({
-  primary: { backgroundColor: '#0d6efd' },
-  danger: { backgroundColor: '#dc3545' },
-})
-
-Button.sizes({
-  sm: { fontSize: 14, paddingX: 8 },
-  lg: { fontSize: 18, paddingX: 20 },
-})
+.states({ primary: { backgroundColor: '#0d6efd' }, danger: { backgroundColor: '#dc3545' } })
+.sizes({ sm: { fontSize: 14, paddingX: 8 }, lg: { fontSize: 18, paddingX: 20 } })
+.multiple({ rounded: { borderRadius: 999 }, shadow: { boxShadow: '0 2px 8px rgba(0,0,0,0.15)' } })
 
-// Multi dimension — multiple can be active at once
-Button.multiple({
-  rounded: { borderRadius: 999 },
-  shadow: { boxShadow: '0 2px 8px rgba(0,0,0,0.15)' },
-})
-```
-
-Dimension methods also accept callbacks:
-
-```ts
-Button.states((theme, mode, css) => ({
+// Callback form — receives (theme, mode, css)
+.states((theme) => ({
   primary: { backgroundColor: theme.colors?.primary ?? '#0d6efd' },
 }))
 ```
 
-### .styles(callback)
+### `.styles(callback)`
 
-Define the CSS template using `@pyreon/styler`'s `css` tagged template.
+CSS template using `@pyreon/styler`'s `css` tagged template.
 
-```ts
-Button.styles(
-  (css) => css`
-    cursor: pointer;
-    border: none;
-    transition: all 0.2s;
-
-    ${({ $rocketstyle }) => makeItResponsive({ theme: $rocketstyle, styles, css })}
-  `,
-)
-```
-
-### .config(options)
-
-Reconfigure the component.
+### `.config(options)`
 
 ```ts
 Button.config({
-  name: 'PrimaryButton',    // change displayName
-  component: NewBase,        // swap base component
-  provider: true,            // make this component a context provider
-  consumer: (ctx) => ...,   // consume parent component context
-  inversed: true,            // invert theme mode
-  DEBUG: true,               // enable debug logging
+  name: 'PrimaryButton',
+  component: NewBase,         // swap base — resets prop chains
+  provider: true,             // make this a context provider for children
+  consumer: (ctx) => …,       // consume parent component context
+  inversed: true,             // invert theme mode for subtree
+  DEBUG: true,
 })
 ```
 
-### .compose(hocs) / .statics(metadata)
-
-Same API as `@pyreon/attrs`:
-
-```ts
-Button.compose({ withTracking: trackingHoc })
-Button.statics({ category: 'action' })
+### `.compose(hocs)` / `.statics(metadata)`
 
-Button.meta.category // => 'action'
-```
+Same API as `@pyreon/attrs`.
 
-### isRocketComponent(value)
+### `isRocketComponent(value)` / `resolveTheme(value)`
 
-Runtime type guard.
+Runtime guard and theme accessor for use inside styled-component interpolations:
 
 ```ts
-import { isRocketComponent } from '@pyreon/rocketstyle'
+import { isRocketComponent, resolveTheme } from '@pyreon/rocketstyle'
+
+isRocketComponent(Button) // true
 
-isRocketComponent(Button) // => true
+styled(Component)`
+  color: ${(props) => resolveTheme(props.$rocketstyle).color};
+`
 ```
 
-## Custom Dimensions
+`resolveTheme` handles both function-accessor (reactive) and plain-object `$rocketstyle` shapes.
 
-Define your own dimensions by passing them to the factory:
+## Custom dimensions
 
 ```ts
 const rocketButton = rocketstyle({
   dimensions: {
-    intent: 'intent', // prop: intent="primary"
-    size: 'size', // prop: size="lg"
-    appearance: {
-      propName: 'appearance',
-      multi: true, // allows multiple values
-    },
+    intent: 'intent',                                  // prop: intent="primary"
+    size:   'size',
+    appearance: { propName: 'appearance', multi: true },
   },
 })
 ```
 
-This creates `.intent()`, `.size()`, and `.appearance()` chain methods.
+Creates `.intent()`, `.size()`, `.appearance()` chain methods.
 
-## Transform Dimensions
+### Transform dimensions
 
-Mark a dimension as `transform: true` to make its values receive the accumulated theme from all prior dimensions. This is ideal for modifiers like `outlined` that derive styles from the active state:
+Mark `transform: true` to make a dimension receive the accumulated theme from all prior dimensions — ideal for modifiers like `outlined` that derive from the active state.
 
 ```ts
 const rocketButton = rocketstyle({
@@ -282,51 +208,44 @@ const rocketButton = rocketstyle({
 
 const Button = rocketButton({ name: 'Button', component: Element })
   .theme({ backgroundColor: '#0d6efd', color: '#fff' })
-  .states({
-    danger: { backgroundColor: '#dc3545', color: '#fff' },
-  })
+  .states({ danger: { backgroundColor: '#dc3545', color: '#fff' } })
   .modifiers({
     outlined: (theme) => ({
-      color: theme.backgroundColor,
+      color: theme.backgroundColor,        // receives merged theme from prior dimensions
       backgroundColor: 'transparent',
     }),
   })
 
-// outlined receives { backgroundColor: '#dc3545', color: '#fff' } from the danger state
-Button({ state: 'danger', modifier: 'outlined' })
+<Button state="danger" modifier="outlined" />  // outlined sees danger's red, becomes red-on-transparent
 ```
 
-## Provider / Consumer
-
-Propagate parent component state to children through Pyreon's context system.
+## Provider / Consumer — parent-child state propagation
 
 ```ts
 // Parent provides its state
 const ButtonGroup = Button.config({ provider: true })
 
 // Child consumes parent state
-const ButtonIcon = rocketstyle()({
-  name: 'ButtonIcon',
-  component: Element,
-})
+const ButtonIcon = rocketstyle()({ name: 'ButtonIcon', component: Element })
   .config({
-    consumer: (ctx) =>
-      ctx(({ pseudo }) => ({
-        state: pseudo.hover ? 'active' : 'default',
-      })),
+    consumer: (ctx) => ctx(({ pseudo }) => ({
+      state: pseudo.hover ? 'active' : 'default',
+    })),
   })
   .states({
     default: { color: '#666' },
-    active: { color: '#fff' },
+    active:  { color: '#fff' },
   })
 
-// Icon reacts to parent's hover state
-ButtonGroup({ state: 'primary', children: [ButtonIcon({}), 'Label'] })
+<ButtonGroup state="primary">
+  <ButtonIcon />
+  Label
+</ButtonGroup>
 ```
 
-## Light / Dark Mode
+## Light / dark mode
 
-Theme callbacks receive a `mode` parameter:
+Theme + dimension callbacks receive `(theme, mode, css)`. `mode === 'light' | 'dark'`. Use `inversed: true` on `.config()` to flip the mode for a subtree.
 
 ```ts
 Button.theme((theme, mode) => ({
@@ -335,32 +254,31 @@ Button.theme((theme, mode) => ({
 }))
 ```
 
-Use `inversed: true` in `.config()` to flip the mode for a component subtree.
-
 ## Performance
 
-Rocketstyle uses a multi-tier caching architecture to minimize per-mount allocations:
+Per-definition WeakMap caches keep per-mount cost flat as instance count grows:
+
+- **`_dimensionsCache`** — `getDimensionsMap` result keyed on dimension-themes identity
+- **`_reservedKeysCache`** — `Object.keys(reservedPropNames)` keyed on keywords identity
+- **`_omitSetCache`** — pre-built `Set<string>` for `omit()` (avoids per-mount Set allocation)
+- **`LocalThemeManager`** — WeakMap tiers for baseTheme, dimensionThemes, and per-mode resolved themes
+- **`_rsMemo`** — dimension-prop memo keyed by `mode|dimensionPropTuple|pseudoState`, LRU-bounded at 32 entries per theme. Hit returns identity-stable `{ rocketstyle, rocketstate }` so the downstream styler `classCache` skips resolve entirely. Real-app E2 benchmark: 200 Buttons × 5 runs, baseline dropped from 8.80ms to 4.80ms (-45%); per-Button `styler.resolve` from 22 to 6 (-73%).
 
-- **Per-definition caches** (shared across all instances via `WeakMap`):
-  - `_dimensionsCache` — `getDimensionsMap` result keyed on dimension-themes identity
-  - `_reservedKeysCache` — `Object.keys(reservedPropNames)` keyed on keywords identity
-  - `_omitSetCache` — pre-built `Set<string>` for `omit()` (avoids per-mount Set construction)
-  - `ALL_PSEUDO_KEYS` / `STATIC_OMIT_KEYS` — merged key arrays computed once
-- **Theme cache** (`LocalThemeManager`): `WeakMap` tiers for baseTheme, dimensionThemes, and per-mode resolved themes
-- **getTheme in-place merge**: dimension slices merged directly onto `finalTheme` instead of allocating a new target per `merge()` call
-- **Frozen `EMPTY_PSEUDO`**: shared frozen `{}` for pseudo-state defaults instead of 6 allocations per call
-- **Dev guard**: uses `__DEV__` (`import.meta.env.DEV`) — tree-shaken to zero bytes in production
+Real apps MUST mount one shared `<PyreonUI>` provider for the memo to span instances — each provider mount creates a fresh `enrichedTheme` via `computed()`, which produces a different WeakMap key.
 
 For a 150-component page with 8 dimensions each: ~1,350 Set allocations, ~300 array spreads, and ~150 map rebuilds eliminated vs naive implementation.
 
-## Peer Dependencies
+## Gotchas
+
+- **`.config({ component: NewBase })` resets `attrs` / `priorityAttrs` / `filterAttrs` / `compose` chains** — they were tailored to the previous component's prop shape. `theme` / `styles` / dimension chains are preserved. Re-chain shared attrs explicitly if you swap the base.
+- **`useBooleans: false` is the default** (since April 2026 alignment fix). String props are the idiomatic surface.
+- **Cache keys are downstream of normalization.** Under `useBooleans: true`, the memo correctly keys by the resolved dimension (not the raw boolean prop) — otherwise every boolean variant would collide on the first cached entry.
+- **Dimension props don't accept function accessors directly.** `state={() => signal()}` is wrong — write `state={signal()}` and let the compiler emit reactive `_rp()` wrapping. Caught by the Reactivity Lens.
+- **`provider: true` + `consumer:` on the same component** is a legal but rare shape. Most apps separate the two for clarity.
+
+## Documentation
 
-| Package            | Version |
-| ------------------ | ------- |
-| @pyreon/core       | \*      |
-| @pyreon/reactivity | \*      |
-| @pyreon/ui-core    | \*      |
-| @pyreon/styler     | \*      |
+Full docs: [docs.pyreon.dev/docs/rocketstyle](https://docs.pyreon.dev/docs/rocketstyle) (or `docs/docs/rocketstyle.md` in this repo).
 
 ## License
 

package/lib/index.js

@@ -543,7 +543,7 @@ const rocketComponent = (options) => {
 	];
 	const _omitSetCache = /* @__PURE__ */ new WeakMap();
 	const _rsMemo = /* @__PURE__ */ new WeakMap();
-	const RS_MEMO_CAP = 32;
+	const RS_MEMO_CAP = 128;
 	const hocsFuncs = [rocketStyleHOC(options), ...calculateHocsFuncs(options.compose)];
 	const EnhancedComponent = (props) => {
 		const localCtx = useLocalContext(options.consumer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/rocketstyle",
-  "version": "0.22.0",
+  "version": "0.24.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.9",
-    "@pyreon/typescript": "^0.22.0",
-    "@pyreon/ui-core": "^0.22.0",
+    "@pyreon/test-utils": "^0.13.11",
+    "@pyreon/typescript": "^0.24.0",
+    "@pyreon/ui-core": "^0.24.0",
     "@vitest/browser-playwright": "^4.1.4",
-    "@vitus-labs/tools-rolldown": "^2.3.0"
+    "@vitus-labs/tools-rolldown": "^2.4.0"
   },
   "engines": {
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.22.0",
-    "@pyreon/reactivity": "^0.22.0",
-    "@pyreon/styler": "^0.22.0",
-    "@pyreon/ui-core": "^0.22.0"
+    "@pyreon/core": "^0.24.0",
+    "@pyreon/reactivity": "^0.24.0",
+    "@pyreon/styler": "^0.24.0",
+    "@pyreon/ui-core": "^0.24.0"
   }
 }

package/src/__tests__/memo-cap.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Regression: `_rsMemo` LRU cap was 32, which thrashed on real-world
+ * high-cardinality workloads (data tables with state derived from row
+ * data, design systems with many tokens × axes, dashboards rendering many
+ * small interactive components). The rs-precompute spike (closed PR #761,
+ * branch `spike/rocketstyle-precompute`) bisect-verified that a 60-unique-
+ * tuple Button mount loop had 45% cache-miss rate at cap=32 (888 out of
+ * 2000 lookups were cold resolves) and 46% wall-clock regression vs the
+ * cap-fits-workload case.
+ *
+ * Fix: raise `RS_MEMO_CAP` from 32 to 128. Memory cost ~12KB per
+ * definition per theme (128 × ~100 bytes) — negligible vs the wall-clock
+ * win.
+ *
+ * This test locks the cap behavior via the counter contract: with N=64
+ * unique state variants (above the OLD cap of 32, below the NEW cap of
+ * 128), a two-pass cold-then-warm render loop must have ZERO cold
+ * resolves on the warm pass. Pre-fix (cap=32): the warm pass would
+ * re-cold-resolve any tuples the first pass had evicted (the oldest 32
+ * of the 64). Post-fix (cap=128): all 64 fit, second pass is fully
+ * cached.
+ *
+ * Bisect verification (run manually before merging):
+ *   1. Revert `RS_MEMO_CAP` to 32 in rocketstyle.ts
+ *   2. Run this test — both warm-pass assertions fail with "expected N to be 0"
+ *   3. Restore cap to 128
+ *   4. Run test — both pass
+ */
+
+import { initTestConfig, withThemeContext } from '@pyreon/test-utils'
+import rocketstyle from '../init'
+
+let cleanup: () => void
+beforeAll(() => {
+  cleanup = initTestConfig()
+})
+afterAll(() => cleanup())
+
+// Lightweight counter sink — rocketstyle emits via `globalThis.__pyreon_count__`
+// without an import dep on @pyreon/perf-harness. We install our own sink to
+// observe the cold-resolve count.
+interface CounterGlobal {
+  __pyreon_count__?: ((name: string) => void) | undefined
+}
+function installCounter(): { snapshot: () => Record<string, number>; reset: () => void; uninstall: () => void } {
+  const counts: Record<string, number> = {}
+  const prev = (globalThis as CounterGlobal).__pyreon_count__
+  ;(globalThis as CounterGlobal).__pyreon_count__ = (name: string) => {
+    counts[name] = (counts[name] ?? 0) + 1
+  }
+  return {
+    snapshot: () => ({ ...counts }),
+    reset: () => {
+      for (const k of Object.keys(counts)) delete counts[k]
+    },
+    uninstall: () => {
+      ;(globalThis as CounterGlobal).__pyreon_count__ = prev
+    },
+  }
+}
+
+// Capture the rocketstyle theme accessor's resolved value so a render
+// actually invokes `_resolveRsEntry` (the function that emits the
+// `rocketstyle.getTheme` counter on cache miss and
+// `rocketstyle.dimensionMemo.hit` on cache hit).
+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'
+
+// Build N state variants in a single rocketstyle component. Each render
+// with a different `state` prop produces a different memo key.
+function makeHighCardinalityComponent(N: number): any {
+  const states: Record<string, { color: string }> = {}
+  for (let i = 0; i < N; i++) {
+    states[`s${i}`] = { color: `rgb(${i % 256}, 0, 0)` }
+  }
+  return rocketstyle()({
+    name: `HighCard${N}`,
+    component: ThemeCapture,
+  }).states(() => states)
+}
+
+describe('rocketstyle — _rsMemo LRU cap (regression PR #762)', () => {
+  it('warm pass over 64 unique tuples has ZERO cold resolves (cap >= 64)', () => {
+    const N = 64
+    const Comp: any = makeHighCardinalityComponent(N)
+    const counter = installCounter()
+
+    try {
+      // Cold pass — fills the memo with N entries.
+      for (let i = 0; i < N; i++) {
+        withThemeContext(() => Comp({ state: `s${i}` }))
+      }
+      const afterCold = counter.snapshot()
+      const coldGetTheme = afterCold['rocketstyle.getTheme'] ?? 0
+      // Sanity: cold pass must have ~N resolves (one per unique state).
+      expect(coldGetTheme).toBeGreaterThanOrEqual(N)
+
+      // Warm pass — same N tuples, in same order. With cap >= N, every
+      // lookup hits cache. Pre-fix (cap=32, N=64): the cold pass filled
+      // the memo and evicted the oldest 32 entries (entries 0..31),
+      // leaving entries 32..63 cached. The warm pass would re-cold-
+      // resolve entries 0..31 → 32 cold resolves. Post-fix (cap=128):
+      // 0 cold resolves on the warm pass.
+      counter.reset()
+      for (let i = 0; i < N; i++) {
+        withThemeContext(() => Comp({ state: `s${i}` }))
+      }
+      const afterWarm = counter.snapshot()
+      const warmColdGetTheme = afterWarm['rocketstyle.getTheme'] ?? 0
+      expect(warmColdGetTheme).toBe(0)
+    } finally {
+      counter.uninstall()
+    }
+  })
+
+  it('warm pass over 100 unique tuples has ZERO cold resolves (cap = 128)', () => {
+    // Second probe at the cap's effective boundary: 100 tuples is comfortably
+    // within the cap=128 limit. If the cap were anything less than 100,
+    // this would fail. The 64-vs-100 split lets a future bump (e.g. to 256)
+    // be detected at the boundary without rewriting tests.
+    const N = 100
+    const Comp: any = makeHighCardinalityComponent(N)
+    const counter = installCounter()
+
+    try {
+      for (let i = 0; i < N; i++) {
+        withThemeContext(() => Comp({ state: `s${i}` }))
+      }
+      const afterCold = counter.snapshot()
+      expect(afterCold['rocketstyle.getTheme'] ?? 0).toBeGreaterThanOrEqual(N)
+
+      counter.reset()
+      for (let i = 0; i < N; i++) {
+        withThemeContext(() => Comp({ state: `s${i}` }))
+      }
+      const afterWarm = counter.snapshot()
+      expect(afterWarm['rocketstyle.getTheme'] ?? 0).toBe(0)
+    } finally {
+      counter.uninstall()
+    }
+  })
+
+  it('cap still bounds growth — workload of 200 tuples DOES evict (cap < 200)', () => {
+    // Control: at workload > cap, the LRU SHOULD evict. This guards against
+    // an accidental "remove the cap entirely" change that would let the
+    // memo grow unbounded.
+    const N = 200
+    const Comp: any = makeHighCardinalityComponent(N)
+    const counter = installCounter()
+
+    try {
+      for (let i = 0; i < N; i++) {
+        withThemeContext(() => Comp({ state: `s${i}` }))
+      }
+      counter.reset()
+      // Re-render in same order: with cap=128, the cold pass kept entries
+      // 72..199 (last 128 of the 200), so the warm pass will re-resolve
+      // entries 0..71 → 72 cold resolves. Some non-zero number must
+      // appear; the exact value depends on insertion order.
+      for (let i = 0; i < N; i++) {
+        withThemeContext(() => Comp({ state: `s${i}` }))
+      }
+      const afterWarm = counter.snapshot()
+      expect(afterWarm['rocketstyle.getTheme'] ?? 0).toBeGreaterThan(0)
+    } finally {
+      counter.uninstall()
+    }
+  })
+})

package/src/rocketstyle.ts

@@ -156,11 +156,23 @@ const rocketComponent: RocketComponent = (options) => {
   // mean the styler's classCache hits earlier and the resolves don't run.
   //
   // LRU bound prevents unbounded growth from prop-tuple churn (e.g. a
-  // table where every cell has a unique state). 32 entries per theme
-  // covers ~99% of unique combos in real apps.
+  // table where every cell has a unique state). 128 entries per theme
+  // covers the E2 perf-dashboard reference workload AND high-cardinality
+  // surfaces (data tables, design systems with many tokens crossed with
+  // size/variant axes, dashboards rendering many small interactive
+  // components). The previous cap of 32 was sized for the reference
+  // workload only and thrashed at higher cardinalities — measured 45%
+  // cache-miss rate (888/2000 lookups) on a 60-unique-tuple Button
+  // mount loop, 46% wall-clock regression vs the cap-fits-workload
+  // case. The rs-precompute spike (closed PR #761, results live on
+  // `spike/rocketstyle-precompute`) bisect-verified that raising the cap
+  // 32 → 128 zeroes the cold-resolves counter for that 60-tuple
+  // workload at zero implementation cost. Memory: ~12KB per definition
+  // per theme at 128 entries × ~100 bytes per entry — negligible vs
+  // the 46% runtime win.
   type RsMemoEntry = { readonly rocketstyle: object; readonly rocketstate: object }
   const _rsMemo = new WeakMap<object, Map<string, RsMemoEntry>>()
-  const RS_MEMO_CAP = 32
+  const RS_MEMO_CAP = 128
 
   // --------------------------------------------------------
   // COMPOSE - high-order components