meno-core 1.0.53 → 1.1.0

package/lib/shared/utilityClassMapper.ts

@@ -1,19 +1,40 @@
 /**
- * Maps CSS property values to utility class names
- * Example: { padding: "10px", display: "flex" } → ["p-10px", "flex"]
+ * Maps CSS property values to Tailwind-style utility class names
+ * Example: { padding: "10px", display: "flex" } → ["p-[10px]", "flex"]
  * Uses centralized configuration from utilityClassConfig.ts
  */
 
-import type { ResponsiveStyleObject, StyleObject, StyleMapping } from './types';
+import type { ResponsiveStyleObject, StyleObject, StyleMapping, StyleValue } from './types';
+import { isResponsiveStyle } from './styleUtils';
 import {
   propertyMap,
-  specialValueMappings,
-  classToStyleSpecialCases,
+  propertyOrder,
+  staticUtilities,
+  staticUtilityReverse,
+  presetClassReverse,
+  keywordValues,
+  genericKeywordRoots,
+  integerValueRoots,
+  colorTokenProps,
   shadowPresets,
   gradientPresets,
   borderPresets,
+  SPACING_SCALE_ROOTS,
+  SPACING_SCALE_REVERSE,
 } from './utilityClassConfig';
-import { registerStyleValue, registerDynamicStyle, getStyleValue } from './styleValueRegistry';
+import {
+  camelToKebab,
+  cssPropertyToCamel,
+  encodeArbitraryValue,
+  parseUtilityClass,
+  splitVariantPrefix,
+  breakpointClassPrefix,
+  normalizeBreakpointVariant,
+  resolveRootProperty,
+  ROOT_CAMEL_OVERRIDES,
+  isBareColorTokenName,
+} from './utilityClassNames';
+import { registerStyleValue, registerDynamicStyle, getStyleValue, getDynamicStyle } from './styleValueRegistry';
 import {
   SCALABLE_CSS_PROPERTIES,
   buildFluidClampWithExplicitMin,
@@ -22,43 +43,13 @@ import {
   type ResponsiveScales,
 } from './responsiveScaling';
 
-// Function name abbreviations for shorter class names
-const functionAbbreviations: Record<string, string> = {
-  blur: 'bl',
-  translateY: 'ty',
-  translateX: 'tx',
-  translate: 't',
-  scale: 'sc',
-  scaleX: 'scx',
-  scaleY: 'scy',
-  rotate: 'ro',
-  skew: 'sk',
-  skewX: 'skx',
-  skewY: 'sky',
-  repeat: 're',
-  minmax: 'mm',
-  calc: 'ca',
-};
-
 /**
  * Check if a value is a StyleMapping object
  */
 function isStyleMapping(value: unknown): value is StyleMapping {
-  return typeof value === 'object' && value !== null && '_mapping' in value && (value as StyleMapping)._mapping === true;
-}
-
-/**
- * Sanitize a value for use in a CSS class name
- * Replaces special characters with safe alternatives
- */
-function sanitizeClassValue(value: string): string {
-  return value
-    .replace(/\s+/g, '-')       // spaces to hyphens
-    .replace(/[()]/g, '')        // remove parentheses
-    .replace(/,/g, '_')          // commas to underscores
-    .replace(/%/g, 'p')          // percent to 'p'
-    .replace(/\./g, 'd')         // dots to 'd' (for decimals)
-    .replace(/[^\w-]/g, '');     // remove other special chars
+  return (
+    typeof value === 'object' && value !== null && '_mapping' in value && (value as StyleMapping)._mapping === true
+  );
 }
 
 /**
@@ -76,166 +67,184 @@ function shortHash(input: string): string {
 }
 
 /**
- * True if a class name contains characters illegal in CSS selectors. We
- * generate dynamic class names from CSS values; complex values (especially
- * Webflow `clamp(2*1rem, ((..2)/(90 - 20)*20)*1rem + ..*100vw, 4*1rem)`)
- * end up with `*`, `(`, `)`, `+`, `,` baked into the class name, none of
- * which are valid in CSS selectors. Browser silently drops the rule and
- * the styled property reverts to UA defaults. Hash-fallback gives us a
- * short, valid-CSS class name, with the actual value resolved via the
- * style-value registry at CSS generation time.
+ * Whether the natural `root-(--x)` / `root-[value]` form would round-trip to a DIFFERENT property
+ * than `prop`. Roots shared by a shorthand and a color/width longhand (`border` → border/borderColor,
+ * `outline` → outline/outlineWidth/outlineColor) are disambiguated on parse by value type via
+ * `resolveRootProperty` — so a color-looking value (notably any opaque `var(--x)`) bound to the
+ * SHORTHAND reads back as the color longhand. Callers fall back to the explicit arbitrary-property
+ * form (`[border:var(--x)]`) when this returns true.
+ *
+ * Mirrors the inverse parser's property derivation EXACTLY (`classToStyle`): `ROOT_CAMEL_OVERRIDES`
+ * wins first (px → paddingInline, …), else `resolveRootProperty`. Comparing kebab CSS names instead
+ * would false-positive on those overridden roots (`px` resolves to `padding`, not `padding-inline`).
  */
-function hasIllegalClassChars(className: string): boolean {
-  return /[^\w-]/.test(className);
+function rootFormMisresolves(root: string, prop: string, value: string): boolean {
+  const parsedProp = ROOT_CAMEL_OVERRIDES[root] ?? cssPropertyToCamel(resolveRootProperty(root, value));
+  return parsedProp !== prop;
 }
 
 /**
- * Converts a CSS property value to a utility class name
- * Example: { prop: "padding", value: "10px" } → "p-10px"
+ * Converts a CSS property value to a Tailwind-style utility class name.
+ * Examples:
+ *   { prop: "padding", value: "16px" }        → "p-4"   (exact scale step)
+ *   { prop: "padding", value: "13px" }        → "p-[13px]" (off-scale → arbitrary)
+ *   { prop: "display", value: "flex" }        → "flex"
+ *   { prop: "color", value: "primary" }       → "text-primary"
+ *   { prop: "width", value: "100%" }          → "w-full"
+ *   { prop: "textOverflow", value: "ellipsis" } → "[text-overflow:ellipsis]"
  *
- * For properties not in propertyMap, generates a dynamic class using
- * a shortened property name prefix (e.g., "textOverflow" → "txov-ellipsis")
+ * Values that can't be encoded reversibly fall back to a hash class
+ * (`pt-h1y9pr6i`) resolved through the style-value registry.
  */
 function propertyValueToClass(prop: string, value: string | number): string | null {
-  const prefix = propertyMap[prop];
-
-  // For properties not in propertyMap, generate a dynamic fallback class
-  if (!prefix) {
-    const stringValue = String(value);
-    // Generate a short prefix from the property name (first 2-4 chars of each word)
-    // e.g., "textOverflow" → "txov", "WebkitBackgroundClip" → "wbbg"
-    const dynamicPrefix = prop
-      .replace(/([A-Z])/g, '-$1')  // camelCase to kebab
-      .toLowerCase()
-      .split('-')
-      .filter(Boolean)
-      .map(word => word.slice(0, 2))  // first 2 chars of each word
-      .join('');
-
-    // Sanitize value for class name
-    const sanitizedValue = sanitizeClassValue(stringValue);
-    const className = `${dynamicPrefix}-${sanitizedValue}`;
-
-    // Convert camelCase to kebab-case for CSS property
-    const cssProperty = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
-
-    // Register in dynamic registry with property info
-    registerDynamicStyle(className, cssProperty, value);
-    return className;
-  }
-
   let stringValue = String(value);
 
   // Strip outer quotes from fontFamily values (e.g. "Space Grotesk" → Space Grotesk)
   if (prop === 'fontFamily') {
-    stringValue = stringValue.split(',').map(font => {
-      const trimmed = font.trim();
-      if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-          (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-        return trimmed.slice(1, -1);
-      }
-      return trimmed;
-    }).join(', ');
+    stringValue = stringValue
+      .split(',')
+      .map((font) => {
+        const trimmed = font.trim();
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+          return trimmed.slice(1, -1);
+        }
+        return trimmed;
+      })
+      .join(', ');
   }
 
-  let className: string | null = null;
-
-  // Check for special value mappings first
-  if (specialValueMappings[prop]) {
-    const mapping = specialValueMappings[prop];
-    if (mapping[stringValue]) {
-      className = mapping[stringValue];
-    }
+  // Static utilities (Tailwind names): display: flex → "flex", textAlign: center → "text-center"
+  const staticClass = staticUtilities[prop]?.[stringValue];
+  if (staticClass) {
+    registerStyleValue(staticClass, stringValue);
+    return staticClass;
   }
 
-  // Check for preset values (e.g., boxShadow: "2" → sh-2)
-  if (!className && prop === 'boxShadow' && shadowPresets[stringValue]) {
-    className = `sh-${stringValue}`;
+  // Preset values (e.g., boxShadow: "2" → shadow-2)
+  const shadowPreset = shadowPresets[stringValue];
+  if (prop === 'boxShadow' && shadowPreset) {
+    const className = `shadow-${stringValue}`;
+    registerStyleValue(className, shadowPreset);
+    return className;
   }
-  if (!className && (prop === 'background' || prop === 'backgroundImage') && gradientPresets[stringValue]) {
-    className = `gr-${stringValue}`;
+  const gradientPreset = gradientPresets[stringValue];
+  if ((prop === 'background' || prop === 'backgroundImage') && gradientPreset) {
+    const className = `bg-gradient-${stringValue}`;
+    registerStyleValue(className, gradientPreset);
+    return className;
   }
-  if (!className && prop === 'border' && borderPresets[stringValue]) {
-    className = `bd-${stringValue}`;
+  const borderPreset = borderPresets[stringValue];
+  if (prop === 'border' && borderPreset) {
+    const className = `border-preset-${stringValue}`;
+    registerStyleValue(className, borderPreset);
+    return className;
   }
 
-  // Handle CSS function values: blur(), translateY(), rotate(), scale(), repeat(), etc.
-  // Uses abbreviations for shorter class names: blur(8px) → bl8, translateY(-15px) → tyn15
-  if (!className && stringValue.includes('(') && stringValue.includes(')')) {
-    const funcMatch = stringValue.match(/^([a-zA-Z]+)\((.+)\)$/);
-    if (funcMatch) {
-      const [, funcName, args] = funcMatch;
-      const abbrev = functionAbbreviations[funcName] || funcName.slice(0, 2);
-      const argNormalized = args
-        .replace(/,\s*/g, '-')        // "3, 1fr" → "3-1fr"
-        .replace(/\s+/g, '')          // Remove spaces
-        .replace(/-(\d)/g, 'n$1')     // "-15px" → "n15px"
-        .replace(/px$/i, '')          // Remove trailing px for brevity
-        .replace(/%$/, 'p');          // "50%" → "50p"
-      className = `${prefix}-${abbrev}${argNormalized}`;
-    }
+  const root = propertyMap[prop];
+
+  // Properties without a Tailwind root use arbitrary-property syntax:
+  // textOverflow: ellipsis → "[text-overflow:ellipsis]"
+  if (!root) {
+    const cssProperty = camelToKebab(prop);
+    const encoded = encodeArbitraryValue(stringValue);
+    const className = encoded != null ? `[${cssProperty}:${encoded}]` : `${cssProperty}-h${shortHash(stringValue)}`;
+    registerDynamicStyle(className, cssProperty, value);
+    return className;
   }
 
-  // CSS variables (e.g., var(--background))
-  if (!className && stringValue.includes('var(')) {
-    const varMatch = stringValue.match(/var\((--[\w-]+)\)/);
-    if (varMatch) {
-      const varName = varMatch[1].replace('--', '');
-      className = `${prefix}-${varName}`;
+  let className: string | null = null;
+
+  // Named keyword values: width: 100% → w-full, margin: auto → m-auto
+  const kwTable = keywordValues[root];
+  if (kwTable) {
+    for (const [keyword, cssValue] of Object.entries(kwTable)) {
+      if (cssValue === stringValue) {
+        className = `${root}-${keyword}`;
+        break;
+      }
     }
   }
 
-  // Detect variable names for color/background properties (e.g., color: "text" → c-text)
-  // These are stored as plain names without var() wrapper and should be treated as variables
-  if (!className &&
-      (prop === 'color' || prop === 'backgroundColor' || prop === 'borderColor') &&
-      !stringValue.match(/^\d/) && !stringValue.includes('#') && !stringValue.includes('rgb')) {
-    className = `${prefix}-${stringValue}`;
+  // Generic keyword roots: cursor: pointer → cursor-pointer, transformOrigin: center → origin-center
+  if (!className && genericKeywordRoots.has(root) && /^[a-z][a-z-]*$/.test(stringValue)) {
+    className = `${root}-${stringValue}`;
   }
 
-  // Direct values (with units)
-  if (!className && (stringValue.match(/^\d+px$/) || stringValue.match(/^\d+em$/))) {
-    className = `${prefix}-${stringValue}`;
+  // Bare numeric values Tailwind-style: zIndex: 10 → z-10, opacity: 0.5 → opacity-50
+  if (!className && integerValueRoots.has(root) && /^-?\d+$/.test(stringValue)) {
+    className = `${root}-${stringValue}`;
   }
-
-  // Percentage values - convert % to p (e.g., "50%" → "50p")
-  if (!className && stringValue.match(/^\d+%$/)) {
-    const percentValue = stringValue.replace('%', 'p');
-    className = `${prefix}-${percentValue}`;
+  if (!className && prop === 'opacity') {
+    const num = Number(stringValue);
+    if (Number.isFinite(num) && num >= 0 && num <= 1) {
+      const scaled = Math.round(num * 100);
+      if (Math.abs(num * 100 - scaled) < 1e-9) {
+        className = `opacity-${scaled}`;
+      }
+    }
   }
 
-  // Handle values with spaces by replacing spaces with hyphens (e.g., "92px 0" → "p-92px-0")
-  if (!className && stringValue.includes(' ')) {
-    const spacedValue = stringValue.replace(/\s+/g, '-');
-    className = `${prefix}-${spacedValue}`;
+  // Named spacing scale (Tailwind steps): padding 16px → p-4, gap 24px → gap-6.
+  // Only EXACT steps; off-scale values fall through to the arbitrary form below.
+  // Keyword values (w-full, m-auto) are matched above, so they still win.
+  if (!className && SPACING_SCALE_ROOTS.has(root)) {
+    const step = SPACING_SCALE_REVERSE[stringValue];
+    if (step !== undefined) {
+      className = `${root}-${step}`;
+    }
   }
 
-  // Special handling for margin/padding "auto"
-  if (!className && stringValue === 'auto') {
-    className = `${prefix}-auto`;
+  // CSS variables: var(--x) → root-(--x). The `font-*` root is shared by font-weight and
+  // font-family and is disambiguated by value type — but a `var(--x)` value is ambiguous, so
+  // weight/size vars carry a Tailwind data-type hint (`number:` / `length:`) the parser reads
+  // back. Without it a `fontWeight: var(--h-fw)` binding would resolve to `font-family` (an
+  // invalid `font-family: 450`), dropping the weight entirely.
+  if (!className) {
+    const varMatch = stringValue.match(/^var\((--[\w-]+)\)$/);
+    if (varMatch) {
+      const varName = (varMatch[1] ?? '').slice(2); // strip the leading `--`
+      if (prop === 'fontSize') className = `text-(length:${varMatch[1]})`;
+      else if (prop === 'fontWeight') className = `font-(number:${varMatch[1]})`;
+      // The `border`/`outline` roots are shared by a shorthand and a color longhand
+      // (`border` vs `borderColor`). The inverse parser disambiguates by value type, but a
+      // `var(--x)` value is opaque and reads as a color — so `border-(--x)` would round-trip
+      // to `borderColor`. When the prop is the shorthand/width longhand, fall back to the
+      // unambiguous arbitrary-property form (`[border:var(--x)]`), which names it explicitly.
+      else if (rootFormMisresolves(root, prop, stringValue)) {
+        className = `[${camelToKebab(prop)}:${stringValue}]`;
+      }
+      // A `var(--token)` on a color-token prop IS a Meno token reference → emit the bare token
+      // form (`bg-muted`), matching the bare-value path so `var(--muted)` and `muted` agree.
+      // (Token-aware inverse recovers it; palette-shaped names fall through to the var shorthand.)
+      else if (colorTokenProps.has(prop) && isBareColorTokenName(varName)) {
+        className = `${root}-${varName}`;
+      } else className = `${root}-(${varMatch[1]})`;
+    }
   }
 
-  // Handle values with slash (e.g., aspectRatio "1/1" → "ar-1s1")
-  if (!className && stringValue.includes('/')) {
-    const slashValue = stringValue.replace(/\//g, 's');
-    className = `${prefix}-${slashValue}`;
+  // Bare color tokens (Meno convention): color: "primary" → text-primary
+  if (!className && colorTokenProps.has(prop) && isBareColorTokenName(stringValue)) {
+    className = `${root}-${stringValue}`;
   }
 
-  // For other cases, append the value
+  // Arbitrary value (Tailwind bracket syntax): padding: "92px 0" → p-[92px_0]
   if (!className) {
-    className = `${prefix}-${stringValue}`;
+    const encoded = encodeArbitraryValue(stringValue);
+    if (encoded != null) {
+      // Same shorthand/longhand guard as the var branch: a bare color value bound to the
+      // `border`/`outline` shorthand would parse back as the color longhand, so name the
+      // property explicitly via the arbitrary-property form instead of `root-[…]`.
+      className = rootFormMisresolves(root, prop, stringValue)
+        ? `[${camelToKebab(prop)}:${encoded}]`
+        : `${root}-[${encoded}]`;
+    }
   }
 
-  // Hash-fallback for class names with illegal CSS selector chars. Webflow's
-  // fluid `clamp(2*1rem, ((2 - .5)/70*20)*1rem + ..*100vw, 4*1rem)` would
-  // otherwise produce `pt-cl2*1rem-((2-.5)/70*20)*1rem+..*100vw-4*1rem`,
-  // with `*`, `(`, `)`, `+`, `,` — none of which are valid in CSS selectors.
-  // Browser drops the rule, the styled element reverts to defaults
-  // (paddings collapse to 0, etc.). Short FNV-1a hash + style-value
-  // registry preserves the original value for the CSS generator without
-  // baking it into the selector.
-  if (hasIllegalClassChars(className)) {
-    className = `${prefix}-h${shortHash(stringValue)}`;
+  // Hash-fallback for values that can't be encoded reversibly (quotes,
+  // brackets, literal underscores). The original value is preserved in the
+  // style-value registry for the CSS generator.
+  if (!className) {
+    className = `${root}-h${shortHash(stringValue)}`;
   }
 
   // Register original value for CSS generation (single registration point)
@@ -243,24 +252,19 @@ function propertyValueToClass(prop: string, value: string | number): string | nu
   return className;
 }
 
-// Get property order from propertyMap for consistent class ordering
-const propertyOrder = Object.keys(propertyMap);
-
 /**
  * Convert a style object to an array of utility classes
- * Example: { padding: "10px", display: "flex" } → ["p-10px", "flex"]
+ * Example: { padding: "10px", display: "flex" } → ["p-[10px]", "flex"]
  *
- * Properties are sorted according to propertyMap order to ensure
+ * Properties are sorted according to propertyOrder to ensure
  * dependent properties (like borderColor) come after their base (border)
  *
  * StyleMapping values are filtered out - they are handled at render time
  */
-export function stylesToClasses(
-  styles: StyleObject | Record<string, string | number> | null | undefined
-): string[] {
+export function stylesToClasses(styles: StyleObject | Record<string, string | number> | null | undefined): string[] {
   if (!styles) return [];
 
-  // Sort properties by their order in propertyMap
+  // Sort properties by their canonical order
   // This ensures border comes before borderColor, etc.
   const sortedProps = Object.keys(styles).sort((a, b) => {
     const indexA = propertyOrder.indexOf(a);
@@ -274,6 +278,7 @@ export function stylesToClasses(
   const classes: string[] = [];
   for (const prop of sortedProps) {
     const value = styles[prop];
+    if (value === undefined) continue;
     // Skip StyleMapping values - they are resolved at render time, not converted to classes
     if (isStyleMapping(value)) continue;
     const className = propertyValueToClass(prop, value);
@@ -287,10 +292,10 @@ export function stylesToClasses(
 /**
  * Convert a responsive style object to utility classes with responsive prefixes
  * Example: { base: { padding: "10px" }, tablet: { padding: "24px" } }
- *   → ["p-10px", "t-p-24px"]
+ *   → ["p-[10px]", "tablet:p-[24px]"]
  *
  * Also handles flat merged style objects:
- * Example: { padding: "10px", display: "flex" } → ["p-10px", "flex"]
+ * Example: { padding: "10px", display: "flex" } → ["p-[10px]", "flex"]
  */
 /** Values that don't make sense in a fluid container pattern. Mirrors cssGeneration.ts. */
 const CONTAINER_RESERVED_VALUES = new Set(['auto', 'inherit', 'initial', 'unset', '']);
@@ -322,7 +327,7 @@ function transformContainerIntent(style: StyleObject): StyleObject {
  * In fluid mode, consume per-node mobile overrides for scalable properties
  * into the base's `clamp()` value. The mobile value becomes the clamp's MIN
  * (small-viewport endpoint), the base stays as MAX. The mobile property is
- * then stripped from the mobile slice so no `.mob-*` @media rule is emitted
+ * then stripped from the mobile slice so no `mobile:*` @media rule is emitted
  * for it — avoiding the jump at the mobile breakpoint that a hard override
  * would create.
  *
@@ -332,12 +337,12 @@ function transformContainerIntent(style: StyleObject): StyleObject {
  *
  * Bails out when units mismatch, parsing fails, or the registered values
  * aren't plain numeric+unit strings — those cases fall back to today's
- * behavior (mobile emits its own .mob-* rule).
+ * behavior (mobile emits its own `mobile:*` rule).
  */
 function consumeMobileIntoBaseClamp(
   base: StyleObject,
   mobile: StyleObject,
-  responsiveScales: ResponsiveScales
+  responsiveScales: ResponsiveScales,
 ): { patchedBase: StyleObject; patchedMobile: StyleObject } {
   const fluidRange = responsiveScales.fluidRange ?? DEFAULT_FLUID_RANGE;
   const patchedBase: StyleObject = { ...base };
@@ -364,7 +369,7 @@ function consumeMobileIntoBaseClamp(
       baseParsed.value,
       baseParsed.unit,
       fluidRange.min,
-      fluidRange.max
+      fluidRange.max,
     );
 
     patchedBase[prop] = clampValue;
@@ -376,7 +381,7 @@ function consumeMobileIntoBaseClamp(
 
 export function responsiveStylesToClasses(
   styles: StyleObject | ResponsiveStyleObject | null | undefined,
-  options?: { fluidActive?: boolean; responsiveScales?: ResponsiveScales }
+  options?: { fluidActive?: boolean; responsiveScales?: ResponsiveScales },
 ): string[] {
   if (!styles) return [];
   const fluidActive = options?.fluidActive === true;
@@ -395,45 +400,35 @@ export function responsiveStylesToClasses(
     let baseSource = responsiveStyles.base;
     let mobileSource = responsiveStyles.mobile;
     if (fluidActive && responsiveScales?.enabled === true && baseSource && mobileSource) {
-      const { patchedBase, patchedMobile } = consumeMobileIntoBaseClamp(
-        baseSource,
-        mobileSource,
-        responsiveScales
-      );
+      const { patchedBase, patchedMobile } = consumeMobileIntoBaseClamp(baseSource, mobileSource, responsiveScales);
       baseSource = patchedBase;
       mobileSource = patchedMobile;
     }
 
     // Base styles (no prefix)
     if (baseSource) {
-      const base = fluidActive
-        ? transformContainerIntent(baseSource)
-        : baseSource;
+      const base = fluidActive ? transformContainerIntent(baseSource) : baseSource;
       classes.push(...stylesToClasses(base));
     }
 
-    // Tablet styles (t- prefix)
+    // Tablet styles (tablet: variant prefix)
     if (responsiveStyles.tablet) {
-      const tablet = fluidActive
-        ? transformContainerIntent(responsiveStyles.tablet)
-        : responsiveStyles.tablet;
+      const tablet = fluidActive ? transformContainerIntent(responsiveStyles.tablet) : responsiveStyles.tablet;
       const tabletClasses = stylesToClasses(tablet);
-      classes.push(...tabletClasses.map((cls) => `t-${cls}`));
+      const prefix = breakpointClassPrefix('tablet');
+      classes.push(...tabletClasses.map((cls) => `${prefix}${cls}`));
     }
 
-    // Mobile styles (mob- prefix to avoid conflict with margin)
+    // Mobile styles (mobile: variant prefix)
     if (mobileSource && Object.keys(mobileSource).length > 0) {
-      const mobile = fluidActive
-        ? transformContainerIntent(mobileSource)
-        : mobileSource;
+      const mobile = fluidActive ? transformContainerIntent(mobileSource) : mobileSource;
       const mobileClasses = stylesToClasses(mobile);
-      classes.push(...mobileClasses.map((cls) => `mob-${cls}`));
+      const prefix = breakpointClassPrefix('mobile');
+      classes.push(...mobileClasses.map((cls) => `${prefix}${cls}`));
     }
   } else {
     // Flat style object - treat all as base classes
-    const flat = fluidActive
-      ? transformContainerIntent(styles as StyleObject)
-      : (styles as StyleObject);
+    const flat = fluidActive ? transformContainerIntent(styles as StyleObject) : (styles as StyleObject);
     classes.push(...stylesToClasses(flat));
   }
 
@@ -442,57 +437,58 @@ export function responsiveStylesToClasses(
 
 /**
  * Parse a utility class back to CSS property and value
- * Example: "p-10px" → { padding: "10px" }
+ * Example: "p-[10px]" → { prop: "padding", value: "10px" }
  */
-export function classToStyle(className: string): { prop: string; value: string } | null {
-  // Remove responsive prefixes for parsing
-  let cleanClass = className;
-  let responsivePrefix = '';
-
-  if (className.startsWith('t-')) {
-    responsivePrefix = 't';
-    cleanClass = className.slice(2);
-  } else if (className.startsWith('mob-')) {
-    responsivePrefix = 'mob';
-    cleanClass = className.slice(4);
+export function classToStyle(
+  className: string,
+  knownTokens?: ReadonlySet<string>,
+): { prop: string; value: string } | null {
+  // Remove responsive variant prefix for parsing (tablet:p-[10px] → p-[10px])
+  const { base: cleanClass } = splitVariantPrefix(className);
+
+  // Static utilities and presets have fixed reverse mappings
+  if (staticUtilityReverse[cleanClass]) {
+    return staticUtilityReverse[cleanClass];
   }
-
-  // Check special cases from config
-  if (classToStyleSpecialCases[cleanClass]) {
-    return classToStyleSpecialCases[cleanClass];
+  if (presetClassReverse[cleanClass]) {
+    return presetClassReverse[cleanClass];
   }
 
-  // Parse prefix-value pattern (e.g., "p-10px", "m-20px")
-  const match = cleanClass.match(/^([a-z-]+)-(.*?)$/);
-  if (!match) return null;
+  const parsed = parseUtilityClass(cleanClass, knownTokens);
 
-  const [, prefix, value] = match;
-
-  // Find the property from the prefix
-  let prop = '';
-  for (const [key, val] of Object.entries(propertyMap)) {
-    if (val === prefix) {
-      prop = key;
-      break;
+  if (!parsed) {
+    // Dynamic (arbitrary-property hash) classes registered for unknown roots
+    const dynamic = getDynamicStyle(cleanClass);
+    if (dynamic) {
+      return { prop: cssPropertyToCamel(dynamic.property), value: String(dynamic.value) };
     }
+    return null;
   }
 
-  if (!prop) return null;
+  if (parsed.kind === 'arbitrary-property') {
+    return { prop: cssPropertyToCamel(parsed.property), value: parsed.value! };
+  }
 
   // Hash-fallback class — value is `h<base36>`, the real CSS value lives in
   // the style-value registry (set when the class was minted from a complex
-  // `clamp()` / `calc()` value that wouldn't fit in a CSS selector). Pull
-  // the real value back out so editor reads see the original expression.
-  if (/^h[0-9a-z]+$/.test(value)) {
+  // value that wouldn't fit in a class name). Pull the real value back out
+  // so editor reads see the original expression.
+  if (parsed.kind === 'hash') {
     const registered = getStyleValue(cleanClass);
-    if (registered != null) {
-      return { prop, value: String(registered) };
-    }
+    if (registered == null) return null;
+    const value = String(registered);
+    const root = parsed.root!;
+    const prop = ROOT_CAMEL_OVERRIDES[root] ?? cssPropertyToCamel(resolveRootProperty(root, value));
+    return { prop, value };
   }
 
-  // Handle CSS variables
-  if (value.includes('background') || value.includes('text') || value.includes('border')) {
-    return { prop, value: `var(--${value})` };
+  const root = parsed.root;
+  const prop = root && ROOT_CAMEL_OVERRIDES[root] ? ROOT_CAMEL_OVERRIDES[root] : cssPropertyToCamel(parsed.property);
+  let value = parsed.value!;
+
+  // Color token props store bare tokens (var(--primary) → "primary")
+  if (parsed.kind === 'var' && colorTokenProps.has(prop)) {
+    value = value.replace(/^var\(--([\w-]+)\)$/, '$1');
   }
 
   return { prop, value };
@@ -500,24 +496,18 @@ export function classToStyle(className: string): { prop: string; value: string }
 
 /**
  * Convert utility classes back to a style object
- * Example: ["p-10px", "t-p-24px"] → { base: { padding: "10px" }, tablet: { padding: "24px" } }
+ * Example: ["p-[10px]", "tablet:p-[24px]"] → { base: { padding: "10px" }, tablet: { padding: "24px" } }
  */
-export function classesToStyles(classes: string[]): ResponsiveStyleObject | null {
+export function classesToStyles(classes: string[], knownTokens?: ReadonlySet<string>): ResponsiveStyleObject | null {
   const styles: ResponsiveStyleObject = { base: {}, tablet: {}, mobile: {} };
 
   for (const className of classes) {
-    let breakpoint: 'base' | 'tablet' | 'mobile' = 'base';
-    let cleanClass = className;
-
-    if (className.startsWith('t-')) {
-      breakpoint = 'tablet';
-      cleanClass = className.slice(2);
-    } else if (className.startsWith('mob-')) {
-      breakpoint = 'mobile';
-      cleanClass = className.slice(4);
-    }
+    const { breakpoint: variant, base: cleanClass } = splitVariantPrefix(className);
+    // Accept both the current desktop-first form (`max-tablet:`) and the legacy bare form (`tablet:`).
+    const bp = normalizeBreakpointVariant(variant);
+    const breakpoint: 'base' | 'tablet' | 'mobile' = bp === 'tablet' ? 'tablet' : bp === 'mobile' ? 'mobile' : 'base';
 
-    const styleEntry = classToStyle(cleanClass);
+    const styleEntry = classToStyle(cleanClass, knownTokens);
     if (styleEntry) {
       if (!styles[breakpoint]) {
         styles[breakpoint] = {};
@@ -530,5 +520,88 @@ export function classesToStyles(classes: string[]): ResponsiveStyleObject | null
   if (Object.keys(styles.tablet || {}).length === 0) delete styles.tablet;
   if (Object.keys(styles.mobile || {}).length === 0) delete styles.mobile;
 
-  return Object.keys(styles.base || {}).length > 0 ? styles : null;
+  // Return the object when ANY breakpoint carries a declaration — not only base. A class string
+  // can legitimately style just a narrower breakpoint (e.g. "tablet:p-[16px]"), and dropping it to
+  // null there would lose class-string styling for that node (class-styling adapter, §11).
+  const hasAny =
+    Object.keys(styles.base || {}).length > 0 ||
+    Object.keys(styles.tablet || {}).length > 0 ||
+    Object.keys(styles.mobile || {}).length > 0;
+  return hasAny ? styles : null;
+}
+
+/**
+ * Whether a single style value can be stored as a STATIC utility class. Static strings (no
+ * `{{template}}`) and numbers can; template-bearing strings and `_mapping` objects cannot — a
+ * template would mint a broken `p-[{{x}}px]`, and a mapping is prop-driven. The latter must stay in
+ * the `style` object (rendered via the runtime var-bridge / `class:list`). This is the boundary that
+ * lets styling default to class storage while keeping dynamic values correct.
+ */
+export function isClassableStyleValue(value: unknown): boolean {
+  if (typeof value === 'number') return true;
+  if (typeof value === 'string') return !value.includes('{{');
+  return false;
+}
+
+function splitStyleBucket(bucket: StyleObject): {
+  classable: StyleObject;
+  residual: StyleObject;
+} {
+  const classable: StyleObject = {};
+  const residual: StyleObject = {};
+  for (const [k, v] of Object.entries(bucket)) {
+    if (isClassableStyleValue(v)) classable[k] = v as string | number;
+    else residual[k] = v as StyleMapping;
+  }
+  return { classable, residual };
+}
+
+/**
+ * Split a style value into the part storable as a utility-class string (static values) and the
+ * residual that must stay in the `style` object (templates + `_mapping`s). Preserves the responsive
+ * shape; a flat object is treated as `base`. Either side is null when it has no declarations. The
+ * canonical home (shared by the studio persistence boundary and the project-wide migration) for the
+ * "what can be a class" decision.
+ */
+export function splitStyleByClassability(style: StyleValue | null | undefined): {
+  classable: ResponsiveStyleObject | null;
+  residual: ResponsiveStyleObject | null;
+} {
+  if (!style || typeof style !== 'object') return { classable: null, residual: null };
+
+  if (isResponsiveStyle(style)) {
+    const classable: ResponsiveStyleObject = {};
+    const residual: ResponsiveStyleObject = {};
+    for (const [bp, bucket] of Object.entries(style)) {
+      if (!bucket || typeof bucket !== 'object') continue;
+      const split = splitStyleBucket(bucket);
+      if (Object.keys(split.classable).length > 0) classable[bp] = split.classable;
+      if (Object.keys(split.residual).length > 0) residual[bp] = split.residual;
+    }
+    return {
+      classable: Object.keys(classable).length > 0 ? classable : null,
+      residual: Object.keys(residual).length > 0 ? residual : null,
+    };
+  }
+
+  const split = splitStyleBucket(style as StyleObject);
+  return {
+    classable: Object.keys(split.classable).length > 0 ? { base: split.classable } : null,
+    residual: Object.keys(split.residual).length > 0 ? { base: split.residual } : null,
+  };
+}
+
+/**
+ * Whether a style value contains at least one prop `_mapping` (in any breakpoint) — flat or
+ * responsive. Prop-driven styling can't be a static utility class, so callers that gate class
+ * conversion (the studio panel, the project migration) check this. Single source of truth.
+ */
+export function styleHasMapping(style: StyleValue | null | undefined): boolean {
+  if (!style || typeof style !== 'object') return false;
+  const buckets = isResponsiveStyle(style) ? Object.values(style) : [style as Record<string, unknown>];
+  for (const bucket of buckets) {
+    if (!bucket || typeof bucket !== 'object') continue;
+    for (const v of Object.values(bucket)) if (isStyleMapping(v)) return true;
+  }
+  return false;
 }