@pyreon/styler 0.18.0 → 0.20.0

package/lib/index.d.ts

@@ -1,4 +1,3 @@
-import * as _$_pyreon_core0 from "@pyreon/core";
 import { ComponentFn, VNode, VNodeChild } from "@pyreon/core";
 
 //#region src/ThemeProvider.d.ts
@@ -16,7 +15,7 @@ type Theme = DefaultTheme & Record<string, unknown>;
  * - String-equality memoization (same CSS class = no DOM update)
  * - Untracked resolve (no exponential cascade)
  */
-declare const ThemeContext: _$_pyreon_core0.ReactiveContext<Theme>;
+declare const ThemeContext: import("@pyreon/core").ReactiveContext<Theme>;
 /**
  * Read the current theme. Returns the theme value (calls the accessor).
  * Inside a reactive scope (computed/effect), this tracks theme changes.
@@ -155,6 +154,8 @@ interface StyleSheetOptions {
 declare class StyleSheet {
   private cache;
   private insertCache;
+  private icKeysByClass;
+  private domRules;
   private sheet;
   private ssrBuffer;
   private isSSR;
@@ -167,6 +168,19 @@ declare class StyleSheet {
   private extractClassName;
   /** Parse existing rules from SSR-rendered <style> tag into cache. */
   private hydrateFromTag;
+  /** Record that `icKey` resolves to `cacheKey` (for lockstep eviction). */
+  private trackIcKey;
+  /** Record a top-level CSSRule this `cacheKey` inserted into the sheet. */
+  private trackDomRule;
+  /**
+   * Evict the given cache keys across ALL three storage layers:
+   * the `cache` Map, the cssText-keyed `insertCache` Map, and the live
+   * DOM rules. Without the latter two, `maxCacheSize` bounded only the
+   * smallest of the three — `insertCache` keys (full CSS text) and the
+   * `<style>` tag's `cssRules` grew unbounded for the app's lifetime,
+   * which is the actual memory leak this method exists to prevent.
+   */
+  private evictKeys;
   /** Evict oldest entries when cache exceeds max size. */
   private evictIfNeeded;
   /**
@@ -201,6 +215,33 @@ declare class StyleSheet {
   insertGlobal(cssText: string): void;
   /** Returns collected CSS for SSR as a complete `<style>` tag string. */
   getStyleTag(): string;
+  /**
+   * Returns the collected SSR rules as a raw array (one entry per
+   * top-level rule, already `@layer`-wrapped + class-prefixed exactly as
+   * `insert()` produced them). Used by the compile-time rocketstyle
+   * collapse resolver: it renders a component under SSR, reads the rules
+   * here, and the build emits an idempotent `injectRules()` call so the
+   * collapsed `_tpl()` site is self-sufficient (no prior runtime mount
+   * needed to populate the sheet). A copy — callers must not mutate the
+   * internal buffer.
+   */
+  getStyleRules(): readonly string[];
+  private injectedBundles;
+  /**
+   * Inject pre-resolved CSS rule text (from `getStyleRules()` captured at
+   * build time by the rocketstyle-collapse resolver) directly into the
+   * live sheet. Unlike `insert()` this does NOT re-hash — the class names
+   * are already baked into `rules` and into the collapsed `_tpl()` HTML;
+   * re-hashing would produce a different class and break the contract.
+   * Idempotent by `key` (the resolver's FNV hash of the bundle).
+   */
+  injectRules(rules: readonly string[], key: string): void;
+  /**
+   * Test-only: live `cssRules.length` (0 in SSR). Mirrors runtime-dom's
+   * `_tplCacheSize()` test-only-accessor convention; lets injectRules /
+   * eviction tests assert without reaching into the private sheet.
+   */
+  ruleCountForTest(): number;
   /** Returns collected CSS rules as a raw string (useful for streaming SSR). */
   getStyles(): string;
   /** Check if any buffered SSR rules use @layer wrapping. */

package/lib/index.js

