meno-core 1.0.47 → 1.0.49

package/lib/server/webflow/styleMapper.ts

@@ -9,9 +9,17 @@ import type {
   ResponsiveStyleObject,
   StyleMapping,
   InteractiveStyles,
+  InteractiveStyleRule,
 } from '../../shared/types/styles';
 import type { BreakpointConfig } from '../../shared/breakpoints';
 import type { WebflowStyleClass, WebflowBreakpoint, WebflowPseudoState, CSSProperties } from './types';
+import {
+  type ResponsiveScales,
+  type CSSPropertyType,
+  getScaleMultiplier,
+  scalePropertyValue,
+} from '../../shared/responsiveScaling';
+import { isCssNamedColor } from '../../shared/cssNamedColors';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -24,6 +32,57 @@ const UNITLESS_PROPERTIES = new Set([
   'tab-size',
 ]);
 
+/**
+ * CSS properties that accept time values (`0`, `0s`, `0ms`). Excluded from
+ * the bare-zero → `0px` normalization below — `transition-duration: 0px`
+ * would be invalid and silently dropped.
+ */
+const TIME_PROPERTIES = new Set([
+  'transition-duration', 'transition-delay',
+  'animation-duration', 'animation-delay',
+]);
+
+/**
+ * Webflow's class system rejects bare `0` for length properties — it expects
+ * a unit. Numeric `0` already flows through as `0px` (see `styleObjectToCSS`),
+ * but string `'0'` (from authored `marginTop: '0'`, shorthand expansion of
+ * `margin: 0 auto`, etc.) needs the same treatment. Unitless props (opacity,
+ * z-index) and time props (transition-duration) keep the bare `0`.
+ */
+function normalizeZero(cssProp: string, cssValue: string): string {
+  if (cssValue !== '0') return cssValue;
+  if (UNITLESS_PROPERTIES.has(cssProp)) return cssValue;
+  if (TIME_PROPERTIES.has(cssProp)) return cssValue;
+  return '0px';
+}
+
+/**
+ * Color properties whose authored value can be a bare token (e.g. `"primary"`)
+ * that Meno's runtime auto-wraps into `var(--primary)` (see
+ * `cssGeneration.ts` `styleObjectToCSS`). Mirrored here so the Webflow exporter
+ * doesn't ship literal `"background-color: primary"` to the Designer — that
+ * value is invalid CSS and Webflow renders nothing. After wrapping, the
+ * second-pass `substituteVarsInStyleClass` in `nodeToWebflow` resolves the
+ * `var(--…)` against the project's theme/variable maps.
+ */
+const COLOR_PROPS_CAMEL = new Set(['color', 'backgroundColor', 'borderColor']);
+
+/**
+ * If `value` is a bare Meno color token on a color-accepting property, wrap it
+ * in `var(--…)`. Hex / rgb / hsl / any functional notation / already-wrapped
+ * `var(...)` / CSS-named keywords (red, transparent, currentColor, inherit, …)
+ * pass through unchanged.
+ */
+function maybeWrapColorVar(camelProp: string, value: string): string {
+  if (!COLOR_PROPS_CAMEL.has(camelProp)) return value;
+  if (!value) return value;
+  if (value.startsWith('#')) return value;
+  if (value.startsWith('var(')) return value;
+  if (value.includes('(')) return value;
+  if (isCssNamedColor(value)) return value;
+  return `var(--${value})`;
+}
+
 function isStyleMapping(value: unknown): value is StyleMapping {
   return (
     typeof value === 'object' &&
@@ -47,7 +106,87 @@ function toKebabCase(prop: string): string {
 }
 
 /**
- * Convert a flat StyleObject to CSS properties, skipping StyleMappings
+ * Split a CSS value at top-level whitespace, leaving parenthesised groups
+ * (`var(--x, 16px)`, `calc(1rem + 2px)`) intact as a single token.
+ */
+function splitTopLevel(value: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let buf = '';
+  for (const ch of value.trim()) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    if (depth === 0 && /\s/.test(ch)) {
+      if (buf) { out.push(buf); buf = ''; }
+      continue;
+    }
+    buf += ch;
+  }
+  if (buf) out.push(buf);
+  return out;
+}
+
+/**
+ * Expand `margin` / `padding` / `gap` shorthand values into the longhand
+ * properties Webflow's class system models directly (per-side margin/padding,
+ * per-axis row-gap/column-gap). Webflow drops or mis-renders these shorthands
+ * when written via `Style.setProperties`, so every Webflow-bound style flows
+ * through this expansion at the CSS-conversion boundary.
+ *
+ * Returns `null` when the property isn't a handled shorthand or the value
+ * shape doesn't match (1–4 tokens for margin/padding, 1–2 for gap). Callers
+ * fall through to passing the value as-is in those cases.
+ */
+function expandShorthand(cssProp: string, cssValue: string): CSSProperties | null {
+  if (cssProp !== 'margin' && cssProp !== 'padding' && cssProp !== 'gap') {
+    return null;
+  }
+  const parts = splitTopLevel(cssValue);
+
+  if (cssProp === 'gap') {
+    if (parts.length === 1) {
+      const v = normalizeZero('row-gap', parts[0]!);
+      return { 'row-gap': v, 'column-gap': v };
+    }
+    if (parts.length === 2) {
+      return {
+        'row-gap': normalizeZero('row-gap', parts[0]!),
+        'column-gap': normalizeZero('column-gap', parts[1]!),
+      };
+    }
+    return null;
+  }
+
+  // margin / padding
+  let top: string, right: string, bottom: string, left: string;
+  if (parts.length === 1) {
+    top = right = bottom = left = parts[0]!;
+  } else if (parts.length === 2) {
+    top = bottom = parts[0]!;
+    right = left = parts[1]!;
+  } else if (parts.length === 3) {
+    top = parts[0]!;
+    right = left = parts[1]!;
+    bottom = parts[2]!;
+  } else if (parts.length === 4) {
+    [top, right, bottom, left] = parts as [string, string, string, string];
+  } else {
+    return null;
+  }
+  return {
+    [`${cssProp}-top`]: normalizeZero(`${cssProp}-top`, top),
+    [`${cssProp}-right`]: normalizeZero(`${cssProp}-right`, right),
+    [`${cssProp}-bottom`]: normalizeZero(`${cssProp}-bottom`, bottom),
+    [`${cssProp}-left`]: normalizeZero(`${cssProp}-left`, left),
+  };
+}
+
+/**
+ * Convert a flat StyleObject to CSS properties, skipping StyleMappings.
+ * `margin`, `padding`, and `gap` shorthands are expanded in place (see
+ * `expandShorthand`) so Webflow's class system receives only longhands.
+ * Iteration order follows CSS cascade — a longhand declared after a
+ * shorthand wins; declared before, the shorthand's expansion clobbers it.
  */
 function styleObjectToCSS(style: StyleObject): CSSProperties {
   const css: CSSProperties = {};
@@ -56,11 +195,18 @@ function styleObjectToCSS(style: StyleObject): CSSProperties {
     if (value === '' || value === undefined || value === null) continue;
     if (typeof value === 'boolean' || typeof value === 'object') continue;
     const cssProp = toKebabCase(prop);
+    let cssValue: string;
     if (typeof value === 'number') {
       if (isNaN(value)) continue;
-      css[cssProp] = UNITLESS_PROPERTIES.has(cssProp) ? String(value) : `${value}px`;
+      cssValue = UNITLESS_PROPERTIES.has(cssProp) ? String(value) : `${value}px`;
+    } else {
+      cssValue = maybeWrapColorVar(prop, String(value));
+    }
+    const expanded = expandShorthand(cssProp, cssValue);
+    if (expanded) {
+      Object.assign(css, expanded);
     } else {
-      css[cssProp] = String(value);
+      css[cssProp] = normalizeZero(cssProp, cssValue);
     }
   }
   return css;
@@ -96,17 +242,154 @@ function collectStyleMappings(
 }
 
 /**
- * Map interactive style postfix to Webflow pseudo-state
+ * Map interactive style postfix to a Webflow pseudo-state.
+ * Order matters — longer suffixes (`:focus-visible`, `:focus-within`,
+ * `:nth-child(odd)`) must be tested before their substring matches.
  */
-function postfixToPseudoState(postfix: string): WebflowPseudoState | null {
-  if (postfix.includes(':hover')) return 'hover';
+export function postfixToPseudoState(postfix: string): WebflowPseudoState | null {
+  // Pseudo-class style: ':hover', ':focus-visible', etc.
   if (postfix.includes(':focus-visible')) return 'focus-visible';
+  if (postfix.includes(':focus-within')) return 'focus-within';
+  if (postfix.includes(':nth-child(odd)')) return 'nth-child(odd)';
+  if (postfix.includes(':nth-child(even)')) return 'nth-child(even)';
+  if (postfix.includes(':first-child')) return 'first-child';
+  if (postfix.includes(':last-child')) return 'last-child';
+  if (postfix.includes(':placeholder')) return 'placeholder';
+  if (postfix.includes(':empty')) return 'empty';
+  if (postfix.includes(':before')) return 'before';
+  if (postfix.includes(':after')) return 'after';
+  if (postfix.includes(':hover')) return 'hover';
   if (postfix.includes(':focus')) return 'focus';
   if (postfix.includes(':active')) return 'active';
   if (postfix.includes(':visited')) return 'visited';
+  if (postfix.includes(':pressed')) return 'pressed';
+  // Pseudo-element style: '::before', '::after', '::placeholder'
+  if (postfix.includes('::before')) return 'before';
+  if (postfix.includes('::after')) return 'after';
+  if (postfix.includes('::placeholder')) return 'placeholder';
   return null;
 }
 
+/**
+ * Whether an interactive-styles rule fits Webflow's class-system surface.
+ * "Yes" means: empty `prefix`, a known pseudo-state `postfix`, and a
+ * non-responsive `style` (no breakpoint subdivision). Webflow's
+ * `Style.setProperties({ pseudo })` covers exactly this case.
+ *
+ * Anything else (descendant selectors via `prefix`, class-style postfixes
+ * like `.is-open`, responsive pseudos that need media queries) gets routed
+ * to the manual-paste `interactiveCss` bundle via `generateInteractiveCSS`.
+ */
+export function isWebflowHandledRule(rule: InteractiveStyleRule): boolean {
+  if (rule.prefix && rule.prefix.trim().length > 0) return false;
+  if (!rule.postfix) return false;
+  if (postfixToPseudoState(rule.postfix) === null) return false;
+  const s = rule.style as ResponsiveStyleObject;
+  if (!s || typeof s !== 'object') return false;
+  const responsiveKeys = Object.keys(s).filter((k) => k !== 'base');
+  return responsiveKeys.length === 0;
+}
+
+/**
+ * Pick the Webflow breakpoint tier closest to a Meno breakpoint by its
+ * max-width threshold. Meno's responsive cascade is max-width based, and
+ * Webflow's tiers below `main` are also max-width — so we map the threshold
+ * into Webflow's bucket.
+ *
+ * Webflow tiers (max-width values per Webflow's defaults):
+ *   tiny < 480, small 480-767, medium 768-991, main 992-1279,
+ *   large 1280-1439, xl 1440-1919, xxl ≥ 1920.
+ */
+function widthToWebflowBreakpoint(maxWidthPx: number): WebflowBreakpoint {
+  if (maxWidthPx < 480) return 'tiny';
+  if (maxWidthPx < 768) return 'small';
+  if (maxWidthPx < 992) return 'medium';
+  if (maxWidthPx < 1280) return 'main';
+  if (maxWidthPx < 1440) return 'large';
+  if (maxWidthPx < 1920) return 'xl';
+  return 'xxl';
+}
+
+/**
+ * Resolve a Meno breakpoint name to its Webflow tier. The two well-known
+ * names (`tablet`, `mobile`) map to fixed tiers; custom names route by their
+ * configured numeric width via `widthToWebflowBreakpoint`. Defaults if a
+ * project's breakpoints config omits the entry.
+ */
+function menoBreakpointToWebflow(
+  bpName: string,
+  breakpoints: BreakpointConfig
+): WebflowBreakpoint {
+  if (bpName === 'tablet') return 'medium';
+  if (bpName === 'mobile') return 'small';
+  const entry = breakpoints[bpName];
+  if (entry && typeof entry.breakpoint === 'number') {
+    return widthToWebflowBreakpoint(entry.breakpoint);
+  }
+  // Unknown name with no width info — default to `main` (no-op).
+  return 'main';
+}
+
+/**
+ * Merge a CSS map into the breakpoints record on a WebflowStyleClass under
+ * the given Webflow tier, layering on top of anything already there.
+ */
+function mergeIntoBreakpoint(
+  cls: WebflowStyleClass,
+  tier: WebflowBreakpoint,
+  css: CSSProperties
+): void {
+  if (!cls.breakpoints) cls.breakpoints = {};
+  cls.breakpoints[tier] = { ...cls.breakpoints[tier], ...css };
+}
+
+/** Convert a kebab-case CSS property to camelCase for scale-category lookup. */
+function kebabToCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * For each scalable property in the class's base map, fill in auto-scaled
+ * values at every Meno breakpoint that doesn't already carry an explicit
+ * value for that property. Mirrors what Meno's runtime CSS generator does
+ * for utility classes, so the Webflow site renders the same numbers per
+ * breakpoint as the Meno preview.
+ *
+ * Skips values that still contain `var(--…)` — the variable-aware pass in
+ * `nodeToWebflow` handles those before this runs (it expands per-breakpoint
+ * variable values into authored breakpoint entries, which take precedence
+ * over global category scaling here).
+ */
+export function applyAutoScaling(
+  cls: WebflowStyleClass,
+  breakpoints: BreakpointConfig,
+  responsiveScales: ResponsiveScales | undefined
+): void {
+  if (!responsiveScales?.enabled) return;
+  const baseRef = responsiveScales.baseReference || 16;
+
+  for (const [prop, baseValue] of Object.entries(cls.base)) {
+    if (!baseValue || baseValue.includes('var(--')) continue;
+    const camelProp = kebabToCamel(prop) as CSSPropertyType;
+
+    for (const [bpName, bpEntry] of Object.entries(breakpoints)) {
+      if (!bpEntry) continue;
+      const scale = getScaleMultiplier(responsiveScales, camelProp, bpName);
+      if (scale === null) continue;
+      const scaled = scalePropertyValue(baseValue, baseRef, scale);
+      if (scaled === null || scaled === baseValue) continue;
+
+      const tier = menoBreakpointToWebflow(bpName, breakpoints);
+      if (!cls.breakpoints) cls.breakpoints = {};
+      const bucket = cls.breakpoints[tier] || {};
+      // Author override wins — only fill missing entries.
+      if (bucket[prop] !== undefined) continue;
+      bucket[prop] = scaled;
+      cls.breakpoints[tier] = bucket;
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main Mapper
 // ---------------------------------------------------------------------------
@@ -114,10 +397,41 @@ function postfixToPseudoState(postfix: string): WebflowPseudoState | null {
 export interface StyleMapperResult {
   /** The primary style class for this element */
   primaryClass: WebflowStyleClass;
-  /** Combo classes for StyleMapping variants */
+  /**
+   * Combo classes carrying *only* the deltas for the current instance's
+   * non-default StyleMapping prop values. Already filtered by the mapper —
+   * the caller attaches every entry to the element verbatim.
+   */
   comboClasses: WebflowStyleClass[];
 }
 
+export interface MapStylesOptions {
+  /**
+   * Resolved props for the current component instance. Only the value the
+   * mapping actually resolves to (`instanceProps[mapping.prop]`) becomes a
+   * combo on this element; other values are ignored. When omitted, no
+   * combos are emitted (page elements without a prop context).
+   */
+  instanceProps?: Record<string, unknown>;
+  /**
+   * Default values from the enclosing component's interface. When provided,
+   * each StyleMapping's default-value entry is baked into `primaryClass.base`
+   * so the primary represents the default-prop visual; combos cover only the
+   * non-default deltas. Omit for page-level elements (defaults unavailable).
+   */
+  componentDefaults?: Record<string, unknown>;
+  /**
+   * Suffix appended to combo class names so two placements that resolve their
+   * `var(--…)` refs against different ancestor themes occupy distinct map
+   * slots in `ctx.styleClasses`. Without this, the default theme's combo and a
+   * non-default theme's combo collapse onto the same name and the last-written
+   * one wins — silently corrupting whichever placement was processed earlier.
+   * Caller passes e.g. `'-theme-dark'`; empty/undefined means default theme,
+   * no suffix added. Caller is responsible for sanitizing the theme name.
+   */
+  themeSuffix?: string;
+}
+
 /**
  * Convert Meno element styles to Webflow style classes.
  *
@@ -125,13 +439,22 @@ export interface StyleMapperResult {
  * @param style - Element's responsive style object
  * @param interactiveStyles - Element's interactive (hover/focus/etc.) styles
  * @param breakpoints - Project breakpoint configuration
+ * @param responsiveScales - When `enabled`, auto-fill scaled per-breakpoint
+ *        values for scalable properties not explicitly authored at that
+ *        breakpoint (mirrors Meno's runtime CSS generator).
+ * @param options - Instance-aware combo emission. See `MapStylesOptions`.
  */
 export function mapStylesToWebflow(
   className: string,
   style: StyleObject | ResponsiveStyleObject | undefined,
   interactiveStyles: InteractiveStyles | undefined,
-  breakpoints: BreakpointConfig
+  breakpoints: BreakpointConfig,
+  responsiveScales?: ResponsiveScales,
+  options?: MapStylesOptions
 ): StyleMapperResult {
+  const instanceProps = options?.instanceProps;
+  const componentDefaults = options?.componentDefaults;
+  const themeSuffix = options?.themeSuffix ?? '';
   // Convert underscores to dashes for Webflow class naming convention
   const webflowClassName = className.replace(/_/g, '-');
 
@@ -141,6 +464,10 @@ export function mapStylesToWebflow(
   };
 
   // --- Base + breakpoint styles ---
+  // Meno's `base` is the desktop default → Webflow's `main` tier (set as
+  // `primaryClass.base` so the consumer writes it without a breakpoint
+  // option). Named tiers (`tablet`, `mobile`) and custom breakpoints route
+  // to Webflow tiers via `menoBreakpointToWebflow`.
   if (style) {
     if (isResponsiveStyle(style)) {
       const responsive = style as ResponsiveStyleObject;
@@ -149,93 +476,220 @@ export function mapStylesToWebflow(
         primaryClass.base = styleObjectToCSS(responsive.base);
       }
 
-      if (responsive.tablet) {
-        if (!primaryClass.breakpoints) primaryClass.breakpoints = {};
-        primaryClass.breakpoints.Tablet = styleObjectToCSS(responsive.tablet);
-      }
-
-      if (responsive.mobile) {
-        if (!primaryClass.breakpoints) primaryClass.breakpoints = {};
-        primaryClass.breakpoints.MobilePortrait = styleObjectToCSS(responsive.mobile);
-      }
-
-      // Handle additional custom breakpoints (map to closest Webflow breakpoint)
       for (const [bpName, bpStyle] of Object.entries(responsive)) {
-        if (!bpStyle || bpName === 'base' || bpName === 'tablet' || bpName === 'mobile') continue;
-        // Custom breakpoints map to Tablet as closest approximation
-        if (!primaryClass.breakpoints) primaryClass.breakpoints = {};
-        primaryClass.breakpoints.Tablet = {
-          ...primaryClass.breakpoints.Tablet,
-          ...styleObjectToCSS(bpStyle),
-        };
+        if (!bpStyle || bpName === 'base') continue;
+        const css = styleObjectToCSS(bpStyle);
+        if (Object.keys(css).length === 0) continue;
+        const tier = menoBreakpointToWebflow(bpName, breakpoints);
+        mergeIntoBreakpoint(primaryClass, tier, css);
       }
     } else {
-      // Flat style object — treat as base/Desktop
+      // Flat style object — treat as base/main.
       primaryClass.base = styleObjectToCSS(style as StyleObject);
     }
   }
 
-  // --- Interactive styles (hover, focus, etc.) ---
+  // --- Interactive styles (hover, focus, …) ---
+  // Pseudo-state postfixes with empty prefix and non-responsive ruleStyle go
+  // to `primaryClass.pseudoStates` so Webflow's class system applies them via
+  // `Style.setProperties({ pseudo })`. Anything else (prefix-built selectors,
+  // class-style postfixes, breakpoint-divided pseudos) is collected into
+  // `interactiveCss` server-side via `generateInteractiveCSS` — see
+  // `buildWebflow.ts` and `isWebflowHandledRule` below.
   if (interactiveStyles && interactiveStyles.length > 0) {
     for (const rule of interactiveStyles) {
-      if (!rule.postfix) continue;
+      if (!isWebflowHandledRule(rule)) continue;
+
+      const baseProps: CSSProperties = isResponsiveStyle(rule.style as StyleObject | ResponsiveStyleObject)
+        ? styleObjectToCSS(((rule.style as ResponsiveStyleObject).base) || {})
+        : styleObjectToCSS(rule.style as StyleObject);
 
-      const pseudoState = postfixToPseudoState(rule.postfix);
+      // Skip empty rules — writing an empty pseudoStates entry triggers a
+      // destructive wipe in `applyStyleScope` on re-import (it diffs
+      // `existing` against `next={}` and removes every property).
+      if (Object.keys(baseProps).length === 0) continue;
+
+      const pseudoState = postfixToPseudoState(rule.postfix!);
       if (!pseudoState) continue;
 
-      const ruleStyle = rule.style;
       if (!primaryClass.pseudoStates) primaryClass.pseudoStates = {};
-
-      if (isResponsiveStyle(ruleStyle)) {
-        const responsive = ruleStyle as ResponsiveStyleObject;
-        // Merge base styles into the pseudo-state
-        if (responsive.base) {
-          primaryClass.pseudoStates[pseudoState] = {
-            ...primaryClass.pseudoStates[pseudoState],
-            ...styleObjectToCSS(responsive.base),
-          };
-        }
-      } else {
-        primaryClass.pseudoStates[pseudoState] = {
-          ...primaryClass.pseudoStates[pseudoState],
-          ...styleObjectToCSS(ruleStyle as StyleObject),
-        };
-      }
+      primaryClass.pseudoStates[pseudoState] = {
+        ...primaryClass.pseudoStates[pseudoState],
+        ...baseProps,
+      };
     }
   }
 
-  // --- Combo classes for StyleMappings ---
+  // --- Default-prop bake + single consolidated combo for the instance ---
+  // Webflow combo classes only make sense as deltas: the primary carries the
+  // default-prop visual; one combo per element holds the merged deltas for
+  // every non-default StyleMapping prop value the instance authored. Folding
+  // every mapped delta into one combo (rather than one combo per prop) means
+  // each element wears exactly one extra class regardless of how many props
+  // its component declares — simpler in the Webflow Designer and avoids
+  // fan-out where two unrelated instances accidentally share a delta combo.
   const comboClasses: WebflowStyleClass[] = [];
   const mappings = collectStyleMappings(style);
 
+  const comboCss: CSSProperties = {};
+  const comboNameParts: string[] = [];
+
   for (const { property, mapping } of mappings) {
-    for (const [value, cssValue] of Object.entries(mapping.values)) {
-      if (cssValue === '' || cssValue === undefined) continue;
-
-      const comboName = `is-${sanitizeClassName(mapping.prop)}-${sanitizeClassName(String(value))}`;
-      const comboClass: WebflowStyleClass = {
-        name: comboName,
-        base: {
-          [toKebabCase(property)]: typeof cssValue === 'number'
-            ? (UNITLESS_PROPERTIES.has(toKebabCase(property)) ? String(cssValue) : `${cssValue}px`)
-            : String(cssValue),
-        },
-        comboParent: webflowClassName,
-      };
-      comboClasses.push(comboClass);
+    const defaultValue = componentDefaults?.[mapping.prop];
+    const defaultKey = defaultValue != null ? String(defaultValue) : undefined;
+
+    // Bake the default-value resolution into the primary class's base so the
+    // primary stands on its own for default-prop instances. Values authored
+    // outside the mapping (declared on `style.fontSize` directly) already
+    // landed in `primaryClass.base` via `styleObjectToCSS`.
+    if (defaultKey !== undefined && defaultKey in mapping.values) {
+      const defaultCss = mappingValueToCSS(property, mapping.values[defaultKey]);
+      if (defaultCss) {
+        // StyleMapping bakes feed into the primary's `main` tier (its `base`),
+        // matching how `styleObjectToCSS` handles non-mapped properties.
+        primaryClass.base = { ...primaryClass.base, ...defaultCss };
+      }
     }
+
+    if (!instanceProps) continue;
+    const instanceValue = instanceProps[mapping.prop];
+    if (instanceValue == null) continue;
+    const instanceKey = String(instanceValue);
+    if (instanceKey === defaultKey) continue;             // covered by primary
+    if (!(instanceKey in mapping.values)) continue;       // unknown value
+    const css = mappingValueToCSS(property, mapping.values[instanceKey]);
+    if (!css) continue;
+
+    Object.assign(comboCss, css);
+    const part = `${sanitizeClassName(mapping.prop)}-${sanitizeClassName(instanceKey)}`;
+    // Same prop appears once per mapping (e.g. `version` on both
+    // `backgroundColor` and `color` Button mappings) — dedupe so the combo
+    // name stays `is-version-secondary` rather than repeating the segment.
+    if (!comboNameParts.includes(part)) comboNameParts.push(part);
+  }
+
+  if (comboNameParts.length > 0 && Object.keys(comboCss).length > 0) {
+    // Sort so different declaration orders of the same prop set produce the
+    // same combo name — instances with identical variants share one class.
+    comboNameParts.sort();
+    comboClasses.push({
+      name: `is-${comboNameParts.join('-')}${themeSuffix}`,
+      base: comboCss,
+      comboParent: webflowClassName,
+    });
+  }
+
+  // --- Auto-scaling: fill in scaled values at each Meno breakpoint for any
+  // scalable base property the author hasn't already overridden. Variable
+  // refs (`var(--…)`) are skipped here — `nodeToWebflow` expands them with
+  // breakpoint awareness before this runs, so authored breakpoint values
+  // already capture the variable's per-breakpoint scaling.
+  applyAutoScaling(primaryClass, breakpoints, responsiveScales);
+  for (const combo of comboClasses) {
+    applyAutoScaling(combo, breakpoints, responsiveScales);
   }
 
   return { primaryClass, comboClasses };
 }
 
+/**
+ * Convert a single StyleMapping value (already looked up from `mapping.values`)
+ * into a CSSProperties entry, mirroring `styleObjectToCSS`'s unit handling
+ * and shorthand expansion. Returns `null` when the value is empty/missing.
+ */
+function mappingValueToCSS(
+  property: string,
+  rawValue: string | number | undefined | null
+): CSSProperties | null {
+  if (rawValue === '' || rawValue === undefined || rawValue === null) return null;
+  const cssProp = toKebabCase(property);
+  const cssValueStr = typeof rawValue === 'number'
+    ? (UNITLESS_PROPERTIES.has(cssProp) ? String(rawValue) : `${rawValue}px`)
+    : maybeWrapColorVar(property, String(rawValue));
+  return expandShorthand(cssProp, cssValueStr) ?? { [cssProp]: normalizeZero(cssProp, cssValueStr) };
+}
+
 /**
  * Sanitize a string for use as a CSS class name segment
  */
-function sanitizeClassName(name: string): string {
+export function sanitizeClassName(name: string): string {
   return name
     .toLowerCase()
     .replace(/[^a-z0-9-]/g, '-')
     .replace(/-+/g, '-')
     .replace(/^-|-$/g, '');
 }
+
+/**
+ * Build a single combo class from a component instance's style /
+ * interactiveStyles overrides — the `acceptsStyles` analogue of the
+ * prop-mapped combo in `mapStylesToWebflow`.
+ *
+ * Every override the instance authored — flat or responsive base values,
+ * per-breakpoint values, Webflow-handled pseudo-state values — is folded
+ * into one combo's `.base` / `.breakpoints` / `.pseudoStates`. The caller
+ * supplies a stable name (typically derived from the instance's outer
+ * location so two distinct instances don't collide) and the body root's
+ * primary class for `comboParent`. Returns `null` if no overrides survive
+ * the filters.
+ */
+export function buildInstanceStyleCombo(
+  comboName: string,
+  rootClassName: string,
+  style: StyleObject | ResponsiveStyleObject | undefined,
+  interactiveStyles: InteractiveStyles | undefined,
+  breakpoints: BreakpointConfig,
+  responsiveScales?: ResponsiveScales,
+): WebflowStyleClass | null {
+  const base: CSSProperties = {};
+  const bps: Partial<Record<WebflowBreakpoint, CSSProperties>> = {};
+  const pseudos: Partial<Record<WebflowPseudoState, CSSProperties>> = {};
+
+  if (style) {
+    if (isResponsiveStyle(style)) {
+      const responsive = style as ResponsiveStyleObject;
+      if (responsive.base) Object.assign(base, styleObjectToCSS(responsive.base));
+      for (const [bpName, bpStyle] of Object.entries(responsive)) {
+        if (!bpStyle || bpName === 'base') continue;
+        const css = styleObjectToCSS(bpStyle);
+        if (Object.keys(css).length === 0) continue;
+        const tier = menoBreakpointToWebflow(bpName, breakpoints);
+        bps[tier] = { ...bps[tier], ...css };
+      }
+    } else {
+      Object.assign(base, styleObjectToCSS(style as StyleObject));
+    }
+  }
+
+  if (interactiveStyles && interactiveStyles.length > 0) {
+    for (const rule of interactiveStyles) {
+      if (!isWebflowHandledRule(rule)) continue;
+      const ruleStyle = rule.style as StyleObject | ResponsiveStyleObject;
+      const flat = isResponsiveStyle(ruleStyle)
+        ? ((ruleStyle as ResponsiveStyleObject).base as StyleObject | undefined)
+        : (ruleStyle as StyleObject);
+      if (!flat) continue;
+      const css = styleObjectToCSS(flat);
+      if (Object.keys(css).length === 0) continue;
+      const pseudo = postfixToPseudoState(rule.postfix!);
+      if (!pseudo) continue;
+      pseudos[pseudo] = { ...pseudos[pseudo], ...css };
+    }
+  }
+
+  if (
+    Object.keys(base).length === 0
+    && Object.keys(bps).length === 0
+    && Object.keys(pseudos).length === 0
+  ) return null;
+
+  const cls: WebflowStyleClass = {
+    name: comboName,
+    base,
+    comboParent: rootClassName,
+  };
+  if (Object.keys(bps).length > 0) cls.breakpoints = bps;
+  if (Object.keys(pseudos).length > 0) cls.pseudoStates = pseudos;
+  applyAutoScaling(cls, breakpoints, responsiveScales);
+  return cls;
+}