@pyreon/unistyle 0.15.0 → 0.16.0

package/lib/index.d.ts

@@ -106,6 +106,20 @@ type MakeItResponsive = ({
   theme?: Theme$1;
   [prop: string]: any;
 }) => any;
+/**
+ * Core responsive engine used by every styled component in the system.
+ *
+ * Returns a styled-components interpolation function that:
+ * 1. Reads the component's theme prop (via `key` or direct `theme`)
+ * 2. Without breakpoints → renders plain CSS
+ * 3. With breakpoints → normalizes, transforms (property-per-breakpoint →
+ *    breakpoint-per-property), optimizes (deduplicates identical breakpoints),
+ *    deltas the per-breakpoint output against the mobile-first cascade
+ *    (drops re-emitted unchanged declarations), and wraps each non-empty
+ *    breakpoint's deltas in the appropriate `@media` query. Falls back to
+ *    the unoptimized path if any breakpoint's render result can't be
+ *    cleanly stringified.
+ */
 declare const makeItResponsive: MakeItResponsive;
 //#endregion
 //#region src/responsive/normalizeTheme.d.ts

package/lib/index.js

@@ -70,6 +70,127 @@ const normalizeTheme = ({ theme, breakpoints }) => {
 	return result;
 };
 
+//#endregion
+//#region src/responsive/optimizeBreakpointDeltas.ts
+/** Parse a CSS string into top-level declarations and opaque blocks. */
+const parse = (css) => {
+	const entries = [];
+	const len = css.length;
+	let depth = 0;
+	let parenDepth = 0;
+	let quote = 0;
+	let segmentStart = 0;
+	const pushSegment = (rawSegment) => {
+		const trimmed = rawSegment.trim();
+		if (!trimmed) return;
+		const text = trimmed.endsWith(";") ? trimmed.slice(0, -1) : trimmed;
+		const colonIdx = text.indexOf(":");
+		if (colonIdx <= 0) {
+			entries.push({
+				kind: "block",
+				raw: `${text};`
+			});
+			return;
+		}
+		const prop = text.slice(0, colonIdx).trim();
+		const value = text.slice(colonIdx + 1).trim();
+		if (!prop || !value) {
+			entries.push({
+				kind: "block",
+				raw: `${text};`
+			});
+			return;
+		}
+		entries.push({
+			kind: "decl",
+			prop,
+			value,
+			raw: `${prop}: ${value};`
+		});
+	};
+	for (let i = 0; i < len; i++) {
+		const code = css.charCodeAt(i);
+		if (quote !== 0) {
+			if (code === 92) i++;
+			else if (code === quote) quote = 0;
+			continue;
+		}
+		if (code === 34 || code === 39) {
+			quote = code;
+			continue;
+		}
+		if (code === 40) {
+			parenDepth++;
+			continue;
+		}
+		if (code === 41) {
+			if (parenDepth > 0) parenDepth--;
+			continue;
+		}
+		if (parenDepth > 0) continue;
+		if (code === 123) {
+			depth++;
+			continue;
+		}
+		if (code === 125) {
+			depth--;
+			if (depth === 0) {
+				const raw = css.slice(segmentStart, i + 1).trim();
+				if (raw) entries.push({
+					kind: "block",
+					raw
+				});
+				segmentStart = i + 1;
+			}
+			continue;
+		}
+		if (depth === 0 && code === 59) {
+			pushSegment(css.slice(segmentStart, i));
+			segmentStart = i + 1;
+		}
+	}
+	if (segmentStart < len) {
+		const trailing = css.slice(segmentStart).trim();
+		if (trailing) if (depth > 0) entries.push({
+			kind: "block",
+			raw: trailing
+		});
+		else pushSegment(trailing);
+	}
+	return entries;
+};
+/**
+* Apply the mobile-first cascade diff. The first entry passes through
+* unchanged; subsequent entries are pruned to the delta vs. the running
+* cascade (declarations by prop, blocks by exact text match).
+*/
+const optimizeBreakpointDeltas = (cssStrings) => {
+	if (cssStrings.length <= 1) return cssStrings;
+	const cascadeDecl = /* @__PURE__ */ new Map();
+	const cascadeBlocks = /* @__PURE__ */ new Set();
+	const out = new Array(cssStrings.length);
+	for (let i = 0; i < cssStrings.length; i++) {
+		const css = cssStrings[i];
+		if (!css) {
+			out[i] = "";
+			continue;
+		}
+		const entries = parse(css);
+		const kept = [];
+		for (const e of entries) if (e.kind === "decl") {
+			if (cascadeDecl.get(e.prop) !== e.value) {
+				kept.push(e.raw);
+				cascadeDecl.set(e.prop, e.value);
+			}
+		} else if (!cascadeBlocks.has(e.raw)) {
+			kept.push(e.raw);
+			cascadeBlocks.add(e.raw);
+		}
+		out[i] = kept.join(" ");
+	}
+	return out;
+};
+
 //#endregion
 //#region src/responsive/optimizeTheme.ts
 const shallowEqual = (a, b) => {
@@ -141,7 +262,39 @@ const transformTheme = ({ theme, breakpoints }) => {
 
 //#endregion
 //#region src/responsive/makeItResponsive.ts
+/**
+* Coerce a styles-callback result to a CSS string for delta optimization.
+* Returns null when the engine's result type can't be stringified cleanly
+* (e.g. styled-components / Emotion objects whose default toString() yields
+* "[object Object]") — caller falls back to the unoptimized path.
+*
+* Styler's CSSResult provides toString() that resolves with empty props,
+* so any function interpolation that needs render-time props must come from
+* the styles-callback closure (theme is destructured at call time, not
+* resolved later). Verified across the project's styles callbacks.
+*/
+const stringifyResult = (result) => {
+	if (result == null) return "";
+	if (typeof result === "string") return result;
+	if (typeof result === "object" && "strings" in result && "values" in result) return String(result);
+	const text = String(result);
+	return text.includes("[object ") ? null : text;
+};
 const themeCache = /* @__PURE__ */ new WeakMap();
+/**
+* Core responsive engine used by every styled component in the system.
+*
+* Returns a styled-components interpolation function that:
+* 1. Reads the component's theme prop (via `key` or direct `theme`)
+* 2. Without breakpoints → renders plain CSS
+* 3. With breakpoints → normalizes, transforms (property-per-breakpoint →
+*    breakpoint-per-property), optimizes (deduplicates identical breakpoints),
+*    deltas the per-breakpoint output against the mobile-first cascade
+*    (drops re-emitted unchanged declarations), and wraps each non-empty
+*    breakpoint's deltas in the appropriate `@media` query. Falls back to
+*    the unoptimized path if any breakpoint's render result can't be
+*    cleanly stringified.
+*/
 const makeItResponsive = ({ theme: customTheme, key = "", css, styles, normalize = true }) => ({ theme = {}, ...props }) => {
 	const internalTheme = customTheme || props[key];
 	if (isEmpty(internalTheme)) return "";
@@ -157,34 +310,61 @@ const makeItResponsive = ({ theme: customTheme, key = "", css, styles, normalize
       `;
 	const { media, sortedBreakpoints } = __PYREON__;
 	let optimizedTheme;
-	const cached = themeCache.get(internalTheme);
-	if (cached && cached.breakpoints === sortedBreakpoints) optimizedTheme = cached.optimized;
+	const entry = themeCache.get(internalTheme);
+	const breakpointsMatch = entry?.breakpoints === sortedBreakpoints;
+	if (entry && breakpointsMatch && entry.rendered) {
+		const memoized = entry.rendered.get(theme);
+		if (memoized) return memoized;
+	}
+	if (entry && breakpointsMatch) optimizedTheme = entry.optimized;
 	else {
 		let helperTheme = internalTheme;
 		if (normalize) helperTheme = normalizeTheme({
 			theme: internalTheme,
-			breakpoints: sortedBreakpoints
+			breakpoints: sortedBreakpoints ?? []
 		});
 		optimizedTheme = optimizeTheme({
 			theme: transformTheme({
 				theme: helperTheme,
-				breakpoints: sortedBreakpoints
+				breakpoints: sortedBreakpoints ?? []
 			}),
-			breakpoints: sortedBreakpoints
+			breakpoints: sortedBreakpoints ?? []
 		});
 		themeCache.set(internalTheme, {
 			breakpoints: sortedBreakpoints,
-			optimized: optimizedTheme
+			optimized: optimizedTheme,
+			rendered: entry?.rendered
 		});
 	}
-	return sortedBreakpoints.map((item) => {
+	const bps = sortedBreakpoints ?? [];
+	const renderedTexts = bps.map((item) => {
 		const breakpointTheme = optimizedTheme[item];
 		if (!breakpointTheme || !media) return "";
-		const result = renderStyles(breakpointTheme);
+		return stringifyResult(renderStyles(breakpointTheme));
+	});
+	const canOptimize = renderedTexts.every((t) => t !== null);
+	let result;
+	if (canOptimize) {
+		const deltas = optimizeBreakpointDeltas(renderedTexts);
+		result = bps.map((item, i) => {
+			const cssText = deltas[i];
+			if (!cssText || !media) return "";
+			return media[item]`${cssText}`;
+		});
+	} else result = bps.map((item) => {
+		const breakpointTheme = optimizedTheme[item];
+		if (!breakpointTheme || !media) return "";
+		const r = renderStyles(breakpointTheme);
 		return media[item]`
-        ${result};
-      `;
+          ${r};
+        `;
 	});
+	const cacheEntry = themeCache.get(internalTheme);
+	if (cacheEntry) {
+		if (!cacheEntry.rendered) cacheEntry.rendered = /* @__PURE__ */ new WeakMap();
+		cacheEntry.rendered.set(theme, result);
+	}
+	return result;
 };
 
 //#endregion
@@ -1913,6 +2093,7 @@ for (let i = 0; i < propertyMap.length; i++) {
 	if (d.key) addKey(d.key);
 	if (d.keys) if (Array.isArray(d.keys)) for (const k of d.keys) addKey(k);
 	else for (const inner of Object.values(d.keys)) addKey(inner);
+	if (d.id) addKey(d.id);
 }
 /**
 * Convert a normalized theme object (Record<key, value>) into a CSS template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/unistyle",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Responsive theming and breakpoint utilities for Pyreon",
   "license": "MIT",
   "repository": {
@@ -43,18 +43,18 @@
   },
   "devDependencies": {
     "@pyreon/manifest": "0.13.1",
-    "@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",
-    "@pyreon/styler": "^0.15.0",
-    "@pyreon/ui-core": "^0.15.0"
-  },
   "engines": {
     "node": ">= 22"
+  },
+  "dependencies": {
+    "@pyreon/core": "^0.16.0",
+    "@pyreon/reactivity": "^0.16.0",
+    "@pyreon/styler": "^0.16.0",
+    "@pyreon/ui-core": "^0.16.0"
   }
 }

package/src/__tests__/makeItResponsive.test.ts

@@ -168,4 +168,264 @@ describe('makeItResponsive', () => {
 
     expect(Array.isArray(result)).toBe(true)
   })
+
+  describe('delta optimization (mirrors vitus-labs)', () => {
+    it('strips re-emitted unchanged declarations across breakpoints', () => {
+      // mockStyles emits `color: red; padding: 0;` at xs and the same color
+      // with a different padding at sm. The delta optimizer should drop
+      // `color: red` from sm because it's already cascaded from xs via
+      // `@media (min-width: …)`.
+      const sortedBreakpoints = ['xs', 'sm']
+      const captured: Record<string, string> = {}
+      const media: Record<string, (s: TemplateStringsArray, ...v: any[]) => string> = {
+        xs: (s, ...vals) => {
+          let out = ''
+          for (let i = 0; i < s.length; i++) {
+            out += s[i]
+            if (i < vals.length) out += String(vals[i])
+          }
+          captured.xs = out
+          return out
+        },
+        sm: (s, ...vals) => {
+          let out = ''
+          for (let i = 0; i < s.length; i++) {
+            out += s[i]
+            if (i < vals.length) out += String(vals[i])
+          }
+          captured.sm = out
+          return out
+        },
+      }
+
+      const responsive = makeItResponsive({
+        theme: { color: { xs: 'red', sm: 'red' }, padding: { xs: '0', sm: '1rem' } },
+        css: mockCss,
+        styles: mockStyles,
+        normalize: true,
+      })
+
+      responsive({
+        theme: {
+          breakpoints: { xs: 0, sm: 576 },
+          __PYREON__: { sortedBreakpoints, media },
+        },
+      })
+
+      // xs sees full output
+      expect(captured.xs).toContain('color: red;')
+      expect(captured.xs).toContain('padding: 0;')
+      // sm sees only the delta — color is in cascade already
+      expect(captured.sm).toContain('padding: 1rem;')
+      expect(captured.sm).not.toContain('color:')
+    })
+
+    it('skips the media-template call entirely when a breakpoint has no deltas', () => {
+      const sortedBreakpoints = ['xs', 'sm']
+      let xsCalls = 0
+      let smCalls = 0
+      const media: Record<string, (s: TemplateStringsArray, ...v: any[]) => string> = {
+        xs: (s, ...vals) => {
+          xsCalls++
+          let out = ''
+          for (let i = 0; i < s.length; i++) {
+            out += s[i]
+            if (i < vals.length) out += String(vals[i])
+          }
+          return out
+        },
+        sm: (s, ...vals) => {
+          smCalls++
+          let out = ''
+          for (let i = 0; i < s.length; i++) {
+            out += s[i]
+            if (i < vals.length) out += String(vals[i])
+          }
+          return out
+        },
+      }
+
+      const responsive = makeItResponsive({
+        // Identical values at both breakpoints — sm produces zero deltas.
+        theme: { color: { xs: 'red', sm: 'red' } },
+        css: mockCss,
+        styles: mockStyles,
+      })
+
+      const result = responsive({
+        theme: {
+          breakpoints: { xs: 0, sm: 576 },
+          __PYREON__: { sortedBreakpoints, media },
+        },
+      })
+
+      // xs renders (has content); sm produces no @media wrapper at all
+      expect(xsCalls).toBe(1)
+      expect(smCalls).toBe(0)
+      // sm slot is the empty-string sentinel
+      expect((result as unknown[])[1]).toBe('')
+    })
+  })
+
+  describe('stringify fallback (mirrors vitus-labs)', () => {
+    // Where the two paths diverge observably: `styles` is invoked
+    // ONCE per breakpoint in the optimized path (for stringification),
+    // and TWICE per breakpoint in the fallback path (once for
+    // stringify which returns null, then again to re-render against
+    // the engine for the @media wrapper). With 2 breakpoints that's
+    // 2 calls vs 4 calls — clean observable distinction.
+
+    it('takes the unoptimized path when styles result has [object Foo] toString', () => {
+      // Foreign-engine result whose default toString is `[object ForeignResult]`.
+      // stringifyResult returns null → canOptimize=false → fallback path.
+      class ForeignResult {
+        constructor(public payload: string) {}
+        // Default toString → "[object ForeignResult]"
+      }
+
+      const sortedBreakpoints = ['xs', 'sm']
+      const media: Record<string, (s: TemplateStringsArray, ...v: any[]) => string> = {
+        xs: mockCss,
+        sm: mockCss,
+      }
+
+      let stylesCalls = 0
+      const stylesReturningForeign = ({ theme }: { theme: Record<string, unknown> }) => {
+        stylesCalls++
+        return new ForeignResult(JSON.stringify(theme))
+      }
+
+      // Distinct values per breakpoint so optimizeTheme keeps both keys
+      // (identical values get deduplicated upstream and never reach the
+      // optimization-vs-fallback split).
+      const responsive = makeItResponsive({
+        theme: { color: { xs: 'red', sm: 'blue' } },
+        css: mockCss,
+        styles: stylesReturningForeign as any,
+      })
+
+      responsive({
+        theme: {
+          breakpoints: { xs: 0, sm: 576 },
+          __PYREON__: { sortedBreakpoints, media },
+        },
+      })
+
+      // Fallback signature: stringify pass + re-render pass = 2 calls per bp
+      expect(stylesCalls).toBe(4)
+    })
+
+    it('takes the optimized path for plain-string styles results', () => {
+      const sortedBreakpoints = ['xs', 'sm']
+      const media: Record<string, (s: TemplateStringsArray, ...v: any[]) => string> = {
+        xs: mockCss,
+        sm: mockCss,
+      }
+
+      let stylesCalls = 0
+      const stylesCountingMock = (args: { theme: Record<string, unknown> }) => {
+        stylesCalls++
+        return mockStyles(args)
+      }
+
+      const responsive = makeItResponsive({
+        theme: { color: { xs: 'red', sm: 'blue' } },
+        css: mockCss,
+        styles: stylesCountingMock,
+      })
+
+      responsive({
+        theme: {
+          breakpoints: { xs: 0, sm: 576 },
+          __PYREON__: { sortedBreakpoints, media },
+        },
+      })
+
+      // Optimized signature: stringify pass only = 1 call per bp
+      expect(stylesCalls).toBe(2)
+    })
+  })
+
+  describe('render-output cache (mirrors vitus-labs)', () => {
+    it('returns the same rendered output by reference when called twice with stable theme + internal-theme refs', () => {
+      const sortedBreakpoints = ['xs', 'sm']
+      let xsCalls = 0
+      const media: Record<string, (s: TemplateStringsArray, ...v: any[]) => string> = {
+        xs: (s, ...vals) => {
+          xsCalls++
+          let out = ''
+          for (let i = 0; i < s.length; i++) {
+            out += s[i]
+            if (i < vals.length) out += String(vals[i])
+          }
+          return out
+        },
+        sm: mockCss,
+      }
+
+      const themeObj = { color: { xs: 'red', sm: 'blue' } }
+      const globalTheme = {
+        breakpoints: { xs: 0, sm: 576 },
+        __PYREON__: { sortedBreakpoints, media },
+      }
+
+      const responsive = makeItResponsive({
+        theme: themeObj,
+        css: mockCss,
+        styles: mockStyles,
+      })
+
+      const result1 = responsive({ theme: globalTheme })
+      const xsCallsAfterFirst = xsCalls
+      const result2 = responsive({ theme: globalTheme })
+
+      // Same identity means the rendered cache hit (no re-rendering)
+      expect(result2).toBe(result1)
+      // Render cache hit means the media template was NOT called again
+      expect(xsCalls).toBe(xsCallsAfterFirst)
+    })
+
+    it('re-renders when the outer theme reference changes (e.g. provider value swap)', () => {
+      const sortedBreakpoints = ['xs', 'sm']
+      let xsCalls = 0
+      const media: Record<string, (s: TemplateStringsArray, ...v: any[]) => string> = {
+        xs: (s, ...vals) => {
+          xsCalls++
+          let out = ''
+          for (let i = 0; i < s.length; i++) {
+            out += s[i]
+            if (i < vals.length) out += String(vals[i])
+          }
+          return out
+        },
+        sm: mockCss,
+      }
+
+      const themeObj = { color: { xs: 'red', sm: 'blue' } }
+
+      const responsive = makeItResponsive({
+        theme: themeObj,
+        css: mockCss,
+        styles: mockStyles,
+      })
+
+      // Two distinct outer-theme objects with the same content
+      const globalA = {
+        breakpoints: { xs: 0, sm: 576 },
+        __PYREON__: { sortedBreakpoints, media },
+      }
+      const globalB = {
+        breakpoints: { xs: 0, sm: 576 },
+        __PYREON__: { sortedBreakpoints, media },
+      }
+
+      responsive({ theme: globalA })
+      const callsAfterA = xsCalls
+      responsive({ theme: globalB })
+
+      // New outer theme object → no render cache hit → media template re-runs
+      expect(xsCalls).toBeGreaterThan(callsAfterA)
+    })
+
+  })
 })

package/src/__tests__/optimizeBreakpointDeltas.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+import { optimizeBreakpointDeltas } from '../responsive'
+
+describe('optimizeBreakpointDeltas', () => {
+  describe('cascade pruning', () => {
+    it('returns input unchanged when there is one or fewer breakpoints', () => {
+      expect(optimizeBreakpointDeltas([])).toEqual([])
+      expect(optimizeBreakpointDeltas(['color: red;'])).toEqual(['color: red;'])
+    })
+
+    it('strips re-emitted unchanged declarations from later breakpoints', () => {
+      const out = optimizeBreakpointDeltas([
+        'color: red; padding: 0;',
+        'color: red; padding: 1rem;',
+      ])
+      expect(out[0]).toBe('color: red; padding: 0;')
+      // `color: red` was already in the cascade — only padding survives
+      expect(out[1]).toBe('padding: 1rem;')
+    })
+
+    it('keeps changed declarations across multiple breakpoints', () => {
+      const out = optimizeBreakpointDeltas([
+        'color: red; font-size: 12px;',
+        'color: blue; font-size: 12px;',
+        'color: blue; font-size: 16px;',
+      ])
+      expect(out[0]).toBe('color: red; font-size: 12px;')
+      expect(out[1]).toBe('color: blue;')
+      expect(out[2]).toBe('font-size: 16px;')
+    })
+
+    it('emits empty string when a later breakpoint adds no deltas', () => {
+      const out = optimizeBreakpointDeltas([
+        'color: red; padding: 0;',
+        'color: red; padding: 0;',
+      ])
+      expect(out[0]).toBe('color: red; padding: 0;')
+      expect(out[1]).toBe('')
+    })
+
+    it('passes through empty / null breakpoints unchanged', () => {
+      const out = optimizeBreakpointDeltas(['color: red;', '', 'color: blue;'])
+      expect(out[0]).toBe('color: red;')
+      expect(out[1]).toBe('')
+      expect(out[2]).toBe('color: blue;')
+    })
+  })
+
+  describe('parser edge cases', () => {
+    it('skips colons inside parens (linear-gradient args)', () => {
+      const out = optimizeBreakpointDeltas([
+        'background: linear-gradient(red 0%, blue 100%);',
+        'background: linear-gradient(red 0%, blue 100%);',
+      ])
+      expect(out[0]).toBe('background: linear-gradient(red 0%, blue 100%);')
+      // Same value cascades — delta is empty
+      expect(out[1]).toBe('')
+    })
+
+    it('skips semicolons inside quoted strings (content: ";")', () => {
+      const out = optimizeBreakpointDeltas([
+        `content: ";"; color: red;`,
+        `content: ";"; color: blue;`,
+      ])
+      // Both declarations parsed correctly on bp1; bp2 only color delta
+      expect(out[0]).toContain(`content: ";";`)
+      expect(out[0]).toContain('color: red;')
+      expect(out[1]).toBe('color: blue;')
+    })
+
+    it('treats nested selector blocks as opaque, deduped by exact text', () => {
+      const out = optimizeBreakpointDeltas([
+        '&:hover { color: red; } padding: 0;',
+        '&:hover { color: red; } padding: 1rem;',
+      ])
+      // The hover block dedupes; padding delta survives
+      expect(out[1]).not.toContain('&:hover')
+      expect(out[1]).toContain('padding: 1rem;')
+    })
+
+    it('keeps differently-shaped nested blocks across breakpoints', () => {
+      const out = optimizeBreakpointDeltas([
+        '&:hover { color: red; }',
+        '&:hover { color: blue; }',
+      ])
+      expect(out[0]).toContain('&:hover { color: red; }')
+      // Different inner text → not deduped
+      expect(out[1]).toContain('&:hover { color: blue; }')
+    })
+
+    it('handles trailing declarations with no terminating semicolon', () => {
+      const out = optimizeBreakpointDeltas(['color: red', 'color: blue'])
+      expect(out[0]).toBe('color: red;')
+      expect(out[1]).toBe('color: blue;')
+    })
+
+    it('preserves @supports / @media-style nested blocks as opaque blocks', () => {
+      const out = optimizeBreakpointDeltas([
+        '@supports (display: grid) { display: grid; }',
+        '@supports (display: grid) { display: grid; } color: red;',
+      ])
+      expect(out[0]).toBe('@supports (display: grid) { display: grid; }')
+      // @supports block dedupes; color is new
+      expect(out[1]).toBe('color: red;')
+    })
+
+    it('keeps shorthand and longhand decls separately (no shorthand modeling)', () => {
+      const out = optimizeBreakpointDeltas([
+        'padding: 1rem;',
+        'padding-top: 0;',
+      ])
+      // Different `prop` keys → both retained
+      expect(out[0]).toBe('padding: 1rem;')
+      expect(out[1]).toBe('padding-top: 0;')
+    })
+
+    it('keeps malformed declaration-shaped fragments without losing them', () => {
+      const out = optimizeBreakpointDeltas([':abc;', ':abc;'])
+      // No prop name (starts with `:`) → kept as opaque block; deduped on bp2
+      expect(out[0]).toBe(':abc;')
+      expect(out[1]).toBe('')
+    })
+  })
+})

package/src/__tests__/special-keys.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import styles from '../styles/styles/index'
+
+const mockCss = (strings: TemplateStringsArray, ...vals: any[]) => {
+  let r = ''
+  for (let i = 0; i < strings.length; i++) {
+    r += strings[i]
+    if (i < vals.length) r += String(vals[i])
+  }
+  return r
+}
+
+// Regression: kind: 'special' descriptors (`fullScreen`, `hideEmpty`,
+// `clearFix`, `extendCss`, `backgroundImage`, `animation`) only carry an
+// `id` field — no `key` / `keys`. The keyToIndices builder used to walk
+// only `d.key` / `d.keys`, so special descriptors were never indexed.
+//
+// In single-special-property themes the bug was masked by the fallback
+// path (`if (fragments.length === 0 && Object.keys(t).length > 0)` triggers
+// a full-scan that hits processSpecial). The moment ANY non-special key is
+// also present in the theme — the real-world shape, e.g. `<Overlay>` with
+// `{ fullScreen: true, background: 'rgba(0,0,0,0.5)' }` — the fast path
+// processes `background`, fragments.length === 1, fallback skipped, the
+// special is silently dropped.
+//
+// Fix: index `d.id` alongside `d.key` / `d.keys` so the fast path resolves
+// special descriptors directly.
+describe('kind: special descriptors paired with non-special properties', () => {
+  it('fullScreen + background → both render', () => {
+    const result = styles({
+      theme: { fullScreen: true, background: 'rgba(0,0,0,0.5)' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('position: fixed;')
+    expect(output).toContain('top: 0;')
+    expect(output).toContain('background: rgba(0,0,0,0.5);')
+  })
+
+  it('hideEmpty + color → both render', () => {
+    const result = styles({
+      theme: { hideEmpty: true, color: 'red' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const normalized = String(result).replace(/\s+/g, ' ')
+    expect(normalized).toContain('&:empty { display: none; }')
+    expect(normalized).toContain('color: red;')
+  })
+
+  it('clearFix + padding → both render', () => {
+    const result = styles({
+      theme: { clearFix: true, padding: 8 },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const normalized = String(result).replace(/\s+/g, ' ')
+    expect(normalized).toContain("&::after { clear: both; content: ''; display: table; }")
+    expect(normalized).toContain('padding:')
+    expect(normalized).toContain('0.5rem')
+  })
+
+  it('extendCss + color → both render', () => {
+    const result = styles({
+      theme: { extendCss: 'border: 1px solid red;', color: 'blue' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('border: 1px solid red;')
+    expect(output).toContain('color: blue;')
+  })
+
+  it('backgroundImage + color → both render', () => {
+    const result = styles({
+      theme: { backgroundImage: 'https://example.com/img.png', color: 'green' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('background-image: url(https://example.com/img.png);')
+    expect(output).toContain('color: green;')
+  })
+
+  it('animation + color → both render', () => {
+    const result = styles({
+      theme: { animation: 'fadeIn 1s ease-in', color: 'purple' },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const output = String(result)
+    expect(output).toContain('animation:')
+    expect(output).toContain('fadeIn 1s ease-in')
+    expect(output).toContain('color: purple;')
+  })
+
+  it('multiple specials + non-specials → all render', () => {
+    const result = styles({
+      theme: {
+        fullScreen: true,
+        hideEmpty: true,
+        clearFix: true,
+        extendCss: 'outline: 2px dashed orange;',
+        color: 'red',
+        padding: 16,
+      },
+      css: mockCss,
+      rootSize: 16,
+    })
+    const normalized = String(result).replace(/\s+/g, ' ')
+    expect(normalized).toContain('position: fixed;')
+    expect(normalized).toContain('&:empty { display: none; }')
+    expect(normalized).toContain("&::after { clear: both; content: ''; display: table; }")
+    expect(normalized).toContain('outline: 2px dashed orange;')
+    expect(normalized).toContain('color: red;')
+    expect(normalized).toContain('padding:')
+    expect(normalized).toContain('1rem')
+  })
+})

package/src/responsive/index.ts

@@ -6,6 +6,7 @@ export type { MakeItResponsive, MakeItResponsiveStyles } from './makeItResponsiv
 export { default as makeItResponsive } from './makeItResponsive'
 export type { NormalizeTheme } from './normalizeTheme'
 export { default as normalizeTheme } from './normalizeTheme'
+export { default as optimizeBreakpointDeltas } from './optimizeBreakpointDeltas'
 export type { OptimizeTheme } from './optimizeTheme'
 export { default as optimizeTheme } from './optimizeTheme'
 export type { SortBreakpoints } from './sortBreakpoints'

package/src/responsive/makeItResponsive.ts

@@ -1,12 +1,40 @@
 import { isEmpty } from '@pyreon/ui-core'
 import type createMediaQueries from './createMediaQueries'
 import normalizeTheme from './normalizeTheme'
+import optimizeBreakpointDeltas from './optimizeBreakpointDeltas'
 import optimizeTheme from './optimizeTheme'
 import type sortBreakpoints from './sortBreakpoints'
 import transformTheme from './transformTheme'
 
 type Css = (strings: TemplateStringsArray, ...values: any[]) => any
 
+/**
+ * Coerce a styles-callback result to a CSS string for delta optimization.
+ * Returns null when the engine's result type can't be stringified cleanly
+ * (e.g. styled-components / Emotion objects whose default toString() yields
+ * "[object Object]") — caller falls back to the unoptimized path.
+ *
+ * Styler's CSSResult provides toString() that resolves with empty props,
+ * so any function interpolation that needs render-time props must come from
+ * the styles-callback closure (theme is destructured at call time, not
+ * resolved later). Verified across the project's styles callbacks.
+ */
+const stringifyResult = (result: unknown): string | null => {
+  if (result == null) return ''
+  if (typeof result === 'string') return result
+  // CSSResult duck-type fast path: has `strings` (TemplateStringsArray) and
+  // `values`. We know its toString() resolves to clean CSS, so we can skip
+  // the "[object Foo]" validation for the common path.
+  if (typeof result === 'object' && 'strings' in result && 'values' in result) {
+    return String(result)
+  }
+  // Foreign engine result — coerce and validate. Default
+  // Object.prototype.toString → "[object Foo]" → bail out so caller can fall
+  // back to the unoptimized path.
+  const text = String(result)
+  return text.includes('[object ') ? null : text
+}
+
 type CustomTheme = Record<string, unknown>
 
 type Theme = Partial<{
@@ -45,16 +73,45 @@ export type MakeItResponsive = ({
   normalize?: boolean
 }) => (props: { theme?: Theme; [prop: string]: any }) => any
 
-const themeCache = new WeakMap<
-  object,
-  { breakpoints: unknown; optimized: Record<string, Record<string, unknown>> }
->()
-
+/**
+ * Per-internal-theme cache:
+ *  - `optimized`: the per-breakpoint theme object (`{ xs: {...}, md: {...} }`)
+ *    after `normalize → transform → optimize`. Reused as long as the same
+ *    `sortedBreakpoints` reference is passed in.
+ *  - `rendered`: memoized FINAL output (array of media-wrapped CSSResults),
+ *    keyed by the outer `theme` reference. Hit when the same internal theme
+ *    AND the same outer theme render again — which is the common case when
+ *    the provider value is stable. Avoids re-running renderStyles +
+ *    optimizeBreakpointDeltas on every parent re-render.
+ */
+interface ThemeCacheEntry {
+  breakpoints: unknown
+  optimized: Record<string, Record<string, unknown>>
+  rendered?: WeakMap<object, unknown[]> | undefined
+}
+
+const themeCache = new WeakMap<object, ThemeCacheEntry>()
+
+/**
+ * Core responsive engine used by every styled component in the system.
+ *
+ * Returns a styled-components interpolation function that:
+ * 1. Reads the component's theme prop (via `key` or direct `theme`)
+ * 2. Without breakpoints → renders plain CSS
+ * 3. With breakpoints → normalizes, transforms (property-per-breakpoint →
+ *    breakpoint-per-property), optimizes (deduplicates identical breakpoints),
+ *    deltas the per-breakpoint output against the mobile-first cascade
+ *    (drops re-emitted unchanged declarations), and wraps each non-empty
+ *    breakpoint's deltas in the appropriate `@media` query. Falls back to
+ *    the unoptimized path if any breakpoint's render result can't be
+ *    cleanly stringified.
+ */
 const makeItResponsive: MakeItResponsive =
   ({ theme: customTheme, key = '', css, styles, normalize = true }) =>
   ({ theme = {}, ...props }) => {
     const internalTheme = customTheme || props[key]
 
+    // if no theme is defined, return empty object
     if (isEmpty(internalTheme)) return ''
 
     const { rootSize, breakpoints, __PYREON__, ...restTheme } = theme as Theme
@@ -62,6 +119,7 @@ const makeItResponsive: MakeItResponsive =
     const renderStyles = (styleTheme: Record<string, unknown>): ReturnType<typeof styles> =>
       styles({ theme: styleTheme, css, rootSize, globalTheme: restTheme })
 
+    // if there are no breakpoints, return just standard css
     if (isEmpty(breakpoints) || isEmpty(__PYREON__)) {
       return css`
         ${renderStyles(internalTheme)}
@@ -72,47 +130,94 @@ const makeItResponsive: MakeItResponsive =
     const { media, sortedBreakpoints } = __PYREON__ as NonNullable<typeof __PYREON__>
 
     let optimizedTheme: Record<string, Record<string, unknown>>
+    const entry = themeCache.get(internalTheme)
+    const breakpointsMatch = entry?.breakpoints === sortedBreakpoints
+
+    // Full-render cache: same internal theme + same outer theme → return
+    // the previous render's output verbatim. CSSResult instances are
+    // immutable so reusing them is safe.
+    if (entry && breakpointsMatch && entry.rendered) {
+      const memoized = entry.rendered.get(theme as object)
+      if (memoized) return memoized
+    }
 
-    const cached = themeCache.get(internalTheme)
-    if (cached && cached.breakpoints === sortedBreakpoints) {
-      optimizedTheme = cached.optimized
+    if (entry && breakpointsMatch) {
+      optimizedTheme = entry.optimized
     } else {
       let helperTheme = internalTheme
 
       if (normalize) {
         helperTheme = normalizeTheme({
           theme: internalTheme,
-          breakpoints: sortedBreakpoints,
+          breakpoints: sortedBreakpoints ?? [],
         })
       }
 
       const transformedTheme = transformTheme({
         theme: helperTheme,
-        breakpoints: sortedBreakpoints,
+        breakpoints: sortedBreakpoints ?? [],
       })
 
       optimizedTheme = optimizeTheme({
         theme: transformedTheme,
-        breakpoints: sortedBreakpoints,
+        breakpoints: sortedBreakpoints ?? [],
       })
 
       themeCache.set(internalTheme, {
         breakpoints: sortedBreakpoints,
         optimized: optimizedTheme,
+        // Preserve any pre-existing rendered cache when re-entering with a
+        // changed sortedBreakpoints reference — usually unreachable because
+        // breakpoints come from a stable provider value, but the explicit
+        // handling avoids a memory cliff in tests / HMR.
+        rendered: entry?.rendered,
       })
     }
 
-    return sortedBreakpoints.map((item: string) => {
-      const breakpointTheme = optimizedTheme[item]
+    const bps = sortedBreakpoints ?? []
 
+    // Resolve each per-breakpoint render to a string so the delta optimizer
+    // can diff at the property level. If any breakpoint's result can't be
+    // cleanly stringified (foreign engine result), fall back to the original
+    // unoptimized path that lets the engine resolve interpolations itself.
+    const renderedTexts: (string | null)[] = bps.map((item: string) => {
+      const breakpointTheme = optimizedTheme[item]
       if (!breakpointTheme || !media) return ''
+      return stringifyResult(renderStyles(breakpointTheme))
+    })
 
-      const result = renderStyles(breakpointTheme)
+    const canOptimize = renderedTexts.every((t) => t !== null)
+    let result: unknown[]
+    if (canOptimize) {
+      const deltas = optimizeBreakpointDeltas(renderedTexts as string[])
+      result = bps.map((item: string, i: number) => {
+        const cssText = deltas[i]
+        if (!cssText || !media) return ''
+        return (media as Record<string, any>)[item]`${cssText}`
+      })
+    } else {
+      result = bps.map((item: string) => {
+        const breakpointTheme = optimizedTheme[item]
+        if (!breakpointTheme || !media) return ''
+        const r = renderStyles(breakpointTheme)
+        return (media as Record<string, any>)[item]`
+          ${r};
+        `
+      })
+    }
 
-      return (media as Record<string, any>)[item]`
-        ${result};
-      `
-    })
+    // Memoize the final rendered output by outer theme reference. Stable
+    // theme + stable internal theme → future renders return immediately.
+    // Invariant: by this point themeCache always has an entry for
+    // internalTheme — earlier paths either hit the rendered-cache and
+    // returned, or wrote one via themeCache.set above.
+    const cacheEntry = themeCache.get(internalTheme)
+    if (cacheEntry) {
+      if (!cacheEntry.rendered) cacheEntry.rendered = new WeakMap()
+      cacheEntry.rendered.set(theme as object, result)
+    }
+
+    return result
   }
 
 export default makeItResponsive

package/src/responsive/optimizeBreakpointDeltas.ts

@@ -0,0 +1,190 @@
+/**
+ * Mobile-first cascade optimizer.
+ *
+ * Given an ordered array of CSS strings (one per breakpoint, smallest first),
+ * returns a parallel array where each non-base breakpoint contains only the
+ * declarations that DIFFER from the cumulative cascade so far. This relies on
+ * mobile-first `@media (min-width: …)` semantics: properties set at smaller
+ * breakpoints inherit at larger ones, so re-emitting an unchanged property is
+ * pure byte waste.
+ *
+ * Example:
+ *   ["color: red; padding: 0;", "color: red; padding: 1rem;"]
+ *   → ["color: red; padding: 0;", "padding: 1rem;"]
+ *
+ * Top-level declarations are diffed by `prop:value`. Selector blocks
+ * (`&:hover { … }`, `@supports { … }`) are treated as opaque and deduped by
+ * exact text. Anything inside parens or quoted strings is skipped over so
+ * `linear-gradient(red 0%, blue 100%)` and `content: ";"` parse correctly.
+ *
+ * Limitations:
+ *  - shorthand/longhand interaction is not modeled. If breakpoint A sets
+ *    `padding: 1rem` and breakpoint B sets `padding-top: 0`, both are kept
+ *    (they have different `prop` keys). If A sets `padding-top: 1rem` and B
+ *    sets `padding: 1rem`, B's `padding` is emitted because the cascade map
+ *    has no entry for `padding`. This is correct: B's shorthand RESETS sides
+ *    A didn't touch, so dropping it would change behaviour.
+ *  - Nested blocks are deduped only by exact textual match. Two equivalent
+ *    blocks with different whitespace would both be emitted.
+ */
+
+interface DeclEntry {
+  kind: 'decl'
+  prop: string
+  value: string
+  raw: string // canonical "prop: value;" form
+}
+
+interface BlockEntry {
+  kind: 'block'
+  raw: string // entire "selector { body }" or stray block
+}
+
+type Entry = DeclEntry | BlockEntry
+
+/** Parse a CSS string into top-level declarations and opaque blocks. */
+const parse = (css: string): Entry[] => {
+  const entries: Entry[] = []
+  const len = css.length
+
+  let depth = 0
+  let parenDepth = 0
+  let quote = 0 // charCode of active quote (0 if none)
+  let segmentStart = 0
+
+  const pushSegment = (rawSegment: string) => {
+    const trimmed = rawSegment.trim()
+    if (!trimmed) return
+    // pushSegment is only reached for segments that ended with a top-level
+    // ";" — full "selector { ... }" blocks are captured separately by the
+    // brace walker, so this path always sees declarations (or malformed
+    // declaration-shaped fragments).
+    const text = trimmed.endsWith(';') ? trimmed.slice(0, -1) : trimmed
+    const colonIdx = text.indexOf(':')
+    if (colonIdx <= 0) {
+      // No ":" or starts with ":" → not a parseable declaration; keep raw
+      entries.push({ kind: 'block', raw: `${text};` })
+      return
+    }
+    const prop = text.slice(0, colonIdx).trim()
+    const value = text.slice(colonIdx + 1).trim()
+    if (!prop || !value) {
+      entries.push({ kind: 'block', raw: `${text};` })
+      return
+    }
+    entries.push({
+      kind: 'decl',
+      prop,
+      value,
+      raw: `${prop}: ${value};`,
+    })
+  }
+
+  for (let i = 0; i < len; i++) {
+    const code = css.charCodeAt(i)
+
+    // Inside a quoted string — skip until matching quote (ignoring escapes)
+    if (quote !== 0) {
+      if (code === 92 /* \ */) {
+        i++ // skip the next character
+      } else if (code === quote) {
+        quote = 0
+      }
+      continue
+    }
+
+    // Quote start
+    if (code === 34 /* " */ || code === 39 /* ' */) {
+      quote = code
+      continue
+    }
+
+    // Parens — content (e.g. linear-gradient args) shouldn't be interpreted
+    if (code === 40 /* ( */) {
+      parenDepth++
+      continue
+    }
+    if (code === 41 /* ) */) {
+      if (parenDepth > 0) parenDepth--
+      continue
+    }
+    if (parenDepth > 0) continue
+
+    if (code === 123 /* { */) {
+      depth++
+      continue
+    }
+    if (code === 125 /* } */) {
+      depth--
+      if (depth === 0) {
+        // End of a top-level block — capture from segmentStart..i (inclusive)
+        const raw = css.slice(segmentStart, i + 1).trim()
+        if (raw) entries.push({ kind: 'block', raw })
+        segmentStart = i + 1
+      }
+      continue
+    }
+
+    if (depth === 0 && code === 59 /* ; */) {
+      pushSegment(css.slice(segmentStart, i))
+      segmentStart = i + 1
+    }
+  }
+
+  // Trailing segment (no terminating semicolon)
+  if (segmentStart < len) {
+    const trailing = css.slice(segmentStart).trim()
+    if (trailing) {
+      if (depth > 0) {
+        // Unbalanced braces — keep the rest as opaque so output isn't lossy
+        entries.push({ kind: 'block', raw: trailing })
+      } else {
+        pushSegment(trailing)
+      }
+    }
+  }
+
+  return entries
+}
+
+/**
+ * Apply the mobile-first cascade diff. The first entry passes through
+ * unchanged; subsequent entries are pruned to the delta vs. the running
+ * cascade (declarations by prop, blocks by exact text match).
+ */
+export const optimizeBreakpointDeltas = (cssStrings: string[]): string[] => {
+  if (cssStrings.length <= 1) return cssStrings
+
+  const cascadeDecl = new Map<string, string>()
+  const cascadeBlocks = new Set<string>()
+  const out: string[] = new Array(cssStrings.length)
+
+  for (let i = 0; i < cssStrings.length; i++) {
+    const css = cssStrings[i]
+    if (!css) {
+      out[i] = ''
+      continue
+    }
+
+    const entries = parse(css)
+    const kept: string[] = []
+
+    for (const e of entries) {
+      if (e.kind === 'decl') {
+        if (cascadeDecl.get(e.prop) !== e.value) {
+          kept.push(e.raw)
+          cascadeDecl.set(e.prop, e.value)
+        }
+      } else if (!cascadeBlocks.has(e.raw)) {
+        kept.push(e.raw)
+        cascadeBlocks.add(e.raw)
+      }
+    }
+
+    out[i] = kept.join(' ')
+  }
+
+  return out
+}
+
+export default optimizeBreakpointDeltas

package/src/styles/styles/index.ts

@@ -53,6 +53,11 @@ for (let i = 0; i < propertyMap.length; i++) {
       }
     }
   }
+  // kind: 'special' descriptors carry only `id` (no key/keys). Index by id so
+  // the fast path resolves them when paired with non-special keys; otherwise
+  // fragments.length > 0 from non-special hits skips the fallback full-scan
+  // and the special is silently dropped.
+  if (d.id) addKey(d.id)
 }
 
 /**