meno-core 1.1.4 → 1.1.6

package/lib/client/core/ComponentBuilder.ts

@@ -46,8 +46,13 @@ import {
 } from '../../shared/itemTemplateUtils';
 import { DEFAULT_I18N_CONFIG, isI18nValue, resolveI18nValue } from '../../shared/i18n';
 import { getChildPath, pathToString } from '../../shared/pathArrayUtils';
-import { responsiveStylesToClasses } from '../../shared/utilityClassMapper';
+import {
+  responsiveStylesToClasses,
+  mergeInstanceClasses,
+  stripClassOverriddenStyleProps,
+} from '../../shared/utilityClassMapper';
 import { getCachedResponsiveScalesConfig } from '../responsiveStyleResolver';
+import { getTemplateVars, TEMPLATE_VARS_KEY } from '../../shared/templateStyleVars';
 import { UtilityClassCollector } from '../styles/UtilityClassCollector';
 import { processCMSTemplate, processCMSPropsTemplate, RAW_HTML_PREFIX } from './cmsTemplateProcessor';
 import type { PrefetchService } from '../services/PrefetchService';
@@ -762,6 +767,14 @@ export class ComponentBuilder {
   ): Record<string, unknown> {
     const nodeStyle = node.style || (isComponentNode(node) ? node.props?.style : undefined);
 
+    // Template-bound style values were var-bridged by processStructure (the style carries
+    // `var(--m-<bp>-<prop>)`, the concrete value lives on the node) — thread the assignments
+    // through props so buildHtmlElement can set them inline via its ref. See templateStyleVars.ts.
+    const templateVars = getTemplateVars(node);
+    if (templateVars) {
+      props = { ...props, [TEMPLATE_VARS_KEY]: templateVars };
+    }
+
     if (nodeStyle && typeof nodeStyle === 'object') {
       // Process item templates in style values (for List context)
       let processedStyle = nodeStyle as Record<string, unknown>;
@@ -1128,26 +1141,38 @@ export class ComponentBuilder {
       // root. A `<Heading class="text-muted p-[24px]" />` instance carries its
       // override as props.class — the class-based equivalent of the legacy
       // instance style object. SSR applies it onto the component root
-      // (ssrRenderer.ts `instanceClassName`); the live client canvas must too, or
+      // (ssrRenderer.ts renderComponent); the live client canvas must too, or
       // instance-level classes silently vanish in Meno Select while rendering
-      // correctly in a real Astro build. Last in source order so it wins,
-      // matching cx's instance-last precedence. Collect the tokens so their CSS
-      // is injected into the canvas's utility sheet (html/link roots also get it
-      // via the recursive mergeAttributes; collecting here covers component roots).
+      // correctly in a real Astro build. Conflict-aware, instance-over-root: a
+      // root class targeting the same (breakpoint, CSS property) is dropped, and
+      // the same properties are stripped from the root's style object — a
+      // prop-bound root style (maxWidth: {_mapping} → "100%") would otherwise
+      // mint a root utility class (max-w-full) that fights the instance's
+      // max-w-[283px] on stylesheet order (equal specificity). Mirrors the
+      // meno-astro runtime's mergeInstanceClasses/inlineStyle pair. Collect the
+      // tokens so their CSS is injected into the canvas's utility sheet
+      // (html/link roots also get it via the recursive mergeAttributes;
+      // collecting here covers component roots).
       const instanceClass = typeof finalProps.class === 'string' ? finalProps.class : '';
       if (instanceClass) {
         const root = processedStructure as ComponentNode & {
           props?: Record<string, unknown>;
           attributes?: Record<string, string | number | boolean>;
+          style?: StyleValue;
         };
+        if (root.style) {
+          const stripped = stripClassOverriddenStyleProps(root.style, instanceClass);
+          if (stripped) root.style = stripped;
+          else delete root.style;
+        }
         if (isHtmlNode(root) || isLinkNode(root)) {
           if (!root.attributes) root.attributes = {};
-          const existing = (root.attributes.class || '') as string;
-          root.attributes.class = existing ? `${existing} ${instanceClass}` : instanceClass;
+          const own = ((root.attributes.class || '') as string).split(/\s+/).filter(Boolean);
+          root.attributes.class = mergeInstanceClasses(own, instanceClass).join(' ');
         } else {
           if (!root.props) root.props = {};
-          const existing = (root.props.className || '') as string;
-          root.props.className = existing ? `${existing} ${instanceClass}` : instanceClass;
+          const own = ((root.props.className || '') as string).split(/\s+/).filter(Boolean);
+          root.props.className = mergeInstanceClasses(own, instanceClass).join(' ');
         }
         const tokens = instanceClass.split(/\s+/).filter(Boolean);
         if (tokens.length > 0) UtilityClassCollector.collect(tokens);
@@ -1230,19 +1255,24 @@ export class ComponentBuilder {
     const { __componentProps, ...customPropsForDOM } = customProps || {};
     const isComponentRoot = !!(customProps && '__componentProps' in customProps);
 
+    // Pull the var-bridge assignments off props (threaded by applyStyleClasses) — they're
+    // applied to the DOM element in the ref below, never spread as a React prop.
+    const { [TEMPLATE_VARS_KEY]: templateVarsRaw, ...propsSansTemplateVars } = props;
+    const templateVars = templateVarsRaw as Record<string, string> | undefined;
+
     // Strip responsive style objects (e.g. { base: { objectFit: 'cover' } }) from inline style.
     // These produce invalid React inline styles — utility classes handle all styling.
     // Flat style objects are kept as inline style for backward compatibility.
     // The style prop is preserved in applyStyleClasses for component instance style merging
     // (buildCustomComponent reads finalProps.style via mergeNodeStyles).
-    let propsForElement = props;
-    const nodeStyle = props.style;
+    let propsForElement = propsSansTemplateVars;
+    const nodeStyle = propsSansTemplateVars.style;
     if (
       nodeStyle &&
       typeof nodeStyle === 'object' &&
       ('base' in (nodeStyle as object) || 'tablet' in (nodeStyle as object) || 'mobile' in (nodeStyle as object))
     ) {
-      const { style: _, ...rest } = props;
+      const { style: _, ...rest } = propsSansTemplateVars;
       propsForElement = rest;
     }
 
@@ -1311,6 +1341,15 @@ export class ComponentBuilder {
             el.style.setProperty(varName, value);
           }
         }
+
+        // Apply var-bridge assignments for template-bound style values — the element's
+        // utility classes read var(--m-<bp>-<prop>); the concrete value is set here,
+        // mirroring the meno-astro runtime's inline style. See templateStyleVars.ts.
+        if (templateVars) {
+          for (const [varName, value] of Object.entries(templateVars)) {
+            el.style.setProperty(varName, value);
+          }
+        }
       }
 
       const componentProps =

package/lib/client/core/builders/embedBuilder.ts

@@ -18,6 +18,7 @@ import {
   resolveExtractedMappings,
 } from '../../../shared/interactiveStyleMappings';
 import { UtilityClassCollector } from '../../styles/UtilityClassCollector';
+import { getTemplateVars } from '../../../shared/templateStyleVars';
 import DOMPurify from 'isomorphic-dompurify';
 import { inlineSvgStyleRules } from '../../../shared/inlineSvgStyleRules';
 import type { ElementRegistry } from '../../elementRegistry';
@@ -291,6 +292,14 @@ export function buildEmbed(node: EmbedNode, ctx: BuilderContext, deps: EmbedBuil
             el.style.setProperty(varName, value);
           }
         }
+        // Var-bridge for template-bound style values (see templateStyleVars.ts) —
+        // the utility classes read var(--m-<bp>-<prop>); set the concrete value inline.
+        const templateVars = getTemplateVars(node);
+        if (templateVars) {
+          for (const [varName, value] of Object.entries(templateVars)) {
+            el.style.setProperty(varName, value);
+          }
+        }
       }
     },
     dangerouslySetInnerHTML: { __html: sanitizedHtml },
