@pyreon/styler 0.18.0 → 0.19.0

package/lib/index.d.ts

@@ -155,6 +155,8 @@ interface StyleSheetOptions {
 declare class StyleSheet {
   private cache;
   private insertCache;
+  private icKeysByClass;
+  private domRules;
   private sheet;
   private ssrBuffer;
   private isSSR;
@@ -167,6 +169,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;
   /**

package/lib/index.js

@@ -434,6 +434,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 +449,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 +490,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 +631,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 +645,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 +662,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 +700,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);
 			}
@@ -667,11 +726,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 +750,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.19.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.6",
+    "@pyreon/typescript": "^0.19.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.19.0",
+    "@pyreon/reactivity": "^0.19.0"
   }
 }

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/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
@@ -379,12 +460,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 +486,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')
+  })
+})