meno-core 1.1.5 → 1.1.7

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/ssr/htmlGenerator.test.ts

@@ -2,7 +2,7 @@
  * Tests for htmlGenerator - SSR HTML document generation
  */
 
-import { describe, test, expect, mock, beforeEach, afterAll } from 'bun:test';
+import { describe, test, expect, mock, beforeEach, afterEach, afterAll } from 'bun:test';
 
 // ---- Mock all dependencies before importing the module under test ----
 
@@ -177,7 +177,11 @@ mock.module('../../shared/libraryLoader', () => ({
 import { generateSSRHTML } from './htmlGenerator';
 import type { PreloadImage } from './ssrRenderer';
 import type { ClientDataCollection } from './clientDataInjector';
-import type { InteractiveStyles } from '../../shared/types';
+import type { ComponentDefinition, InteractiveStyles, JSONPage } from '../../shared/types';
+import { getProjectRoot, setProjectRoot } from '../projectContext';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 // ---- Fixtures ----
 
@@ -342,6 +346,105 @@ describe('generateSSRHTML', () => {
       expect(result).not.toContain('data-meno-page-css');
     });
 
+    // Local-file imports need a real project root: these tests point projectContext
+    // at a temp dir with CSS files on disk, covering page AND component frontmatter
+    // imports (a component's `import './card.css'` is bundled by the real Astro build,
+    // so the select canvas must surface it too).
+    describe('local CSS files on disk', () => {
+      let tmpRoot: string;
+      let prevRoot: string;
+
+      beforeEach(() => {
+        prevRoot = getProjectRoot();
+        tmpRoot = mkdtempSync(join(tmpdir(), 'meno-htmlgen-css-'));
+        mkdirSync(join(tmpRoot, 'src/components'), { recursive: true });
+        mkdirSync(join(tmpRoot, 'src/styles'), { recursive: true });
+        setProjectRoot(tmpRoot);
+      });
+
+      afterEach(() => {
+        setProjectRoot(prevRoot);
+        rmSync(tmpRoot, { recursive: true, force: true });
+      });
+
+      const cardImporter: ComponentDefinition = { component: { _frontmatter: "import './card.css';" } };
+      const pageUsing = (...names: string[]) =>
+        ({
+          root: { type: 'node', tag: 'div', children: names.map((n) => ({ type: n })) },
+          meta: { title: 'Test' },
+        }) as unknown as JSONPage;
+
+      test('inlines a CSS file imported by a component used on the page', async () => {
+        writeFileSync(join(tmpRoot, 'src/components/card.css'), '.card { color: rebeccapurple; }');
+        const result = (await generateSSRHTML({
+          pageData: pageUsing('Card'),
+          globalComponents: { Card: cardImporter },
+        })) as string;
+        expect(result).toContain('data-meno-page-css="./card.css"');
+        expect(result).toContain('rebeccapurple');
+        // After the generated stylesheet, so hand-authored CSS can override utilities.
+        expect(result.indexOf('id="meno-styles"')).toBeLessThan(result.indexOf('data-meno-page-css'));
+      });
+
+      test('skips CSS from a component the page does not use', async () => {
+        writeFileSync(join(tmpRoot, 'src/components/card.css'), '.card { color: rebeccapurple; }');
+        const result = (await generateSSRHTML({
+          pageData: pageUsing('Hero'),
+          globalComponents: { Card: cardImporter },
+        })) as string;
+        expect(result).not.toContain('data-meno-page-css');
+      });
+
+      test('reaches components transitively (page → Layout → Header)', async () => {
+        writeFileSync(join(tmpRoot, 'src/components/header.css'), '.hdr { outline: 1px solid red; }');
+        const components: Record<string, ComponentDefinition> = {
+          Layout: { component: { structure: { type: 'node', tag: 'div', children: [{ type: 'Header' }] } as never } },
+          Header: { component: { _frontmatter: "import './header.css';" } },
+        };
+        const result = (await generateSSRHTML({
+          pageData: pageUsing('Layout'),
+          globalComponents: components,
+        })) as string;
+        expect(result).toContain('data-meno-page-css="./header.css"');
+      });
+
+      test('inlines a stylesheet shared by two components only once', async () => {
+        writeFileSync(join(tmpRoot, 'src/components/shared.css'), '.shared { --shared-marker: 1; }');
+        const importer: ComponentDefinition = { component: { _frontmatter: "import './shared.css';" } };
+        const result = (await generateSSRHTML({
+          pageData: pageUsing('Card', 'Hero'),
+          globalComponents: { Card: importer, Hero: importer },
+        })) as string;
+        expect(result.split('--shared-marker').length - 1).toBe(1);
+      });
+
+      test('resolves a page-relative ./sibling.css against the page directory from options.pagePath', async () => {
+        // Regression: the call site once passed the positional `pagePath` parameter,
+        // which is stuck at '/' for options-object calls, so `./post.css` on a nested
+        // page resolved against src/pages instead of src/pages/blog and vanished.
+        mkdirSync(join(tmpRoot, 'src/pages/blog'), { recursive: true });
+        writeFileSync(join(tmpRoot, 'src/pages/blog/post.css'), '.post { letter-spacing: 2px; }');
+        const page = { ...minimalPage, _frontmatter: "import './post.css';" };
+        const result = (await generateSSRHTML({ pageData: page, pagePath: '/blog/my-post' })) as string;
+        expect(result).toContain('data-meno-page-css="./post.css"');
+        expect(result).toContain('letter-spacing: 2px');
+      });
+
+      test('orders component CSS before page CSS so the page wins the cascade', async () => {
+        writeFileSync(join(tmpRoot, 'src/components/card.css'), '.card { color: rebeccapurple; }');
+        writeFileSync(join(tmpRoot, 'src/styles/extra.css'), '.extra { color: teal; }');
+        const page = {
+          ...(pageUsing('Card') as object),
+          _frontmatter: "import '../styles/extra.css';",
+        } as unknown as JSONPage;
+        const result = (await generateSSRHTML({
+          pageData: page,
+          globalComponents: { Card: cardImporter },
+        })) as string;
+        expect(result.indexOf('rebeccapurple')).toBeLessThan(result.indexOf('teal'));
+      });
+    });
+
     test('should minify CSS in production mode (useBuiltBundle=true)', async () => {
       mockRenderPageSSR.mockImplementation(async () => ({
         html: '<div>Content</div>',