meno-core 1.1.7 → 1.1.8

package/lib/shared/responsiveScaling.ts

@@ -206,9 +206,14 @@ export function getScaleMultiplier(
  * Returns array of individual values
  */
 export function parseMultiValue(valueStr: string): string[] {
-  // First, convert hyphen separators to spaces (for class names like "p-0-80px" → "0-80px")
-  // But only convert hyphens between values (digit/px followed by hyphen followed by digit/px)
-  const normalized = valueStr.replace(/(?<=\w)-(?=\d|auto|inherit|initial|unset)/g, ' ');
+  // Convert hyphen separators to spaces (for class-name-derived values like "0-80px" → "0 80px"),
+  // but NEVER when the value contains a CSS function/token. A hyphen inside `var(--text-6xl)` or
+  // `calc(100% - 20px)` is part of the identifier, not a value separator — splitting it corrupts the
+  // token (`var(--text-6xl)` → `var(--text 6xl)`, an invalid var reference the styles panel then
+  // shows at scaled breakpoints). Any value with `(` is a function and keeps its hyphens verbatim.
+  const normalized = valueStr.includes('(')
+    ? valueStr
+    : valueStr.replace(/(?<=\w)-(?=\d|auto|inherit|initial|unset)/g, ' ');
   return normalized
     .trim()
     .split(/\s+/)

package/lib/shared/styleUtils.ts

@@ -60,3 +60,56 @@ export function isStyleValue(style: unknown): style is StyleValue {
   // Check if it's a StyleObject
   return isStyleObject(style);
 }
+
+/**
+ * Rewrite the LOGICAL box-spacing props `paddingInline`/`paddingBlock`/`marginInline`/`marginBlock`
+ * to REGULAR physical padding/margin, in place. The `px`/`py`/`mx`/`my` classes decode (via
+ * `ROOT_CAMEL_OVERRIDES`) to those logical properties, which would surface in the Styles panel as
+ * "Padding Inline/Block" rows the author never asked for and emit as `padding-inline`/`padding-block`
+ * — logical properties that read as wrong to an author who wrote a plain `px-`/`py-` and behave subtly
+ * differently from physical padding (writing-mode / `direction`).
+ *
+ * Called from `classesToStyles` (so every class→style decode is already physical) and from
+ * `styleObjectToCSS` (defensive: also physicalizes a stray `[padding-inline:…]` arbitrary property).
+ *
+ * Conversion per family (`padding`, `margin`):
+ *   - both axes set, both plain strings, and no physical/shorthand key of that family already present
+ *     → one compact `padding`/`margin` shorthand `<block> <inline>` (`py-[100px] px-0` →
+ *     `padding: 100px 0px`, i.e. CSS's `vertical horizontal`)
+ *   - otherwise → the two physical side longhands for each present axis (`px-[100px]` alone →
+ *     paddingLeft + paddingRight), never overwriting a side the caller set explicitly so an
+ *     accompanying `pl-`/`pr-` still wins.
+ *
+ * A no-op when no logical box props are present. Returns the same object for chaining.
+ */
+export function physicalizeBoxSpacing<T extends Record<string, unknown>>(style: T): T {
+  const s = style as Record<string, unknown>;
+  for (const family of ['padding', 'margin'] as const) {
+    const inline = s[`${family}Inline`];
+    const block = s[`${family}Block`];
+    if (inline == null && block == null) continue;
+    delete s[`${family}Inline`];
+    delete s[`${family}Block`];
+    const hasPhysical =
+      s[family] != null ||
+      s[`${family}Top`] != null ||
+      s[`${family}Right`] != null ||
+      s[`${family}Bottom`] != null ||
+      s[`${family}Left`] != null;
+    // Both axes with no competing key → one shorthand. Bound (`_mapping`) axis values aren't
+    // string-composable, so they fall through to the side-longhand branch (which keeps the object).
+    if (typeof inline === 'string' && typeof block === 'string' && !hasPhysical) {
+      s[family] = `${block} ${inline}`;
+      continue;
+    }
+    if (inline != null) {
+      if (s[`${family}Left`] == null) s[`${family}Left`] = inline;
+      if (s[`${family}Right`] == null) s[`${family}Right`] = inline;
+    }
+    if (block != null) {
+      if (s[`${family}Top`] == null) s[`${family}Top`] = block;
+      if (s[`${family}Bottom`] == null) s[`${family}Bottom`] = block;
+    }
+  }
+  return style;
+}

package/lib/shared/tailwindThemeScale.ts

@@ -217,6 +217,97 @@ export const THEME_SCALE_BY_CSSVAR: ReadonlyMap<string, ThemeScaleEntry> = new M
   THEME_SCALE_ENTRIES.map((e) => [e.cssVar, e]),
 );
 
+/**
+ * Specs indexed by class root. A root can carry MORE than one spec — `font-*` reads both
+ * `--font-weight-*` (weight) and `--font-*` (family) — so which namespace a class lands in
+ * is decided by the token the project actually declares, not by the class shape.
+ */
+const SPECS_BY_ROOT: ReadonlyMap<string, ScaleSpec[]> = (() => {
+  const map = new Map<string, ScaleSpec[]>();
+  for (const spec of SPECS) {
+    const existing = map.get(spec.root);
+    if (existing) existing.push(spec);
+    else map.set(spec.root, [spec]);
+  }
+  return map;
+})();
+
+export interface ThemeScaleTokenMatch {
+  property: string;
+  cssVar: string;
+  value: string;
+}
+
+/**
+ * Generic token fallback: resolve `<root>-<suffix>` against the PROJECT's own theme tokens
+ * when the suffix isn't one of the built-in scale steps above. `font-display` →
+ * `font-family: var(--font-display)`, but only when the project declares `--font-display`.
+ *
+ * This is what makes a project-specific token a first-class utility class. Without it only
+ * the built-in suffixes (`font-sans`, `text-lg`, …) resolve, and a custom token needs the
+ * explicit `font-(--font-display)` var form — while the natural `font-display` silently
+ * lands in `class=""` as dead weight that styles nothing.
+ *
+ * Gated on `knownTokens` deliberately: an undeclared `font-typo` stays an unrecognized
+ * foreign class rather than emitting an inert `var(--font-typo)`. A typo must not look
+ * like it worked. When a root spans two namespaces the declared one wins; if both are
+ * declared the first spec listed wins, which is why the weight spec precedes family.
+ */
+export function resolveThemeScaleToken(
+  root: string,
+  suffix: string,
+  knownTokens: ReadonlySet<string> | undefined,
+): ThemeScaleTokenMatch | null {
+  if (!knownTokens || !suffix) return null;
+  const specs = SPECS_BY_ROOT.get(root);
+  if (!specs) return null;
+  for (const spec of specs) {
+    const name = `${spec.varPrefix}-${suffix}`;
+    if (knownTokens.has(name)) {
+      return { property: spec.property, cssVar: `--${name}`, value: `var(--${name})` };
+    }
+  }
+  return null;
+}
+
+/**
+ * Inverse of `resolveThemeScaleToken`: the compact class for a project token that isn't a
+ * built-in scale step. `--font-display` + `font-family` → `font-display`. Keeps the styles
+ * panel from rewriting a hand-authored `font-display` into `font-(--font-display)` on the
+ * first round-trip. The property gate is what stops `--font-weight-bold` from being read
+ * under the family namespace (both share the `font-` prefix).
+ */
+export function themeScaleClassForToken(cssVar: string, property: string): string | null {
+  const name = cssVar.startsWith('--') ? cssVar.slice(2) : cssVar;
+  for (const spec of SPECS) {
+    if (spec.property !== property) continue;
+    const prefix = `${spec.varPrefix}-`;
+    if (name.startsWith(prefix) && name.length > prefix.length) {
+      return `${spec.root}-${name.slice(prefix.length)}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Class root → camelCase property, for merge-key recovery where the token set ISN'T
+ * available (the meno-astro runtime). Lets a project-token class conflict-detect against a
+ * built-in one — `font-display` must override `font-sans` on the same element.
+ *
+ * `text` is deliberately absent: it collides with the color root, and `COLOR_ROOT_TO_PROP`
+ * already claims it. `font` resolves to fontFamily, so a project defining a custom
+ * `--font-weight-*` token gets a merge key of fontFamily at runtime — an accepted
+ * imprecision (custom weight tokens are rare, and studio, which has the token set, is exact).
+ */
+export const THEME_SCALE_ROOT_PROPERTY: Readonly<Record<string, string>> = {
+  font: 'fontFamily',
+  rounded: 'borderRadius',
+  shadow: 'boxShadow',
+  leading: 'lineHeight',
+  tracking: 'letterSpacing',
+  'max-w': 'maxWidth',
+};
+
 /**
  * The CSS value a themed class resolves to: a plain `var(--token)` reference with no fallback.
  * Renders the project variable when defined, inert otherwise (token-based by design — no baked

package/lib/shared/types/components.ts

@@ -9,7 +9,17 @@ import type { LibrariesConfig } from './libraries';
 /**
  * Prop type definitions
  */
-export type PropType = 'string' | 'select' | 'boolean' | 'number' | 'link' | 'file' | 'rich-text' | 'embed' | 'list';
+export type PropType =
+  | 'string'
+  | 'select'
+  | 'boolean'
+  | 'number'
+  | 'link'
+  | 'file'
+  | 'rich-text'
+  | 'embed'
+  | 'list'
+  | 'reference';
 
 /**
  * Project-level enum configuration
@@ -20,11 +30,12 @@ export type EnumsConfig = Record<string, readonly string[]>;
 /**
  * Internationalization (i18n) value object
  * Keys are locale codes (e.g., 'en', 'pl', 'de')
- * Values can be strings (for string props) or arrays (for list props)
+ * Values can be strings (for string props), arrays (for list props), or booleans
+ * (for a node's localized `if` — per-locale visibility)
  */
 export interface I18nValue {
   _i18n: true;
-  [locale: string]: string | unknown[] | true; // true is for the _i18n marker, arrays for list props
+  [locale: string]: string | unknown[] | boolean; // `_i18n: true` is the marker; arrays for list props, booleans for localized visibility
 }
 
 /**
@@ -64,7 +75,7 @@ export interface LinkPropValue {
  * Base prop definition without list-specific fields
  */
 export interface BasePropDefinition {
-  type: Exclude<PropType, 'list'>;
+  type: Exclude<PropType, 'list' | 'reference'>;
   default?: string | number | boolean | I18nValue | LinkPropValue;
   options?: readonly string[]; // Required for "select" type (inline options)
   enumName?: string; // For "select" type: reference to project-level enum
@@ -95,10 +106,30 @@ export interface ListPropDefinition {
   default?: ListItemValue[];
 }
 
+/**
+ * Reference prop definition — a hand-picked selection of CMS items from a collection.
+ *
+ * A component declares a reference prop (e.g. `posts`) bound to a `collection`; each
+ * instance stores the chosen item id(s) as its value: a single id string when `multiple`
+ * is false, an ordered id array when true. The component body iterates the selection with a
+ * `list` node whose `sourceType: 'collection'`, `source: <collection>`, and
+ * `items: "{{<prop>}}"` — the runtime's getCollectionList resolves the ids to full items
+ * (order-preserving, missing ids skipped). Edited per-instance via the CMS item picker.
+ */
+export interface ReferencePropDefinition {
+  type: 'reference';
+  /** Collection the pickable items come from (e.g. "blog"). */
+  collection: string;
+  /** Multi-select (ordered id array) vs single (id string). Defaults to multi in the UI. */
+  multiple?: boolean;
+  /** Default selection: an ordered id array (multi) or a single id (single). */
+  default?: string | string[];
+}
+
 /**
  * Prop definition with improved type safety
  */
-export type PropDefinition = BasePropDefinition | ListPropDefinition;
+export type PropDefinition = BasePropDefinition | ListPropDefinition | ReferencePropDefinition;
 
 /**
  * Type guard to check if a prop definition is a list type
@@ -108,10 +139,17 @@ export function isListPropDefinition(def: PropDefinition): def is ListPropDefini
 }
 
 /**
- * Type guard to check if a prop definition is a base (non-list) type
+ * Type guard to check if a prop definition is a reference (CMS item picker) type
+ */
+export function isReferencePropDefinition(def: PropDefinition): def is ReferencePropDefinition {
+  return def.type === 'reference';
+}
+
+/**
+ * Type guard to check if a prop definition is a base (non-list, non-reference) type
  */
 export function isBasePropDefinition(def: PropDefinition): def is BasePropDefinition {
-  return def.type !== 'list';
+  return def.type !== 'list' && def.type !== 'reference';
 }
 
 /**

package/lib/shared/types/index.ts

@@ -206,6 +206,7 @@ export {
   PERMISSION_ROLES,
   RESOURCE_KINDS,
   CONFIG_AREAS,
+  LEGACY_CONFIG_AREA_ALIASES,
   CURRENT_PERMISSIONS_VERSION,
 } from './permissions';
 

package/lib/shared/types/permissions.ts

@@ -33,19 +33,35 @@ export const RESOURCE_KINDS: readonly ResourceKind[] = ['page', 'component', 'cm
 
 /**
  * Named global-config capabilities (the `config` resource kind's id namespace):
- *   - `project`   → `project.config.json` (site URL, breakpoints, fonts, …)
- *   - `colors`    → `colors.json`
- *   - `variables` → `variables.json`
- *   - `i18n`      → locale config inside `project.config.json`
+ *   - `project` → `project.config.json` (site URL, breakpoints, fonts, …)
+ *   - `theme`   → `src/styles/theme.css` — colors AND variables (design tokens)
+ *   - `i18n`    → locale config inside `project.config.json`
  *
- * NOTE: `i18n` lives *inside* `project.config.json`, so the CI checker (which
- * maps whole files) enforces it at `project` granularity — granting `i18n`
- * without `project` is advisory only (no file maps to it on its own), and
- * granting `project` implies `i18n`.
+ * Areas track FILE granularity, because the CI checker maps whole changed files
+ * back to a resource. Two consequences:
+ *
+ * - `theme` is a single area (not separate `colors` / `variables`) because both
+ *   halves live in the one `theme.css` stylesheet — the project's sole token
+ *   source of truth. Nothing can grant one half without the other.
+ * - `i18n` lives *inside* `project.config.json`, so the checker enforces it at
+ *   `project` granularity — granting `i18n` without `project` is advisory only
+ *   (no file maps to it on its own), and granting `project` implies `i18n`.
  */
-export type ConfigArea = 'project' | 'colors' | 'variables' | 'i18n';
+export type ConfigArea = 'project' | 'theme' | 'i18n';
+
+export const CONFIG_AREAS: readonly ConfigArea[] = ['project', 'theme', 'i18n'] as const;
 
-export const CONFIG_AREAS: readonly ConfigArea[] = ['project', 'colors', 'variables', 'i18n'] as const;
+/**
+ * Pre-`theme` area names, kept readable so policies committed before colors and
+ * variables collapsed into `theme.css` still resolve. Both map to `theme`, which
+ * WIDENS such a grant: an editor allowed only `colors` may now also change
+ * variables. That is the granularity the single stylesheet actually has, and
+ * this is a soft (UI-coordination) boundary — see the file header.
+ */
+export const LEGACY_CONFIG_AREA_ALIASES: Readonly<Record<string, ConfigArea>> = {
+  colors: 'theme',
+  variables: 'theme',
+};
 
 /**
  * A reference to one editable resource, checked against a {@link PermissionRule}.
@@ -72,7 +88,7 @@ export interface PermissionRule {
   components?: string[];
   /** CMS collection ids, e.g. `["posts", "*"]`. */
   cms?: string[];
-  /** Config areas, e.g. `["colors", "variables"]` or `["*"]`. */
+  /** Config areas ({@link ConfigArea}), e.g. `["theme", "i18n"]` or `["*"]`. */
   config?: string[];
 }
 

package/lib/shared/utilityClassMapper.test.ts

@@ -461,6 +461,50 @@ describe('utilityClassMapper', () => {
       expect(classToStyle('border-wrapper')).toBeNull();
     });
 
+    test('project theme tokens resolve on theme-scale roots, gated on knownTokens', () => {
+      const tokens = new Set(['font-display', 'radius-card', 'shadow-glow', 'text-hero']);
+      // The whole point: `font-display` is a font-FAMILY, not the font-weight the `font` prefix
+      // map would otherwise imply.
+      expect(classToStyle('font-display', tokens)).toEqual({
+        prop: 'fontFamily',
+        value: 'var(--font-display)',
+      });
+      expect(classToStyle('rounded-card', tokens)).toEqual({
+        prop: 'borderRadius',
+        value: 'var(--radius-card)',
+      });
+      expect(classToStyle('shadow-glow', tokens)).toEqual({
+        prop: 'boxShadow',
+        value: 'var(--shadow-glow)',
+      });
+      // Undeclared token stays a foreign class — a typo must not emit an inert var().
+      expect(classToStyle('font-dispaly', tokens)).toBeNull();
+      // No token set at all (the astro runtime) → unresolved, as before.
+      expect(classToStyle('font-display')).toBeNull();
+      // Built-in scale steps still win and are token-set-free.
+      expect(classToStyle('font-sans', tokens)).toEqual({ prop: 'fontFamily', value: 'var(--font-sans)' });
+    });
+
+    test('a bare color token keeps winning a shared root over the theme-scale namespace', () => {
+      // `--text-primary` is overwhelmingly a COLOR name in practice; reading `text-primary` as a
+      // font-size the moment a theme declares it would break every project that names it that way.
+      expect(classToStyle('text-primary', new Set(['primary', 'text-primary']))).toEqual({
+        prop: 'color',
+        value: 'primary',
+      });
+      // With no color token of that name, the font-size namespace is free to claim it.
+      expect(classToStyle('text-hero', new Set(['text-hero']))).toEqual({
+        prop: 'fontSize',
+        value: 'var(--text-hero)',
+      });
+    });
+
+    test('theme-token classes round-trip instead of degrading to the var form', () => {
+      expect(stylesToClasses({ fontFamily: 'var(--font-display)' })).toContain('font-display');
+      // An unknown property/namespace pairing still falls back to the explicit var form.
+      expect(stylesToClasses({ color: 'var(--font-display)' })).not.toContain('font-display');
+    });
+
     test('composes across classes without collision', () => {
       expect(classesToStyles(['border', 'border-b-2', 'border-dashed'])).toEqual({
         base: {
@@ -889,6 +933,8 @@ describe('utilityClassMapper', () => {
       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' });
+      // Singular `classToStyle` yields the LOGICAL intermediate (one class can't carry a two-sided
+      // expansion); `classesToStyles` physicalizes the whole object — see the `px/py/mx/my` block below.
       expect(classToStyle('px-4')).toEqual({ prop: 'paddingInline', value: '16px' });
       expect(classToStyle('w-64')).toEqual({ prop: 'width', value: '256px' });
     });
@@ -904,6 +950,55 @@ describe('utilityClassMapper', () => {
     });
   });
 
+  describe('px/py/mx/my decode to REGULAR padding/margin (not logical inline/block)', () => {
+    test('a lone axis → its two physical side longhands', () => {
+      expect(classesToStyles(['px-[100px]'])).toEqual({ base: { paddingLeft: '100px', paddingRight: '100px' } });
+      expect(classesToStyles(['py-4'])).toEqual({ base: { paddingTop: '16px', paddingBottom: '16px' } });
+      expect(classesToStyles(['mx-auto'])).toEqual({ base: { marginLeft: 'auto', marginRight: 'auto' } });
+    });
+
+    test('both axes with no competing key → one compact shorthand (block inline)', () => {
+      expect(classesToStyles(['px-0', 'py-[100px]'])).toEqual({ base: { padding: '100px 0px' } });
+      expect(classesToStyles(['mx-[8px]', 'my-[4px]'])).toEqual({ base: { margin: '4px 8px' } });
+    });
+
+    test('an explicit physical side wins over the axis shorthand', () => {
+      // `pl-[50px]` must survive: the axis fills only the sides the caller left unset.
+      expect(classesToStyles(['px-[100px]', 'pl-[50px]'])).toEqual({
+        base: { paddingLeft: '50px', paddingRight: '100px' },
+      });
+    });
+
+    test('physicalization is per-breakpoint', () => {
+      expect(classesToStyles(['px-[100px]', 'max-lg:py-[8px]'])).toEqual({
+        base: { paddingLeft: '100px', paddingRight: '100px' },
+        tablet: { paddingTop: '8px', paddingBottom: '8px' },
+      });
+    });
+
+    test('no logical box props ever leak out of a multi-class decode', () => {
+      const decoded = classesToStyles(['px-4', 'py-2', 'mx-2', 'my-1']);
+      const keys = Object.keys(decoded?.base ?? {});
+      expect(keys.some((k) => /Inline$|Block$/.test(k))).toBe(false);
+    });
+
+    test('physicalize:false keeps the LOGICAL axis prop (one row per axis, for the Styles panel)', () => {
+      // The panel opts out so px-/py- show as a single Padding X/Y row and re-emit px-/py- on save.
+      expect(classesToStyles(['px-[100px]'], undefined, { physicalize: false })).toEqual({
+        base: { paddingInline: '100px' },
+      });
+      expect(classesToStyles(['py-4'], undefined, { physicalize: false })).toEqual({
+        base: { paddingBlock: '16px' },
+      });
+      expect(classesToStyles(['px-0', 'py-[100px]'], undefined, { physicalize: false })).toEqual({
+        base: { paddingInline: '0px', paddingBlock: '100px' }, // two axes, NOT collapsed to `padding`
+      });
+      expect(classesToStyles(['mx-auto', 'my-[4px]'], undefined, { physicalize: false })).toEqual({
+        base: { marginInline: 'auto', marginBlock: '4px' },
+      });
+    });
+  });
+
   describe('bare color tokens (token-aware)', () => {
     const TOKENS = new Set(['primary', 'text', 'border', 'border-light']);
 
@@ -1012,6 +1107,16 @@ describe('utilityClassMapper', () => {
       expect(classMergeKey('m_hero_ab12cd')).toBeNull();
       expect(classMergeKey('js-toggle')).toBeNull();
     });
+
+    test('project theme-token class conflicts with the built-in scale on the same root', () => {
+      // The runtime has no token set, so `font-display` can't be resolved — but its property is
+      // recoverable from the root, which is what makes it override `font-sans` on a merge.
+      expect(classMergeKey('font-display')).toBe(classMergeKey('font-sans'));
+      expect(classMergeKey('rounded-card')).toBe(classMergeKey('rounded-lg'));
+      expect(classMergeKey('shadow-glow')).toBe(classMergeKey('shadow-md'));
+      // Distinct properties must NOT collide.
+      expect(classMergeKey('font-display')).not.toBe(classMergeKey('shadow-glow'));
+    });
   });
 
   describe('mergeInstanceClasses', () => {

package/lib/shared/utilityClassMapper.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ResponsiveStyleObject, StyleObject, StyleMapping, StyleValue } from './types';
-import { isResponsiveStyle } from './styleUtils';
+import { isResponsiveStyle, physicalizeBoxSpacing } from './styleUtils';
 import {
   propertyMap,
   propertyOrder,
@@ -39,7 +39,7 @@ import {
   isBareColorTokenName,
 } from './utilityClassNames';
 import { registerStyleValue, registerDynamicStyle, getStyleValue, getDynamicStyle } from './styleValueRegistry';
-import { THEME_SCALE_BY_CSSVAR } from './tailwindThemeScale';
+import { THEME_SCALE_BY_CSSVAR, THEME_SCALE_ROOT_PROPERTY, themeScaleClassForToken } from './tailwindThemeScale';
 import {
   SCALABLE_CSS_PROPERTIES,
   buildFluidClampWithExplicitMin,
@@ -115,6 +115,12 @@ function propertyValueToClass(prop: string, value: string | number): string | nu
     if (entry && entry.property === camelToKebab(prop)) {
       return entry.className;
     }
+    // Project token outside the built-in scale (`var(--font-display)` → `font-display`).
+    // Without this the value falls through to the explicit var form below, so a hand-authored
+    // `font-display` would be rewritten to `font-(--font-display)` the first time the styles
+    // panel round-trips the element — same rendering, gratuitous churn in the .astro diff.
+    const tokenClass = themeScaleClassForToken(varRef[1] ?? '', camelToKebab(prop));
+    if (tokenClass) return tokenClass;
   }
 
   // Strip outer quotes from fontFamily values (e.g. "Space Grotesk" → Space Grotesk)
@@ -564,7 +570,11 @@ export function classToStyle(
  * Convert utility classes back to a style object
  * Example: ["p-[10px]", "tablet:p-[24px]"] → { base: { padding: "10px" }, tablet: { padding: "24px" } }
  */
-export function classesToStyles(classes: string[], knownTokens?: ReadonlySet<string>): ResponsiveStyleObject | null {
+export function classesToStyles(
+  classes: string[],
+  knownTokens?: ReadonlySet<string>,
+  options?: { physicalize?: boolean },
+): ResponsiveStyleObject | null {
   const styles: ResponsiveStyleObject = { base: {}, tablet: {}, mobile: {} };
 
   for (const className of classes) {
@@ -594,6 +604,25 @@ export function classesToStyles(classes: string[], knownTokens?: ReadonlySet<str
     }
   }
 
+  // Physicalize logical box spacing so `px`/`py`/`mx`/`my` classes decode to REGULAR padding/margin
+  // (paddingLeft/Right, paddingTop/Bottom, or the compact `padding`/`margin` shorthand) rather than
+  // the logical `paddingInline`/`paddingBlock` their roots map to. Applied per breakpoint bucket, after
+  // the size-*/rounded-* mirroring above (which can add a physical side the shorthand collapse must
+  // see). The singular `classToStyle` keeps the logical prop — it can't express a two-sided expansion
+  // or the both-axes shorthand from one class — so this whole-object pass is the right home. No-op
+  // unless a logical box prop is present.
+  //
+  // `physicalize: false` keeps the LOGICAL axis prop (`paddingInline`/`paddingBlock`/…) so the Styles
+  // panel can show one "Padding X/Y" row per axis instead of two physical side rows (and re-emit the
+  // idiomatic `px-`/`py-` on save, not `pl-`+`pr-`). Only the panel adapter opts out; every other
+  // caller (e.g. the interactive-variant lossless gate) keeps the physical default it round-trips against.
+  if (options?.physicalize !== false) {
+    for (const bp of ['base', 'tablet', 'mobile'] as const) {
+      const bucket = styles[bp];
+      if (bucket) physicalizeBoxSpacing(bucket);
+    }
+  }
+
   // Clean up empty breakpoints
   if (Object.keys(styles.tablet || {}).length === 0) delete styles.tablet;
   if (Object.keys(styles.mobile || {}).length === 0) delete styles.mobile;
@@ -648,8 +677,17 @@ export function classMergeKey(className: string): string | null {
   // `bg-[var(--gray-200)]` still conflicts with a root's `bg-accent`.
   const dash = base.indexOf('-');
   if (dash > 0) {
-    const prop = COLOR_ROOT_TO_PROP[base.slice(0, dash)];
-    if (prop && /^[a-zA-Z][\w-]*$/.test(base.slice(dash + 1))) return `${bp}|${prop}`;
+    const root = base.slice(0, dash);
+    const suffix = base.slice(dash + 1);
+    if (/^[a-zA-Z][\w-]*$/.test(suffix)) {
+      const colorProp = COLOR_ROOT_TO_PROP[root];
+      if (colorProp) return `${bp}|${colorProp}`;
+      // Project theme-token class (`font-display`). Same recovery, for the roots the token
+      // fallback in parseUtilityClass covers — without it `font-display` has a null key and
+      // would sit alongside an instance's `font-sans` instead of overriding it.
+      const themeProp = THEME_SCALE_ROOT_PROPERTY[root];
+      if (themeProp) return `${bp}|${themeProp}`;
+    }
   }
   return null;
 }

package/lib/shared/utilityClassNames.ts

@@ -35,7 +35,7 @@ import {
   filterStepToArg,
 } from './utilityClassConfig';
 import { isCssNamedColor } from './cssNamedColors';
-import { THEME_SCALE_BY_CLASS, themeScaleValue } from './tailwindThemeScale';
+import { THEME_SCALE_BY_CLASS, resolveThemeScaleToken, themeScaleValue } from './tailwindThemeScale';
 
 /** Class roots sorted longest-first so `border-t-…` wins over `border-…`. */
 export const SORTED_ROOTS: readonly string[] = Object.keys(prefixToCSSProperty).sort((a, b) => b.length - a.length);
@@ -759,6 +759,19 @@ function parseRootValue(root: string, rest: string, knownTokens?: ReadonlySet<st
     return { property: resolveRootProperty(root, value), value, root, kind: 'var' };
   }
 
+  // Project theme token on a theme-scale root (`font-display` → var(--font-display)), for
+  // suffixes outside the built-in scale that THEME_SCALE_BY_CLASS handles up front. Gated on
+  // the project token set, same as the color branch above.
+  //
+  // Deliberately placed AFTER the color branch so a bare color token keeps winning a shared
+  // root: `--text-primary` is a far more common COLOR name than a font-size one, and reading
+  // `text-primary` as a font-size the moment a theme declares `--text-primary` would silently
+  // break every existing project that names its text color that way.
+  const themeToken = resolveThemeScaleToken(root, rest, knownTokens);
+  if (themeToken) {
+    return { property: themeToken.property, value: themeToken.value, root, kind: 'var' };
+  }
+
   // Hash fallback: value lives in the style-value registry
   if (HASH_VALUE_RE.test(rest)) {
     return { property: prefixToCSSProperty[root] ?? root, value: null, root, kind: 'hash' };

package/lib/shared/validation/propValidator.test.ts

@@ -233,6 +233,53 @@ describe('Prop Validator', () => {
     });
   });
 
+  describe('Reference props', () => {
+    test('single reference (id string) passes validation', () => {
+      const propDefs: Record<string, PropDefinition> = {
+        featured: { type: 'reference', collection: 'blog', multiple: false, default: '' },
+      };
+      const result = validateComponentProps(propDefs, { featured: 'post-1' });
+      expect(result.valid).toBe(true);
+      expect(result.props.featured).toBe('post-1');
+    });
+
+    test('multi reference (ordered id array) passes validation and preserves order', () => {
+      const propDefs: Record<string, PropDefinition> = {
+        posts: { type: 'reference', collection: 'blog', multiple: true, default: [] },
+      };
+      const result = validateComponentProps(propDefs, { posts: ['post-7', 'post-1', 'post-3'] });
+      expect(result.valid).toBe(true);
+      expect(result.props.posts).toEqual(['post-7', 'post-1', 'post-3']);
+    });
+
+    test('a {{…}} binding string is preserved, not coerced away', () => {
+      const propDefs: Record<string, PropDefinition> = {
+        posts: { type: 'reference', collection: 'blog', multiple: true, default: [] },
+      };
+      const result = validateComponentProps(propDefs, { posts: '{{cms.relatedPosts}}' });
+      expect(result.valid).toBe(true);
+      expect(result.props.posts).toBe('{{cms.relatedPosts}}');
+    });
+
+    test('missing reference prop uses its default', () => {
+      const propDefs: Record<string, PropDefinition> = {
+        posts: { type: 'reference', collection: 'blog', multiple: true, default: [] },
+      };
+      const result = validateComponentProps(propDefs, {});
+      expect(result.valid).toBe(true);
+      expect(result.props.posts).toEqual([]);
+    });
+
+    test('an invalid value (number) degrades gracefully to the default', () => {
+      const propDefs: Record<string, PropDefinition> = {
+        posts: { type: 'reference', collection: 'blog', multiple: true, default: [] },
+      };
+      const result = validateComponentProps(propDefs, { posts: 123 });
+      // Invalid type → validation error, but graceful degradation keeps the default
+      expect(result.props.posts).toEqual([]);
+    });
+  });
+
   describe('Backward compatibility maintained', () => {
     test('unknown props allowed but logged', () => {
       const propDefs: Record<string, PropDefinition> = {

package/lib/shared/validation/propValidator.ts

@@ -180,6 +180,14 @@ function validateSingleProp(
       typeValid = Array.isArray(value) || isI18nValue(value);
       break;
 
+    case 'reference':
+      // Reference stores a picked CMS item id (single) or an ordered array of ids (multi).
+      // A `{{…}}` binding string (e.g. an instance inside a CMS template) is also valid and
+      // resolved later — never coerce it away.
+      coercedValue = value;
+      typeValid = typeof value === 'string' || Array.isArray(value);
+      break;
+
     default:
       return {
         valid: false,