@@ -399,7 +408,12 @@ export function buildEmbed(node: EmbedNode, ctx: BuilderContext, deps: EmbedBuil
       (extractedAttributes as Record<string, unknown>).className ??
       '') as string;
     if (attrClass) {
-      classNames.push(...attrClass.split(/\s+/));
+      // Class-string styling: utility tokens stored in attributes.class (e.g. h-[30px])
+      // must inject their CSS into the live canvas, same as ComponentBuilder does for
+      // element nodes. collect() skips foreign tokens that generate no rule.
+      const classTokens = attrClass.split(/\s+/).filter(Boolean);
+      UtilityClassCollector.collect(classTokens);
+      classNames.push(...classTokens);
     }
     delete (extractedAttributes as Record<string, unknown>).class;
     delete (extractedAttributes as Record<string, unknown>).className;

package/lib/client/core/builders/linkNodeBuilder.ts

@@ -19,6 +19,7 @@ import {
 } from '../../../shared/interactiveStyleMappings';
 import { processItemPropsTemplate, type ValueResolver } from '../../../shared/itemTemplateUtils';
 import { UtilityClassCollector } from '../../styles/UtilityClassCollector';
+import { getTemplateVars } from '../../../shared/templateStyleVars';
 import { resolveI18nValue, DEFAULT_I18N_CONFIG } from '../../../shared/i18n';
 import { isCurrentLink } from '../../../shared/linkUtils';
 import type { ElementRegistry } from '../../elementRegistry';
