meno-core 1.0.53 → 1.1.0

package/lib/shared/utilityClassMapper.test.ts

@@ -1,29 +1,52 @@
 import { describe, test, expect } from 'bun:test';
-import { stylesToClasses, responsiveStylesToClasses, classToStyle, classesToStyles } from './utilityClassMapper';
+import {
+  stylesToClasses,
+  responsiveStylesToClasses,
+  classToStyle,
+  classesToStyles,
+  splitStyleByClassability,
+  isClassableStyleValue,
+  styleHasMapping,
+} from './utilityClassMapper';
 import { getStyleValue, clearRegistry } from './styleValueRegistry';
 import type { ResponsiveScales } from './responsiveScaling';
 
 describe('utilityClassMapper', () => {
   describe('stylesToClasses', () => {
-    test('converts padding to utility class', () => {
-      const classes = stylesToClasses({ padding: '10px' });
-      expect(classes).toContain('p-10px');
+    test('converts padding on an exact scale step to a named token', () => {
+      expect(stylesToClasses({ padding: '16px' })).toContain('p-4');
+      expect(stylesToClasses({ padding: '10px' })).toContain('p-2.5');
     });
 
-    test('converts display flex to short form', () => {
+    test('off-scale padding falls back to the arbitrary form', () => {
+      expect(stylesToClasses({ padding: '13px' })).toContain('p-[13px]');
+      expect(stylesToClasses({ padding: '5px' })).toContain('p-[5px]');
+    });
+
+    test('converts display flex to Tailwind static utility', () => {
       const classes = stylesToClasses({ display: 'flex' });
-      expect(classes).toContain('f');
+      expect(classes).toContain('flex');
+    });
+
+    test('converts display none to hidden', () => {
+      const classes = stylesToClasses({ display: 'none' });
+      expect(classes).toContain('hidden');
     });
 
     test('converts multiple properties', () => {
       const classes = stylesToClasses({ padding: '10px', margin: '20px' });
-      expect(classes).toContain('p-10px');
-      expect(classes).toContain('m-20px');
+      expect(classes).toContain('p-2.5');
+      expect(classes).toContain('m-5');
     });
 
     test('handles percentage values', () => {
       const classes = stylesToClasses({ width: '50%' });
-      expect(classes).toContain('w-50p');
+      expect(classes).toContain('w-[50%]');
+    });
+
+    test('maps width 100% to w-full', () => {
+      const classes = stylesToClasses({ width: '100%' });
+      expect(classes).toContain('w-full');
     });
 
     test('handles auto values', () => {
@@ -31,9 +54,9 @@ describe('utilityClassMapper', () => {
       expect(classes).toContain('m-auto');
     });
 
-    test('handles values with spaces', () => {
+    test('handles values with spaces (underscore encoding)', () => {
       const classes = stylesToClasses({ padding: '92px 0' });
-      expect(classes).toContain('p-92px-0');
+      expect(classes).toContain('p-[92px_0]');
     });
 
     test('returns empty array for null', () => {
@@ -41,60 +64,129 @@ describe('utilityClassMapper', () => {
       expect(stylesToClasses(undefined)).toEqual([]);
     });
 
-    test('handles color variables', () => {
-      const classes = stylesToClasses({ color: 'text' });
-      expect(classes).toContain('c-text');
+    test('handles bare color tokens (Meno token form)', () => {
+      expect(stylesToClasses({ color: 'text' })).toContain('text-text');
+      expect(stylesToClasses({ backgroundColor: 'primary' })).toContain('bg-primary');
+      expect(stylesToClasses({ borderColor: 'border-light' })).toContain('border-border-light');
     });
 
-    test('converts shadow preset to sh- class', () => {
+    test('named CSS colors / hex / Tailwind palette shapes stay arbitrary (not bare tokens)', () => {
+      expect(stylesToClasses({ backgroundColor: 'red' })).toContain('bg-[red]');
+      expect(stylesToClasses({ color: '#fff' })).toContain('text-[#fff]');
+      expect(stylesToClasses({ backgroundColor: 'gray-500' })).toContain('bg-[gray-500]');
+    });
+
+    test('handles font-size with explicit value', () => {
+      const classes = stylesToClasses({ fontSize: '48px' });
+      expect(classes).toContain('text-[48px]');
+    });
+
+    test('handles font-size variables with length hint', () => {
+      const classes = stylesToClasses({ fontSize: 'var(--font-size-lg)' });
+      expect(classes).toContain('text-(length:--font-size-lg)');
+    });
+
+    test('font-weight var carries a number hint (not misread as font-family)', () => {
+      // `font-*` is shared by weight/family; without the hint a var binding resolves to
+      // font-family (`font-family: 450`), so the weight never applies and the family changes.
+      expect(stylesToClasses({ fontWeight: 'var(--h-fw)' })).toContain('font-(number:--h-fw)');
+      expect(stylesToClasses({ fontFamily: 'var(--l-ff)' })).toContain('font-(--l-ff)');
+      // round-trips back to the right property
+      expect(classToStyle('font-(number:--h-fw)')).toEqual({ prop: 'fontWeight', value: 'var(--h-fw)' });
+      expect(classToStyle('font-(--l-ff)')).toEqual({ prop: 'fontFamily', value: 'var(--l-ff)' });
+    });
+
+    test('border/outline shorthand var binding stays the shorthand (not the color longhand)', () => {
+      // `border`/`outline` roots are shared by a shorthand and a color longhand. A `var(--x)` value
+      // is opaque and reads as a color, so the bare `border-(--x)` form would round-trip to
+      // `borderColor`. The shorthand must emit the explicit arbitrary-property form instead.
+      expect(stylesToClasses({ border: 'var(--bs)' })).toEqual(['[border:var(--bs)]']);
+      expect(stylesToClasses({ outline: 'var(--ol)' })).toEqual(['[outline:var(--ol)]']);
+      expect(stylesToClasses({ outlineWidth: 'var(--ow)' })).toEqual(['[outline-width:var(--ow)]']);
+      // round-trips back to the SAME property + var value
+      expect(classToStyle('[border:var(--bs)]')).toEqual({ prop: 'border', value: 'var(--bs)' });
+      expect(classToStyle('[outline:var(--ol)]')).toEqual({ prop: 'outline', value: 'var(--ol)' });
+      // the COLOR longhand emits the BARE token form (`var(--bs)` is a token reference); the
+      // token-aware inverse recovers it, and the `var(--bs)` shorthand still parses (back-compat).
+      expect(stylesToClasses({ borderColor: 'var(--bs)' })).toEqual(['border-bs']);
+      expect(classToStyle('border-bs', new Set(['bs']))).toEqual({ prop: 'borderColor', value: 'bs' });
+      expect(classToStyle('border-(--bs)')).toEqual({ prop: 'borderColor', value: 'bs' });
+    });
+
+    test('converts shadow preset to shadow- class', () => {
       const classes = stylesToClasses({ boxShadow: '2' });
-      expect(classes).toContain('sh-2');
+      expect(classes).toContain('shadow-2');
     });
 
-    test('converts gradient preset to gr- class', () => {
+    test('converts gradient preset to bg-gradient- class', () => {
       const classes = stylesToClasses({ background: '1' });
-      expect(classes).toContain('gr-1');
+      expect(classes).toContain('bg-gradient-1');
     });
 
-    test('converts border preset to bd- class', () => {
+    test('converts border preset to border-preset- class', () => {
       const classes = stylesToClasses({ border: '0' });
-      expect(classes).toContain('bd-0');
+      expect(classes).toContain('border-preset-0');
     });
 
     test('handles aspectRatio with slash value', () => {
       const classes = stylesToClasses({ aspectRatio: '1/1' });
-      expect(classes).toContain('ar-1s1');
+      expect(classes).toContain('aspect-[1/1]');
+    });
+
+    test('handles CSS function values', () => {
+      const classes = stylesToClasses({ transform: 'translateY(-50%)' });
+      expect(classes).toContain('transform-[translateY(-50%)]');
+    });
+
+    test('handles grid template repeat()', () => {
+      const classes = stylesToClasses({ gridTemplateColumns: 'repeat(3, 1fr)' });
+      expect(classes).toContain('grid-cols-[repeat(3,_1fr)]');
+    });
+
+    test('handles z-index Tailwind-style bare number', () => {
+      const classes = stylesToClasses({ zIndex: 10 });
+      expect(classes).toContain('z-10');
+    });
+
+    test('handles opacity on Tailwind 0-100 scale', () => {
+      const classes = stylesToClasses({ opacity: 0.5 });
+      expect(classes).toContain('opacity-50');
+    });
+
+    test('handles properties without a Tailwind root via arbitrary properties', () => {
+      const classes = stylesToClasses({ textOverflow: 'ellipsis' });
+      expect(classes).toContain('[text-overflow:ellipsis]');
     });
 
     test('align-items stretch maps to a distinct class from flex-start', () => {
-      // Regression: stretch used to share the `ai-s` class with flex-start,
-      // so imported `align-items: stretch` silently rendered as flex-start
-      // — exactly what made Finsweet's mobile CTA buttons line up to the
-      // left instead of stretching to full width.
+      // Regression: stretch must never share a class with flex-start,
+      // otherwise imported `align-items: stretch` silently renders as
+      // flex-start — exactly what made Finsweet's mobile CTA buttons line
+      // up to the left instead of stretching to full width.
       const stretchClasses = stylesToClasses({ alignItems: 'stretch' });
       const flexStartClasses = stylesToClasses({ alignItems: 'flex-start' });
-      expect(stretchClasses).toContain('ai-st');
-      expect(flexStartClasses).toContain('ai-s');
-      expect(stretchClasses).not.toContain('ai-s');
-      expect(classToStyle('ai-st')).toEqual({ prop: 'alignItems', value: 'stretch' });
+      expect(stretchClasses).toContain('items-stretch');
+      expect(flexStartClasses).toContain('items-start');
+      expect(stretchClasses).not.toContain('items-start');
+      expect(classToStyle('items-stretch')).toEqual({ prop: 'alignItems', value: 'stretch' });
     });
 
     test('justify-content space-evenly maps to a distinct class from flex-end', () => {
-      // Same bug shape as align-items: `space-evenly` previously aliased to
-      // `jc-e` (flex-end), silently changing layout.
+      // Same bug shape as align-items: `space-evenly` must not alias to
+      // flex-end, silently changing layout.
       const evenly = stylesToClasses({ justifyContent: 'space-evenly' });
       const end = stylesToClasses({ justifyContent: 'flex-end' });
-      expect(evenly).toContain('jc-ev');
-      expect(end).toContain('jc-e');
-      expect(evenly).not.toContain('jc-e');
-      expect(classToStyle('jc-ev')).toEqual({ prop: 'justifyContent', value: 'space-evenly' });
+      expect(evenly).toContain('justify-evenly');
+      expect(end).toContain('justify-end');
+      expect(evenly).not.toContain('justify-end');
+      expect(classToStyle('justify-evenly')).toEqual({ prop: 'justifyContent', value: 'space-evenly' });
     });
   });
 
   describe('responsiveStylesToClasses', () => {
     test('handles flat style object', () => {
       const classes = responsiveStylesToClasses({ padding: '10px' });
-      expect(classes).toContain('p-10px');
+      expect(classes).toContain('p-2.5');
     });
 
     test('handles responsive styles with base', () => {
@@ -102,17 +194,19 @@ describe('utilityClassMapper', () => {
         base: { padding: '10px' },
         tablet: { padding: '20px' },
       });
-      expect(classes).toContain('p-10px');
-      expect(classes).toContain('t-p-20px');
+      expect(classes).toContain('p-2.5');
+      // Desktop-first: breakpoint overrides carry Tailwind's max-width `max-` marker.
+      expect(classes).toContain('max-lg:p-5');
     });
 
-    test('handles mobile styles with mob prefix', () => {
+    test('handles mobile styles with mobile: variant prefix', () => {
       const classes = responsiveStylesToClasses({
         base: { padding: '10px' },
         mobile: { padding: '5px' },
       });
-      expect(classes).toContain('p-10px');
-      expect(classes).toContain('mob-p-5px');
+      expect(classes).toContain('p-2.5');
+      // 5px is off the scale → stays arbitrary
+      expect(classes).toContain('max-sm:p-[5px]');
     });
 
     test('returns empty array for null', () => {
@@ -120,6 +214,35 @@ describe('utilityClassMapper', () => {
       expect(responsiveStylesToClasses(undefined)).toEqual([]);
     });
 
+    test('desktop-first breakpoint prefix: emits Tailwind max-lg:/max-sm:, parses every legacy form', () => {
+      // Meno is desktop-first (max-width); the two default tiers carry Tailwind's canonical scale
+      // names in the class string — tablet → max-lg: (1024px = Tailwind lg), mobile → max-sm: (540px,
+      // Meno keeps its threshold). The breakpoint IDENTITY in the style object stays tablet/mobile.
+      const classes = responsiveStylesToClasses({
+        base: { padding: '16px' },
+        tablet: { padding: '8px' },
+        mobile: { padding: '4px' },
+      });
+      expect(classes).toEqual(['p-4', 'max-lg:p-2', 'max-sm:p-1']);
+
+      const expected = { base: { padding: '16px' }, tablet: { padding: '8px' }, mobile: { padding: '4px' } };
+      // The canonical max-lg:/max-sm: form round-trips back to the tablet/mobile buckets.
+      expect(classesToStyles(['p-4', 'max-lg:p-2', 'max-sm:p-1'])).toEqual(expected);
+      // Transitional un-aliased max-tablet:/max-mobile: form (emitted briefly before the alias) parses.
+      expect(classesToStyles(['p-4', 'max-tablet:p-2', 'max-mobile:p-1'])).toEqual(expected);
+      // Legacy bare prefixes (pre-`max-` projects) still parse to the same buckets.
+      expect(classesToStyles(['p-4', 'tablet:p-2', 'mobile:p-1'])).toEqual(expected);
+    });
+
+    test('foreign real-Tailwind min-width prefixes (bare lg:/sm:) are NOT absorbed as breakpoints', () => {
+      // A bare `lg:`/`sm:` is real-Tailwind MIN-width (opposite cascade) — Meno never emits it, so it
+      // must stay unrecognized rather than fold into the tablet/mobile buckets. (classesToStyles only
+      // buckets tablet/mobile; an un-mapped variant lands in base, but the studio adapter keeps such
+      // tokens foreign — see classAttrStyleAdapter.) Here: bare `lg:`/`sm:` do not map to tablet/mobile.
+      expect(classesToStyles(['lg:p-2'])?.tablet).toBeUndefined();
+      expect(classesToStyles(['sm:p-2'])?.mobile).toBeUndefined();
+    });
+
     describe('fluid mode — mobile-as-MIN consumption', () => {
       const fluidScales: ResponsiveScales = {
         enabled: true,
@@ -130,39 +253,39 @@ describe('utilityClassMapper', () => {
         padding: { tablet: 0.75, mobile: 0.5 },
       };
 
-      test('consumes scalable mobile override into base clamp; no mob- class emitted', () => {
+      test('consumes scalable mobile override into base clamp; no mobile: class emitted', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           { base: { fontSize: '150px' }, mobile: { fontSize: '94px' } },
-          { fluidActive: true, responsiveScales: fluidScales }
+          { fluidActive: true, responsiveScales: fluidScales },
         );
-        // base became a hashed class wrapping clamp(94px, ..., 150px)
-        const hashed = classes.find((c) => /^fs-h[0-9a-z]+$/.test(c));
-        expect(hashed).toBeDefined();
-        expect(getStyleValue(hashed!)).toMatch(/^clamp\(94px,/);
-        expect(getStyleValue(hashed!)).toContain(', 150px)');
-        // no .mob-fs-* emitted
-        expect(classes.some((c) => c.startsWith('mob-fs-'))).toBe(false);
+        // base became an arbitrary class wrapping clamp(94px, ..., 150px)
+        const clamped = classes.find((c) => c.startsWith('text-[clamp('));
+        expect(clamped).toBeDefined();
+        expect(String(getStyleValue(clamped!))).toMatch(/^clamp\(94px,/);
+        expect(String(getStyleValue(clamped!))).toContain(', 150px)');
+        // no mobile:text-* emitted
+        expect(classes.some((c) => c.startsWith('mobile:text-'))).toBe(false);
       });
 
-      test('mobile-only non-scalable property (display) stays as mob- class', () => {
+      test('mobile-only non-scalable property (display) stays as mobile: class', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           {
             base: { fontSize: '150px' },
             mobile: { fontSize: '94px', display: 'none' },
           },
-          { fluidActive: true, responsiveScales: fluidScales }
+          { fluidActive: true, responsiveScales: fluidScales },
         );
         // fontSize consumed into base clamp
-        const hashed = classes.find((c) => /^fs-h[0-9a-z]+$/.test(c));
-        expect(hashed).toBeDefined();
-        expect(getStyleValue(hashed!)).toMatch(/^clamp\(94px,/);
+        const clamped = classes.find((c) => c.startsWith('text-[clamp('));
+        expect(clamped).toBeDefined();
+        expect(String(getStyleValue(clamped!))).toMatch(/^clamp\(94px,/);
         // display:none survives on mobile
-        expect(classes).toContain('mob-h');
+        expect(classes).toContain('max-sm:hidden');
       });
 
-      test('tablet override stays as .t-* class (unchanged behavior)', () => {
+      test('tablet override stays as max-lg: class (unchanged behavior)', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           {
@@ -170,96 +293,132 @@ describe('utilityClassMapper', () => {
             tablet: { fontSize: '120px' },
             mobile: { fontSize: '94px' },
           },
-          { fluidActive: true, responsiveScales: fluidScales }
+          { fluidActive: true, responsiveScales: fluidScales },
         );
-        expect(classes).toContain('t-fs-120px');
+        expect(classes).toContain('max-lg:text-[120px]');
         // mobile consumed
-        expect(classes.some((c) => c.startsWith('mob-fs-'))).toBe(false);
+        expect(classes.some((c) => c.startsWith('max-sm:text-'))).toBe(false);
       });
 
       test('no mobile override → base passes through unchanged (no consumption)', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           { base: { fontSize: '150px' } },
-          { fluidActive: true, responsiveScales: fluidScales }
+          { fluidActive: true, responsiveScales: fluidScales },
         );
-        expect(classes).toContain('fs-150px');
-        expect(classes.some((c) => /^fs-h/.test(c))).toBe(false);
+        expect(classes).toContain('text-[150px]');
+        expect(classes.some((c) => c.startsWith('text-[clamp('))).toBe(false);
       });
 
-      test('mismatched units (rem vs px) → falls back, mob- class still emitted', () => {
+      test('mismatched units (rem vs px) → falls back, mobile: class still emitted', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           { base: { fontSize: '10rem' }, mobile: { fontSize: '94px' } },
-          { fluidActive: true, responsiveScales: fluidScales }
+          { fluidActive: true, responsiveScales: fluidScales },
         );
-        expect(classes).toContain('fs-10rem');
-        expect(classes).toContain('mob-fs-94px');
+        expect(classes).toContain('text-[10rem]');
+        expect(classes).toContain('max-sm:text-[94px]');
       });
 
       test('non-scalable mobile override (display) is not consumed', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           { base: { display: 'flex' }, mobile: { display: 'block' } },
-          { fluidActive: true, responsiveScales: fluidScales }
+          { fluidActive: true, responsiveScales: fluidScales },
         );
-        expect(classes).toContain('f');
-        expect(classes).toContain('mob-b');
+        expect(classes).toContain('flex');
+        expect(classes).toContain('max-sm:block');
       });
 
-      test('fluidActive off → no consumption, mob- class emitted', () => {
+      test('fluidActive off → no consumption, mobile: class emitted', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           { base: { fontSize: '150px' }, mobile: { fontSize: '94px' } },
-          { fluidActive: false, responsiveScales: fluidScales }
+          { fluidActive: false, responsiveScales: fluidScales },
         );
-        expect(classes).toContain('fs-150px');
-        expect(classes).toContain('mob-fs-94px');
+        expect(classes).toContain('text-[150px]');
+        expect(classes).toContain('max-sm:text-[94px]');
       });
 
       test('fluidActive on but responsiveScales disabled → no consumption', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           { base: { fontSize: '150px' }, mobile: { fontSize: '94px' } },
-          { fluidActive: true, responsiveScales: { ...fluidScales, enabled: false } }
+          { fluidActive: true, responsiveScales: { ...fluidScales, enabled: false } },
         );
-        expect(classes).toContain('fs-150px');
-        expect(classes).toContain('mob-fs-94px');
+        expect(classes).toContain('text-[150px]');
+        expect(classes).toContain('max-sm:text-[94px]');
       });
 
       test('clamp math: MIN=94px, MAX=150px, fluidRange 320–1700', () => {
         clearRegistry();
         const classes = responsiveStylesToClasses(
           { base: { fontSize: '150px' }, mobile: { fontSize: '94px' } },
-          { fluidActive: true, responsiveScales: fluidScales }
+          { fluidActive: true, responsiveScales: fluidScales },
         );
-        const hashed = classes.find((c) => /^fs-h[0-9a-z]+$/.test(c))!;
-        const value = String(getStyleValue(hashed));
+        const clamped = classes.find((c) => c.startsWith('text-[clamp('))!;
+        const value = String(getStyleValue(clamped));
         // slope = (150-94)/(1700-320) = 56/1380 ≈ 0.04058 px/px → slopeVw ≈ 4.058vw
         // intercept = 94 - 0.04058*320 = 94 - 12.9855 ≈ 81.0145px
         expect(value).toMatch(/clamp\(94px,\s*81\.0145px\s*\+\s*4\.058vw,\s*150px\)/);
       });
     });
+
+    describe('fluid mode — container intent (width === maxWidth)', () => {
+      test('rewrites equal width/maxWidth into the fluid container pattern', () => {
+        const classes = responsiveStylesToClasses(
+          { base: { width: '1200px', maxWidth: '1200px' } },
+          { fluidActive: true },
+        );
+        // width becomes a margin-aware calc, gains mx-auto; maxWidth (the cap) is kept.
+        expect(classes).toContain('w-[calc(100%_-_var(--site-margin)_*_2)]');
+        expect(classes).toContain('ml-auto');
+        expect(classes).toContain('mr-auto');
+        expect(classes).toContain('max-w-[1200px]');
+        expect(classes).not.toContain('w-[1200px]');
+      });
+
+      test('fluidActive off → plain width/maxWidth classes, no container rewrite', () => {
+        expect(responsiveStylesToClasses({ base: { width: '1200px', maxWidth: '1200px' } })).toEqual([
+          'w-[1200px]',
+          'max-w-[1200px]',
+        ]);
+      });
+
+      test('width !== maxWidth is not container intent (left untouched even in fluid mode)', () => {
+        const classes = responsiveStylesToClasses(
+          { base: { width: '1200px', maxWidth: '100%' } },
+          { fluidActive: true },
+        );
+        expect(classes).toContain('w-[1200px]');
+        expect(classes).not.toContain('w-[calc(100%_-_var(--site-margin)_*_2)]');
+      });
+    });
   });
 
   describe('classToStyle', () => {
     test('parses padding class', () => {
-      const style = classToStyle('p-10px');
+      const style = classToStyle('p-[10px]');
       expect(style).toEqual({ prop: 'padding', value: '10px' });
     });
 
-    test('parses special case flex', () => {
-      const style = classToStyle('f');
+    test('parses static flex utility', () => {
+      const style = classToStyle('flex');
       expect(style).toEqual({ prop: 'display', value: 'flex' });
     });
 
-    test('handles tablet prefix', () => {
-      const style = classToStyle('t-p-20px');
+    test('parses hidden utility', () => {
+      const style = classToStyle('hidden');
+      expect(style).toEqual({ prop: 'display', value: 'none' });
+    });
+
+    test('handles tablet variant prefix', () => {
+      const style = classToStyle('tablet:p-[20px]');
       expect(style).toEqual({ prop: 'padding', value: '20px' });
     });
 
-    test('handles mobile prefix', () => {
-      const style = classToStyle('mob-p-5px');
+    test('handles mobile variant prefix', () => {
+      const style = classToStyle('mobile:p-[5px]');
       expect(style).toEqual({ prop: 'padding', value: '5px' });
     });
 
@@ -268,32 +427,69 @@ describe('utilityClassMapper', () => {
       expect(classToStyle('unknown-class')).toBeNull();
     });
 
+    test('decodes underscores back to spaces', () => {
+      const style = classToStyle('p-[92px_0]');
+      expect(style).toEqual({ prop: 'padding', value: '92px 0' });
+    });
+
+    test('decodes color variables to bare tokens', () => {
+      const style = classToStyle('bg-(--primary)');
+      expect(style).toEqual({ prop: 'backgroundColor', value: 'primary' });
+    });
+
+    test('decodes non-color variables to var() values', () => {
+      const style = classToStyle('w-(--site-width)');
+      expect(style).toEqual({ prop: 'width', value: 'var(--site-width)' });
+    });
+
+    test('disambiguates text- by value: font-size vs color', () => {
+      expect(classToStyle('text-[14px]')).toEqual({ prop: 'fontSize', value: '14px' });
+      expect(classToStyle('text-[#fff]')).toEqual({ prop: 'color', value: '#fff' });
+      expect(classToStyle('text-(length:--font-size-lg)')).toEqual({
+        prop: 'fontSize',
+        value: 'var(--font-size-lg)',
+      });
+    });
+
+    test('decodes keyword utilities', () => {
+      expect(classToStyle('w-full')).toEqual({ prop: 'width', value: '100%' });
+      expect(classToStyle('h-screen')).toEqual({ prop: 'height', value: '100vh' });
+      expect(classToStyle('rounded-full')).toEqual({ prop: 'borderRadius', value: '9999px' });
+    });
+
+    test('decodes arbitrary-property classes', () => {
+      expect(classToStyle('[text-overflow:ellipsis]')).toEqual({ prop: 'textOverflow', value: 'ellipsis' });
+    });
+
     test('parses shadow preset class', () => {
-      const style = classToStyle('sh-2');
+      const style = classToStyle('shadow-2');
       expect(style).toEqual({ prop: 'boxShadow', value: '0 4px 12px rgba(0, 0, 0, 0.1)' });
     });
 
     test('parses gradient preset class', () => {
-      const style = classToStyle('gr-1');
-      expect(style).toEqual({ prop: 'background', value: 'linear-gradient(90deg, rgba(10,22,40,0.85) 0%, rgba(10,22,40,0.2) 100%)' });
+      const style = classToStyle('bg-gradient-1');
+      expect(style).toEqual({
+        prop: 'background',
+        value: 'linear-gradient(90deg, rgba(10,22,40,0.85) 0%, rgba(10,22,40,0.2) 100%)',
+      });
     });
 
     test('parses border preset class', () => {
-      const style = classToStyle('bd-0');
+      const style = classToStyle('border-preset-0');
       expect(style).toEqual({ prop: 'border', value: '1px solid var(--border)' });
     });
   });
 
   describe('classesToStyles', () => {
     test('converts base classes to style object', () => {
-      const styles = classesToStyles(['p-10px', 'm-20px']);
+      const styles = classesToStyles(['p-[10px]', 'm-[20px]']);
       expect(styles).toEqual({
         base: { padding: '10px', margin: '20px' },
       });
     });
 
     test('handles responsive classes', () => {
-      const styles = classesToStyles(['p-10px', 't-p-20px']);
+      const styles = classesToStyles(['p-[10px]', 'tablet:p-[20px]']);
       expect(styles).toEqual({
         base: { padding: '10px' },
         tablet: { padding: '20px' },
@@ -301,7 +497,7 @@ describe('utilityClassMapper', () => {
     });
 
     test('handles mobile classes', () => {
-      const styles = classesToStyles(['p-10px', 'mob-p-5px']);
+      const styles = classesToStyles(['p-[10px]', 'mobile:p-[5px]']);
       expect(styles).toEqual({
         base: { padding: '10px' },
         mobile: { padding: '5px' },
@@ -312,11 +508,153 @@ describe('utilityClassMapper', () => {
       expect(classesToStyles([])).toBeNull();
     });
 
+    test('keeps a narrower-breakpoint-only class string (no base) instead of returning null', () => {
+      // A class can style only a narrower breakpoint; this must not collapse to null (§11 adapter).
+      expect(classesToStyles(['tablet:p-[16px]'])).toEqual({ base: {}, tablet: { padding: '16px' } });
+      expect(classesToStyles(['mobile:p-[8px]'])).toEqual({ base: {}, mobile: { padding: '8px' } });
+    });
+
     test('removes empty breakpoints', () => {
-      const styles = classesToStyles(['p-10px']);
+      const styles = classesToStyles(['p-[10px]']);
       expect(styles).toEqual({ base: { padding: '10px' } });
       expect(styles?.tablet).toBeUndefined();
       expect(styles?.mobile).toBeUndefined();
     });
+
+    test('round-trips styles → classes → styles', () => {
+      const original = {
+        base: { padding: '92px 0', display: 'flex', color: 'primary', width: '100%' },
+        mobile: { padding: '12px 0' },
+      };
+      const classes = responsiveStylesToClasses(original);
+      // `color: primary` emits the bare token `text-primary`, which round-trips
+      // only against the project's known tokens (the new token-aware contract).
+      expect(classesToStyles(classes, new Set(['primary']))).toEqual(original);
+    });
+  });
+
+  describe('named spacing scale', () => {
+    test('forward: exact steps emit named tokens; off-scale stays arbitrary', () => {
+      expect(stylesToClasses({ padding: '16px' })).toEqual(['p-4']);
+      expect(stylesToClasses({ gap: '24px' })).toEqual(['gap-6']);
+      expect(stylesToClasses({ marginTop: '8px' })).toEqual(['mt-2']);
+      expect(stylesToClasses({ paddingInline: '16px' })).toEqual(['px-4']);
+      expect(stylesToClasses({ width: '256px' })).toEqual(['w-64']);
+      expect(stylesToClasses({ padding: '0px' })).toEqual(['p-0']);
+      expect(stylesToClasses({ padding: '2px' })).toEqual(['p-0.5']);
+      // off-scale + negatives keep the arbitrary form
+      expect(stylesToClasses({ padding: '13px' })).toEqual(['p-[13px]']);
+      expect(stylesToClasses({ margin: '-16px' })).toEqual(['m-[-16px]']);
+    });
+
+    test('keyword values still win over the scale', () => {
+      expect(stylesToClasses({ width: '100%' })).toEqual(['w-full']);
+      expect(stylesToClasses({ minHeight: '100vh' })).toEqual(['min-h-screen']);
+      expect(stylesToClasses({ margin: 'auto' })).toEqual(['m-auto']);
+    });
+
+    test('inverse: named steps decode back to px (durable from the name alone)', () => {
+      expect(classToStyle('p-4')).toEqual({ prop: 'padding', value: '16px' });
+      expect(classToStyle('p-2.5')).toEqual({ prop: 'padding', value: '10px' });
+      expect(classToStyle('gap-6')).toEqual({ prop: 'gap', value: '24px' });
+      expect(classToStyle('px-4')).toEqual({ prop: 'paddingInline', value: '16px' });
+      expect(classToStyle('w-64')).toEqual({ prop: 'width', value: '256px' });
+    });
+
+    test('round-trips through classesToStyles', () => {
+      const classes = responsiveStylesToClasses({ base: { padding: '16px', gap: '24px' }, tablet: { padding: '8px' } });
+      expect(classes).toEqual(['p-4', 'gap-6', 'max-lg:p-2']);
+      expect(classesToStyles(classes)).toEqual({ base: { padding: '16px', gap: '24px' }, tablet: { padding: '8px' } });
+    });
+
+    test('back-compat: the arbitrary form still parses', () => {
+      expect(classToStyle('p-[16px]')).toEqual({ prop: 'padding', value: '16px' });
+    });
+  });
+
+  describe('bare color tokens (token-aware)', () => {
+    const TOKENS = new Set(['primary', 'text', 'border', 'border-light']);
+
+    test('forward emits the bare token form', () => {
+      expect(stylesToClasses({ backgroundColor: 'primary' })).toEqual(['bg-primary']);
+      expect(stylesToClasses({ color: 'text' })).toEqual(['text-text']);
+      expect(stylesToClasses({ borderColor: 'border-light' })).toEqual(['border-border-light']);
+    });
+
+    test('a var() value on a color prop also emits the bare form (var(--muted) → bg-muted)', () => {
+      // The editor stores color tokens as `var(--x)`; that IS a token reference, so it emits the same
+      // bare form as the bare value would — `var(--muted)` and `muted` agree on `bg-muted`.
+      expect(stylesToClasses({ backgroundColor: 'var(--muted)' })).toEqual(['bg-muted']);
+      expect(stylesToClasses({ color: 'var(--text)' })).toEqual(['text-text']);
+      expect(stylesToClasses({ borderColor: 'var(--border)' })).toEqual(['border-border']);
+      expect(stylesToClasses({ outlineColor: 'var(--ring)' })).toEqual(['outline-ring']);
+      expect(classToStyle('bg-muted', new Set(['muted']))).toEqual({ prop: 'backgroundColor', value: 'muted' });
+    });
+
+    test('inverse needs the project token set; foreign classes are never tokens', () => {
+      expect(classToStyle('bg-primary', TOKENS)).toEqual({ prop: 'backgroundColor', value: 'primary' });
+      expect(classToStyle('border-border-light', TOKENS)).toEqual({ prop: 'borderColor', value: 'border-light' });
+      // unknown name → not a token (left for foreign-class passthrough)
+      expect(classToStyle('text-wrapper', TOKENS)).toBeNull();
+      // no token set → bare form is unrecognized (foreign-safe default)
+      expect(classToStyle('bg-primary')).toBeNull();
+    });
+
+    test('round-trips with the token set', () => {
+      const classes = responsiveStylesToClasses({ base: { backgroundColor: 'primary', color: 'text' } });
+      expect(classes).toEqual(['bg-primary', 'text-text']);
+      expect(classesToStyles(classes, TOKENS)).toEqual({ base: { backgroundColor: 'primary', color: 'text' } });
+    });
+
+    test('back-compat: the var() shorthand still parses without a token set', () => {
+      expect(classToStyle('bg-(--primary)')).toEqual({ prop: 'backgroundColor', value: 'primary' });
+    });
+  });
+
+  describe('splitStyleByClassability', () => {
+    test('isClassableStyleValue: static strings/numbers yes; templates/objects no', () => {
+      expect(isClassableStyleValue('24px')).toBe(true);
+      expect(isClassableStyleValue(100)).toBe(true);
+      expect(isClassableStyleValue('{{x}}px')).toBe(false);
+      expect(isClassableStyleValue({ _mapping: true })).toBe(false);
+    });
+
+    test('separates static (classable) from template/mapping (residual), preserving breakpoints', () => {
+      const mapping = { _mapping: true as const, prop: 'theme', values: { a: 'red' } };
+      expect(
+        splitStyleByClassability({
+          base: { padding: '24px', width: '{{w}}px', color: mapping },
+          tablet: { padding: '16px' },
+        }),
+      ).toEqual({
+        classable: { base: { padding: '24px' }, tablet: { padding: '16px' } },
+        residual: { base: { width: '{{w}}px', color: mapping } },
+      });
+    });
+
+    test('flat object splits under base; null/empty → null both sides', () => {
+      expect(splitStyleByClassability({ width: 100, label: '{{t}}' })).toEqual({
+        classable: { base: { width: 100 } },
+        residual: { base: { label: '{{t}}' } },
+      });
+      expect(splitStyleByClassability(null)).toEqual({ classable: null, residual: null });
+      expect(splitStyleByClassability({})).toEqual({ classable: null, residual: null });
+    });
+  });
+
+  describe('styleHasMapping', () => {
+    const mapping = { _mapping: true as const, prop: 'theme', values: { a: 'red' } };
+    test('detects a prop _mapping in any breakpoint (flat or responsive)', () => {
+      expect(styleHasMapping({ base: { color: mapping } })).toBe(true);
+      expect(styleHasMapping({ base: { padding: '8px' }, tablet: { color: mapping } })).toBe(true);
+      expect(styleHasMapping({ color: mapping })).toBe(true); // flat
+    });
+    test('false for plain / empty / nullish styles', () => {
+      expect(styleHasMapping({ base: { padding: '24px' } })).toBe(false);
+      expect(styleHasMapping({ padding: '24px' })).toBe(false);
+      expect(styleHasMapping({})).toBe(false);
+      expect(styleHasMapping(null)).toBe(false);
+      expect(styleHasMapping(undefined)).toBe(false);
+    });
   });
 });