@@ -9,6 +9,8 @@ const _countSink$2 = globalThis;
 * deferred until a styled component renders (or until explicitly resolved).
 */
 var CSSResult = class {
+	strings;
+	values;
 	constructor(strings, values) {
 		this.strings = strings;
 		this.values = values;
@@ -434,6 +436,8 @@ const DEFAULT_MAX_CACHE_SIZE = 1e4;
 var StyleSheet = class {
 	cache = /* @__PURE__ */ new Map();
 	insertCache = /* @__PURE__ */ new Map();
+	icKeysByClass = /* @__PURE__ */ new Map();
+	domRules = /* @__PURE__ */ new Map();
 	sheet = null;
 	ssrBuffer = [];
 	isSSR;
@@ -447,6 +451,7 @@ var StyleSheet = class {
 		if (!this.isSSR) this.mount();
 	}
 	mount() {
+		if (this.isSSR) return;
 		const existing = document.querySelector(`style[${ATTR}]`);
 		if (existing) {
 			this.sheet = existing.sheet ?? null;
@@ -487,16 +492,67 @@ var StyleSheet = class {
 			}
 		}
 	}
+	/** Record that `icKey` resolves to `cacheKey` (for lockstep eviction). */
+	trackIcKey(cacheKey, icKey) {
+		let s = this.icKeysByClass.get(cacheKey);
+		if (!s) {
+			s = /* @__PURE__ */ new Set();
+			this.icKeysByClass.set(cacheKey, s);
+		}
+		s.add(icKey);
+	}
+	/** Record a top-level CSSRule this `cacheKey` inserted into the sheet. */
+	trackDomRule(cacheKey, ref) {
+		if (!ref) return;
+		let a = this.domRules.get(cacheKey);
+		if (!a) {
+			a = [];
+			this.domRules.set(cacheKey, a);
+		}
+		a.push(ref);
+	}
+	/**
+	* Evict the given cache keys across ALL three storage layers:
+	* the `cache` Map, the cssText-keyed `insertCache` Map, and the live
+	* DOM rules. Without the latter two, `maxCacheSize` bounded only the
+	* smallest of the three — `insertCache` keys (full CSS text) and the
+	* `<style>` tag's `cssRules` grew unbounded for the app's lifetime,
+	* which is the actual memory leak this method exists to prevent.
+	*/
+	evictKeys(keys) {
+		const ruleRefs = /* @__PURE__ */ new Set();
+		for (const key of keys) {
+			this.cache.delete(key);
+			const ics = this.icKeysByClass.get(key);
+			if (ics) {
+				for (const ic of ics) this.insertCache.delete(ic);
+				this.icKeysByClass.delete(key);
+			}
+			const refs = this.domRules.get(key);
+			if (refs) {
+				for (const r of refs) ruleRefs.add(r);
+				this.domRules.delete(key);
+			}
+		}
+		if (this.sheet && ruleRefs.size > 0) for (let i = this.sheet.cssRules.length - 1; i >= 0; i--) {
+			const r = this.sheet.cssRules[i];
+			if (r && ruleRefs.has(r)) try {
+				this.sheet.deleteRule(i);
+			} catch {}
+		}
+	}
 	/** Evict oldest entries when cache exceeds max size. */
 	evictIfNeeded() {
 		if (this.cache.size <= this.maxCacheSize) return;
 		const toDelete = Math.floor(this.maxCacheSize * .1);
+		const evicted = [];
 		let count = 0;
 		for (const key of this.cache.keys()) {
 			if (count >= toDelete) break;
-			this.cache.delete(key);
+			evicted.push(key);
 			count++;
 		}
+		this.evictKeys(evicted);
 	}
 	/**
 	* Extract nested at-rules (@media, @supports, @container) from CSS text
@@ -577,6 +633,7 @@ var StyleSheet = class {
 		const className = `${PREFIX}-${hash(cssText)}`;
 		if (this.cache.has(className)) {
 			this.insertCache.set(icKey, className);
+			this.trackIcKey(className, icKey);
 			return className;
 		}
 		this.evictIfNeeded();
@@ -590,11 +647,13 @@ var StyleSheet = class {
 		const finalRules = layerName ? rules.map((r) => `@layer ${layerName}{${r}}`) : rules;
 		if (this.isSSR) for (const rule of finalRules) this.ssrBuffer.push(rule);
 		else if (this.sheet) for (const rule of finalRules) try {
-			this.sheet.insertRule(rule, this.sheet.cssRules.length);
+			const at = this.sheet.insertRule(rule, this.sheet.cssRules.length);
+			this.trackDomRule(className, this.sheet.cssRules[at]);
 		} catch (_e) {
 			if (__DEV__) console.warn("[styler] Failed to insert CSS rule:", rule, _e);
 		}
 		this.insertCache.set(icKey, className);
+		this.trackIcKey(className, icKey);
 		return className;
 	}
 	/** Insert a @keyframes rule. Deduplicates by animation name. */
@@ -605,7 +664,8 @@ var StyleSheet = class {
 		const rule = `@keyframes ${name}{${body}}`;
 		if (this.isSSR) this.ssrBuffer.push(rule);
 		else if (this.sheet) try {
-			this.sheet.insertRule(rule, this.sheet.cssRules.length);
+			const at = this.sheet.insertRule(rule, this.sheet.cssRules.length);
+			this.trackDomRule(name, this.sheet.cssRules[at]);
 		} catch (_e) {
 			if (__DEV__) console.warn("[styler] Failed to insert @keyframes rule:", rule, _e);
 		}
@@ -642,7 +702,8 @@ var StyleSheet = class {
 		else if (this.sheet) {
 			const rules = this.splitRules(cssText);
 			for (const rule of rules) try {
-				this.sheet.insertRule(rule, this.sheet.cssRules.length);
+				const at = this.sheet.insertRule(rule, this.sheet.cssRules.length);
+				this.trackDomRule(key, this.sheet.cssRules[at]);
 			} catch (_e) {
 				if (__DEV__) console.warn("[styler] Failed to insert global CSS rule:", rule, _e);
 			}
@@ -653,6 +714,50 @@ var StyleSheet = class {
 		if (this.ssrBuffer.length === 0) return `<style ${ATTR}=""></style>`;
 		return `<style ${ATTR}="">${((this.hasLayeredRules() ? "@layer elements, rocketstyle;" : this.layer ? `@layer ${this.layer};` : "") + this.ssrBuffer.join("")).replace(/<\/style/gi, "<\\/style")}</style>`;
 	}
+	/**
+	* Returns the collected SSR rules as a raw array (one entry per
+	* top-level rule, already `@layer`-wrapped + class-prefixed exactly as
+	* `insert()` produced them). Used by the compile-time rocketstyle
+	* collapse resolver: it renders a component under SSR, reads the rules
+	* here, and the build emits an idempotent `injectRules()` call so the
+	* collapsed `_tpl()` site is self-sufficient (no prior runtime mount
+	* needed to populate the sheet). A copy — callers must not mutate the
+	* internal buffer.
+	*/
+	getStyleRules() {
+		return this.ssrBuffer.slice();
+	}
+	injectedBundles = /* @__PURE__ */ new Set();
+	/**
+	* Inject pre-resolved CSS rule text (from `getStyleRules()` captured at
+	* build time by the rocketstyle-collapse resolver) directly into the
+	* live sheet. Unlike `insert()` this does NOT re-hash — the class names
+	* are already baked into `rules` and into the collapsed `_tpl()` HTML;
+	* re-hashing would produce a different class and break the contract.
+	* Idempotent by `key` (the resolver's FNV hash of the bundle).
+	*/
+	injectRules(rules, key) {
+		if (this.injectedBundles.has(key)) return;
+		this.injectedBundles.add(key);
+		if (this.isSSR) {
+			for (const rule of rules) this.ssrBuffer.push(rule);
+			return;
+		}
+		if (!this.sheet) return;
+		for (const rule of rules) try {
+			this.sheet.insertRule(rule, this.sheet.cssRules.length);
+		} catch (_e) {
+			if (__DEV__) console.warn("[styler] injectRules: failed to insert collapsed rule:", rule, _e);
+		}
+	}
+	/**
+	* Test-only: live `cssRules.length` (0 in SSR). Mirrors runtime-dom's
+	* `_tplCacheSize()` test-only-accessor convention; lets injectRules /
+	* eviction tests assert without reaching into the private sheet.
+	*/
+	ruleCountForTest() {
+		return this.sheet?.cssRules.length ?? 0;
+	}
 	/** Returns collected CSS rules as a raw string (useful for streaming SSR). */
 	getStyles() {
 		if (this.ssrBuffer.length === 0) return "";
@@ -667,11 +772,15 @@ var StyleSheet = class {
 		this.ssrBuffer = [];
 		this.cache.clear();
 		this.insertCache.clear();
+		this.icKeysByClass.clear();
+		this.domRules.clear();
 	}
 	/** Clear the dedup cache. Useful for HMR / dev-time reloads. */
 	clearCache() {
 		this.cache.clear();
 		this.insertCache.clear();
+		this.icKeysByClass.clear();
+		this.domRules.clear();
 		clearNormCache();
 	}
 	/**
@@ -687,6 +796,8 @@ var StyleSheet = class {
 	clearAll() {
 		this.cache.clear();
 		this.insertCache.clear();
+		this.icKeysByClass.clear();
+		this.domRules.clear();
 		clearNormCache();
 		this.ssrBuffer = [];
 		if (this.sheet) while (this.sheet.cssRules.length > 0) this.sheet.deleteRule(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/styler",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Lightweight CSS-in-JS engine for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,8 +42,9 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/test-utils": "^0.13.5",
-    "@pyreon/typescript": "^0.18.0",
+    "@pyreon/manifest": "0.13.1",
+    "@pyreon/test-utils": "^0.13.7",
+    "@pyreon/typescript": "^0.20.0",
     "@vitest/browser-playwright": "^4.1.4",
     "@vitus-labs/tools-rolldown": "^2.3.0"
   },
@@ -51,7 +52,7 @@
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.18.0",
-    "@pyreon/reactivity": "^0.18.0"
+    "@pyreon/core": "^0.20.0",
+    "@pyreon/reactivity": "^0.20.0"
   }
 }

package/src/__tests__/inject-rules.browser.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+import { createSheet } from '../sheet'
+
+// Layer 1 of the P0 rocketstyle-collapse slice: the styler injects
+// pre-resolved rule text (captured at build time by the collapse
+// resolver) into the LIVE sheet, idempotently, WITHOUT re-hashing — the
+// class names are already baked into the rules AND into the collapsed
+// _tpl() HTML, so a re-hash would break the contract.
+
+describe('StyleSheet.injectRules (real browser)', () => {
+  it('inserts pre-resolved rules into the live sheet verbatim (no re-hash)', () => {
+    const s = createSheet()
+    const before = s.ruleCountForTest()
+    s.injectRules(['.pyr-abc123{color:rgb(1,2,3)}'], 'k1')
+    expect(s.ruleCountForTest()).toBe(before + 1)
+    // Class name is preserved exactly — proves no re-hash happened.
+    const probe = document.createElement('div')
+    probe.className = 'pyr-abc123'
+    document.body.appendChild(probe)
+    expect(getComputedStyle(probe).color).toBe('rgb(1, 2, 3)')
+    probe.remove()
+  })
+
+  it('is idempotent by key — re-injecting the same bundle adds nothing', () => {
+    const s = createSheet()
+    s.injectRules(['.pyr-dup{color:red}', '.pyr-dup2{color:blue}'], 'dup')
+    const afterFirst = s.ruleCountForTest()
+    s.injectRules(['.pyr-dup{color:red}', '.pyr-dup2{color:blue}'], 'dup')
+    s.injectRules(['.pyr-dup{color:red}', '.pyr-dup2{color:blue}'], 'dup')
+    expect(s.ruleCountForTest()).toBe(afterFirst)
+  })
+
+  it('distinct keys inject independently', () => {
+    const s = createSheet()
+    const before = s.ruleCountForTest()
+    s.injectRules(['.pyr-x{margin:1px}'], 'kx')
+    s.injectRules(['.pyr-y{margin:2px}'], 'ky')
+    expect(s.ruleCountForTest()).toBe(before + 2)
+  })
+})

package/src/__tests__/memory-growth.test.ts

@@ -76,6 +76,74 @@ describe('memory growth', () => {
     })
   })
 
+  // Regression: `evictIfNeeded()` historically trimmed ONLY `this.cache`.
+  // `insertCache` (keyed by full CSS text — the large keys) and the live
+  // `<style>` tag's `cssRules` were never evicted, so `maxCacheSize`
+  // bounded the smallest of the three layers while the two memory-heavy
+  // ones grew for the process lifetime. These tests inspect the two
+  // previously-unbounded layers directly. Bisect-verified.
+  describe('lockstep eviction bounds insertCache + DOM cssRules', () => {
+    beforeEach(() => {
+      document.querySelectorAll('style[data-pyreon-styler]').forEach((el) => {
+        el.remove()
+      })
+    })
+
+    it('insertCache stays bounded under N >> maxCacheSize unique inserts', () => {
+      const maxSize = 50
+      const s = createSheet({ maxCacheSize: maxSize })
+      const N = maxSize * 6
+
+      for (let i = 0; i < N; i++) s.insert(`prop-${i}: value-${i};`)
+
+      const ic = (s as unknown as { insertCache: Map<string, string> }).insertCache
+      // Pre-fix: ic.size === N (insertCache never evicted). Post-fix it
+      // tracks `cache`, which trims oldest 10% on each overflow.
+      expect(s.cacheSize).toBeLessThanOrEqual(maxSize * 1.5)
+      expect(ic.size).toBeLessThanOrEqual(maxSize * 1.5)
+      expect(ic.size).toBeLessThan(N)
+    })
+
+    it('live DOM cssRules count does not grow unbounded', () => {
+      const maxSize = 30
+      const s = createSheet({ maxCacheSize: maxSize })
+
+      for (let i = 0; i < maxSize; i++) s.insert(`a-${i}: ${i};`)
+      const el = document.querySelector('style[data-pyreon-styler]') as HTMLStyleElement
+      expect(el?.sheet).toBeTruthy()
+
+      for (let i = 0; i < maxSize * 5; i++) s.insert(`b-${i}: ${i};`)
+
+      const after = el.sheet!.cssRules.length
+      // Pre-fix: `after` ≈ maxSize*6 (+@layer decl) — every unique insert
+      // appended a rule, none ever deleted. Post-fix: eviction calls
+      // deleteRule in lockstep, so the live rule count stays within
+      // ~1.5× maxSize no matter how many uniques flowed through.
+      expect(after).toBeLessThanOrEqual(maxSize * 1.5 + 2)
+    })
+
+    it('dedup still works after eviction cycles', () => {
+      const maxSize = 20
+      const s = createSheet({ maxCacheSize: maxSize })
+
+      const recent: string[] = []
+      for (let i = 0; i < 5; i++) recent.push(s.insert(`keep-${i}: v;`))
+      // Overflow to force eviction of older entries (not `recent`).
+      for (let i = 0; i < maxSize * 3; i++) s.insert(`churn-${i}: v;`)
+      // Recent entries: re-inserting yields the SAME deterministic
+      // className and exactly one live DOM rule each.
+      for (let i = 0; i < 5; i++) expect(s.insert(`keep-${i}: v;`)).toBe(recent[i])
+
+      const el = document.querySelector('style[data-pyreon-styler]') as HTMLStyleElement
+      let keepRules = 0
+      for (let i = 0; i < el.sheet!.cssRules.length; i++) {
+        const r = el.sheet!.cssRules[i]
+        if (r && r.cssText.includes('keep-0')) keepRules++
+      }
+      expect(keepRules).toBe(1)
+    })
+  })
+
   describe('SSR mode memory', () => {
     let originalDocument: typeof document
 

package/src/__tests__/static-styler-resolve-cost.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Measurement gate: per-mount cost of a fully-static `styled()` component.
+ *
+ * BACKGROUND. "Proposed compiler win #2 — static styler extraction" theorised
+ * that a fully-static styled component (`styled('div')`\`color: red\``, no
+ * function interpolations) wastes a per-mount `styler.resolve`, and that a
+ * bounded runtime memo slice could be carved out of the (multi-week,
+ * roadmap-scale) compile-time extraction effort. This gate MEASURES that
+ * premise with the real `styler.resolve` / `styler.staticVNode.hit` /
+ * `styler.sheet.insert*` perf counters and DISPROVES it for the runtime
+ * layer: the static path is already optimal.
+ *
+ * WHAT THE COUNTERS PROVE (the contrast IS the proof — self-discriminating,
+ * no fake fix to revert; same shape as the static-text baking gate):
+ *
+ *   Fully-static `styled('div')`\`color: red\`` (values.length === 0):
+ *     - `createStyledComponent` takes `raw = strings[0]` — `resolve()` is
+ *       NEVER called → `styler.resolve` === 0 for the lifetime.
+ *     - `sheet.insert` fires EXACTLY ONCE at component-creation time
+ *       (definition, not mount) → `styler.sheet.insert` === 1.
+ *     - Every mount with no extra props returns the pre-built
+ *       `cachedEmptyVNode` → `styler.staticVNode.hit` === N, with ZERO
+ *       additional resolve / sheet work per mount.
+ *
+ *   Contrast — function-interpolated `styled('div')`\`color: ${p => p.c}\``
+ *   with NO `$rocketstyle` / `$element` identity (the only shape that DOES
+ *   re-resolve per call): `styler.resolve` === N. This is CORRECT, not waste
+ *   — the CSS genuinely depends on per-call props; and real-app shapes
+ *   (rocketstyle dimensions, Element `$element` interning) already hit
+ *   `classCache` / `elClassCache` so they collapse to ~0 (proven elsewhere:
+ *   PR #344 dimension memo, the `$element` interning gate). So #2's runtime
+ *   layer needs no fix; the remaining #2 surface is purely compile-time /
+ *   bundle (don't ship the styled wrapper + sheet.insert for provably-static
+ *   CSS at all) — that is the roadmap item, deliberately NOT half-built here.
+ *
+ * Bisect note: there is intentionally no fix to revert. The discriminating
+ * assertion is `static.resolve === 0 && dynamic.resolve === N` in the SAME
+ * run — if the static path ever regressed to per-mount resolve, the static
+ * block's `toBe(0)` fails while the dynamic block still passes, pinpointing
+ * the regression to the static fast path specifically.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { sheet } from '../sheet'
+import { styled } from '../styled'
+
+type Sink = { __pyreon_count__?: (name: string, n?: number) => void }
+const g = globalThis as Sink
+
+let counts: Map<string, number>
+
+const get = (name: string): number => counts.get(name) ?? 0
+
+beforeEach(() => {
+  counts = new Map()
+  g.__pyreon_count__ = (name: string, n = 1) => {
+    counts.set(name, (counts.get(name) ?? 0) + n)
+  }
+})
+
+afterEach(() => {
+  delete g.__pyreon_count__
+  // clearAll (not reset) — fires onSheetClear so styled.tsx's
+  // staticComponentCache / _hotCache reset between cases; otherwise the
+  // single-entry hot cache leaks a prior case's component.
+  sheet.clearAll()
+})
+
+const N = 100
+
+describe('static styled() per-mount cost (measurement gate)', () => {
+  it('a fully-static component resolves ZERO times and inserts ONCE, regardless of mount count', () => {
+    // Distinct source-location template literal → its own
+    // TemplateStringsArray identity (independent of every other case).
+    const Comp = styled('div')`
+      color: red;
+      padding: 4px;
+    `
+
+    // The sheet.insert at *definition* time already happened above. Snapshot
+    // AFTER definition so the per-mount measurement is isolated from the
+    // one-time creation cost.
+    const insertsAtDefinition = get('styler.sheet.insert')
+    expect(insertsAtDefinition).toBe(1) // exactly one — at creation, not mount
+    expect(get('styler.resolve')).toBe(0) // values.length===0 → raw=strings[0], no resolve()
+
+    for (let i = 0; i < N; i++) Comp({})
+
+    // THE PROOF: N mounts added ZERO resolves and ZERO new sheet inserts.
+    expect(get('styler.resolve')).toBe(0)
+    expect(get('styler.sheet.insert')).toBe(1) // still just the creation insert
+    expect(get('styler.sheet.insert.hit')).toBe(0) // never re-inserted
+    // Every mount took the pre-built cachedEmptyVNode fast path.
+    expect(get('styler.staticVNode.hit')).toBe(N)
+  })
+
+  it('two distinct static components: 2 inserts total, 0 resolves, N/2 hits each', () => {
+    const A = styled('div')`
+      color: blue;
+    `
+    const B = styled('span')`
+      color: green;
+    `
+    expect(get('styler.sheet.insert')).toBe(2) // one per definition
+    expect(get('styler.resolve')).toBe(0)
+
+    for (let i = 0; i < N / 2; i++) {
+      A({})
+      B({})
+    }
+
+    expect(get('styler.resolve')).toBe(0)
+    expect(get('styler.sheet.insert')).toBe(2)
+    expect(get('styler.staticVNode.hit')).toBe(N) // N/2 + N/2
+  })
+
+  it('CONTRAST — a function-interpolated styled with no rocketstyle/$element identity DOES resolve per call (correct, not waste)', () => {
+    const Dyn = styled('div')<{ c: string }>`
+      color: ${(p) => p.c};
+    `
+    // No object $rocketstyle / $rocketstate / $element on rawProps → neither
+    // classCache nor elClassCache can fire; doResolve() runs every call.
+    // Same prop value each call → cssText identical → sheet dedups (hit).
+    for (let i = 0; i < N; i++) Dyn({ c: 'red' })
+
+    expect(get('styler.resolve')).toBe(N) // genuinely per-call (CSS depends on props)
+    expect(get('styler.staticVNode.hit')).toBe(0) // never the static fast path
+    // `styler.sheet.insert` counts every insert() CALL (one per mount here);
+    // `.hit` is the dedup subset — identical cssText each call, so all but
+    // the first hit the insertCache and inject NO new DOM rule. The dynamic
+    // path still pays the resolve() + the insert() call-overhead per mount;
+    // only the actual rule injection is deduped. That call-overhead is the
+    // residual the rocketstyle/$element identity caches (classCache /
+    // elClassCache) eliminate in real-app shapes — proven elsewhere.
+    expect(get('styler.sheet.insert')).toBe(N) // one insert() call per mount
+    expect(get('styler.sheet.insert.hit')).toBe(N - 1) // first builds cache, rest dedup
+  })
+
+  it('SELF-DISCRIMINATING — static.resolve===0 AND dynamic.resolve===N in one run', () => {
+    const Static = styled('div')`
+      margin: 8px;
+    `
+    counts = new Map() // isolate from the definition insert
+    for (let i = 0; i < N; i++) Static({})
+    const staticResolve = get('styler.resolve')
+
+    const Dyn = styled('div')<{ c: string }>`
+      color: ${(p) => p.c};
+    `
+    counts = new Map()
+    for (let i = 0; i < N; i++) Dyn({ c: 'blue' })
+    const dynResolve = get('styler.resolve')
+
+    // The discriminator: if the static fast path ever regressed to
+    // per-mount resolve, this is the assertion that pinpoints it — the
+    // static side moves off 0 while the dynamic side stays at N.
+    expect(staticResolve).toBe(0)
+    expect(dynResolve).toBe(N)
+    expect(dynResolve - staticResolve).toBe(N)
+  })
+})

package/src/manifest.ts

@@ -0,0 +1,332 @@
+import { defineManifest } from '@pyreon/manifest'
+
+export default defineManifest({
+  name: '@pyreon/styler',
+  title: 'CSS-in-JS',
+  tagline:
+    'CSS-in-JS — styled() / css / keyframes / createGlobalStyle, reactive theming, FNV-1a-deduped StyleSheet (SSR-safe)',
+  description:
+    "Pyreon's CSS-in-JS engine. `styled('div')` is a tagged template that returns a `ComponentFn` injecting a generated class; `css` is a tagged template returning a LAZY `CSSResult` resolved on use (not a string); `keyframes` returns the generated animation-name string. Tagged-template interpolations receive the component's `props` (and the theme) so styles can be signal-driven — function interpolations flip the component onto the dynamic resolve path (`isDynamic`). A singleton `StyleSheet` with FNV-1a hashing dedupes and supports SSR; `createSheet()` makes an isolated instance. Theme is delivered through a REACTIVE context — `useTheme()` snapshots at call time, `useThemeAccessor()` returns the raw `() => Theme` accessor for tracking inside effects so whole-theme swaps re-resolve without remounting.",
+  category: 'browser',
+  features: [
+    "styled('div')`...` / styled(Component)`...` / styled.div`...` (Proxy) — component factory with `as` polymorphism + $-transient props",
+    'css`...` — lazy CSSResult, resolved on use (NOT a string)',
+    'keyframes`...` — returns the generated @keyframes animation-name string',
+    'createGlobalStyle`...` — returns a ComponentFn that injects global CSS when mounted',
+    'useCSS(template, props?, boost?) — resolve a CSSResult to a class name inside a component',
+    'Reactive theming — useTheme() snapshot vs useThemeAccessor() accessor; ThemeProvider merges nested',
+    'Singleton StyleSheet (FNV-1a dedup, SSR) + createSheet() for isolated instances',
+    'buildProps / filterProps — $-transient + shouldForwardProp DOM prop forwarding (descriptor-preserving)',
+  ],
+  api: [
+    {
+      name: 'styled',
+      kind: 'function',
+      signature:
+        'styled: ((tag: Tag, options?: StyledOptions) => TagTemplateFn) & { div: TagTemplateFn; span: TagTemplateFn; /* …all HTML tags via Proxy */ }',
+      summary:
+        "Component factory. `styled('div')`, `styled(MyComp)`, and `styled.div` (Proxy sugar) are all tagged templates returning a `ComponentFn` that injects a generated class. Tagged-template interpolations are called with the live `props` object (theme included), so a function interpolation reading `p.theme.color` / signal-driven values works and puts the component on the dynamic resolve path. Supports the polymorphic `as` prop and `$`-prefixed TRANSIENT props (consumed by styles, NOT forwarded to the DOM). Per-definition caching keys generated classes so repeat mounts skip re-resolution.",
+      example: `import { styled } from "@pyreon/styler"
+
+const Button = styled("button")\`
+  background: \${(p) => p.theme.colors.primary};
+  padding: \${(p) => (p.$compact ? "4px" : "12px")};
+\`
+// <Button $compact onClick={...}>Go</Button>  — $compact not forwarded to <button>`,
+      mistakes: [
+        "Expecting `$`-prefixed props to reach the DOM — they are transient by design (consumed by the template, stripped before forwarding). Use a non-`$` name if the attribute must land on the element",
+        'Destructuring `props` in the interpolation (`${({ theme }) => …}`) and being surprised it does not update on a whole-theme swap — read `props.theme` lazily; the theme context is reactive and the styled resolver re-runs on swap',
+        'Passing a resolved value where a function interpolation is needed for reactivity — `${signal()}` snapshots once at definition; use `${() => signal()}` (or `${(p) => p.x}`) to stay on the dynamic path',
+        'Using `styled.div` and expecting a different identity per call — the Proxy returns the same tag template fn shape; per-definition caches key on the template, not the call site',
+      ],
+      seeAlso: ['css', 'useCSS', 'useTheme'],
+    },
+    {
+      name: 'css',
+      kind: 'function',
+      signature:
+        'css(strings: TemplateStringsArray, ...values: Interpolation[]): CSSResult',
+      summary:
+        'Tagged-template that returns a LAZY `CSSResult` — it is NOT a class name or a CSS string until resolved by `styled()`, `useCSS()`, or composition into another template. Compose reusable fragments with it (assign a `css` result to `const base`, then interpolate `base` inside a `styled` template). Resolution is deferred so it can read the props/theme of the consuming component at use time.',
+      example: `import { css, useCSS } from "@pyreon/styler"
+
+const card = css\`border: 1px solid #ddd; padding: 16px;\`
+function Card(props) {
+  const cls = useCSS(card)
+  return <div class={cls}>{props.children}</div>
+}`,
+      mistakes: [
+        'Treating the `css` tagged-template return value as a string / class name — it is a lazy `CSSResult`; interpolating it into text (e.g. `class={card}`) renders `[object Object]`. Resolve via `useCSS` or embed in a `styled` template',
+        'Reading props/theme at `css` call time — the template is resolved later; put dynamic bits in function interpolations so they read the LIVE props at use',
+      ],
+      seeAlso: ['styled', 'useCSS', 'keyframes'],
+    },
+    {
+      name: 'keyframes',
+      kind: 'function',
+      signature:
+        'keyframes(strings: TemplateStringsArray, ...values: Interpolation[]): KeyframesResult',
+      summary:
+        'Tagged-template returning a `KeyframesResult` whose string form is the GENERATED, content-hashed `@keyframes` animation NAME. Reference it inside a `css` / `styled` template as the `animation-name` value; the `@keyframes` rule is injected (deduped via FNV-1a) on first use.',
+      example: `import { keyframes, styled } from "@pyreon/styler"
+
+const spin = keyframes\`from { transform: rotate(0) } to { transform: rotate(360deg) }\`
+const Spinner = styled("div")\`animation: \${spin} 1s linear infinite;\``,
+      mistakes: [
+        'Expecting a CSS class — `keyframes` yields an animation-NAME token, used as the `animation` / `animation-name` value, not a class applied to an element',
+        'Defining `keyframes` inside the render body per mount — define once at module scope so the hashed rule is injected once and reused',
+      ],
+      seeAlso: ['css', 'styled'],
+    },
+    {
+      name: 'createGlobalStyle',
+      kind: 'function',
+      signature:
+        'createGlobalStyle(strings: TemplateStringsArray, ...values: Interpolation[]): ComponentFn',
+      summary:
+        'Returns a `ComponentFn` that injects GLOBAL CSS (resets, `:root` tokens, body styles) when MOUNTED — it is not a side-effecting call. Render the returned component once near the app root; unmounting removes the global rule. Function interpolations make the global block dynamic (re-resolves on prop/theme change).',
+      example: `import { createGlobalStyle } from "@pyreon/styler"
+
+const GlobalReset = createGlobalStyle\`
+  *, *::before, *::after { box-sizing: border-box }
+  body { margin: 0; font-family: \${(p) => p.theme.fonts.body}; }
+\`
+// render <GlobalReset /> once at the app root`,
+      mistakes: [
+        'Calling `createGlobalStyle` (the tagged template) and expecting the CSS to inject — nothing happens until the returned component is RENDERED. Mount `<GlobalReset />` once near the root',
+        'Mounting it in many components — duplicates the global rule lifetime management; mount exactly once',
+      ],
+      seeAlso: ['styled', 'css'],
+    },
+    {
+      name: 'useCSS',
+      kind: 'hook',
+      signature:
+        'useCSS(template: CSSResult, props?: Record<string, any>, boost?: boolean): string',
+      summary:
+        'Resolves a `CSSResult` (from the `css` tagged template) to an injected class-name string inside a component. Pass `props` so function interpolations in the template read live values; `boost` opts into a faster cache path for hot, stable templates. The returned class is deduped/hashed by the active `StyleSheet`.',
+      example: `import { css, useCSS } from "@pyreon/styler"
+
+const box = css\`color: \${(p) => p.danger ? "red" : "inherit"};\`
+function Box(props) {
+  return <div class={useCSS(box, props)}>{props.children}</div>
+}`,
+      mistakes: [
+        'Forgetting to pass `props` when the template has function interpolations — they then resolve against an empty object and the dynamic values are lost',
+        'Calling `useCSS` outside a component setup — it depends on the active sheet/theme context like any hook',
+      ],
+      seeAlso: ['css', 'styled'],
+    },
+    {
+      name: 'useTheme',
+      kind: 'hook',
+      signature: 'useTheme<T extends object = Theme>(): T',
+      summary:
+        'Returns the current theme as a SNAPSHOT at call time. `ThemeContext` is a REACTIVE context — `useTheme()` reads it once, so the returned object is static unless the read happens inside a reactive scope. For values that must track whole-theme swaps inside an `effect` / `computed`, use `useThemeAccessor()` instead.',
+      example: `import { useTheme } from "@pyreon/styler"
+
+function Badge() {
+  const t = useTheme()
+  return <span style={{ color: t.colors.primary }}>{/* … */}</span>
+}`,
+      mistakes: [
+        'Destructuring `const { colors } = useTheme()` and expecting it to update on a user-preference theme swap — the snapshot is captured once. Use `useThemeAccessor()` and read inside the reactive scope, or rely on `styled` templates (their resolver tracks the theme)',
+        'Calling `useTheme()` at module scope — it must run during component setup where the context is available',
+      ],
+      seeAlso: ['useThemeAccessor', 'ThemeProvider', 'styled'],
+    },
+    {
+      name: 'useThemeAccessor',
+      kind: 'hook',
+      signature: 'useThemeAccessor<T extends object = Theme>(): () => T',
+      summary:
+        'Returns the raw `() => T` theme accessor (not a snapshot). Call it inside an `effect` / `computed` / JSX thunk so the read TRACKS the reactive theme context — whole-theme swaps (user-preference themes) then re-run the consumer without a remount. This is the escape hatch `styled()` itself uses internally.',
+      example: `import { useThemeAccessor } from "@pyreon/styler"
+import { effect } from "@pyreon/reactivity"
+
+const theme = useThemeAccessor()
+effect(() => applyChartPalette(theme().colors)) // re-runs on theme swap`,
+      mistakes: [
+        'Calling the accessor once at setup and caching the result — that defeats the point; call it INSIDE the reactive scope every time so the dependency is tracked',
+        'Reaching for this when a `styled` template would do — the template resolver already tracks the theme; use the accessor only for imperative/non-CSS theme reads',
+      ],
+      seeAlso: ['useTheme', 'ThemeProvider'],
+    },
+    {
+      name: 'ThemeProvider',
+      kind: 'component',
+      signature:
+        'ThemeProvider(props: { theme: Theme | ((parent: Theme) => Theme); children?: VNodeChild }): VNodeChild',
+      summary:
+        'Provides a theme to the reactive `ThemeContext`. Nested providers compose — a function `theme` receives the parent theme so subtrees can extend rather than replace. Because the context is reactive, swapping the `theme` prop re-resolves every `styled` / `useCSS` consumer below without remounting the tree. Marked `nativeCompat` so it works inside `@pyreon/{react,preact,vue,solid}-compat` apps.',
+      example: `import { ThemeProvider } from "@pyreon/styler"
+
+<ThemeProvider theme={{ colors: { primary: "#06f" } }}>
+  <App />
+</ThemeProvider>`,
+      mistakes: [
+        'Replacing the whole theme in a nested provider when you meant to extend — pass `theme={(parent) => ({ ...parent, colors: { ...parent.colors, accent: "#0a0" } })}`',
+        'Expecting most apps to mount this directly — `<PyreonUI>` wraps it; use `ThemeProvider` standalone only outside the `@pyreon/ui-core` provider',
+      ],
+      seeAlso: ['useTheme', 'useThemeAccessor', 'ThemeContext'],
+    },
+    {
+      name: 'ThemeContext',
+      kind: 'constant',
+      signature: 'ThemeContext: ReactiveContext<Theme>',
+      summary:
+        'The reactive context backing the theme. Created via `createReactiveContext<Theme>` — `useContext(ThemeContext)` returns a `() => Theme` accessor (which is what `useTheme()` / `useThemeAccessor()` wrap). Exposed for advanced consumers building their own theme-aware primitives; prefer the hooks for app code.',
+      example: `import { ThemeContext } from "@pyreon/styler"
+import { useContext } from "@pyreon/core"
+
+const themeAccessor = useContext(ThemeContext) // () => Theme`,
+      mistakes: [
+        'Treating `useContext(ThemeContext)` as the theme object — it is the ACCESSOR `() => Theme` (reactive context). Call it to read',
+      ],
+      seeAlso: ['useTheme', 'useThemeAccessor', 'ThemeProvider'],
+    },
+    {
+      name: 'createSheet',
+      kind: 'function',
+      signature: 'createSheet(options?: StyleSheetOptions): StyleSheet',
+      summary:
+        'Creates an ISOLATED `StyleSheet` instance (its own FNV-1a dedup cache + rule registry) instead of the shared singleton `sheet`. Use for shadow-DOM roots, multi-window/iframe rendering, or test isolation where one request/realm must not share the global dedup cache. Most apps never need this — the singleton is correct for a single document.',
+      example: `import { createSheet } from "@pyreon/styler"
+
+const shadowSheet = createSheet({ /* StyleSheetOptions */ })`,
+      mistakes: [
+        'Creating a fresh sheet per render — defeats dedup; create once per realm/root and reuse',
+        'Mixing the singleton and an isolated sheet for the same DOM — classes from one will not be deduped against the other; pick one per document root',
+      ],
+      seeAlso: ['StyleSheet', 'sheet'],
+    },
+    {
+      name: 'StyleSheet',
+      kind: 'class',
+      signature: 'class StyleSheet { constructor(options?: StyleSheetOptions) }',
+      summary:
+        'The CSS injection engine: FNV-1a content hashing, a dedup cache (identical CSS → one rule), and SSR support (collect rules to a string on the server, hydrate on the client). `sheet` is the process singleton; `createSheet()` wraps `new StyleSheet()`. Direct instantiation is for custom integrations (server frameworks collecting critical CSS, test harnesses).',
+      example: `import { StyleSheet } from "@pyreon/styler"
+
+const s = new StyleSheet({ /* options */ })`,
+      mistakes: [
+        'Instantiating `new StyleSheet()` in app code — use the exported `sheet` singleton (or `createSheet()` for explicit isolation); a stray instance will not be where `styled()` injects',
+      ],
+      seeAlso: ['createSheet', 'sheet'],
+    },
+    {
+      name: 'sheet',
+      kind: 'constant',
+      signature: 'sheet: StyleSheet',
+      summary:
+        'The process-wide singleton `StyleSheet` that `styled()` / `css` / `keyframes` / `createGlobalStyle` inject into by default. Read it for SSR critical-CSS extraction or debugging the rule registry; do not mutate it directly.',
+      example: `import { sheet } from "@pyreon/styler"
+// SSR: render the app, then read the collected rules off \`sheet\` for the <head>`,
+      seeAlso: ['StyleSheet', 'createSheet'],
+    },
+    {
+      name: 'resolve',
+      kind: 'function',
+      signature:
+        'resolve(strings: TemplateStringsArray, values: Interpolation[], props: Record<string, any>): string',
+      summary:
+        'Low-level: resolve a tagged-template (strings + interpolations) against a `props` object into a final CSS string (function interpolations invoked with `props`). The engine `styled()` / `useCSS` build on. Direct use is for custom CSS-in-JS layered on top of styler; app code should prefer `styled` / `css`.',
+      example: `import { resolve } from "@pyreon/styler"
+
+const cssText = resolve(strings, values, { theme, $compact: true })`,
+      seeAlso: ['normalizeCSS', 'resolveValue', 'styled'],
+    },
+    {
+      name: 'normalizeCSS',
+      kind: 'function',
+      signature: 'normalizeCSS(css: string): string',
+      summary:
+        'Normalizes a raw CSS string (whitespace/format canonicalization) so identical-intent CSS hashes to the same FNV-1a key and dedupes. Memoized via an internal cache — call `clearNormCache()` to drop it (tests / long-lived processes).',
+      example: `import { normalizeCSS } from "@pyreon/styler"
+
+normalizeCSS("color:  red ;") // canonical form, dedup-stable`,
+      seeAlso: ['clearNormCache', 'resolve'],
+    },
+    {
+      name: 'resolveValue',
+      kind: 'function',
+      signature:
+        'resolveValue(value: Interpolation, props: Record<string, any>): string',
+      summary:
+        'Resolves a SINGLE interpolation against `props`: invokes function interpolations with `props`, flattens nested `CSSResult` / `KeyframesResult`, and stringifies the result. The per-interpolation primitive `resolve()` loops over.',
+      example: `import { resolveValue } from "@pyreon/styler"
+
+resolveValue((p) => p.theme.colors.primary, { theme })`,
+      seeAlso: ['resolve', 'isDynamic'],
+    },
+    {
+      name: 'clearNormCache',
+      kind: 'function',
+      signature: 'clearNormCache(): void',
+      summary:
+        'Clears the `normalizeCSS` memo cache. Needed in test suites that assert on injection counts / sheet contents across cases, and in long-lived processes that churn unique CSS and want to bound the cache. No effect on already-injected rules.',
+      example: `import { clearNormCache } from "@pyreon/styler"
+
+afterEach(() => clearNormCache())`,
+      seeAlso: ['normalizeCSS'],
+    },
+    {
+      name: 'buildProps',
+      kind: 'function',
+      signature:
+        'buildProps(rawProps: Record<string, any>, generatedCls: string, isDOM: boolean, customFilter?: (prop: string) => boolean): Record<string, any>',
+      summary:
+        "Builds the final prop object forwarded to the rendered element: merges the generated class, drops `$`-transient props, and (for DOM targets) filters non-DOM attributes — `customFilter` overrides per-component. **Copies DESCRIPTORS, not values**, so compiler-emitted reactive (`_rp` getter) props survive forwarding instead of collapsing to a static snapshot.",
+      example: `import { buildProps } from "@pyreon/styler"
+
+const forwarded = buildProps(rawProps, "sc-abc123", true)`,
+      mistakes: [
+        'Re-implementing prop forwarding with `result[key] = source[key]` — that fires getters and freezes reactive props to a one-time value. styler uses descriptor copy specifically to preserve the `_rp` getter contract; any custom forwarder must do the same',
+        'Passing `isDOM: true` for a component target — DOM-attr filtering will strip props the wrapped component legitimately needs',
+      ],
+      seeAlso: ['filterProps', 'styled'],
+    },
+    {
+      name: 'filterProps',
+      kind: 'function',
+      signature:
+        'filterProps(props: Record<string, unknown>): Record<string, unknown>',
+      summary:
+        'Returns a copy of `props` with `$`-transient and known non-DOM props removed — the DOM-safety filter `buildProps` applies for element targets. Exposed for consumers doing their own forwarding who still want the styler allowlist semantics. Descriptor-preserving, same reactive-prop rationale as `buildProps`.',
+      example: `import { filterProps } from "@pyreon/styler"
+
+const domSafe = filterProps(props)`,
+      seeAlso: ['buildProps'],
+    },
+    {
+      name: 'isDynamic',
+      kind: 'function',
+      signature: 'isDynamic(v: Interpolation): boolean',
+      summary:
+        'True when an interpolation is a function (signal accessor / props reader) — i.e. the styled component must take the DYNAMIC resolve path (re-resolve per prop/theme change) rather than the static cached path. Used internally to decide the resolver branch; exported for tooling that mirrors that decision.',
+      example: `import { isDynamic } from "@pyreon/styler"
+
+isDynamic((p) => p.color) // true → dynamic path
+isDynamic("12px")          // false → static, cached`,
+      seeAlso: ['resolve', 'styled'],
+    },
+  ],
+  gotchas: [
+    {
+      label: 'css / keyframes return lazy values, not strings',
+      note: 'The `css` tagged template yields a `CSSResult` (resolved on use); `keyframes` stringifies to an animation NAME; `createGlobalStyle` returns a `ComponentFn` that must be MOUNTED. None of them inject CSS at call time — only on resolution/mount.',
+    },
+    {
+      label: 'Theme context is reactive',
+      note: '`useTheme()` is a snapshot; `useThemeAccessor()` is the tracking accessor. `styled` / `useCSS` templates already track the theme through their resolver, so whole-theme swaps re-resolve CSS + swap class names WITHOUT remounting the VNode. Destructuring `useTheme()` and reading outside a reactive scope freezes the value.',
+    },
+    {
+      label: 'Prop forwarding copies descriptors',
+      note: '`buildProps` / `filterProps` copy property DESCRIPTORS (not values) so compiler-emitted `_rp` getter props keep their reactive subscription end-to-end. Any custom prop-forwarding wrapper layered on styler MUST do the same — plain `result[k] = src[k]` silently collapses signal-driven props to a one-time snapshot.',
+    },
+    {
+      label: 'Singleton sheet by default',
+      note: 'All injection goes through the `sheet` singleton (FNV-1a dedup, SSR). `createSheet()` / `new StyleSheet()` are only for isolated realms (shadow DOM, iframes, test isolation) — mixing sheets for one document breaks dedup.',
+    },
+  ],
+})

package/src/sheet.ts

@@ -32,6 +32,16 @@ export interface StyleSheetOptions {
 export class StyleSheet {
   private cache = new Map<string, string>()
   private insertCache = new Map<string, string>()
+  // Reverse index: cache key (className / keyframe name / global key) →
+  // the insertCache keys that resolve to it. Lets eviction drop the
+  // (large) cssText-keyed insertCache entries in lockstep with `cache`,
+  // instead of letting them grow unbounded for the process lifetime.
+  private icKeysByClass = new Map<string, Set<string>>()
+  // Reverse index: cache key → the top-level CSSRule objects it inserted
+  // into the live sheet. Object references survive `deleteRule()`
+  // reindexing (only the numeric index shifts), so eviction can locate
+  // and remove the exact DOM rules without fragile index bookkeeping.
+  private domRules = new Map<string, CSSRule[]>()
   private sheet: CSSStyleSheet | null = null
   private ssrBuffer: string[] = []
   private isSSR: boolean
@@ -47,6 +57,10 @@ export class StyleSheet {
   }
 
   private mount() {
+    // SSR guard: the constructor only calls mount() when !this.isSSR, but
+    // keep the guard in-method so it's self-evidently SSR-safe regardless
+    // of caller (matches `this.isSSR = typeof document === 'undefined'`).
+    if (this.isSSR) return
     // Reuse existing <style> tag from SSR hydration
     const existing = document.querySelector(`style[${ATTR}]`) as HTMLStyleElement | null
 
@@ -118,18 +132,80 @@ export class StyleSheet {
     }
   }
 
+  /** Record that `icKey` resolves to `cacheKey` (for lockstep eviction). */
+  private trackIcKey(cacheKey: string, icKey: string): void {
+    let s = this.icKeysByClass.get(cacheKey)
+    if (!s) {
+      s = new Set()
+      this.icKeysByClass.set(cacheKey, s)
+    }
+    s.add(icKey)
+  }
+
+  /** Record a top-level CSSRule this `cacheKey` inserted into the sheet. */
+  private trackDomRule(cacheKey: string, ref: CSSRule | null | undefined): void {
+    if (!ref) return
+    let a = this.domRules.get(cacheKey)
+    if (!a) {
+      a = []
+      this.domRules.set(cacheKey, a)
+    }
+    a.push(ref)
+  }
+
+  /**
+   * Evict the given cache keys across ALL three storage layers:
+   * the `cache` Map, the cssText-keyed `insertCache` Map, and the live
+   * DOM rules. Without the latter two, `maxCacheSize` bounded only the
+   * smallest of the three — `insertCache` keys (full CSS text) and the
+   * `<style>` tag's `cssRules` grew unbounded for the app's lifetime,
+   * which is the actual memory leak this method exists to prevent.
+   */
+  private evictKeys(keys: string[]): void {
+    const ruleRefs = new Set<CSSRule>()
+    for (const key of keys) {
+      this.cache.delete(key)
+      const ics = this.icKeysByClass.get(key)
+      if (ics) {
+        for (const ic of ics) this.insertCache.delete(ic)
+        this.icKeysByClass.delete(key)
+      }
+      const refs = this.domRules.get(key)
+      if (refs) {
+        for (const r of refs) ruleRefs.add(r)
+        this.domRules.delete(key)
+      }
+    }
+    if (this.sheet && ruleRefs.size > 0) {
+      // Descending walk: deleting at i never shifts a not-yet-visited
+      // lower index, so identity matching stays correct mid-loop.
+      for (let i = this.sheet.cssRules.length - 1; i >= 0; i--) {
+        const r = this.sheet.cssRules[i]
+        if (r && ruleRefs.has(r)) {
+          try {
+            this.sheet.deleteRule(i)
+          } catch {
+            // Rule already gone (e.g. external clearAll) — ignore.
+          }
+        }
+      }
+    }
+  }
+
   /** Evict oldest entries when cache exceeds max size. */
   private evictIfNeeded() {
     if (this.cache.size <= this.maxCacheSize) return
 
     // Map iteration order is insertion order — delete oldest 10%
     const toDelete = Math.floor(this.maxCacheSize * 0.1)
+    const evicted: string[] = []
     let count = 0
     for (const key of this.cache.keys()) {
       if (count >= toDelete) break
-      this.cache.delete(key)
+      evicted.push(key)
       count++
     }
+    this.evictKeys(evicted)
   }
 
   /**
@@ -226,6 +302,7 @@ export class StyleSheet {
 
     if (this.cache.has(className)) {
       this.insertCache.set(icKey, className)
+      this.trackIcKey(className, icKey)
       return className
     }
 
@@ -254,7 +331,8 @@ export class StyleSheet {
     } else if (this.sheet) {
       for (const rule of finalRules) {
         try {
-          this.sheet.insertRule(rule, this.sheet.cssRules.length)
+          const at = this.sheet.insertRule(rule, this.sheet.cssRules.length)
+          this.trackDomRule(className, this.sheet.cssRules[at])
         } catch (_e) {
           if (__DEV__) {
             // oxlint-disable-next-line no-console
@@ -265,6 +343,7 @@ export class StyleSheet {
     }
 
     this.insertCache.set(icKey, className)
+    this.trackIcKey(className, icKey)
     return className
   }
 
@@ -281,7 +360,8 @@ export class StyleSheet {
       this.ssrBuffer.push(rule)
     } else if (this.sheet) {
       try {
-        this.sheet.insertRule(rule, this.sheet.cssRules.length)
+        const at = this.sheet.insertRule(rule, this.sheet.cssRules.length)
+        this.trackDomRule(name, this.sheet.cssRules[at])
       } catch (_e) {
         if (__DEV__) {
           // oxlint-disable-next-line no-console
@@ -332,7 +412,8 @@ export class StyleSheet {
       const rules = this.splitRules(cssText)
       for (const rule of rules) {
         try {
-          this.sheet.insertRule(rule, this.sheet.cssRules.length)
+          const at = this.sheet.insertRule(rule, this.sheet.cssRules.length)
+          this.trackDomRule(key, this.sheet.cssRules[at])
         } catch (_e) {
           if (__DEV__) {
             // oxlint-disable-next-line no-console
@@ -358,6 +439,64 @@ export class StyleSheet {
     return `<style ${ATTR}="">${css}</style>`
   }
 
+  /**
+   * Returns the collected SSR rules as a raw array (one entry per
+   * top-level rule, already `@layer`-wrapped + class-prefixed exactly as
+   * `insert()` produced them). Used by the compile-time rocketstyle
+   * collapse resolver: it renders a component under SSR, reads the rules
+   * here, and the build emits an idempotent `injectRules()` call so the
+   * collapsed `_tpl()` site is self-sufficient (no prior runtime mount
+   * needed to populate the sheet). A copy — callers must not mutate the
+   * internal buffer.
+   */
+  getStyleRules(): readonly string[] {
+    return this.ssrBuffer.slice()
+  }
+
+  // Idempotency guard for injectRules — keyed by the FNV hash the
+  // collapse resolver computes over the rule set. A second injection of
+  // the same resolved bundle (e.g. the module re-evaluated under HMR, or
+  // two collapsed call sites resolving to the same dimension combo) is a
+  // no-op instead of duplicate live `cssRules`.
+  private injectedBundles = new Set<string>()
+
+  /**
+   * Inject pre-resolved CSS rule text (from `getStyleRules()` captured at
+   * build time by the rocketstyle-collapse resolver) directly into the
+   * live sheet. Unlike `insert()` this does NOT re-hash — the class names
+   * are already baked into `rules` and into the collapsed `_tpl()` HTML;
+   * re-hashing would produce a different class and break the contract.
+   * Idempotent by `key` (the resolver's FNV hash of the bundle).
+   */
+  injectRules(rules: readonly string[], key: string): void {
+    if (this.injectedBundles.has(key)) return
+    this.injectedBundles.add(key)
+    if (this.isSSR) {
+      for (const rule of rules) this.ssrBuffer.push(rule)
+      return
+    }
+    if (!this.sheet) return
+    for (const rule of rules) {
+      try {
+        this.sheet.insertRule(rule, this.sheet.cssRules.length)
+      } catch (_e) {
+        if (__DEV__) {
+          // oxlint-disable-next-line no-console
+          console.warn('[styler] injectRules: failed to insert collapsed rule:', rule, _e)
+        }
+      }
+    }
+  }
+
+  /**
+   * Test-only: live `cssRules.length` (0 in SSR). Mirrors runtime-dom's
+   * `_tplCacheSize()` test-only-accessor convention; lets injectRules /
+   * eviction tests assert without reaching into the private sheet.
+   */
+  ruleCountForTest(): number {
+    return this.sheet?.cssRules.length ?? 0
+  }
+
   /** Returns collected CSS rules as a raw string (useful for streaming SSR). */
   getStyles(): string {
     if (this.ssrBuffer.length === 0) return ''
@@ -379,12 +518,16 @@ export class StyleSheet {
     this.ssrBuffer = []
     this.cache.clear()
     this.insertCache.clear()
+    this.icKeysByClass.clear()
+    this.domRules.clear()
   }
 
   /** Clear the dedup cache. Useful for HMR / dev-time reloads. */
   clearCache(): void {
     this.cache.clear()
     this.insertCache.clear()
+    this.icKeysByClass.clear()
+    this.domRules.clear()
     clearNormCache()
   }
 
@@ -401,6 +544,8 @@ export class StyleSheet {
   clearAll(): void {
     this.cache.clear()
     this.insertCache.clear()
+    this.icKeysByClass.clear()
+    this.domRules.clear()
     clearNormCache()
     this.ssrBuffer = []
     if (this.sheet) {

package/src/tests/manifest-snapshot.test.ts

@@ -0,0 +1,51 @@
+import {
+  renderApiReferenceEntries,
+  renderLlmsFullSection,
+  renderLlmsTxtLine,
+} from '@pyreon/manifest'
+import manifest from '../manifest'
+
+describe('gen-docs — styler snapshot', () => {
+  it('renders a llms.txt bullet starting with the package prefix', () => {
+    const line = renderLlmsTxtLine(manifest)
+    expect(line.startsWith('- @pyreon/styler —')).toBe(true)
+  })
+
+  it('renders a llms-full.txt section with the right header', () => {
+    const section = renderLlmsFullSection(manifest)
+    expect(section.startsWith('## @pyreon/styler —')).toBe(true)
+    expect(section).toContain('```typescript')
+  })
+
+  it('renders MCP api-reference entries for every api[] item', () => {
+    const record = renderApiReferenceEntries(manifest)
+    expect(Object.keys(record).sort()).toEqual([
+      'styler/StyleSheet',
+      'styler/ThemeContext',
+      'styler/ThemeProvider',
+      'styler/buildProps',
+      'styler/clearNormCache',
+      'styler/createGlobalStyle',
+      'styler/createSheet',
+      'styler/css',
+      'styler/filterProps',
+      'styler/isDynamic',
+      'styler/keyframes',
+      'styler/normalizeCSS',
+      'styler/resolve',
+      'styler/resolveValue',
+      'styler/sheet',
+      'styler/styled',
+      'styler/useCSS',
+      'styler/useTheme',
+      'styler/useThemeAccessor',
+    ])
+  })
+
+  it('carries the CSS-in-JS foot-gun catalog into MCP mistakes for flagship APIs', () => {
+    const r = renderApiReferenceEntries(manifest)
+    expect(r['styler/styled']?.mistakes).toContain('transient')
+    expect(r['styler/css']?.mistakes).toContain('lazy')
+    expect(r['styler/useTheme']?.mistakes).toContain('snapshot')
+  })
+})