@@ -87,6 +88,14 @@ export function buildLinkNode(
             el.style.setProperty(varName, value);
           }
         }
+        // Var-bridge for template-bound style values (see templateStyleVars.ts) —
+        // the utility classes read var(--m-<bp>-<prop>); set the concrete value inline.
+        const templateVars = getTemplateVars(node);
+        if (templateVars) {
+          for (const [varName, value] of Object.entries(templateVars)) {
+            el.style.setProperty(varName, value);
+          }
+        }
       }
     },
   };
@@ -194,7 +203,12 @@ export function buildLinkNode(
       (extractedAttributes as Record<string, unknown>).className ??
       '') as string;
     if (attrClass) {
-      classNames.push(...attrClass.split(/\s+/));
+      // Class-string styling: utility tokens stored in attributes.class (e.g. h-[30px])
+      // must inject their CSS into the live canvas, same as ComponentBuilder does for
+      // element nodes. collect() skips foreign tokens that generate no rule.
+      const classTokens = attrClass.split(/\s+/).filter(Boolean);
+      UtilityClassCollector.collect(classTokens);
+      classNames.push(...classTokens);
     }
     delete (extractedAttributes as Record<string, unknown>).class;
     delete (extractedAttributes as Record<string, unknown>).className;

package/lib/client/core/builders/localeListBuilder.ts

@@ -18,6 +18,7 @@ import {
   resolveExtractedMappings,
 } from '../../../shared/interactiveStyleMappings';
 import { UtilityClassCollector } from '../../styles/UtilityClassCollector';
+import { getTemplateVars } from '../../../shared/templateStyleVars';
 import type { ElementRegistry } from '../../elementRegistry';
 import type { BuilderContext } from './types';
 
@@ -68,6 +69,14 @@ export function buildLocaleList(node: LocaleListNode, ctx: BuilderContext, deps:
             el.style.setProperty(varName, value);
           }
         }
+        // Var-bridge for template-bound style values (see templateStyleVars.ts) —
+        // the utility classes read var(--m-<bp>-<prop>); set the concrete value inline.
+        const templateVars = getTemplateVars(node);
+        if (templateVars) {
+          for (const [varName, value] of Object.entries(templateVars)) {
+            el.style.setProperty(varName, value);
+          }
+        }
       }
     },
   };
@@ -160,7 +169,12 @@ export function buildLocaleList(node: LocaleListNode, ctx: BuilderContext, deps:
       (extractedAttributes as Record<string, unknown>).className ??
       '') as string;
     if (attrClass) {
-      classNames.push(...attrClass.split(/\s+/));
+      // Class-string styling: utility tokens stored in attributes.class (e.g. h-[30px])
+      // must inject their CSS into the live canvas, same as ComponentBuilder does for
+      // element nodes. collect() skips foreign tokens that generate no rule.
+      const classTokens = attrClass.split(/\s+/).filter(Boolean);
+      UtilityClassCollector.collect(classTokens);
+      classNames.push(...classTokens);
     }
     delete (extractedAttributes as Record<string, unknown>).class;
     delete (extractedAttributes as Record<string, unknown>).className;

package/lib/client/templateEngine.test.ts

