meno-core 1.0.48 → 1.0.50

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

@@ -8,6 +8,7 @@ import type { ReactElement } from "react";
 import type { EmbedNode, StyleObject, ResponsiveStyleObject, InteractiveStyles } from "../../../shared/types";
 import { extractAttributesFromNode } from "../../../shared/attributeNodeUtils";
 import { responsiveStylesToClasses } from "../../../shared/utilityClassMapper";
+import { getCachedResponsiveScalesConfig } from "../../responsiveStyleResolver";
 import { pathToString } from "../../../shared/pathArrayUtils";
 import { generateElementClassName, type ElementClassContext } from "../../../shared/elementClassName";
 import { InteractiveStylesRegistry } from "../../InteractiveStylesRegistry";
@@ -126,7 +127,13 @@ export function buildEmbed(
         i18nResolver
       ) as StyleObject | ResponsiveStyleObject;
     }
-    const utilityClasses = responsiveStylesToClasses(processedStyle as StyleObject | ResponsiveStyleObject);
+    const scales = getCachedResponsiveScalesConfig();
+    const fluidActive =
+      scales?.enabled === true && scales?.mode === 'fluid';
+    const utilityClasses = responsiveStylesToClasses(
+      processedStyle as StyleObject | ResponsiveStyleObject,
+      { fluidActive, responsiveScales: scales ?? undefined }
+    );
     UtilityClassCollector.collect(utilityClasses);
     classNames.push(...utilityClasses);
   }
@@ -174,7 +181,13 @@ export function buildEmbed(
         const previewClasses: string[] = [];
         for (const rule of nodeInteractiveStyles) {
           if (rule.previewProp && ctx.componentResolvedProps[rule.previewProp] === true) {
-            const styleClasses = responsiveStylesToClasses(rule.style as StyleObject | ResponsiveStyleObject);
+            const previewScales = getCachedResponsiveScalesConfig();
+            const previewFluidActive =
+              previewScales?.enabled === true && previewScales?.mode === 'fluid';
+            const styleClasses = responsiveStylesToClasses(
+              rule.style as StyleObject | ResponsiveStyleObject,
+              { fluidActive: previewFluidActive, responsiveScales: previewScales ?? undefined }
+            );
             UtilityClassCollector.collect(styleClasses);
             previewClasses.push(...styleClasses);
           }
@@ -186,11 +199,19 @@ export function buildEmbed(
     }
   }
 
-  // Add extracted attributes className if present
-  if (extractedAttributes.className) {
-    const attrClasses = (extractedAttributes.className as string).split(/\s+/);
-    classNames.push(...attrClasses);
-    delete extractedAttributes.className;
+  // Add extracted attributes class/className if present
+  // JSON uses "class"; React uses "className". Without merging, the raw "class"
+  // would be spread onto the React element below and override the className that
+  // holds the utility classes derived from node.style.
+  if ('class' in extractedAttributes || 'className' in extractedAttributes) {
+    const attrClass = ((extractedAttributes as Record<string, unknown>).class
+      ?? (extractedAttributes as Record<string, unknown>).className
+      ?? '') as string;
+    if (attrClass) {
+      classNames.push(...attrClass.split(/\s+/));
+    }
+    delete (extractedAttributes as Record<string, unknown>).class;
+    delete (extractedAttributes as Record<string, unknown>).className;
   }
 
   // Set final className

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

@@ -8,6 +8,7 @@ import type { ReactElement } from "react";
 import type { LinkNode, StyleObject, ResponsiveStyleObject, InteractiveStyles } from "../../../shared/types";
 import { extractAttributesFromNode } from "../../../shared/attributeNodeUtils";
 import { responsiveStylesToClasses } from "../../../shared/utilityClassMapper";
+import { getCachedResponsiveScalesConfig } from "../../responsiveStyleResolver";
 import { pathToString } from "../../../shared/pathArrayUtils";
 import { generateElementClassName, type ElementClassContext } from "../../../shared/elementClassName";
 import { InteractiveStylesRegistry } from "../../InteractiveStylesRegistry";
@@ -101,7 +102,13 @@ export function buildLinkNode(
         i18nResolver
       ) as StyleObject | ResponsiveStyleObject;
     }
-    const utilityClasses = responsiveStylesToClasses(processedStyle as StyleObject | ResponsiveStyleObject);
+    const scales = getCachedResponsiveScalesConfig();
+    const fluidActive =
+      scales?.enabled === true && scales?.mode === 'fluid';
+    const utilityClasses = responsiveStylesToClasses(
+      processedStyle as StyleObject | ResponsiveStyleObject,
+      { fluidActive, responsiveScales: scales ?? undefined }
+    );
     UtilityClassCollector.collect(utilityClasses);
     classNames.push(...utilityClasses);
   }
