meno-core 1.1.5 → 1.1.6

package/lib/server/ssr/htmlGenerator.ts

@@ -85,26 +85,9 @@ function minifyCSS(code: string): string {
   );
 }
 
-/**
- * Inline a page's hand-authored CSS imports into the head.
- *
- * A page can `import '../styles/extra.css'` in its `.astro` frontmatter. The codec
- * can't model such an import, so it's captured verbatim as `_frontmatter`
- * passthrough — the real `astro build` bundles + injects it, but the meno-core SSR
- * canvas (Meno Select) never learned about it, so hand-imported stylesheets rendered
- * in Astro mode yet vanished in select mode. Here we extract those side-effect CSS
- * imports, read each file, and inline it into a `<style>` so the select canvas
- * matches the build. Best-effort: an unresolvable/remote-only import is skipped, not
- * fatal. theme.css / local libraries are regenerated elsewhere and are never captured
- * as passthrough, so they don't appear here.
- */
-async function collectPageCssImports(
-  frontmatter: string | undefined,
-  pagePath: string | undefined,
-  nonceAttr: string,
-): Promise<string> {
-  if (!frontmatter?.includes('.css')) return '';
-
+/** Side-effect CSS import specifiers in a frontmatter passthrough block, in source order. */
+function extractCssImportSpecs(frontmatter: string | undefined): string[] {
+  if (!frontmatter?.includes('.css')) return [];
   const seen = new Set<string>();
   const specs: string[] = [];
   const re = /import\b[^'"]*['"]([^'"]+\.css)(?:\?[^'"]*)?['"]/g;
@@ -117,39 +100,110 @@ async function collectPageCssImports(
     if (spec.endsWith('styles/theme.css')) continue; // regenerated by the color/variable services
     specs.push(spec);
   }
-  if (specs.length === 0) return '';
+  return specs;
+}
+
+/**
+ * Component definitions reachable from the page: a name counts as used when it
+ * appears (quoted) in the page's JSON, or in the JSON of an already-used component
+ * (components nest). Same best-effort heuristic the de-mirror audit uses — a false
+ * positive merely inlines a stylesheet the build would have bundled on another page.
+ */
+function usedComponentDefs(pageData: JSONPage, components: Record<string, ComponentDefinition>): ComponentDefinition[] {
+  const entries = Object.entries(components);
+  const used = new Map<string, ComponentDefinition>();
+  let hay = JSON.stringify(pageData ?? '');
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const [name, def] of entries) {
+      if (used.has(name) || !hay.includes(`"${name}"`)) continue;
+      used.set(name, def);
+      hay += JSON.stringify(def ?? '');
+      grew = true;
+    }
+  }
+  return [...used.values()];
+}
 