@@ -605,8 +605,14 @@ describe('Template Engine - processStructure', () => {
       const node = result as ComponentNode;
       const baseStyle = (node.style as any)?.base;
       expect(baseStyle).toBeDefined();
-      expect(baseStyle?.opacity).toBe('0');
-      expect(baseStyle?.fontSize).toBe('16px');
+      // Template-bound values are var-bridged (templateStyleVars.ts): the style reads a
+      // CSS variable (so the class is never auto-responsive-scaled, matching the real
+      // Astro build) and the concrete resolved value rides on __templateVars for the
+      // element's inline style.
+      expect(baseStyle?.opacity).toBe('var(--m-base-opacity)');
+      expect(baseStyle?.fontSize).toBe('var(--m-base-font-size)');
+      const vars = (node as any).__templateVars;
+      expect(vars).toEqual({ '--m-base-opacity': '0', '--m-base-font-size': '16px' });
     });
 
     test('defers full templates containing dotted terms (e.g. decimals) to item processing', () => {
@@ -647,12 +653,109 @@ describe('Template Engine - processStructure', () => {
       const result = processStructure(structure, createContext({}));
       const node = result as ComponentNode;
       const baseStyle = (node.style as any)?.base;
-      expect(baseStyle?.display).toBe('none');
+      // Var-bridged (see templateStyleVars.ts) — resolved value lands on __templateVars.
+      expect(baseStyle?.display).toBe('var(--m-base-display)');
+      expect((node as any).__templateVars).toEqual({ '--m-base-display': 'none' });
 
       resetGlobalTemplateContext();
     });
   });
 
