@pyreon/styler 0.15.0 → 0.16.0

package/lib/index.d.ts

@@ -204,6 +204,12 @@ declare class StyleSheet {
   /**
    * Full cleanup: clear cache and remove all CSS rules from the DOM.
    * Intended for HMR / dev-time reloads where stale styles must be purged.
+   *
+   * Also fires `onSheetClear` subscribers so downstream caches (e.g.
+   * `styled.tsx`'s static-component cache) reset alongside the sheet.
+   * Without this, stale `StaticStyled` ComponentFn references survive HMR
+   * and continue to apply CSS class names that were just deleted from
+   * the DOM — observable as missing styles after every hot reload.
    */
   clearAll(): void;
   /**

package/lib/index.js

@@ -665,6 +665,12 @@ var StyleSheet = class {
 	/**
 	* Full cleanup: clear cache and remove all CSS rules from the DOM.
 	* Intended for HMR / dev-time reloads where stale styles must be purged.
+	*
+	* Also fires `onSheetClear` subscribers so downstream caches (e.g.
+	* `styled.tsx`'s static-component cache) reset alongside the sheet.
+	* Without this, stale `StaticStyled` ComponentFn references survive HMR
+	* and continue to apply CSS class names that were just deleted from
+	* the DOM — observable as missing styles after every hot reload.
 	*/
 	clearAll() {
 		this.cache.clear();
@@ -672,6 +678,7 @@ var StyleSheet = class {
 		clearNormCache();
 		this.ssrBuffer = [];
 		if (this.sheet) while (this.sheet.cssRules.length > 0) this.sheet.deleteRule(0);
+		fireSheetClearSubscribers();
 	}
 	/**
 	* Compute className and full CSS rule text without injecting.
@@ -710,6 +717,22 @@ const sheet = new StyleSheet();
 * Use in SSR to get per-request isolation.
 */
 const createSheet = (options) => new StyleSheet(options);
+const _sheetClearSubscribers = /* @__PURE__ */ new Set();
+const fireSheetClearSubscribers = () => {
+	for (const cb of _sheetClearSubscribers) cb();
+};
+/**
+* Subscribe to `sheet.clearAll()`. Fires after the sheet has been
+* fully cleared, so subscribers can drop downstream caches that depend
+* on the sheet's class names being live in the DOM.
+*
+* Returns a disposer for symmetry; in practice subscribers register
+* once at module load and never unsubscribe.
+*/
+const onSheetClear = (callback) => {
+	_sheetClearSubscribers.add(callback);
+	return () => _sheetClearSubscribers.delete(callback);
+};
 
 //#endregion
 //#region src/ThemeProvider.ts
@@ -799,20 +822,28 @@ const keyframes = (strings, ...values) => new KeyframesResult(strings, values);
 //#region src/styled.tsx
 const _countSink = globalThis;
 const getDisplayName = (tag) => typeof tag === "string" ? tag : tag.displayName || tag.name || "Component";
-const staticComponentCache = /* @__PURE__ */ new WeakMap();
-let _hotStrings = null;
-let _hotTag = null;
-let _hotComponent = null;
+let staticComponentCache = /* @__PURE__ */ new WeakMap();
+const _hotCache = {
+	strings: null,
+	tag: null,
+	component: null
+};
+onSheetClear(() => {
+	staticComponentCache = /* @__PURE__ */ new WeakMap();
+	_hotCache.strings = null;
+	_hotCache.tag = null;
+	_hotCache.component = null;
+});
 const createStyledComponent = (tag, strings, values, options) => {
 	if (values.length === 0 && !options) {
-		if (strings === _hotStrings && tag === _hotTag) return _hotComponent;
+		if (strings === _hotCache.strings && tag === _hotCache.tag) return _hotCache.component;
 		const tagMap = staticComponentCache.get(strings);
 		if (tagMap) {
 			const cached = tagMap.get(tag);
 			if (cached) {
-				_hotStrings = strings;
-				_hotTag = tag;
-				_hotComponent = cached;
+				_hotCache.strings = strings;
+				_hotCache.tag = tag;
+				_hotCache.component = cached;
 				return cached;
 			}
 		}
@@ -823,9 +854,20 @@ const createStyledComponent = (tag, strings, values, options) => {
 	if (!hasDynamicValues) {
 		const cssText = normalizeCSS(values.length === 0 ? strings[0] : resolve(strings, values, {}));
 		const staticClassName = cssText.length > 0 ? sheet.insert(cssText, false, insertLayer) : "";
+		const tagIsDOM = typeof tag === "string";
+		const cachedEmptyVNode = h(tag, staticClassName ? { class: staticClassName } : {});
 		const StaticStyled = (rawProps) => {
+			let hasExtraProps = false;
+			for (const _k in rawProps) {
+				hasExtraProps = true;
+				break;
+			}
+			if (!hasExtraProps && rawProps.ref == null) {
+				if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("styler.staticVNode.hit");
+				return cachedEmptyVNode;
+			}
 			const finalTag = rawProps.as || tag;
-			return h(finalTag, buildProps(rawProps, staticClassName, typeof finalTag === "string", customFilter), ...Array.isArray(rawProps.children) ? rawProps.children : rawProps.children != null ? [rawProps.children] : []);
+			return h(finalTag, buildProps(rawProps, staticClassName, finalTag === tag ? tagIsDOM : typeof finalTag === "string", customFilter), ...Array.isArray(rawProps.children) ? rawProps.children : rawProps.children != null ? [rawProps.children] : []);
 		};
 		StaticStyled.displayName = `styled(${getDisplayName(tag)})`;
 		if (!options && values.length === 0) {
@@ -835,9 +877,9 @@ const createStyledComponent = (tag, strings, values, options) => {
 				staticComponentCache.set(strings, tagMap);
 			}
 			tagMap.set(tag, StaticStyled);
-			_hotStrings = strings;
-			_hotTag = tag;
-			_hotComponent = StaticStyled;
+			_hotCache.strings = strings;
+			_hotCache.tag = tag;
+			_hotCache.component = StaticStyled;
 		}
 		return StaticStyled;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/styler",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Lightweight CSS-in-JS engine for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,16 +42,16 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/test-utils": "^0.13.2",
-    "@pyreon/typescript": "^0.15.0",
+    "@pyreon/test-utils": "^0.13.3",
+    "@pyreon/typescript": "^0.16.0",
     "@vitest/browser-playwright": "^4.1.4",
     "@vitus-labs/tools-rolldown": "^2.3.0"
   },
-  "peerDependencies": {
-    "@pyreon/core": "^0.15.0",
-    "@pyreon/reactivity": "^0.15.0"
-  },
   "engines": {
     "node": ">= 22"
+  },
+  "dependencies": {
+    "@pyreon/core": "^0.16.0",
+    "@pyreon/reactivity": "^0.16.0"
   }
 }

package/src/__tests__/sheet.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { hash } from '../hash'
-import { sheet, StyleSheet } from '../sheet'
+import { onSheetClear, sheet, StyleSheet } from '../sheet'
 
 describe('StyleSheet', () => {
   beforeEach(() => {
@@ -152,6 +152,47 @@ describe('StyleSheet', () => {
     })
   })
 
+  describe('onSheetClear', () => {
+    // Subscriber registry used by `styled.tsx` to drop its static-component
+    // cache when the singleton sheet is cleared. Without this, stale
+    // `StaticStyled` ComponentFns survive HMR and continue returning class
+    // names the sheet just deleted from the DOM.
+    it('fires subscribers after clearAll', () => {
+      const cb = vi.fn()
+      const dispose = onSheetClear(cb)
+      sheet.clearAll()
+      expect(cb).toHaveBeenCalledTimes(1)
+      dispose()
+    })
+
+    it('does NOT fire subscribers on clearCache (partial cleanup)', () => {
+      const cb = vi.fn()
+      const dispose = onSheetClear(cb)
+      sheet.insert('color: red;')
+      sheet.clearCache()
+      expect(cb).not.toHaveBeenCalled()
+      dispose()
+    })
+
+    it('disposer removes the subscriber', () => {
+      const cb = vi.fn()
+      const dispose = onSheetClear(cb)
+      dispose()
+      sheet.clearAll()
+      expect(cb).not.toHaveBeenCalled()
+    })
+
+    it('fires multiple subscribers in registration order', () => {
+      const order: number[] = []
+      const dispose1 = onSheetClear(() => order.push(1))
+      const dispose2 = onSheetClear(() => order.push(2))
+      sheet.clearAll()
+      expect(order).toEqual([1, 2])
+      dispose1()
+      dispose2()
+    })
+  })
+
   describe('has', () => {
     it('returns true for cached classNames', () => {
       const className = sheet.insert('color: red;')

package/src/__tests__/styled.test.ts

@@ -398,4 +398,114 @@ describe('styled.tag (Proxy)', () => {
     const vnode = Comp({}) as VNode
     expect(vnode.type).toBe('section')
   })
+
+  describe('empty-rawProps static VNode cache', () => {
+    // Hot path for `<MyStyled />` with no props: pre-built VNode returned
+    // from the StaticStyled closure verbatim. Skips `buildProps` + `h()` +
+    // children-array construction per render. Mirrors vitus-labs PR #228.
+    it('returns the SAME VNode identity across renders when rawProps is empty', () => {
+      const Comp = styled('div')`
+        color: red;
+      `
+      const v1 = Comp({}) as VNode
+      const v2 = Comp({}) as VNode
+      // Same VNode object — proves the pre-built cache fires.
+      expect(v1).toBe(v2)
+      expect(v1.type).toBe('div')
+      expect((v1.props as Record<string, string>).class).toMatch(/^pyr-/)
+    })
+
+    it('falls through to the full path when ANY prop is provided', () => {
+      const Comp = styled('div')`
+        color: red;
+      `
+      const v1 = Comp({}) as VNode
+      const v2 = Comp({ 'data-x': '1' }) as VNode
+      // Different identity — the second call bypassed the cache because
+      // `for (const _k in rawProps) hasExtraProps = true` fires.
+      expect(v1).not.toBe(v2)
+      // Both still produce the correct className.
+      expect((v1.props as Record<string, unknown>).class).toMatch(/^pyr-/)
+      expect((v2.props as Record<string, unknown>).class).toMatch(/^pyr-/)
+      // Second VNode carries the extra prop forwarded through buildProps.
+      expect((v2.props as Record<string, unknown>)['data-x']).toBe('1')
+    })
+
+    it('falls through to the full path when `as` overrides the tag', () => {
+      const Comp = styled('div')`
+        color: red;
+      `
+      const v1 = Comp({}) as VNode
+      const v2 = Comp({ as: 'span' }) as VNode
+      // `as` is enumerable → `hasExtraProps = true` → bypasses cache.
+      // Output tag is the override.
+      expect(v2.type).toBe('span')
+      expect(v1).not.toBe(v2)
+    })
+
+    it('falls through to the full path when a ref is provided', () => {
+      const Comp = styled('div')`
+        color: red;
+      `
+      const refCb = () => {}
+      const v1 = Comp({}) as VNode
+      const v2 = Comp({ ref: refCb }) as VNode
+      // `ref` is enumerable in JS, so `hasExtraProps = true` already fires.
+      // The explicit `rawProps.ref == null` guard is defense-in-depth for
+      // any future call site that uses Object.defineProperty(rawProps, 'ref',
+      // { enumerable: false, ... }) — that shape would otherwise return the
+      // cached no-ref VNode and silently drop the user's callback.
+      expect(v1).not.toBe(v2)
+    })
+  })
+
+  describe('clearAll resets static-component cache', () => {
+    // Regression: pre-fix, `staticComponentCache` (WeakMap) and the
+    // single-entry hot cache (`_hotStrings` / `_hotTag` / `_hotComponent`)
+    // survived `sheet.clearAll()`. After HMR / dev reload, the same
+    // template-literal call site re-invoked `styled('div')\`...\`` and got
+    // back the SAME ComponentFn instance — but the class name that
+    // component returns was deleted from the DOM by `clearAll`. End-user
+    // symptom: every hot reload silently broke styles for any static
+    // styled component until full page refresh.
+    //
+    // Fix wires `onSheetClear` so styled.tsx subscribes at module load
+    // and resets both caches alongside the sheet.
+    it('producing a new component after clearAll, with a fresh class name', () => {
+      // First mount: get baseline component + className.
+      const tag = 'div'
+      const literal: TemplateStringsArray = Object.assign(
+        ['color: red;'] as unknown as TemplateStringsArray,
+        { raw: ['color: red;'] },
+      )
+      const Comp1 = (styled(tag) as (s: TemplateStringsArray) => any)(literal)
+      const vnode1 = Comp1({}) as VNode
+      const class1 = (vnode1.props as Record<string, string>).class
+
+      // Same call, no clear: hot cache returns the SAME function identity.
+      const Comp1Again = (styled(tag) as (s: TemplateStringsArray) => any)(literal)
+      expect(Comp1Again).toBe(Comp1)
+
+      // Clear the sheet (HMR simulation).
+      sheet.clearAll()
+
+      // After clear: same template-literal identity should produce a NEW
+      // component (caches were dropped). Its className resolves against
+      // the now-empty sheet, so the new className IS re-inserted into
+      // the DOM and the class is observable.
+      const Comp2 = (styled(tag) as (s: TemplateStringsArray) => any)(literal)
+      expect(Comp2).not.toBe(Comp1)
+      const vnode2 = Comp2({}) as VNode
+      const class2 = (vnode2.props as Record<string, string>).class
+      // FNV-1a hashing is content-deterministic, so class names are
+      // structurally equal — but the sheet has freshly re-inserted the
+      // rule. Asserting non-empty + same format is the load-bearing
+      // observation: pre-fix, Comp2 === Comp1 and class2 would also have
+      // been `''` if the user had run `clearAll` between insertions
+      // (cache stale, sheet empty).
+      expect(class1).toMatch(/^pyr-/)
+      expect(class2).toMatch(/^pyr-/)
+      expect(sheet.has(class2!)).toBe(true)
+    })
+  })
 })

package/src/sheet.ts

@@ -391,6 +391,12 @@ export class StyleSheet {
   /**
    * Full cleanup: clear cache and remove all CSS rules from the DOM.
    * Intended for HMR / dev-time reloads where stale styles must be purged.
+   *
+   * Also fires `onSheetClear` subscribers so downstream caches (e.g.
+   * `styled.tsx`'s static-component cache) reset alongside the sheet.
+   * Without this, stale `StaticStyled` ComponentFn references survive HMR
+   * and continue to apply CSS class names that were just deleted from
+   * the DOM — observable as missing styles after every hot reload.
    */
   clearAll(): void {
     this.cache.clear()
@@ -402,6 +408,7 @@ export class StyleSheet {
         this.sheet.deleteRule(0)
       }
     }
+    fireSheetClearSubscribers()
   }
 
   /**
@@ -447,3 +454,29 @@ export const sheet = new StyleSheet()
  * Use in SSR to get per-request isolation.
  */
 export const createSheet = (options?: StyleSheetOptions): StyleSheet => new StyleSheet(options)
+
+// ─── onSheetClear subscriber registry ─────────────────────────────────────
+//
+// Used by `styled.tsx` to reset its static-component cache when the
+// singleton sheet is cleared via `clearAll()`. Module-level Set so the
+// subscription survives between calls; ports the vitus-labs pattern from
+// `connector-styler/sheet.ts:onClear`. Scoped to the singleton sheet —
+// per-instance sheets created via `createSheet()` don't fire the hook.
+const _sheetClearSubscribers = new Set<() => void>()
+
+const fireSheetClearSubscribers = (): void => {
+  for (const cb of _sheetClearSubscribers) cb()
+}
+
+/**
+ * Subscribe to `sheet.clearAll()`. Fires after the sheet has been
+ * fully cleared, so subscribers can drop downstream caches that depend
+ * on the sheet's class names being live in the DOM.
+ *
+ * Returns a disposer for symmetry; in practice subscribers register
+ * once at module load and never unsubscribe.
+ */
+export const onSheetClear = (callback: () => void): (() => void) => {
+  _sheetClearSubscribers.add(callback)
+  return () => _sheetClearSubscribers.delete(callback)
+}

package/src/styled.tsx

@@ -21,7 +21,7 @@ import { computed, renderEffect, runUntracked } from '@pyreon/reactivity'
 import { buildProps } from './forward'
 import { type Interpolation, normalizeCSS, resolve } from './resolve'
 import { isDynamic } from './shared'
-import { sheet } from './sheet'
+import { onSheetClear, sheet } from './sheet'
 import { useThemeAccessor } from './ThemeProvider'
 
 // Dev-time counter sink — see packages/internals/perf-harness/COUNTERS.md.
@@ -50,12 +50,33 @@ const getDisplayName = (tag: Tag): string =>
 
 // Component cache: same template literal + tag + no options → same component.
 // WeakMap on `strings` (TemplateStringsArray is object-identity per source location).
-const staticComponentCache = new WeakMap<TemplateStringsArray, Map<Tag, ComponentFn>>()
-
-// Single-entry hot cache — just 3 reference comparisons, no Map/WeakMap overhead.
-let _hotStrings: TemplateStringsArray | null = null
-let _hotTag: Tag | null = null
-let _hotComponent: ComponentFn | null = null
+// `let` so `sheet.clearAll()` (HMR / dev reload) can drop stale entries by
+// swapping the WeakMap reference — WeakMap has no `.clear()` method, and stale
+// `StaticStyled` ComponentFns left behind would keep returning class names the
+// sheet just deleted from the DOM.
+let staticComponentCache = new WeakMap<TemplateStringsArray, Map<Tag, ComponentFn>>()
+
+// Single-entry hot cache — 3 reference comparisons, no Map/WeakMap overhead.
+// All 3 fields move atomically (consolidated into one object so `clearAll`
+// resets them together — pre-fix, partial state was possible if a reset
+// path forgot one field).
+const _hotCache: {
+  strings: TemplateStringsArray | null
+  tag: Tag | null
+  component: ComponentFn | null
+} = { strings: null, tag: null, component: null }
+
+// Subscribe to `sheet.clearAll()` (HMR / dev-time reset). Drops both the
+// WeakMap and the hot-cache slots so subsequent `styled()` calls produce
+// fresh components with up-to-date class names. Static class names emitted
+// before `clearAll` are stale by the time the user observes them — the rule
+// they pointed at has been deleted from the DOM.
+onSheetClear(() => {
+  staticComponentCache = new WeakMap()
+  _hotCache.strings = null
+  _hotCache.tag = null
+  _hotCache.component = null
+})
 
 const createStyledComponent = (
   tag: Tag,
@@ -65,16 +86,17 @@ const createStyledComponent = (
 ): ComponentFn => {
   // Ultra-fast hot cache: 3 reference comparisons → return immediately
   if (values.length === 0 && !options) {
-    if (strings === _hotStrings && tag === _hotTag) return _hotComponent as ComponentFn
+    if (strings === _hotCache.strings && tag === _hotCache.tag)
+      return _hotCache.component as ComponentFn
 
     // WeakMap fallback for alternating patterns
     const tagMap = staticComponentCache.get(strings)
     if (tagMap) {
       const cached = tagMap.get(tag)
       if (cached) {
-        _hotStrings = strings
-        _hotTag = tag
-        _hotComponent = cached
+        _hotCache.strings = strings
+        _hotCache.tag = tag
+        _hotCache.component = cached
         return cached
       }
     }
@@ -94,9 +116,56 @@ const createStyledComponent = (
 
     const staticClassName = hasCss ? sheet.insert(cssText, false, insertLayer) : ''
 
+    // Hoisted out of the render fn: `tag` is known at component-creation time,
+    // and `tag` matches `rawProps.as ?? tag` whenever rawProps is empty (the
+    // common case for `<MyStyled />` without any props). The DOM-ness check
+    // doesn't change between renders for the same `tag`.
+    const tagIsDOM = typeof tag === 'string'
+
+    // Pre-built VNode for the no-extra-props hot path (`<MyStyled />`). Same
+    // shape `h(tag, { class })` would produce per render, but allocated once
+    // at component-creation time. Mount.ts spreads `vnode.props` into a new
+    // object before invoking the component (mount.ts:404-418 doesn't mutate
+    // the source vnode), so sharing the same VNode across mount sites is
+    // safe. `vnode.children` is empty here because the empty-rawProps branch
+    // also implies no children were passed — `rawProps.children` would be
+    // `undefined` and the `Array.isArray ? : ?? : []` chain produces `[]`.
+    //
+    // **Cache lifetime**: this VNode references `staticClassName`, which is
+    // the className the sheet just inserted. If `sheet.clearAll()` runs
+    // (HMR / dev reload), the className becomes stale BUT the outer
+    // `staticComponentCache` (and `_hot*` caches) ALSO survive that path —
+    // so consumers continue to receive the stale className regardless. The
+    // companion fix to wire `onSheetClear` and reset both caches is tracked
+    // separately (see PR #561). This optimization is correct under the
+    // existing cache lifetime contract; the HMR-staleness issue is broader
+    // than the VNode cache.
+    const cachedEmptyVNode = h(
+      tag as string,
+      staticClassName ? { class: staticClassName } : {},
+    )
+
     const StaticStyled: ComponentFn = (rawProps: Record<string, any>): VNode | null => {
+      // Hot path: no extra props beyond what's empty AND no `ref` / `as`.
+      // `for ... in` over an empty object is O(0); the `break` exits on the
+      // first key. Skipping the cache when `ref` is present is necessary
+      // because the user expects their callback to fire on the mounted DOM
+      // node — the pre-built VNode has no `ref` in its props.
+      let hasExtraProps = false
+      for (const _k in rawProps) {
+        hasExtraProps = true
+        break
+      }
+      if (!hasExtraProps && rawProps.ref == null) {
+        if (process.env.NODE_ENV !== 'production')
+          _countSink.__pyreon_count__?.('styler.staticVNode.hit')
+        return cachedEmptyVNode
+      }
+
       const finalTag = rawProps.as || tag
-      const isDOM = typeof finalTag === 'string'
+      // Fast `isDOM` when the user didn't pass `as` — reuses the closure-time
+      // check. Only `typeof` is needed when `as` overrides the tag.
+      const isDOM = finalTag === tag ? tagIsDOM : typeof finalTag === 'string'
       const finalProps = buildProps(rawProps, staticClassName, isDOM, customFilter)
 
       return h(
@@ -121,9 +190,9 @@ const createStyledComponent = (
         staticComponentCache.set(strings, tagMap)
       }
       tagMap.set(tag, StaticStyled)
-      _hotStrings = strings
-      _hotTag = tag
-      _hotComponent = StaticStyled
+      _hotCache.strings = strings
+      _hotCache.tag = tag
+      _hotCache.component = StaticStyled
     }
 
     return StaticStyled