+/**
+ * Inline hand-authored CSS imports into the head.
+ *
+ * A page or component can `import '../styles/extra.css'` in its `.astro`
+ * frontmatter. The codec can't model such an import, so it's captured verbatim as
+ * `_frontmatter` passthrough — the real `astro build` bundles + injects it, but the
+ * meno-core SSR canvas (Meno Select) never learned about it, so hand-imported
+ * stylesheets rendered in Astro mode yet vanished in select mode. Here we extract
+ * those side-effect CSS imports — from the page AND from every component the page
+ * (transitively) uses — read each file, and inline it into a `<style>` so the
+ * select canvas matches the build. Best-effort: an unresolvable/remote-only import
+ * is skipped, not fatal. theme.css / local libraries are regenerated elsewhere and
+ * are never captured as passthrough, so they don't appear here.
+ */
+async function collectPageCssImports(
+  pageData: JSONPage,
+  components: Record<string, ComponentDefinition>,
+  pagePath: string | undefined,
+  nonceAttr: string,
+): Promise<string> {
   // The page's source directory, reconstructed from its URL path
   // (src/pages/<dir>). dirname('/') and dirname('/about') both yield the pages root.
   const pageDir = posix.join('src/pages', posix.dirname(pagePath || '/'));
 
+  // (spec, baseDir) pairs. Component imports resolve against src/components (where
+  // every component .astro lives) and come first; the page's own imports come last
+  // so they can override component styles, matching the build's cascade order
+  // (a page imports its components before its own stylesheet).
+  const sources: Array<{ spec: string; baseDir: string }> = [];
+  if (Object.values(components).some((d) => d?.component?._frontmatter?.includes('.css'))) {
+    for (const def of usedComponentDefs(pageData, components)) {
+      for (const spec of extractCssImportSpecs(def.component?._frontmatter)) {
+        sources.push({ spec, baseDir: 'src/components' });
+      }
+    }
+  }
+  for (const spec of extractCssImportSpecs(pageData._frontmatter)) {
+    sources.push({ spec, baseDir: pageDir });
+  }
+  if (sources.length === 0) return '';
+
   const tags: string[] = [];
-  for (const spec of specs) {
+  const linkedRemote = new Set<string>();
+  const inlinedFiles = new Set<string>();
+  for (const { spec, baseDir } of sources) {
     // Remote stylesheet — link it directly (can't inline what we can't read).
     if (/^(?:https?:)?\/\//.test(spec)) {
+      if (linkedRemote.has(spec)) continue;
+      linkedRemote.add(spec);
       tags.push(`<link rel="stylesheet" href="${escapeHtml(spec)}">`);
       continue;
     }
     // Candidate project-relative paths, tried in order:
-    //   1. resolved against the page's own directory — correct for `./sibling.css`
-    //      and correctly-depthed `../` on un-prefixed routes;
+    //   1. resolved against the importing file's own directory — correct for
+    //      `./sibling.css` and correctly-depthed `../` on un-prefixed routes;
     //   2. leading traversal stripped, anchored at src/ — robust for the dominant
     //      `../styles/*.css` pattern even on localized `[locale]` routes where
     //      pagePath doesn't map 1:1 to the source file's depth.
     const candidates = spec.startsWith('/')
       ? [spec.slice(1)]
-      : [posix.normalize(posix.join(pageDir, spec)), `src/${spec.replace(/^(?:\.\.?\/)+/, '')}`];
+      : [posix.normalize(posix.join(baseDir, spec)), `src/${spec.replace(/^(?:\.\.?\/)+/, '')}`];
     let css: string | null = null;
+    let resolved: string | null = null;
     for (const rel of candidates) {
       if (rel.startsWith('..')) continue; // never read outside the project root
       try {
         css = await readTextFile(resolveProjectPath(rel));
+        resolved = rel;
         break;
       } catch {
         /* try the next candidate */
       }
     }
-    if (css == null) continue;
+    if (css == null || resolved == null) continue;
+    // Same file imported from several places (e.g. two components sharing a
+    // stylesheet) is inlined once.
+    if (inlinedFiles.has(resolved)) continue;
+    inlinedFiles.add(resolved);
     // Stabilize viewport units for the design canvas (same as the generated sheet)
     // and neutralize any literal `</style>` so it can't break out of the tag.
     const content = rewriteViewportUnitsInStylesheet(css).replace(/<\/style/gi, '<\\/style');
@@ -719,6 +773,11 @@ picture {
   // matches the iframe document's locked-in CSP — so Chromium would drop the
   // node and ALL CSS would vanish. Mutating the already-approved node's text
   // doesn't re-trigger nonce validation (same trick StyleInjector uses in dev).
+  // The `data-meno-page-css` tags (hand-imported stylesheets inlined by
+  // collectPageCssImports) get the same in-place treatment, matched by index +
+  // attribute; a changed tag SET (an import added or removed) falls back to a
+  // full reload, since inserting a new <style> node would need a nonce the
+  // locked-in CSP no longer accepts.
   //
   // For the same reason, the `<script id="meno-cms-*">` context scripts (which
   // ARE recreated, since an inline script must be a fresh node to re-execute)
@@ -727,7 +786,7 @@ picture {
   // HTML. Without it, nonce-only `script-src` would drop the recreated script
   // and CMS hot-reload (updated `window.__MENO_CMS__` data) would silently fail.
   const liveReloadScript = injectLiveReload
-    ? `<script${nonceAttr}>(function(){var ws,timer,gen=0,lastSrvRoot=null,dn=document.querySelector('meta[name="csp-nonce"]'),docNonce=dn?dn.getAttribute('content'):'';function strip(s){return s?s.replace(/[?&]_r=\\d+/,''):''}function iScroll(x,y){var de=document.documentElement,b=document.body,pd=de.style.scrollBehavior,pb=b?b.style.scrollBehavior:'';de.style.scrollBehavior='auto';if(b)b.style.scrollBehavior='auto';try{window.scrollTo(x,y)}catch(e){}de.style.scrollBehavior=pd;if(b)b.style.scrollBehavior=pb}function classList(el){return (el.getAttribute('class')||'').split(/\\s+/).filter(Boolean)}function syncEl(cur,srv,old){var cc=classList(cur),sc=classList(srv),oc=old?new Set(classList(old)):new Set();var rt=cc.filter(function(c){return !oc.has(c)});var seen=new Set(),fin=[];sc.concat(rt).forEach(function(c){if(!seen.has(c)){seen.add(c);fin.push(c)}});var fs=fin.join(' ');if((cur.getAttribute('class')||'')!==fs){if(fs)cur.setAttribute('class',fs);else cur.removeAttribute('class')}for(var i=0;i<srv.attributes.length;i++){var a=srv.attributes[i];if(a.name==='class')continue;var ov=old?old.getAttribute(a.name):null;if(a.value!==ov){if(cur.getAttribute(a.name)!==a.value)cur.setAttribute(a.name,a.value)}}if(old){for(var i=0;i<old.attributes.length;i++){var a=old.attributes[i];if(a.name==='class')continue;if(!srv.hasAttribute(a.name)&&cur.hasAttribute(a.name))cur.removeAttribute(a.name)}}}function syncText(cur,srv){var cc=cur.childNodes,sc=srv.childNodes;for(var i=0;i<sc.length;i++){var s=sc[i],c=cc[i];if(s.nodeType===3&&c&&c.nodeType===3){if(c.textContent!==s.textContent)c.textContent=s.textContent}}}function ek(el){var p=el.getAttribute('data-element-path'),ci=el.getAttribute('data-cms-item-index');return ci?p+'|'+ci:p}function structKey(root){var e=root.querySelectorAll('[data-element-path]'),k=[];for(var i=0;i<e.length;i++)k.push(ek(e[i]));return k.sort().join('~')}function softSync(curR,srvR,oldR){var ce=curR.querySelectorAll('[data-element-path]');var sbp={},se=srvR.querySelectorAll('[data-element-path]');for(var i=0;i<se.length;i++)sbp[ek(se[i])]=se[i];var obp={};if(oldR){var oe=oldR.querySelectorAll('[data-element-path]');for(var i=0;i<oe.length;i++)obp[ek(oe[i])]=oe[i]}for(var i=0;i<ce.length;i++){var c=ce[i],p=ek(c),s=sbp[p];if(!s)continue;syncEl(c,s,obp[p]);syncText(c,s)}syncText(curR,srvR)}function connect(){ws=new WebSocket(${wsUrl});ws.onmessage=function(e){var d=JSON.parse(e.data);if(d.type==='hmr:libraries-update'){location.reload()}else if(d.type==='hmr:update'||d.type==='hmr:cms-update'||d.type==='hmr:colors-update'||d.type==='hmr:variables-update')hotReload()};ws.onclose=function(){clearTimeout(timer);timer=setTimeout(connect,1000)}}function hotReload(){var g=++gen;var sx=window.scrollX,sy=window.scrollY;fetch(location.href,{cache:'no-store'}).then(function(r){return r.text()}).then(function(html){if(g!==gen)return;var p=new DOMParser();var d=p.parseFromString(html,'text/html');var or=document.getElementById('root'),nr=d.getElementById('root');var oscr=document.querySelector('script[src^="/_scripts/"]'),nscr=d.querySelector('script[src^="/_scripts/"]');var oss=oscr?strip(oscr.getAttribute('src')):'',nss=nscr?strip(nscr.getAttribute('src')):'';var hardReset=(oss!==nss)||!lastSrvRoot||!or||!nr||structKey(lastSrvRoot)!==structKey(nr);if(or&&nr){if(hardReset){if(or.innerHTML!==nr.innerHTML)or.innerHTML=nr.innerHTML}else{softSync(or,nr,lastSrvRoot)}}if(nr)lastSrvRoot=nr.cloneNode(true);var os=document.getElementById('meno-styles'),ns=d.getElementById('meno-styles');if(os&&ns&&os.textContent!==ns.textContent)os.textContent=ns.textContent;var nh=d.documentElement;if(nh){var nl=nh.getAttribute('lang')||'en',nt=nh.getAttribute('theme')||'light';if(document.documentElement.getAttribute('lang')!==nl)document.documentElement.setAttribute('lang',nl);if(document.documentElement.getAttribute('theme')!==nt)document.documentElement.setAttribute('theme',nt)}var ocms=document.querySelectorAll('script[id^="meno-cms-"]'),ncms=d.querySelectorAll('script[id^="meno-cms-"]');var ock=JSON.stringify(Array.prototype.map.call(ocms,function(s){return [s.id,s.textContent]}));var nck=JSON.stringify(Array.prototype.map.call(ncms,function(s){return [s.id,s.textContent]}));if(ock!==nck){ocms.forEach(function(s){s.remove()});ncms.forEach(function(s){var c=document.createElement('script');c.type=s.type;c.id=s.id;if(docNonce)c.nonce=docNonce;c.textContent=s.textContent;document.head.appendChild(c)})}window.__menoHotReload=true;var olib=document.querySelectorAll('body > script[src^="/libraries/"]'),nlib=d.querySelectorAll('body > script[src^="/libraries/"]');var olk=JSON.stringify(Array.prototype.map.call(olib,function(s){return strip(s.getAttribute('src'))}).sort());var nlk=JSON.stringify(Array.prototype.map.call(nlib,function(s){return strip(s.getAttribute('src'))}).sort());if(olk!==nlk){olib.forEach(function(o){o.remove()});nlib.forEach(function(n){var src=n.getAttribute('src');var ls=document.createElement('script');ls.src=src+(src.indexOf('?')>-1?'&':'?')+'_r='+Date.now();document.body.appendChild(ls)})}if(!hardReset){iScroll(sx,sy)}else{if(oscr)oscr.remove();if(nscr){var src=nscr.getAttribute('src');var s=document.createElement('script');s.src=src+(src.indexOf('?')>-1?'&':'?')+'_r='+Date.now();s.onload=function(){document.dispatchEvent(new Event('DOMContentLoaded'));iScroll(sx,sy)};s.onerror=function(){iScroll(sx,sy)};document.body.appendChild(s)}else{document.dispatchEvent(new Event('DOMContentLoaded'));iScroll(sx,sy)}}}).catch(function(){location.reload()})}var iR=document.getElementById('root');if(iR)lastSrvRoot=iR.cloneNode(true);connect()})()</script>`
+    ? `<script${nonceAttr}>(function(){var ws,timer,gen=0,lastSrvRoot=null,dn=document.querySelector('meta[name="csp-nonce"]'),docNonce=dn?dn.getAttribute('content'):'';function strip(s){return s?s.replace(/[?&]_r=\\d+/,''):''}function iScroll(x,y){var de=document.documentElement,b=document.body,pd=de.style.scrollBehavior,pb=b?b.style.scrollBehavior:'';de.style.scrollBehavior='auto';if(b)b.style.scrollBehavior='auto';try{window.scrollTo(x,y)}catch(e){}de.style.scrollBehavior=pd;if(b)b.style.scrollBehavior=pb}function classList(el){return (el.getAttribute('class')||'').split(/\\s+/).filter(Boolean)}function syncEl(cur,srv,old){var cc=classList(cur),sc=classList(srv),oc=old?new Set(classList(old)):new Set();var rt=cc.filter(function(c){return !oc.has(c)});var seen=new Set(),fin=[];sc.concat(rt).forEach(function(c){if(!seen.has(c)){seen.add(c);fin.push(c)}});var fs=fin.join(' ');if((cur.getAttribute('class')||'')!==fs){if(fs)cur.setAttribute('class',fs);else cur.removeAttribute('class')}for(var i=0;i<srv.attributes.length;i++){var a=srv.attributes[i];if(a.name==='class')continue;var ov=old?old.getAttribute(a.name):null;if(a.value!==ov){if(cur.getAttribute(a.name)!==a.value)cur.setAttribute(a.name,a.value)}}if(old){for(var i=0;i<old.attributes.length;i++){var a=old.attributes[i];if(a.name==='class')continue;if(!srv.hasAttribute(a.name)&&cur.hasAttribute(a.name))cur.removeAttribute(a.name)}}}function syncText(cur,srv){var cc=cur.childNodes,sc=srv.childNodes;for(var i=0;i<sc.length;i++){var s=sc[i],c=cc[i];if(s.nodeType===3&&c&&c.nodeType===3){if(c.textContent!==s.textContent)c.textContent=s.textContent}}}function ek(el){var p=el.getAttribute('data-element-path'),ci=el.getAttribute('data-cms-item-index');return ci?p+'|'+ci:p}function structKey(root){var e=root.querySelectorAll('[data-element-path]'),k=[];for(var i=0;i<e.length;i++)k.push(ek(e[i]));return k.sort().join('~')}function softSync(curR,srvR,oldR){var ce=curR.querySelectorAll('[data-element-path]');var sbp={},se=srvR.querySelectorAll('[data-element-path]');for(var i=0;i<se.length;i++)sbp[ek(se[i])]=se[i];var obp={};if(oldR){var oe=oldR.querySelectorAll('[data-element-path]');for(var i=0;i<oe.length;i++)obp[ek(oe[i])]=oe[i]}for(var i=0;i<ce.length;i++){var c=ce[i],p=ek(c),s=sbp[p];if(!s)continue;syncEl(c,s,obp[p]);syncText(c,s)}syncText(curR,srvR)}function connect(){ws=new WebSocket(${wsUrl});ws.onmessage=function(e){var d=JSON.parse(e.data);if(d.type==='hmr:libraries-update'){location.reload()}else if(d.type==='hmr:update'||d.type==='hmr:cms-update'||d.type==='hmr:colors-update'||d.type==='hmr:variables-update')hotReload()};ws.onclose=function(){clearTimeout(timer);timer=setTimeout(connect,1000)}}function hotReload(){var g=++gen;var sx=window.scrollX,sy=window.scrollY;fetch(location.href,{cache:'no-store'}).then(function(r){return r.text()}).then(function(html){if(g!==gen)return;var p=new DOMParser();var d=p.parseFromString(html,'text/html');var or=document.getElementById('root'),nr=d.getElementById('root');var oscr=document.querySelector('script[src^="/_scripts/"]'),nscr=d.querySelector('script[src^="/_scripts/"]');var oss=oscr?strip(oscr.getAttribute('src')):'',nss=nscr?strip(nscr.getAttribute('src')):'';var hardReset=(oss!==nss)||!lastSrvRoot||!or||!nr||structKey(lastSrvRoot)!==structKey(nr);if(or&&nr){if(hardReset){if(or.innerHTML!==nr.innerHTML)or.innerHTML=nr.innerHTML}else{softSync(or,nr,lastSrvRoot)}}if(nr)lastSrvRoot=nr.cloneNode(true);var os=document.getElementById('meno-styles'),ns=d.getElementById('meno-styles');if(os&&ns&&os.textContent!==ns.textContent)os.textContent=ns.textContent;var ops=document.querySelectorAll('style[data-meno-page-css]'),nps=d.querySelectorAll('style[data-meno-page-css]');var pcMismatch=ops.length!==nps.length;if(!pcMismatch){for(var pi=0;pi<nps.length;pi++){if(ops[pi].getAttribute('data-meno-page-css')!==nps[pi].getAttribute('data-meno-page-css')){pcMismatch=true;break}if(ops[pi].textContent!==nps[pi].textContent)ops[pi].textContent=nps[pi].textContent}}if(pcMismatch){location.reload();return}var nh=d.documentElement;if(nh){var nl=nh.getAttribute('lang')||'en',nt=nh.getAttribute('theme')||'light';if(document.documentElement.getAttribute('lang')!==nl)document.documentElement.setAttribute('lang',nl);if(document.documentElement.getAttribute('theme')!==nt)document.documentElement.setAttribute('theme',nt)}var ocms=document.querySelectorAll('script[id^="meno-cms-"]'),ncms=d.querySelectorAll('script[id^="meno-cms-"]');var ock=JSON.stringify(Array.prototype.map.call(ocms,function(s){return [s.id,s.textContent]}));var nck=JSON.stringify(Array.prototype.map.call(ncms,function(s){return [s.id,s.textContent]}));if(ock!==nck){ocms.forEach(function(s){s.remove()});ncms.forEach(function(s){var c=document.createElement('script');c.type=s.type;c.id=s.id;if(docNonce)c.nonce=docNonce;c.textContent=s.textContent;document.head.appendChild(c)})}window.__menoHotReload=true;var olib=document.querySelectorAll('body > script[src^="/libraries/"]'),nlib=d.querySelectorAll('body > script[src^="/libraries/"]');var olk=JSON.stringify(Array.prototype.map.call(olib,function(s){return strip(s.getAttribute('src'))}).sort());var nlk=JSON.stringify(Array.prototype.map.call(nlib,function(s){return strip(s.getAttribute('src'))}).sort());if(olk!==nlk){olib.forEach(function(o){o.remove()});nlib.forEach(function(n){var src=n.getAttribute('src');var ls=document.createElement('script');ls.src=src+(src.indexOf('?')>-1?'&':'?')+'_r='+Date.now();document.body.appendChild(ls)})}if(!hardReset){iScroll(sx,sy)}else{if(oscr)oscr.remove();if(nscr){var src=nscr.getAttribute('src');var s=document.createElement('script');s.src=src+(src.indexOf('?')>-1?'&':'?')+'_r='+Date.now();s.onload=function(){document.dispatchEvent(new Event('DOMContentLoaded'));iScroll(sx,sy)};s.onerror=function(){iScroll(sx,sy)};document.body.appendChild(s)}else{document.dispatchEvent(new Event('DOMContentLoaded'));iScroll(sx,sy)}}}).catch(function(){location.reload()})}var iR=document.getElementById('root');if(iR)lastSrvRoot=iR.cloneNode(true);connect()})()</script>`
     : '';
 
   // Scroll position handlers for preview mode iframe switching
@@ -738,11 +797,12 @@ picture {
   // In production, output minified CSS on single line; in dev, preserve formatting
   const styleContent = useBundled ? finalCSS : `\n    ${combinedCSS.split('\n').join('\n    ')}\n  `;
 
-  // Inline any hand-authored CSS the page imports in its frontmatter (foreign
-  // passthrough the Astro build bundles but the select canvas otherwise misses).
-  // Placed after #meno-styles so it can override generated utilities, matching the
-  // intent of a page pulling in its own stylesheet.
-  const pageCssTags = await collectPageCssImports(pageData._frontmatter, pagePath, nonceAttr);
+  // Inline any hand-authored CSS the page or its components import in frontmatter
+  // (foreign passthrough the Astro build bundles but the select canvas otherwise
+  // misses). Placed after #meno-styles so it can override generated utilities,
+  // matching the intent of a file pulling in its own stylesheet. NOTE: `path`, not
+  // `pagePath` — the positional param is stuck at '/' for options-object calls.
+  const pageCssTags = await collectPageCssImports(pageData, components, path, nonceAttr);
 
   const htmlDocument = `<!DOCTYPE html>
 <html lang="${rendered.locale}" theme="${themeConfig.default}">

package/lib/server/ssr/ssrRenderer.test.ts

@@ -1140,6 +1140,70 @@ describe('ssrRenderer', () => {
       expect(classMatch?.[1]).toContain('text-[#ff0000]');
     });
 
+    test('instance class override BEATS the root prop-bound style for the same property', async () => {
+      // The root's maxWidth is prop-bound ({{maxWidth}} → "100%" → max-w-full at render);
+      // the instance overrides it with class="max-w-[283px]". Both classes have equal
+      // specificity, so if both land on the element the stylesheet ORDER picks the winner —
+      // the root's max-w-full must therefore never be emitted at all, mirroring the
+      // meno-astro runtime's mergeInstanceClasses/inlineStyle (where the instance wins).
+      const componentDef: ComponentDefinition = {
+        component: {
+          structure: {
+            type: 'node',
+            tag: 'h1',
+            style: { maxWidth: '{{maxWidth}}' },
+            children: '{{text}}',
+          },
+          interface: {
+            text: { type: 'string', default: 'Hi' },
+            maxWidth: { type: 'string', default: '100%' },
+          },
+        },
+      };
+
+      const node = {
+        type: 'component',
+        component: 'Heading',
+        props: { text: 'Hi', maxWidth: '100%', class: 'max-w-[283px]' },
+      };
+
+      const html = await render(node, { globalComponents: { Heading: componentDef } });
+      const classMatch = html.match(/<h1[^>]*\sclass="([^"]*)"/);
+      expect(classMatch).not.toBeNull();
+      expect(classMatch?.[1]).toContain('max-w-[283px]');
+      expect(classMatch?.[1]).not.toContain('max-w-full');
+    });
+
+    test('instance class override drops the conflicting root class but keeps other breakpoints', async () => {
+      // Root carries a static base class AND a tablet override; the instance overrides only
+      // the base — the root's tablet class must survive (conflicts are per-breakpoint).
+      const componentDef: ComponentDefinition = {
+        component: {
+          structure: {
+            type: 'node',
+            tag: 'div',
+            attributes: { class: 'max-w-full max-lg:max-w-[90%] flex' },
+            children: 'Content',
+          },
+          interface: {},
+        },
+      };
+
+      const node = {
+        type: 'component',
+        component: 'Card',
+        props: { class: 'max-w-[283px]' },
+      };
+
+      const html = await render(node, { globalComponents: { Card: componentDef } });
+      const classMatch = html.match(/<div[^>]*\sclass="([^"]*)"/);
+      expect(classMatch).not.toBeNull();
+      expect(classMatch?.[1]).toContain('max-w-[283px]');
+      expect(classMatch?.[1]).toContain('max-lg:max-w-[90%]');
+      expect(classMatch?.[1]).toContain('flex');
+      expect(classMatch?.[1]?.split(/\s+/)).not.toContain('max-w-full');
+    });
+
     test('component with defineVars: true adds data attributes', async () => {
       const componentDef: ComponentDefinition = {
         component: {
@@ -1380,6 +1444,42 @@ describe('ssrRenderer', () => {
       const html = await render(node, { globalComponents: { InlineStyleComp: compDef } });
       expect(html).toContain('<div');
     });
+
+    test('var-bridges template-bound style values in a component structure (templateStyleVars.ts)', async () => {
+      // A prop-bound declaration (`gap: "{{gap}}px"`) must render exactly like the real
+      // Astro build: the element's class reads `var(--m-base-gap)` (so auto-responsive
+      // scaling never rewrites the value) and the element sets the variable inline.
+      const compDef: ComponentDefinition = {
+        component: {
+          structure: {
+            type: 'node',
+            tag: 'div',
+            style: { base: { gap: '{{gap}}px', display: 'flex' } },
+            children: 'bridged',
+          },
+          interface: {
+            gap: { type: 'number', default: 24 },
+          },
+        },
+      };
+
+      const node = {
+        type: 'component',
+        component: 'BridgedGap',
+        props: { gap: 40 },
+      };
+
+      const html = await render(node, { globalComponents: { BridgedGap: compDef } });
+      // Class reads the bridge variable, not the concrete value — the mapper normalizes
+      // `var(--x)` values to the self-describing shorthand form `gap-(--x)`, exactly as
+      // the meno-astro runtime's style() does (same mapper).
+      expect(html).toContain('gap-(--m-base-gap)');
+      expect(html).not.toContain('gap-[40px]');
+      // …and the element sets the variable inline to the resolved value.
+      expect(html).toContain('--m-base-gap: 40px');
+      // Static values in the same style object keep their normal utility class.
+      expect(html).toContain('flex');
+    });
   });
 
   // -----------------------------------------------------------------------

package/lib/server/ssr/ssrRenderer.ts

@@ -18,10 +18,11 @@ import {
 } from '../../shared/itemTemplateUtils';
 import { singularize, isItemDraftForLocale } from '../../shared/types/cms';
 import { applyCmsFilters, applyCmsSorting } from '../../shared/cmsQuery';
-import type { ResponsiveStyleObject, StyleObject } from '../../shared/types';
+import type { ResponsiveStyleObject, StyleObject, StyleValue } from '../../shared/types';
 import type { BreakpointConfig } from '../../shared/breakpoints';
 import type { ResponsiveScales } from '../../shared/responsiveScaling';
 import { processStructure, isResponsiveStyle, isHtmlMapping, resolveHtmlMapping } from '../../client/templateEngine';
+import { getTemplateVars } from '../../shared/templateStyleVars';
 import { resolvePropsFromDefinition } from '../../shared/propResolver';
 import { loadBreakpointConfig, loadI18nConfig } from '../jsonLoader';
 import { configService } from '../services/configService';
@@ -76,7 +77,11 @@ function getDOMPurify(): DOMPurifyLike | null {
   }
   return _DOMPurify;
 }
-import { responsiveStylesToClasses } from '../../shared/utilityClassMapper';
+import {
+  responsiveStylesToClasses,
+  mergeInstanceClasses,
+  stripClassOverriddenStyleProps,
+} from '../../shared/utilityClassMapper';
 import { validateStyleCoverage } from '../validateStyleCoverage';
 import { generateElementClassName, type ElementClassContext } from '../../shared/elementClassName';
 import type { InteractiveStyles } from '../../shared/types/styles';
@@ -1587,6 +1592,12 @@ async function renderNode(
         embedCssVariables = registerInteractiveStyles(ctx, elementClass, embedInteractiveStyles);
       }
 
+      // Var-bridge for template-bound style values (see templateStyleVars.ts).
+      const embedTemplateVars = getTemplateVars(node);
+      if (embedTemplateVars) {
+        embedCssVariables = { ...embedCssVariables, ...embedTemplateVars };
+      }
+
       const embedStyleAttr = buildCssVariableStyleAttr(embedCssVariables);
 
       // Add attribute className if present
@@ -1614,9 +1625,11 @@ async function renderNode(
 
     const attrs = buildAttributes(nodeAttributes);
     const classAttr = classNames.length > 0 ? ` class="${escapeHtml(classNames.filter(Boolean).join(' '))}"` : '';
+    // Var-bridge for template-bound style values (see templateStyleVars.ts).
+    const embedStyleAttr = buildCssVariableStyleAttr(getTemplateVars(node) ?? {});
 
     // Always use span for embeds - valid inside <p> and other phrasing content
-    return `<span${classAttr}${attrs}${editorAttrs(ctx, { isSlotContent: isSlotContent(node) })}>${optimizedHtml}</span>`;
+    return `<span${classAttr}${embedStyleAttr}${attrs}${editorAttrs(ctx, { isSlotContent: isSlotContent(node) })}>${optimizedHtml}</span>`;
   }
 
   // Handle link nodes (render as <a> tag in SSR)
@@ -1684,9 +1697,15 @@ async function renderNode(
       if (olinkInteractiveStyles && olinkInteractiveStyles.length > 0) {
         olinkCssVariables = registerInteractiveStyles(ctx, elementClass, olinkInteractiveStyles);
       }
-      olinkStyleAttr = buildCssVariableStyleAttr(olinkCssVariables);
     }
 
+    // Var-bridge for template-bound style values (see templateStyleVars.ts).
+    const olinkTemplateVars = getTemplateVars(node);
+    if (olinkTemplateVars) {
+      olinkCssVariables = { ...olinkCssVariables, ...olinkTemplateVars };
+    }
+    olinkStyleAttr = buildCssVariableStyleAttr(olinkCssVariables);
+
     // Add attribute className if present
     const attrClassName = (nodeAttributes.className || nodeAttributes.class || '') as string;
     if (attrClassName) {
@@ -1843,6 +1862,16 @@ async function renderNode(
     }
   }
 
+  // Var-bridge for template-bound style values (see templateStyleVars.ts): the node's
+  // utility classes read var(--m-<bp>-<prop>); set the concrete value inline, mirroring
+  // the meno-astro runtime. Component instances never carry these (bridge skips them).
+  const nodeTemplateVars = getTemplateVars(node);
+  if (nodeTemplateVars) {
+    for (const [varName, value] of Object.entries(nodeTemplateVars)) {
+      (resolvedStyle as Record<string, string | number>)[varName] = value;
+    }
+  }
+
   // Merge resolved style into props.style, and merge attributes
   // Handle class/className specially - merge with utility classes instead of replacing
   const attrClassName = (nodeAttributes.className || nodeAttributes.class || '') as string;
@@ -1984,20 +2013,30 @@ async function renderComponent(
         mergeNodeStyles(rootNode, propsWithStyleAndAttrs.style as StyleObject | ResponsiveStyleObject);
       }
 
-      // Merge className from component instance (includes responsive utility classes)
+      // Merge className from component instance (includes responsive utility classes).
+      // Conflict-aware, instance-over-root: a root class targeting the same
+      // (breakpoint, CSS property) as an instance class is dropped, and the same
+      // properties are stripped from the root's style object — a prop-bound root
+      // style (maxWidth: {_mapping} → "100%") mints a root utility class
+      // (max-w-full) during the recursive render, which would otherwise fight the
+      // instance's max-w-[283px] on stylesheet order (equal specificity). Mirrors
+      // the meno-astro runtime's mergeInstanceClasses/inlineStyle pair, so Meno
+      // Select agrees with a real Astro build on which value wins.
       if (propsWithStyleAndAttrs.className) {
+        const instanceClassName = propsWithStyleAndAttrs.className as string;
+        if (rootNode.style) {
+          const stripped = stripClassOverriddenStyleProps(rootNode.style as StyleValue, instanceClassName);
+          if (stripped) rootNode.style = stripped as Record<string, unknown>;
+          else delete rootNode.style;
+        }
         if (isHtmlNode(rootNode) || isLinkNode(rootNode)) {
           // For HTML and Link root nodes, merge into attributes where the renderer reads them
           if (!rootNode.attributes) rootNode.attributes = {};
-          const existingClass = (rootNode.attributes.class || '') as string;
-          rootNode.attributes.class = existingClass
-            ? `${existingClass} ${propsWithStyleAndAttrs.className}`
-            : (propsWithStyleAndAttrs.className as string);
+          const own = ((rootNode.attributes.class || '') as string).split(/\s+/).filter(Boolean);
+          rootNode.attributes.class = mergeInstanceClasses(own, instanceClassName).join(' ');
         } else {
-          const existingClassName = rootNode.props.className || '';
-          rootNode.props.className = existingClassName
-            ? `${existingClassName} ${propsWithStyleAndAttrs.className}`
-            : propsWithStyleAndAttrs.className;
+          const own = ((rootNode.props.className || '') as string).split(/\s+/).filter(Boolean);
+          rootNode.props.className = mergeInstanceClasses(own, instanceClassName).join(' ');
         }
       }
 
@@ -2402,9 +2441,15 @@ function renderLocaleList(node: import('../../shared/types').LocaleListNode, ctx
       if (localeListInteractiveStyles && localeListInteractiveStyles.length > 0) {
         localeListCssVariables = registerInteractiveStyles(ctx, elementClass, localeListInteractiveStyles);
       }
-      localeListStyleAttr = buildCssVariableStyleAttr(localeListCssVariables);
     }
 
+    // Var-bridge for template-bound style values (see templateStyleVars.ts).
+    const localeListTemplateVars = getTemplateVars(node);
+    if (localeListTemplateVars) {
+      localeListCssVariables = { ...localeListCssVariables, ...localeListTemplateVars };
+    }
+    localeListStyleAttr = buildCssVariableStyleAttr(localeListCssVariables);
+
     const containerClassAttr = containerClasses.length > 0 ? ` class="${escapeHtml(containerClasses.join(' '))}"` : '';
 
     // Convert item styles to utility classes

package/lib/shared/templateStyleVars.ts

@@ -0,0 +1,49 @@
+/**
+ * Design-canvas bridge for `{{template}}`-bound style declarations — meno-core's mirror
+ * of the meno-astro var-bridge (packages/astro `runtime/cssValue.ts` templateVarName +
+ * `runtime/style.ts` resolveMappingsInFlat).
+ *
+ * A style value bound to a prop template (`gap: "{{gap}}px"`) can't be a static utility
+ * class in a real Astro build — its value is per-instance — so meno-astro emits the class
+ * `gap-[var(--m-<bp>-gap)]` and sets that variable inline on the element. Two consequences
+ * the design canvas must reproduce for WYSIWYG parity:
+ *
+ *   1. Auto-responsive scaling never applies to the declaration (the scaler can't scale a
+ *      `var()`), so the value renders CONSTANT across breakpoints in a real build. Before
+ *      this bridge, the canvas resolved the template to a concrete class (`gap-[40px]`)
+ *      which the scaler happily shrank at tablet/mobile — values looked responsive in
+ *      Fast Design Mode and fixed on the published site.
+ *   2. The inline style sets the VARIABLE, not the property, so interactive class rules
+ *      (`:hover`, `.is-open`) still override the declaration by normal specificity.
+ *
+ * `processStructure` (templateEngine) performs the bridging when it resolves a component
+ * structure's templates: the resolved style carries `var(--m-<bp>-<prop>)` values and the
+ * variable assignments land on the node under {@link TEMPLATE_VARS_KEY} — an EPHEMERAL,
+ * render-only field (never persisted, never validated). The client builders apply it via
+ * their element ref (like interactive-style variables); the SSR renderer folds it into the
+ * element's inline `style="…"`.
+ */
+
+/**
+ * The CSS custom-property name bridging a `{{template}}`-bound declaration to its utility
+ * rule. MUST stay byte-identical to meno-astro's `templateVarName` (runtime/cssValue.ts) —
+ * the canvas and the real build render the same variable names so what you inspect in
+ * Fast Design Mode matches the published output.
+ */
+export function templateVarName(breakpoint: string, cssProp: string): string {
+  const kebab = cssProp.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+  return `--m-${breakpoint}-${kebab}`;
+}
+
+/** Ephemeral node field carrying the bridged variable assignments (render-only). */
+export const TEMPLATE_VARS_KEY = '__templateVars';
+
+/** Read the bridged `--m-<bp>-<prop>` assignments off a processed node, if any. */
+export function getTemplateVars(node: unknown): Record<string, string> | undefined {
+  if (!node || typeof node !== 'object') return undefined;
+  const vars = (node as Record<string, unknown>)[TEMPLATE_VARS_KEY];
+  if (!vars || typeof vars !== 'object' || Array.isArray(vars)) return undefined;
+  const entries = Object.entries(vars as Record<string, unknown>);
+  if (entries.length === 0) return undefined;
+  return vars as Record<string, string>;
+}

package/lib/shared/utilityClassMapper.test.ts

@@ -7,6 +7,9 @@ import {
   splitStyleByClassability,
   isClassableStyleValue,
   styleHasMapping,
+  classMergeKey,
+  mergeInstanceClasses,
+  stripClassOverriddenStyleProps,
 } from './utilityClassMapper';
 import { getStyleValue, clearRegistry } from './styleValueRegistry';
 import { defaultTailwindThemeVariables } from './tailwindThemeScale';
@@ -986,4 +989,81 @@ describe('utilityClassMapper', () => {
       expect(styleHasMapping(undefined)).toBe(false);
     });
   });
+
+  describe('classMergeKey', () => {
+    test('same (breakpoint, property) → same key across value forms', () => {
+      expect(classMergeKey('max-w-full')).toBe(classMergeKey('max-w-[283px]'));
+      expect(classMergeKey('p-4')).toBe(classMergeKey('p-[13px]'));
+    });
+
+    test('breakpoint forms normalize to one key (max-lg / legacy tablet / bare lg)', () => {
+      const key = classMergeKey('max-lg:p-4');
+      expect(classMergeKey('tablet:p-[10px]')).toBe(key);
+      expect(classMergeKey('lg:p-2.5')).toBe(key);
+      expect(classMergeKey('p-4')).not.toBe(key); // base ≠ tablet
+    });
+
+    test('bare color-token class recovers the property from its root', () => {
+      expect(classMergeKey('bg-accent')).toBe(classMergeKey('bg-[var(--gray-200)]'));
+      expect(classMergeKey('text-muted')).toBe(classMergeKey('text-[#ff0000]'));
+    });
+
+    test('unrecognized classes (element hashes, foreign) yield null', () => {
+      expect(classMergeKey('m_hero_ab12cd')).toBeNull();
+      expect(classMergeKey('js-toggle')).toBeNull();
+    });
+  });
+
+  describe('mergeInstanceClasses', () => {
+    test('instance class drops the root class for the same property', () => {
+      expect(mergeInstanceClasses(['max-w-full', 'flex'], 'max-w-[283px]')).toEqual(['flex', 'max-w-[283px]']);
+    });
+
+    test('conflicts are per-breakpoint — root tablet override survives a base instance class', () => {
+      expect(mergeInstanceClasses(['max-w-full', 'max-lg:max-w-[90%]'], 'max-w-[283px]')).toEqual([
+        'max-lg:max-w-[90%]',
+        'max-w-[283px]',
+      ]);
+    });
+
+    test('null-key classes on either side are always kept', () => {
+      expect(mergeInstanceClasses(['m_hero_ab12cd', 'p-4'], 'p-[24px] js-x')).toEqual([
+        'm_hero_ab12cd',
+        'p-[24px]',
+        'js-x',
+      ]);
+    });
+
+    test('empty instance string is a no-op', () => {
+      expect(mergeInstanceClasses(['p-4'], '')).toEqual(['p-4']);
+    });
+  });
+
+  describe('stripClassOverriddenStyleProps', () => {
+    test('drops the flat style property an instance class overrides', () => {
+      expect(stripClassOverriddenStyleProps({ maxWidth: '100%', display: 'flex' }, 'max-w-[283px]')).toEqual({
+        display: 'flex',
+      });
+    });
+
+    test('drops per-breakpoint: base class strips base only, tablet override survives', () => {
+      expect(
+        stripClassOverriddenStyleProps({ base: { maxWidth: '100%' }, tablet: { maxWidth: '90%' } }, 'max-w-[283px]'),
+      ).toEqual({ tablet: { maxWidth: '90%' } });
+    });
+
+    test('unresolved bindings are stripped by property key too', () => {
+      const mapping = { _mapping: true as const, prop: 'maxWidth', values: { narrow: '283px' } };
+      expect(stripClassOverriddenStyleProps({ maxWidth: mapping, color: 'red' }, 'max-w-[283px]')).toEqual({
+        color: 'red',
+      });
+    });
+
+    test('returns the same object when nothing conflicts, null when nothing remains', () => {
+      const style = { maxWidth: '100%' };
+      expect(stripClassOverriddenStyleProps(style, 'p-[24px]')).toBe(style);
+      expect(stripClassOverriddenStyleProps(style, 'max-w-[283px]')).toBeNull();
+      expect(stripClassOverriddenStyleProps(null, 'max-w-[283px]')).toBeNull();
+    });
+  });
 });