+  describe('Template style var-bridge (templateStyleVars.ts)', () => {
+    test('bridges per breakpoint: tablet/mobile templates get breakpoint-scoped var names', () => {
+      const structure: ComponentNode = {
+        type: 'node',
+        tag: 'div',
+        style: {
+          base: { gap: '{{gap}}px' },
+          tablet: { gap: '{{gapTablet}}px' },
+        },
+      };
+      const result = processStructure(structure, createContext({ gap: 40, gapTablet: 24 })) as ComponentNode;
+      expect((result.style as any).base.gap).toBe('var(--m-base-gap)');
+      expect((result.style as any).tablet.gap).toBe('var(--m-tablet-gap)');
+      expect((result as any).__templateVars).toEqual({
+        '--m-base-gap': '40px',
+        '--m-tablet-gap': '24px',
+      });
+    });
+
+    test('bridges flat (non-responsive) style objects as base', () => {
+      const structure: ComponentNode = {
+        type: 'node',
+        tag: 'div',
+        style: { maxWidth: '{{maxWidth}}' } as any,
+      };
+      const result = processStructure(structure, createContext({ maxWidth: '283px' })) as ComponentNode;
+      expect((result.style as any).maxWidth).toBe('var(--m-base-max-width)');
+      expect((result as any).__templateVars).toEqual({ '--m-base-max-width': '283px' });
+    });
+
+    test('does NOT bridge _mapping values — they resolve to static, auto-scalable classes', () => {
+      const structure: ComponentNode = {
+        type: 'node',
+        tag: 'div',
+        style: {
+          base: { padding: { _mapping: true, prop: 'size', values: { small: '8px', large: '24px' } } },
+        } as any,
+      };
+      const result = processStructure(structure, createContext({ size: 'large' })) as ComponentNode;
+      expect((result.style as any).base.padding).toBe('24px');
+      expect((result as any).__templateVars).toBeUndefined();
+    });
+
+    test('undefined prop still bridges — the empty substitution yields an invalid var value, so the property is unset (matching Astro)', () => {
+      const structure: ComponentNode = {
+        type: 'node',
+        tag: 'div',
+        style: { base: { gap: '{{gap}}px' } },
+      };
+      const result = processStructure(structure, createContext({})) as ComponentNode;
+      expect((result.style as any).base.gap).toBe('var(--m-base-gap)');
+      expect((result as any).__templateVars).toEqual({ '--m-base-gap': 'px' });
+    });
+
+    test('does NOT bridge a template preserved verbatim by processCodeTemplates', () => {
+      // When the template survives resolution unchanged (here: the DoS length guard
+      // returns the original {{...}} match), the resolved value still contains a
+      // template and the bridge skips it — legacy pass-through.
+      const tooLong = `{{${'a'.repeat(501)}}}px`;
+      const structure: ComponentNode = {
+        type: 'node',
+        tag: 'div',
+        style: { base: { gap: tooLong } },
+      };
+      const result = processStructure(structure, createContext({ gap: 40 })) as ComponentNode;
+      expect((result.style as any).base.gap).toBe(tooLong);
+      expect((result as any).__templateVars).toBeUndefined();
+    });
+
+    test('does NOT bridge item templates ({{item.x}} resolves later during rendering)', () => {
+      const structure: ComponentNode = {
+        type: 'node',
+        tag: 'div',
+        style: { base: { color: '{{item.color}}' } },
+      };
+      const result = processStructure(structure, createContext({})) as ComponentNode;
+      expect((result.style as any).base.color).toBe('{{item.color}}');
+      expect((result as any).__templateVars).toBeUndefined();
+    });
+
+    test('does NOT bridge component INSTANCE node styles (they merge into the child root)', () => {
+      const structure: ComponentNode = {
+        type: 'component',
+        component: 'Card',
+        props: {},
+        style: { base: { gap: '{{gap}}px' } },
+      } as ComponentNode;
+      const result = processStructure(structure, createContext({ gap: 40 })) as ComponentNode;
+      // Instance styles keep the concrete resolved value — the child structure root
+      // renders them, and the vars would otherwise be applied to no element.
+      expect((result.style as any).base.gap).toBe('40px');
+      expect((result as any).__templateVars).toBeUndefined();
+    });
+  });
+
   describe('Edge cases and error handling', () => {
     test('should return null for null structure', () => {
       const result = processStructure(null, createContext({}));

package/lib/client/templateEngine.ts

@@ -33,6 +33,7 @@ import {
 import { applyStylesToNode } from '../shared/styleNodeUtils';
 import { isRichTextMarker, richTextMarkerToHtml } from '../shared/propResolver';
 import { hasItemTemplates } from '../shared/itemTemplateUtils';
+import { templateVarName, TEMPLATE_VARS_KEY } from '../shared/templateStyleVars';
 import { safeEvaluate } from '../shared/expressionEvaluator';
 import { RAW_HTML_PREFIX } from '../shared/constants';
 import { getGlobalTemplateContext } from '../shared/globalTemplateContext';
@@ -274,6 +275,21 @@ function processStyleValue(
   return undefined;
 }
 
+/**
+ * True when an ORIGINAL style value was a prop-template string that processStyleValue
+ * successfully resolved — the case the var-bridge applies to (see templateStyleVars.ts).
+ * Item templates ({{item.x}}) resolve later during rendering, and an unresolved template
+ * (undefined prop) keeps its legacy pass-through behavior, so neither bridges.
+ */
+function isBridgeableTemplateValue(original: unknown, resolved: string | number): boolean {
+  return (
+    typeof original === 'string' &&
+    hasTemplates(original) &&
+    !hasItemTemplates(original) &&
+    !(typeof resolved === 'string' && resolved.includes('{{'))
+  );
+}
+
 /**
  * Build evaluation context for template processing.
  * Merges global context, props, componentDef, and optionally itemContext.
@@ -670,6 +686,12 @@ export function processStructure(
 
       // First pass: process all keys and resolve style mappings
       let resolvedStyle: StyleValue | null = null;
+      // Var-bridge assignments for template-resolved style values (see templateStyleVars.ts).
+      // Component INSTANCE nodes are exempt: their style merges into the child structure
+      // root (mergeNodeStyles / SSR renderComponent), which renders a different element
+      // than the one these vars would be applied to.
+      const templateVars: Record<string, string> = {};
+      const bridgeTemplates = preservedType !== NODE_TYPE.COMPONENT;
 
       for (const [key, value] of Object.entries(structure)) {
         try {
@@ -777,6 +799,22 @@ export function processStructure(
             if (processedStyle && typeof processedStyle === 'object' && !Array.isArray(processedStyle)) {
               // Check if it's a responsive style object
               const styleEvalContext = buildEvalContext(context, false);
+              // Land one resolved declaration, var-bridging template-resolved values: the
+              // style gets `var(--m-<bp>-<prop>)` and the concrete value is stashed for the
+              // element's inline style — mirroring the meno-astro runtime, so a prop-bound
+              // value renders constant across breakpoints (no auto-responsive scaling) in
+              // Fast Design Mode exactly as it does in a real build. See templateStyleVars.ts.
+              const landStyleValue = (target: StyleObject, bp: string, styleKey: string, styleValue: unknown): void => {
+                const processedValue = processStyleValue(styleValue, styleEvalContext);
+                if (processedValue === undefined) return;
+                if (bridgeTemplates && isBridgeableTemplateValue(styleValue, processedValue)) {
+                  const varName = templateVarName(bp, styleKey);
+                  templateVars[varName] = String(processedValue);
+                  target[styleKey] = `var(${varName})`;
+                } else {
+                  target[styleKey] = processedValue;
+                }
+              };
               if (isResponsiveStyle(processedStyle as StyleValue)) {
                 // Preserve responsive styles (for both SSR and editor)
                 // responsiveStylesToClasses will generate prefixed classes (tablet:, mobile:)
@@ -784,25 +822,21 @@ export function processStructure(
                 const resolvedResponsive: ResponsiveStyleObject = {};
                 for (const [bkeyName, bkeyValue] of Object.entries(processedStyle)) {
                   if (typeof bkeyValue === 'object' && bkeyValue !== null) {
-                    resolvedResponsive[bkeyName] = {};
+                    const bpTarget: StyleObject = {};
+                    resolvedResponsive[bkeyName] = bpTarget;
                     for (const [styleKey, styleValue] of Object.entries(bkeyValue)) {
-                      const processedValue = processStyleValue(styleValue, styleEvalContext);
-                      if (processedValue !== undefined) {
-                        resolvedResponsive[bkeyName]![styleKey] = processedValue;
-                      }
+                      landStyleValue(bpTarget, bkeyName, styleKey, styleValue);
                     }
                   }
                 }
                 resolvedStyle = resolvedResponsive;
               } else {
                 // Legacy flat style object - resolve mappings and evaluate templates
-                resolvedStyle = {};
+                const flatTarget: StyleObject = {};
                 for (const [styleKey, styleValue] of Object.entries(processedStyle)) {
-                  const processedValue = processStyleValue(styleValue, styleEvalContext);
-                  if (processedValue !== undefined) {
-                    resolvedStyle[styleKey] = processedValue;
-                  }
+                  landStyleValue(flatTarget, 'base', styleKey, styleValue);
                 }
+                resolvedStyle = flatTarget;
               }
             }
           } else if (key === 'props' && typeof value === 'object' && value !== null) {
@@ -987,6 +1021,12 @@ export function processStructure(
         }
       }
 
+      // Attach the var-bridge assignments (ephemeral, render-only) so the element
+      // renderers can set them inline — client builders via ref, SSR via style="…".
+      if (Object.keys(templateVars).length > 0) {
+        (processed as unknown as Record<string, unknown>)[TEMPLATE_VARS_KEY] = templateVars;
+      }
+
       return processed;
     }
 

package/lib/server/fileWatcher.test.ts

@@ -243,6 +243,96 @@ describe('FileWatcher astro CMS template pages', () => {
   });
 });
 
+describe('FileWatcher theme.css', () => {
+  let projectRoot: string;
+  let stylesDir: string;
+
+  beforeEach(() => {
+    projectRoot = join(tmpdir(), `meno-fw-theme-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    stylesDir = join(projectRoot, 'src', 'styles');
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(projectRoot, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  // theme.css holds BOTH token halves (colors + variables), so one edit must
+  // invalidate both service caches — an external write (e.g. an AI tool adding
+  // a token) previously stayed invisible until a dev-server restart.
+  test('fires onColorsChange AND onVariablesChange when theme.css is written', async () => {
+    let colorChanges = 0;
+    let variableChanges = 0;
+    const watcher = new FileWatcher({
+      onColorsChange: async () => {
+        colorChanges++;
+      },
+      onVariablesChange: async () => {
+        variableChanges++;
+      },
+    });
+
+    mkdirSync(stylesDir, { recursive: true });
+    writeFileSync(join(stylesDir, 'theme.css'), ':root { --bg: #fff; }');
+    watcher.watchThemeCss(stylesDir);
+    await settle(50);
+
+    writeFileSync(join(stylesDir, 'theme.css'), ':root { --bg: #fff; --accent: #f00; }');
+    await waitFor(() => colorChanges >= 1 && variableChanges >= 1);
+
+    watcher.stopAll();
+    expect(colorChanges).toBeGreaterThanOrEqual(1);
+    expect(variableChanges).toBeGreaterThanOrEqual(1);
+  });
+
+  // src/styles may not exist at startup (blank project — theme.css lands later
+  // via the JSON migration or an external tool), so the watcher must defer-attach.
+  test('fires after src/styles is created post-startup', async () => {
+    let colorChanges = 0;
+    const watcher = new FileWatcher({
+      onColorsChange: async () => {
+        colorChanges++;
+      },
+    });
+
+    watcher.watchThemeCss(stylesDir);
+    await settle(50);
+    mkdirSync(stylesDir, { recursive: true });
+    await settle(100);
+    writeFileSync(join(stylesDir, 'theme.css'), ':root { --bg: #fff; }');
+    await waitFor(() => colorChanges >= 1);
+
+    watcher.stopAll();
+    expect(colorChanges).toBeGreaterThanOrEqual(1);
+  });
+
+  test('ignores writes to other files in src/styles', async () => {
+    let fired = 0;
+    const watcher = new FileWatcher({
+      onColorsChange: async () => {
+        fired++;
+      },
+      onVariablesChange: async () => {
+        fired++;
+      },
+    });
+
+    mkdirSync(stylesDir, { recursive: true });
+    watcher.watchThemeCss(stylesDir);
+    await settle(50);
+
+    writeFileSync(join(stylesDir, 'global.css'), 'body { margin: 0; }');
+    await settle(200);
+
+    watcher.stopAll();
+    expect(fired).toBe(0);
+  });
+});
+
 describe('FileWatcher project.config.json', () => {
   let projectRoot: string;
   let prevRoot: string;

package/lib/server/fileWatcher.ts

@@ -152,6 +152,7 @@ export class FileWatcher {
   private templatesWatcher: FSWatcher | null = null;
   private colorsWatcher: FSWatcher | null = null;
   private variablesWatcher: FSWatcher | null = null;
+  private themeCssWatcher: FSWatcher | null = null;
   private enumsWatcher: FSWatcher | null = null;
   private cmsWatcher: FSWatcher | null = null;
   private imagesWatcher: FSWatcher | null = null;
@@ -261,6 +262,35 @@ export class FileWatcher {
     });
   }
 
+  /**
+   * Start watching `src/styles/theme.css` — the token source of truth for
+   * astro-format projects, where colors AND variables share the one file
+   * (colors.json / variables.json were migrated away, so the two watchers
+   * above never fire there). An external edit (e.g. an AI tool adding tokens)
+   * must invalidate both service caches and refresh connected clients, or the
+   * new tokens only appear after a dev-server restart. Deferred attach:
+   * `src/styles` may not exist yet (theme.css lands later via migration or an
+   * external tool). No-op in legacy JSON projects (no `src/`).
+   */
+  watchThemeCss(dirPath: string = join(getProjectRoot(), 'src', 'styles')): void {
+    attachWhenDirExists(
+      dirPath,
+      () =>
+        watch(dirPath, { recursive: false }, async (_event, filename) => {
+          if (filename !== 'theme.css') return;
+          if (this.callbacks.onColorsChange) {
+            await this.callbacks.onColorsChange();
+          }
+          if (this.callbacks.onVariablesChange) {
+            await this.callbacks.onVariablesChange();
+          }
+        }),
+      (w) => {
+        this.themeCssWatcher = w;
+      },
+    );
+  }
+
   /**
    * Start watching enums.json file
    */
@@ -425,6 +455,7 @@ export class FileWatcher {
     this.watchTemplates();
     this.watchColors();
     this.watchVariables();
+    this.watchThemeCss();
     this.watchEnums();
     this.watchCMS();
     this.watchImages();
@@ -465,6 +496,11 @@ export class FileWatcher {
       this.variablesWatcher = null;
     }
 
+    if (this.themeCssWatcher) {
+      this.themeCssWatcher.close();
+      this.themeCssWatcher = null;
+    }
+
     if (this.enumsWatcher) {
       this.enumsWatcher.close();
       this.enumsWatcher = null;

package/lib/server/services/configService.ts

@@ -66,7 +66,6 @@ interface RawProjectConfig {
   imageFormat?: ImageFormat;
   remConversion?: Partial<RemConversionConfig>;
   customCode?: CustomCodeConfig;
-  showMenoBadge?: boolean;
 }
 
 /**
@@ -343,10 +342,6 @@ export class ConfigService {
     return this.config.customCode;
   }
 
-  getShowMenoBadge(): boolean {
-    return this.config?.showMenoBadge === true;
-  }
-
   getImageFormat(): ImageFormat {
     if (this.config?.imageFormat === 'avif') return 'avif';
     return 'webp';