@@ -149,7 +156,13 @@ export function buildLinkNode(
         const previewClasses: string[] = [];
         for (const rule of nodeInteractiveStyles) {
           if (rule.previewProp && ctx.componentResolvedProps[rule.previewProp] === true) {
-            const styleClasses = responsiveStylesToClasses(rule.style as StyleObject | ResponsiveStyleObject);
+            const previewScales = getCachedResponsiveScalesConfig();
+            const previewFluidActive =
+              previewScales?.enabled === true && previewScales?.mode === 'fluid';
+            const styleClasses = responsiveStylesToClasses(
+              rule.style as StyleObject | ResponsiveStyleObject,
+              { fluidActive: previewFluidActive, responsiveScales: previewScales ?? undefined }
+            );
             UtilityClassCollector.collect(styleClasses);
             previewClasses.push(...styleClasses);
           }
@@ -161,11 +174,19 @@ export function buildLinkNode(
     }
   }
 
-  // Add extracted attributes className if present
-  if (extractedAttributes.className) {
-    const attrClasses = (extractedAttributes.className as string).split(/\s+/);
-    classNames.push(...attrClasses);
-    delete extractedAttributes.className;
+  // Add extracted attributes class/className if present
+  // JSON uses "class"; React uses "className". Without merging, the raw "class"
+  // would be spread onto the React element below and override the className that
+  // holds the utility classes derived from node.style.
+  if ('class' in extractedAttributes || 'className' in extractedAttributes) {
+    const attrClass = ((extractedAttributes as Record<string, unknown>).class
+      ?? (extractedAttributes as Record<string, unknown>).className
+      ?? '') as string;
+    if (attrClass) {
+      classNames.push(...attrClass.split(/\s+/));
+    }
+    delete (extractedAttributes as Record<string, unknown>).class;
+    delete (extractedAttributes as Record<string, unknown>).className;
   }
 
   // Add is-current class when link href matches current page path

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

@@ -8,6 +8,7 @@ import type { ReactElement } from "react";
 import type { LocaleListNode, StyleObject, ResponsiveStyleObject, InteractiveStyles } from "../../../shared/types";
 import { extractAttributesFromNode } from "../../../shared/attributeNodeUtils";
 import { responsiveStylesToClasses } from "../../../shared/utilityClassMapper";
+import { getCachedResponsiveScalesConfig } from "../../responsiveStyleResolver";
 import { pathToString } from "../../../shared/pathArrayUtils";
 import { generateElementClassName, type ElementClassContext } from "../../../shared/elementClassName";
 import { InteractiveStylesRegistry } from "../../InteractiveStylesRegistry";
@@ -73,9 +74,16 @@ export function buildLocaleList(
   // Start building className
   let classNames: string[] = [];
 
+  // Resolve fluid mode once for all conversions in this builder
+  const scales = getCachedResponsiveScalesConfig();
+  const fluidActive = scales?.enabled === true && scales?.mode === 'fluid';
+
   // Convert container styles to utility classes
   if (node.style) {
-    const utilityClasses = responsiveStylesToClasses(node.style as StyleObject | ResponsiveStyleObject);
+    const utilityClasses = responsiveStylesToClasses(
+      node.style as StyleObject | ResponsiveStyleObject,
+      { fluidActive, responsiveScales: scales ?? undefined }
+    );
     UtilityClassCollector.collect(utilityClasses);
     classNames.push(...utilityClasses);
   }
@@ -123,7 +131,10 @@ export function buildLocaleList(
         const previewClasses: string[] = [];
         for (const rule of nodeInteractiveStyles) {
           if (rule.previewProp && ctx.componentResolvedProps[rule.previewProp] === true) {
-            const styleClasses = responsiveStylesToClasses(rule.style as StyleObject | ResponsiveStyleObject);
+            const styleClasses = responsiveStylesToClasses(
+              rule.style as StyleObject | ResponsiveStyleObject,
+              { fluidActive, responsiveScales: scales ?? undefined }
+            );
             UtilityClassCollector.collect(styleClasses);
             previewClasses.push(...styleClasses);
           }
@@ -135,11 +146,19 @@ export function buildLocaleList(
     }
   }
 
-  // Add extracted attributes className if present
-  if (extractedAttributes.className) {
-    const attrClasses = (extractedAttributes.className as string).split(/\s+/);
-    classNames.push(...attrClasses);
-    delete extractedAttributes.className;
+  // Add extracted attributes class/className if present
+  // JSON uses "class"; React uses "className". Without merging, the raw "class"
+  // would be spread onto the React element below and override the className that
+  // holds the utility classes derived from node.style.
+  if ('class' in extractedAttributes || 'className' in extractedAttributes) {
+    const attrClass = ((extractedAttributes as Record<string, unknown>).class
+      ?? (extractedAttributes as Record<string, unknown>).className
+      ?? '') as string;
+    if (attrClass) {
+      classNames.push(...attrClass.split(/\s+/));
+    }
+    delete (extractedAttributes as Record<string, unknown>).class;
+    delete (extractedAttributes as Record<string, unknown>).className;
   }
 
   // Set final className
@@ -169,10 +188,10 @@ export function buildLocaleList(
   const currentLocaleCode = locale || i18nConfig?.defaultLocale || 'en';
 
   // Convert item styles, active item styles, separator styles, and flag styles to utility classes
-  const itemClasses = node.itemStyle ? responsiveStylesToClasses(node.itemStyle as StyleObject | ResponsiveStyleObject) : [];
-  const activeItemClasses = node.activeItemStyle ? responsiveStylesToClasses(node.activeItemStyle as StyleObject | ResponsiveStyleObject) : [];
-  const separatorClasses = node.separatorStyle ? responsiveStylesToClasses(node.separatorStyle as StyleObject | ResponsiveStyleObject) : [];
-  const flagClasses = node.flagStyle ? responsiveStylesToClasses(node.flagStyle as StyleObject | ResponsiveStyleObject) : [];
+  const itemClasses = node.itemStyle ? responsiveStylesToClasses(node.itemStyle as StyleObject | ResponsiveStyleObject, { fluidActive, responsiveScales: scales ?? undefined }) : [];
+  const activeItemClasses = node.activeItemStyle ? responsiveStylesToClasses(node.activeItemStyle as StyleObject | ResponsiveStyleObject, { fluidActive, responsiveScales: scales ?? undefined }) : [];
+  const separatorClasses = node.separatorStyle ? responsiveStylesToClasses(node.separatorStyle as StyleObject | ResponsiveStyleObject, { fluidActive, responsiveScales: scales ?? undefined }) : [];
+  const flagClasses = node.flagStyle ? responsiveStylesToClasses(node.flagStyle as StyleObject | ResponsiveStyleObject, { fluidActive, responsiveScales: scales ?? undefined }) : [];
   UtilityClassCollector.collect(itemClasses);
   UtilityClassCollector.collect(activeItemClasses);
   UtilityClassCollector.collect(separatorClasses);

package/lib/client/styles/StyleInjector.ts

@@ -12,7 +12,7 @@ import type { ComponentRegistry } from '../componentRegistry';
 import type { ElementRegistry } from '../elementRegistry';
 import { hasTemplates, processCodeTemplates } from '../templateEngine';
 import { generateAllInteractiveCSS } from '../../shared/cssGeneration';
-import { getCachedBreakpointConfig, getCachedRemConversionConfig } from '../responsiveStyleResolver';
+import { getCachedBreakpointConfig, getCachedRemConversionConfig, getCachedResponsiveScalesConfig } from '../responsiveStyleResolver';
 import { DEFAULT_BREAKPOINTS } from '../../shared/breakpoints';
 import { InteractiveStylesRegistry } from '../InteractiveStylesRegistry';
 import { UtilityClassCollector } from './UtilityClassCollector';
@@ -153,7 +153,8 @@ export class StyleInjector {
 
       const breakpointConfig = getCachedBreakpointConfig() || DEFAULT_BREAKPOINTS;
       const remConversionConfig = getCachedRemConversionConfig() || undefined;
-      const interactiveCSS = generateAllInteractiveCSS(interactiveStylesMap, breakpointConfig, remConversionConfig);
+      const responsiveScalesConfig = getCachedResponsiveScalesConfig() || undefined;
+      const interactiveCSS = generateAllInteractiveCSS(interactiveStylesMap, breakpointConfig, remConversionConfig, responsiveScalesConfig);
       if (!interactiveCSS) return;
 
       if (document.head) {

package/lib/client/templateEngine.ts

@@ -797,6 +797,30 @@ export function processStructure(
             // Special handling for interactiveStyles - preserve as-is without mangling
             // Interactive styles contain StyleMapping objects that shouldn't be converted to nodes
             (processed as unknown as Record<string, unknown>).interactiveStyles = value;
+          } else if (key === 'source' && preservedType === NODE_TYPE.LIST) {
+            // Pre-resolve a bare prop-name source against the current component's
+            // props. Without this, a list with `sourceType: "prop"` placed inside
+            // another component's slot would fail to resolve at SSR time, because
+            // by then `ctx.componentResolvedProps` belongs to the slot host (not
+            // the component whose prop this references). The {{template}} form is
+            // already handled by the default-recursion branch below.
+            const structureRec = structure as Record<string, unknown>;
+            const sourceType = (structureRec.sourceType as string | undefined) ?? 'prop';
+            if (
+              sourceType === 'prop' &&
+              typeof value === 'string' &&
+              value !== '' &&
+              !hasTemplates(value) &&
+              context.props &&
+              Array.isArray((context.props as Record<string, unknown>)[value])
+            ) {
+              (processed as unknown as Record<string, unknown>).source = (context.props as Record<string, unknown>)[value];
+            } else {
+              const processedValue = processStructure(value as ComponentNode | ComponentNode[] | string | number | null | undefined, context, viewportWidth, instanceChildren, preserveResponsiveStyles, depth + 1);
+              if (processedValue !== null && processedValue !== undefined) {
+                (processed as unknown as Record<string, unknown>).source = processedValue;
+              }
+            }
           } else if (key !== 'type' && key !== 'children' && key !== 'style' && key !== 'props') {
             const processedValue = processStructure(value as ComponentNode | ComponentNode[] | string | number | null | undefined, context, viewportWidth, instanceChildren, preserveResponsiveStyles, depth + 1);
             // Only assign if it's a valid value

package/lib/client/theme.ts

@@ -77,9 +77,9 @@ const lightThemeColors: ThemeColors = {
     backgroundTertiary: '#eaeef2',
     border: '#d0d7de',
     borderSecondary: '#d1d5da',
-    text: '#24292e',
+    text: '#1a1a1a',
     textSecondary: '#586069',
-    textMuted: '#6a737d',
+    textMuted: '#525a63',
     codeString: '#032f62',
     codeNumber: '#005cc5',
     codeKey: '#005cc5',
@@ -125,9 +125,9 @@ const darkThemeColors: ThemeColors = {
     backgroundTertiary: '#252525',
     border: '#333333',
     borderSecondary: '#444444',
-    text: '#cccccc',
+    text: '#ebebeb',
     textSecondary: '#cccccc',
-    textMuted: '#888888',
+    textMuted: '#b0b0b0',
     codeString: '#ffffff',
     codeNumber: '#b5cea8',
     codeKey: '#9cdcfe',

package/lib/server/cssGenerator.test.ts

@@ -1,6 +1,8 @@
 import { describe, test, expect } from 'bun:test';
-import { generateColorVariablesCSS, generateThemeColorVariablesCSS } from './cssGenerator';
+import { generateColorVariablesCSS, generateThemeColorVariablesCSS, generateVariablesCSS } from './cssGenerator';
 import type { ColorVariables, ThemeConfig } from '../shared/types/colors';
+import type { ResponsiveScales } from '../shared/responsiveScaling';
+import { DEFAULT_BREAKPOINTS } from '../shared/breakpoints';
 
 describe('cssGenerator', () => {
   describe('generateColorVariablesCSS', () => {
@@ -169,4 +171,65 @@ describe('cssGenerator', () => {
       expect(css).toContain('\n\n');
     });
   });
+
+  describe('generateVariablesCSS — fluid mode', () => {
+    const fluidScales: ResponsiveScales = {
+      enabled: true,
+      mode: 'fluid',
+      baseReference: 16,
+      fluidRange: { min: 320, max: 1440 },
+      siteMargin: { min: 16, max: 32 },
+      fontSize: { tablet: 0.88, mobile: 0.75 },
+    };
+
+    test('emits --site-margin clamp on :root when fluid mode is enabled (no user vars)', () => {
+      const css = generateVariablesCSS(
+        { variables: [] },
+        DEFAULT_BREAKPOINTS,
+        fluidScales
+      );
+      expect(css).toContain('--site-margin: clamp(16px,');
+      expect(css).toContain(', 32px)');
+      expect(css).not.toContain('@media');
+    });
+
+
+    test('emits user variables with clamp() in fluid mode (no @media)', () => {
+      const css = generateVariablesCSS(
+        {
+          variables: [
+            { name: 'h1-fs', cssVar: '--h1-fs', value: '32px', type: 'fontSize' },
+          ],
+        },
+        DEFAULT_BREAKPOINTS,
+        fluidScales
+      );
+      // mobile fontSize scale=0.75 → MIN=28
+      expect(css).toContain('--h1-fs: clamp(28px,');
+      expect(css).toContain(', 32px)');
+      expect(css).not.toContain('@media');
+      // and the site-margin var still emitted
+      expect(css).toContain('--site-margin: clamp(16px,');
+    });
+
+    test('breakpoints mode (default) keeps @media blocks for vars and DOES NOT emit --site-margin', () => {
+      const css = generateVariablesCSS(
+        {
+          variables: [
+            { name: 'h1-fs', cssVar: '--h1-fs', value: '32px', type: 'fontSize' },
+          ],
+        },
+        DEFAULT_BREAKPOINTS,
+        { ...fluidScales, mode: 'breakpoints' }
+      );
+      expect(css).not.toContain('--site-margin');
+      expect(css).toContain('@media (max-width: 1024px)');
+      expect(css).not.toContain('clamp(');
+    });
+
+    test('returns empty string when no user vars AND fluid disabled', () => {
+      const css = generateVariablesCSS({ variables: [] }, DEFAULT_BREAKPOINTS);
+      expect(css).toBe('');
+    });
+  });
 });

package/lib/server/cssGenerator.ts

@@ -9,7 +9,14 @@ import { resolvePaletteColor } from '../shared/types/colors';
 import type { VariablesConfig, CSSVariable } from '../shared/types/variables';
 import type { BreakpointConfig } from '../shared/breakpoints';
 import type { ResponsiveScales, BreakpointScales } from '../shared/responsiveScaling';
-import { scalePropertyValue } from '../shared/responsiveScaling';
+import {
+  scalePropertyValue,
+  buildSiteMarginClamp,
+  buildFluidPropertyValue,
+  getSmallestBreakpointName,
+  DEFAULT_FLUID_RANGE,
+  DEFAULT_SITE_MARGIN,
+} from '../shared/responsiveScaling';
 
 /**
  * Generate CSS color variable declarations from color variables
@@ -75,18 +82,50 @@ export function generateVariablesCSS(
   breakpoints?: BreakpointConfig,
   responsiveScales?: ResponsiveScales
 ): string {
-  if (!config.variables || config.variables.length === 0) {
-    return '';
+  const cssBlocks: string[] = [];
+  const fluidActive =
+    responsiveScales?.enabled === true && responsiveScales?.mode === 'fluid';
+
+  // Build base :root block: user-defined variables + (in fluid mode) --site-margin.
+  // In fluid mode user variables get clamp() values directly on :root rather
+  // than @media overrides — so we run them through buildFluidPropertyValue here.
+  const fluidRange = responsiveScales?.fluidRange ?? DEFAULT_FLUID_RANGE;
+  const fluidBaseRef = responsiveScales?.baseReference || 16;
+  const smallestBp = fluidActive ? getSmallestBreakpointName(breakpoints) : null;
+
+  const baseVars: string[] = (config.variables ?? []).map(v => {
+    if (fluidActive && smallestBp && v.type !== 'none') {
+      const categoryScales = responsiveScales?.[v.type] as BreakpointScales | undefined;
+      const scale = categoryScales?.[smallestBp];
+      if (scale != null && scale !== 1) {
+        const fluid = buildFluidPropertyValue(
+          v.value,
+          scale,
+          fluidRange.min,
+          fluidRange.max,
+          fluidBaseRef
+        );
+        if (fluid) return `  ${v.cssVar}: ${fluid};`;
+      }
+    }
+    return `  ${v.cssVar}: ${v.value};`;
+  });
+
+  if (fluidActive) {
+    const siteMargin = responsiveScales?.siteMargin ?? DEFAULT_SITE_MARGIN;
+    baseVars.push(`  --site-margin: ${buildSiteMarginClamp(siteMargin, fluidRange)};`);
   }
 
-  const cssBlocks: string[] = [];
+  if (baseVars.length === 0) {
+    return '';
+  }
 
-  // Base :root block with all variables
-  const baseVars = config.variables.map(v => `  ${v.cssVar}: ${v.value};`);
   cssBlocks.push(`:root {\n${baseVars.join('\n')}\n}`);
 
-  // Generate @media blocks for responsive scaling
-  if (breakpoints && responsiveScales?.enabled) {
+  // Generate @media blocks for responsive scaling — only in breakpoints mode.
+  // In fluid mode all scaling is encoded in clamp() on the base :root block.
+  const userVariables = config.variables ?? [];
+  if (breakpoints && responsiveScales?.enabled && !fluidActive && userVariables.length > 0) {
     const baseRef = responsiveScales.baseReference || 16;
 
     // Sort breakpoints by value descending (largest first)
@@ -96,7 +135,7 @@ export function generateVariablesCSS(
     for (const [bpName, bpEntry] of sortedBreakpoints) {
       const scaledVars: string[] = [];
 
-      for (const variable of config.variables) {
+      for (const variable of userVariables) {
         // Per-variable override takes priority — stored string is the CSS value
         if (variable.scales && variable.scales[bpName]) {
           const overrideValue = variable.scales[bpName];

package/lib/server/fileWatcher.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect, afterEach, beforeEach } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { FileWatcher } from './fileWatcher';
+import { setProjectRoot, getProjectRoot } from './projectContext';
+
+/**
+ * Regression test for the "blank project" case: when `templates/` (or `cms/`)
+ * doesn't exist when the dev server starts, the watcher used to silently
+ * early-out and never fire onPageChange / onCMSChange even after the
+ * directory was created by an external tool. The deferred-attach path in
+ * fileWatcher.ts fixes this — the test asserts that callbacks now fire after
+ * a target directory is created post-startup.
+ *
+ * fs.watch on different OSes coalesces events differently, so the test waits
+ * generously and only asserts that the callback fires at least once.
+ */
+async function settle(ms = 300): Promise<void> {
+  await new Promise(r => setTimeout(r, ms));
+}
+
+describe('FileWatcher deferred attach', () => {
+  let projectRoot: string;
+
+  beforeEach(() => {
+    projectRoot = join(tmpdir(), `meno-fw-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(projectRoot, { recursive: true });
+  });
+
+  afterEach(() => {
+    try { rmSync(projectRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  test('watchTemplates fires onPageChange after templates/ is created post-startup', async () => {
+    const seen: string[] = [];
+    const watcher = new FileWatcher({
+      onPageChange: async (p) => { seen.push(p); },
+    });
+
+    // templates/ does NOT exist yet — pre-fix this returned silently.
+    const templatesDir = join(projectRoot, 'templates');
+    watcher.watchTemplates(templatesDir);
+
+    // Simulate the external write that triggers the bug: create templates/
+    // and drop a JSON file into it.
+    await settle(50);
+    mkdirSync(templatesDir);
+    await settle(100);
+    writeFileSync(join(templatesDir, 'blog.json'), '{}');
+    await settle(300);
+
+    watcher.stopAll();
+    expect(seen.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test('watchCMS fires onCMSChange after cms/ is created post-startup', async () => {
+    const seen: string[] = [];
+    const watcher = new FileWatcher({
+      onCMSChange: async (collection) => { seen.push(collection); },
+    });
+
+    const cmsDir = join(projectRoot, 'cms');
+    watcher.watchCMS(cmsDir);
+
+    await settle(50);
+    mkdirSync(join(cmsDir, 'blog'), { recursive: true });
+    await settle(100);
+    writeFileSync(join(cmsDir, 'blog', 'post.json'), '{}');
+    await settle(300);
+
+    watcher.stopAll();
+    expect(seen.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test('returns silently when parent dir also does not exist', () => {
+    const watcher = new FileWatcher({});
+    expect(() => watcher.watchTemplates(join(projectRoot, 'nonexistent-parent', 'templates'))).not.toThrow();
+    watcher.stopAll();
+  });
+});
+
+describe('FileWatcher project.config.json', () => {
+  let projectRoot: string;
+  let prevRoot: string;
+
+  beforeEach(() => {
+    prevRoot = getProjectRoot();
+    projectRoot = join(tmpdir(), `meno-fw-cfg-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(projectRoot, { recursive: true });
+    // watchProjectConfig reads getProjectRoot() — point it at the temp dir.
+    setProjectRoot(projectRoot);
+  });
+
+  afterEach(() => {
+    setProjectRoot(prevRoot);
+    try { rmSync(projectRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  test('fires onProjectConfigChange when project.config.json is written', async () => {
+    let fired = 0;
+    const watcher = new FileWatcher({
+      onProjectConfigChange: async () => { fired++; },
+    });
+
+    watcher.watchProjectConfig();
+    await settle(50);
+
+    // Simulate AI / external tool editing project.config.json to add a locale.
+    writeFileSync(join(projectRoot, 'project.config.json'), JSON.stringify({
+      i18n: { defaultLocale: 'en', locales: [{ code: 'en' }, { code: 'fr' }] }
+    }));
+    await settle(300);
+
+    watcher.stopAll();
+    expect(fired).toBeGreaterThanOrEqual(1);
+  });
+
+  test('ignores writes to unrelated files at the project root', async () => {
+    let fired = 0;
+    const watcher = new FileWatcher({
+      onProjectConfigChange: async () => { fired++; },
+    });
+
+    watcher.watchProjectConfig();
+    await settle(50);
+
+    writeFileSync(join(projectRoot, 'README.md'), 'hello');
+    await settle(200);
+
+    watcher.stopAll();
+    expect(fired).toBe(0);
+  });
+});