meno-core 1.0.52 → 1.0.53

package/lib/client/scripts/ScriptExecutor.ts

@@ -42,10 +42,42 @@ function generateDestructure(
 export class ScriptExecutor {
   private componentRegistry: ComponentRegistry;
   private elementRegistry: ElementRegistry;
+  // Tracks which (element, componentName) pairs have already had their user
+  // JS executed. Prevents stacking side effects (IntersectionObservers,
+  // event listeners, intervals) when execute() is re-called on the same
+  // DOM nodes after a structural commit. WeakMap stays out of the DOM and
+  // GCs cleanly when React unmounts elements.
+  private boundElements: WeakMap<Element, Set<string>> = new WeakMap();
 
   constructor(config: ScriptExecutorConfig) {
     this.componentRegistry = config.componentRegistry;
     this.elementRegistry = config.elementRegistry;
+
+    // Install a host-side hook on `window` so the generated IIFE in
+    // executeWithInitPattern (which runs through `new Function`) can ask
+    // whether a given (element, componentName) should be bound. The
+    // wrapper degrades gracefully when the hook is absent (e.g. direct
+    // <script> use outside the runtime) — see executeWithInitPattern.
+    if (typeof window !== 'undefined') {
+      (window as { __menoShouldBind?: (el: Element, name: string) => boolean }).__menoShouldBind =
+        (el: Element, name: string) => this.shouldBind(el, name);
+    }
+  }
+
+  /**
+   * Check whether (element, componentName) has already been bound this
+   * session. Records the bind on first call. Returns `true` if the caller
+   * should run the user JS, `false` if it should skip.
+   */
+  private shouldBind(el: Element, componentName: string): boolean {
+    let names = this.boundElements.get(el);
+    if (names && names.has(componentName)) return false;
+    if (!names) {
+      names = new Set();
+      this.boundElements.set(el, names);
+    }
+    names.add(componentName);
+    return true;
   }
 
   /**
@@ -91,6 +123,13 @@ export class ScriptExecutor {
         return;
       }
 
+      // Skip re-execution if this element already had its JS bound for this
+      // component. Prevents stacked side effects on structural-edit re-runs.
+      const instanceEl = this.elementRegistry.get(rootPath);
+      if (instanceEl && !this.shouldBind(instanceEl, componentName)) {
+        return;
+      }
+
       try {
         const processedJS = processCodeTemplates(originalJS, props);
         this.executeWrappedJS(processedJS, `${componentName} (instance: ${rootPath})`);
@@ -124,10 +163,20 @@ export class ScriptExecutor {
       // Component: ${componentName} (defineVars)
       try {
         var elements = document.querySelectorAll('[data-component~="${componentName}"]');
+        var shouldBind = (typeof window !== 'undefined' && typeof window.__menoShouldBind === 'function')
+          ? window.__menoShouldBind
+          : null;
         elements.forEach(function(el) {
+          // Skip elements already bound for this component. When the host
+          // hook is absent (direct <script> use, test harness), bind
+          // unconditionally — preserves legacy "runs once at page load"
+          // semantics for non-runtime contexts.
+          if (shouldBind && !shouldBind(el, ${JSON.stringify(componentName)})) {
+            return;
+          }
           var propsStr = el.getAttribute('data-props');
           var allProps = propsStr ? JSON.parse(propsStr) : {};
-          var props = allProps["${componentName}"] || {};
+          var props = allProps[${JSON.stringify(componentName)}] || {};
           (function(el, props) {
             ${destructure}
             ${js}
@@ -256,7 +305,12 @@ export class ScriptExecutor {
 
   /**
    * Re-execute JavaScript for a specific element instance (used for editor reactivity)
-   * Updates data-props attribute and re-runs the component JS for that element
+   * Updates data-props attribute and re-runs the component JS for that element.
+   *
+   * NOTE: This path intentionally bypasses the per-element bind dedup
+   * (`boundElements` / `shouldBind`). It exists so live prop edits in the
+   * editor can re-run the user JS on demand with new prop values — the
+   * caller is signaling "re-bind this element now," not "bind once."
    * @param componentName - Component name
    * @param element - The DOM element to re-execute for
    * @param newProps - New props to inject

package/lib/client/styles/StyleInjector.ts

@@ -12,11 +12,13 @@ import type { ComponentRegistry } from '../componentRegistry';
 import type { ElementRegistry } from '../elementRegistry';
 import { hasTemplates, processCodeTemplates } from '../templateEngine';
 import { generateAllInteractiveCSS } from '../../shared/cssGeneration';
+import { rewriteViewportUnits } from '../../shared/viewportUnits';
 import { getCachedBreakpointConfig, getCachedRemConversionConfig, getCachedResponsiveScalesConfig } from '../responsiveStyleResolver';
 import { DEFAULT_BREAKPOINTS } from '../../shared/breakpoints';
 import { InteractiveStylesRegistry } from '../InteractiveStylesRegistry';
 import { UtilityClassCollector } from './UtilityClassCollector';
 import { logRuntimeError } from '../../shared/errorLogger';
+import { applyNonce } from './cspNonce';
 
 export interface StyleInjectorConfig {
   componentRegistry: ComponentRegistry;
@@ -121,19 +123,29 @@ export class StyleInjector {
 
     if (processedCSSBlocks.length === 0) return;
 
-    const combinedCSS = processedCSSBlocks.join('\n\n');
+    // Rewrite vh/vw → calc(var(--design-vh, 1vh) * N) so design-canvas mode
+    // can pin viewport units to a stable height. No-op when --design-vh is
+    // unset (see viewportUnits.ts).
+    const combinedCSS = rewriteViewportUnits(processedCSSBlocks.join('\n\n'));
     const hash = simpleHash(combinedCSS);
 
-    // Skip if component CSS hasn't changed
-    if (hash === this.previousComponentCSSHash) return;
+    // Skip only when the hash matches AND the style tag is still in the DOM.
+    // If something removed the tag externally (e.g. a hot-reload pass that
+    // wiped <head>), the hash short-circuit would otherwise leave the page
+    // unstyled until the CSS itself changed.
+    const existing = typeof document !== 'undefined'
+      ? document.getElementById(this.styleId) as HTMLStyleElement | null
+      : null;
+    if (hash === this.previousComponentCSSHash && existing) return;
     this.previousComponentCSSHash = hash;
 
     // Update textContent in-place if tag exists, otherwise create
     if (document.head) {
-      let styleTag = document.getElementById(this.styleId) as HTMLStyleElement | null;
+      let styleTag = existing;
       if (!styleTag) {
         styleTag = document.createElement('style');
         styleTag.id = this.styleId;
+        applyNonce(styleTag);
         document.head.appendChild(styleTag);
       }
       styleTag.textContent = combinedCSS;
@@ -154,7 +166,9 @@ export class StyleInjector {
       const breakpointConfig = getCachedBreakpointConfig() || DEFAULT_BREAKPOINTS;
       const remConversionConfig = getCachedRemConversionConfig() || undefined;
       const responsiveScalesConfig = getCachedResponsiveScalesConfig() || undefined;
-      const interactiveCSS = generateAllInteractiveCSS(interactiveStylesMap, breakpointConfig, remConversionConfig, responsiveScalesConfig);
+      const interactiveCSS = rewriteViewportUnits(
+        generateAllInteractiveCSS(interactiveStylesMap, breakpointConfig, remConversionConfig, responsiveScalesConfig)
+      );
       if (!interactiveCSS) return;
 
       if (document.head) {
@@ -162,6 +176,7 @@ export class StyleInjector {
         if (!styleTag) {
           styleTag = document.createElement('style');
           styleTag.id = interactiveStyleId;
+          applyNonce(styleTag);
           document.head.appendChild(styleTag);
         }
         styleTag.textContent = interactiveCSS;

package/lib/client/styles/UtilityClassCollector.ts

@@ -14,10 +14,12 @@
  */
 
 import { generateSingleClassCSS, sortClassesByPropertyOrder, generateRuleForClass } from '../../shared/cssGeneration';
+import { rewriteViewportUnits } from '../../shared/viewportUnits';
 import { getCachedBreakpointConfig, getCachedResponsiveScalesConfig, getCachedRemConversionConfig } from '../responsiveStyleResolver';
 import { DEFAULT_BREAKPOINTS, getBreakpointValues } from '../../shared/breakpoints';
 import type { BreakpointConfig } from '../../shared/breakpoints';
 import { DEFAULT_RESPONSIVE_SCALES } from '../../shared/responsiveScaling';
+import { applyNonce } from './cspNonce';
 
 /**
  * Build a map from responsive prefix (e.g. 't', 'mob') to breakpoint value.
@@ -128,6 +130,7 @@ class UtilityClassCollectorImpl {
     if (document.head) {
       this.styleEl = document.createElement('style');
       this.styleEl.id = 'utility-css';
+      applyNonce(this.styleEl);
       document.head.appendChild(this.styleEl);
     }
 
@@ -156,7 +159,10 @@ class UtilityClassCollectorImpl {
 
       const css = generateSingleClassCSS(name, breakpointConfig, responsiveScalesConfig, remConversionConfig);
       if (css) {
-        this.injectedRules.set(name, css);
+        // Rewrite vh/vw so design-canvas mode can pin viewport units to a
+        // stable px value (see viewportUnits.ts). No-op when --design-vh
+        // isn't set on documentElement.
+        this.injectedRules.set(name, rewriteViewportUnits(css));
         hasNew = true;
       }
     }

package/lib/client/styles/cspNonce.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { getCspNonce, applyNonce, _resetCspNonceCacheForTests } from './cspNonce';
+
+// Minimal DOM mock — just enough for querySelector('meta[name="csp-nonce"]')
+// and for setting `el.nonce`. Bun's runtime does not ship a DOM.
+function installMockDocument(metaContent: string | null) {
+  const meta = metaContent === null
+    ? null
+    : { getAttribute: (k: string) => (k === 'content' ? metaContent : null) };
+  (globalThis as any).document = {
+    querySelector: (selector: string) =>
+      selector === 'meta[name="csp-nonce"]' ? meta : null,
+  };
+}
+
+describe('cspNonce', () => {
+  let originalDocument: unknown;
+
+  beforeEach(() => {
+    originalDocument = (globalThis as any).document;
+    _resetCspNonceCacheForTests();
+  });
+
+  afterEach(() => {
+    (globalThis as any).document = originalDocument;
+    _resetCspNonceCacheForTests();
+  });
+
+  test('returns the meta content when present', () => {
+    installMockDocument('abc123==');
+    expect(getCspNonce()).toBe('abc123==');
+  });
+
+  test('returns null when no meta is present', () => {
+    installMockDocument(null);
+    expect(getCspNonce()).toBeNull();
+  });
+
+  test('returns null when document is undefined (SSR path)', () => {
+    (globalThis as any).document = undefined;
+    expect(getCspNonce()).toBeNull();
+  });
+
+  test('caches the lookup across calls', () => {
+    installMockDocument('first-nonce');
+    expect(getCspNonce()).toBe('first-nonce');
+    // Replace the meta after the first read; cached value should stick.
+    installMockDocument('second-nonce');
+    expect(getCspNonce()).toBe('first-nonce');
+    _resetCspNonceCacheForTests();
+    expect(getCspNonce()).toBe('second-nonce');
+  });
+
+  test('applyNonce stamps the IDL `nonce` property when a nonce is present', () => {
+    installMockDocument('the-nonce');
+    const el: any = { tagName: 'STYLE' };
+    applyNonce(el);
+    expect(el.nonce).toBe('the-nonce');
+  });
+
+  test('applyNonce is a no-op when no nonce is present', () => {
+    installMockDocument(null);
+    const el: any = { tagName: 'STYLE' };
+    applyNonce(el);
+    expect(el.nonce).toBeUndefined();
+  });
+});

package/lib/client/styles/cspNonce.ts

@@ -0,0 +1,63 @@
+/**
+ * Reads the per-page CSP nonce that SSR emits via
+ * `<meta name="csp-nonce" content="…">` and applies it to dynamically
+ * created `<style>` (or other) elements.
+ *
+ * Why this exists: when Electron's preview CSP is `style-src 'self'
+ * 'nonce-X'`, CSP3 ignores the `'unsafe-inline'` fallback even if it is
+ * also listed. That means every `document.createElement('style')` call we
+ * make in the preview runtime MUST stamp `el.nonce = X` or Chromium will
+ * drop the element. The nonce is server-rendered once per page load and
+ * does not mutate during the page's lifetime, so the lookup is cached.
+ *
+ * SSR pipeline (in case you're chasing a missing nonce):
+ *   1. `packages/core/lib/server/routes/pages.ts` generates the nonce and
+ *      sets the `x-meno-csp-nonce` response header.
+ *   2. `packages/core/lib/server/ssr/htmlGenerator.ts` emits the meta tag
+ *      in `<head>` and stamps inline <script>/<style> tags with the nonce.
+ *   3. `electron-app/main/window.js` reads the header and emits CSP with
+ *      `'nonce-X'` in script-src and style-src.
+ *
+ * When the meta is absent (non-SSR responses, tests, server-rendered HTML
+ * that bypassed the route handler), `applyNonce` is a no-op — the
+ * corresponding CSP also falls back to `'unsafe-inline'`, so unstamped
+ * elements still load.
+ */
+
+let cached: string | null | undefined;
+
+export function getCspNonce(): string | null {
+  if (cached !== undefined) return cached;
+  if (typeof document === 'undefined') {
+    cached = null;
+    return cached;
+  }
+  // Wrap in try/catch — some test DOMs (happy-dom in particular) throw
+  // from inside querySelector for selectors they fail to parse. We treat
+  // any DOM-level error here as "no nonce available" — the corresponding
+  // CSP path falls back to 'unsafe-inline', so unstamped elements still
+  // load and no production behavior is affected.
+  try {
+    const meta = document.querySelector('meta[name="csp-nonce"]');
+    cached = meta?.getAttribute('content') ?? null;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+export function applyNonce(el: HTMLElement): void {
+  const n = getCspNonce();
+  if (n) {
+    // Both the `nonce` IDL attribute and the `nonce` content attribute work,
+    // but only the IDL attribute is readable post-render (the content
+    // attribute is wiped by the browser to prevent CSS exfiltration of the
+    // nonce itself). Setting the IDL property is the right move.
+    (el as HTMLStyleElement & { nonce: string }).nonce = n;
+  }
+}
+
+/** Test-only: reset the module-level cache between cases. */
+export function _resetCspNonceCacheForTests(): void {
+  cached = undefined;
+}

package/lib/client/templateEngine.test.ts

@@ -712,6 +712,86 @@ describe("Template Engine - processStructure", () => {
   });
 });
 
+describe("Template Engine - parentProps cascade", () => {
+  const mockComponentDef: StructuredComponentDefinition = {
+    interface: {},
+    structure: { type: 'node' as const, tag: 'div' }
+  };
+
+  test("falls back to parentProps when child doesn't declare the prop", () => {
+    const structure: ComponentNode = {
+      type: "node",
+      tag: "span",
+      children: ["{{ctaText}}"]
+    };
+    const ctx: TemplateContext = {
+      props: {},
+      parentProps: { ctaText: "Take the assessment" },
+      componentDef: mockComponentDef
+    };
+
+    const result = processStructure(structure, ctx) as ComponentNode;
+    expect(result.children).toEqual(["Take the assessment"]);
+  });
+
+  test("child props win over parentProps on key collision", () => {
+    const structure: ComponentNode = {
+      type: "node",
+      tag: "span",
+      children: ["{{label}}"]
+    };
+    const ctx: TemplateContext = {
+      props: { label: "child" },
+      parentProps: { label: "parent" },
+      componentDef: mockComponentDef
+    };
+
+    const result = processStructure(structure, ctx) as ComponentNode;
+    expect(result.children).toEqual(["child"]);
+  });
+
+  test("partial templates (prefix-{{x}}) also cascade", () => {
+    const structure: ComponentNode = {
+      type: "node",
+      tag: "div",
+      attributes: { class: "btn-{{variant}}" }
+    };
+    const ctx: TemplateContext = {
+      props: {},
+      parentProps: { variant: "primary" },
+      componentDef: mockComponentDef
+    };
+
+    const result = processStructure(structure, ctx) as ComponentNode;
+    expect((result as any).attributes?.class).toBe("btn-primary");
+  });
+
+  test("style mappings cascade against parentProps", () => {
+    const structure: ComponentNode = {
+      type: "node",
+      tag: "div",
+      style: {
+        base: {
+          color: {
+            _mapping: true,
+            prop: "variant",
+            values: { default: "black", featured: "white" }
+          }
+        }
+      }
+    } as ComponentNode;
+    const ctx: TemplateContext = {
+      props: {},
+      parentProps: { variant: "featured" },
+      componentDef: mockComponentDef
+    };
+
+    const result = processStructure(structure, ctx) as ComponentNode;
+    const baseStyle = (result.style as any)?.base;
+    expect(baseStyle?.color).toBe("white");
+  });
+});
+
 describe("Template Engine - Slot Default Values", () => {
   const mockComponentDef: StructuredComponentDefinition = {
     interface: {},

package/lib/client/templateEngine.ts

@@ -263,8 +263,13 @@ function buildEvalContext(
   context: TemplateContext,
   includeItemContext: boolean = false
 ): Record<string, unknown> {
+  // Layer order (lowest → highest precedence): global → parent component
+  // props → this component's own props. The middle layer lets a `{{x}}` in
+  // a child component's structure cascade to the host's `x` when the child
+  // didn't declare the prop. Mirrors `buildListResolutionScope` in ssrRenderer.
   const evalContext: Record<string, unknown> = {
     ...getGlobalTemplateContext(),
+    ...(context.parentProps ?? {}),
     ...context.props
   };
 

package/lib/server/astro/cmsPageEmitter.ts

@@ -16,6 +16,13 @@ import type { RemConversionConfig } from '../../shared/pxToRem';
 import { generateAllInteractiveCSS } from '../../shared/cssGeneration';
 import { astroComponentName } from './astroEmitHelpers';
 
+/**
+ * Slug token baked into the SSR metadata pass's dummy URL (build-astro renders
+ * each CMS template once with this stand-in slug to collect meta). The emitter
+ * swaps it for the per-entry slug expression so canonical/og:url are correct.
+ */
+export const CMS_SLUG_PLACEHOLDER = '__placeholder__';
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -71,6 +78,10 @@ export interface CMSPageEmitOptions {
   processedRawHtml?: Map<string, string>;
   /** Rem conversion config for interactive CSS generation */
   remConfig?: RemConversionConfig;
+  /** Components that consume the CMS entry (thread `cms={entry}` into them) */
+  cmsConsumers?: Set<string>;
+  /** collectionId → `_url` template expression for flattened collection lists */
+  collectionUrlExpr?: Map<string, string>;
 }
 
 // ---------------------------------------------------------------------------
@@ -326,6 +337,11 @@ export function emitCMSPage(options: CMSPageEmitOptions): string {
     imageImports: new Map<string, string>(),
     fileDepth,
     collectedInteractiveStyles: new Map<string, InteractiveStyles>(),
+    // Frontmatter sink for any page-level collection-sourced lists.
+    frontmatterLines: [],
+    astroImports: new Set<string>(),
+    cmsConsumers: options.cmsConsumers,
+    collectionUrlExpr: options.collectionUrlExpr,
   };
 
   // Emit the template body
@@ -365,10 +381,18 @@ export function emitCMSPage(options: CMSPageEmitOptions): string {
   const libraryTagsLiteral = `{ headCSS: \`${escapeTemplateLiteral(libraryTags.headCSS || '')}\`, headJS: \`${escapeTemplateLiteral(libraryTags.headJS || '')}\`, bodyEndJS: \`${escapeTemplateLiteral(libraryTags.bodyEndJS || '')}\` }`;
 
   // Escape meta first, then transform CMS templates ({{cms.X}} survives escaping intact)
-  const escapedMeta = escapeTemplateLiteral(meta).replace(
-    /\{\{cms\.([^}]+)\}\}/g,
-    (_, fieldPath) => `\${${wrapFn}(${binding}.data.${fieldPath.trim()})}`
-  );
+  const slugField = cmsSchema.slugField || 'slug';
+  const escapedMeta = escapeTemplateLiteral(meta)
+    .replace(
+      /\{\{cms\.([^}]+)\}\}/g,
+      (_, fieldPath) => `\${${wrapFn}(${binding}.data.${fieldPath.trim()})}`
+    )
+    // Replace the metadata-pass stand-in slug with the per-entry slug so
+    // canonical/og:url point at the real page instead of "__placeholder__".
+    .replace(
+      new RegExp(CMS_SLUG_PLACEHOLDER, 'g'),
+      `\${${wrapFn}(${binding}.data.${slugField}) || ${binding}.id}`
+    );
   const escapedFontPreloads = escapeTemplateLiteral(fontPreloads);
 
   // Transform title for CMS entry data
@@ -380,6 +404,12 @@ export function emitCMSPage(options: CMSPageEmitOptions): string {
   return v ?? '';
 }`;
 
+  // Page-level collection queries emitted by collection-sourced list nodes
+  // (getCollection import is already present in importLines above).
+  const extraFrontmatter = ctx.frontmatterLines && ctx.frontmatterLines.length > 0
+    ? '\n' + ctx.frontmatterLines.join('\n')
+    : '';
+
   // Generate interactive style block for page-level interactive styles
   const interactiveStyleSection = ctx.collectedInteractiveStyles!.size > 0
     ? `\n<style is:global>\n${generateAllInteractiveCSS(ctx.collectedInteractiveStyles!, breakpoints, remConfig, responsiveScales)}\n</style>\n`
@@ -390,7 +420,7 @@ ${importLines.join('\n')}
 
 ${staticPaths}
 
-${resolverHelper}
+${resolverHelper}${extraFrontmatter}
 ---
 <BaseLayout
   title=${titleExpr}

package/lib/server/astro/componentEmitter.ts

@@ -129,6 +129,16 @@ function mergeClassNameOntoRoot(template: string): string {
 /**
  * Generate a .astro file string from a component definition
  */
+/** CMS-aware emission options threaded from build-astro. */
+export interface ComponentCmsOptions {
+  /** Names of components that consume the CMS entry (transitive). */
+  cmsConsumers?: Set<string>;
+  /** Rich-text field names across all collections (for `set:html`). */
+  cmsRichTextFields?: Set<string>;
+  /** collectionId → `_url` template expression for flattened lists. */
+  collectionUrlExpr?: Map<string, string>;
+}
+
 export function emitAstroComponent(
   name: string,
   def: ComponentDefinition,
@@ -136,7 +146,8 @@ export function emitAstroComponent(
   breakpoints: BreakpointConfig = DEFAULT_BREAKPOINTS,
   defaultLocale: string = 'en',
   responsiveScales?: ResponsiveScales,
-  remConfig?: RemConversionConfig
+  remConfig?: RemConversionConfig,
+  cmsOptions?: ComponentCmsOptions
 ): string {
   const comp = def.component;
   const propDefs = comp.interface || {};
@@ -147,6 +158,11 @@ export function emitAstroComponent(
     return buildNoStructureComponent(name, comp);
   }
 
+  // A "CMS consumer" references {{cms.*}} (transitively). It receives the CMS
+  // entry via a `cms` prop and resolves field refs against it (binding 'cms'),
+  // mirroring how the CMS template page resolves them against `entry`.
+  const isCmsConsumer = cmsOptions?.cmsConsumers?.has(name) ?? false;
+
   // Build the Astro context for template emission
   const ctx: AstroEmitContext = {
     imports: new Set<string>(),
@@ -164,6 +180,19 @@ export function emitAstroComponent(
     imageImports: new Map<string, string>(),
     fileDepth: 0, // components live at src/components/
     collectedInteractiveStyles: new Map<string, InteractiveStyles>(),
+    // Frontmatter sink for collection queries (getCollection) emitted by lists.
+    frontmatterLines: [],
+    astroImports: new Set<string>(),
+    cmsConsumers: cmsOptions?.cmsConsumers,
+    collectionUrlExpr: cmsOptions?.collectionUrlExpr,
+    ...(isCmsConsumer
+      ? {
+          cmsMode: true,
+          cmsEntryBinding: 'cms',
+          cmsWrapFn: 'r',
+          cmsRichTextFields: cmsOptions?.cmsRichTextFields,
+        }
+      : {}),
   };
 
   // Emit the template body
@@ -172,14 +201,18 @@ export function emitAstroComponent(
   // Merge instance className onto the root element (for acceptsStyles support)
   templateBody = mergeClassNameOntoRoot(templateBody);
 
-  // Build frontmatter (includes class prop for instance style support)
+  // Build frontmatter (includes class prop for instance style support).
+  // Consumers always get the `r` resolver (the cms wrap fn) and a `cms` prop.
   const frontmatter = buildFrontmatter(
     name,
     propDefs,
     ctx.imports,
     ctx.dynamicTags,
-    ctx.needsI18nResolver ? defaultLocale : undefined,
-    ctx.imageImports
+    (ctx.needsI18nResolver || isCmsConsumer) ? defaultLocale : undefined,
+    ctx.imageImports,
+    ctx.astroImports,
+    ctx.frontmatterLines,
+    isCmsConsumer
   );
 
   // Build style/script sections
@@ -203,10 +236,18 @@ function buildFrontmatter(
   imports: Set<string>,
   dynamicTags?: Map<string, string>,
   i18nDefaultLocale?: string,
-  imageImports?: Map<string, string>
+  imageImports?: Map<string, string>,
+  astroImports?: Set<string>,
+  frontmatterLines?: string[],
+  isCmsConsumer?: boolean
 ): string {
   const lines: string[] = [];
 
+  // Astro API imports (e.g., getCollection) needed by collection-sourced lists
+  if (astroImports && astroImports.size > 0) {
+    lines.push(`import { ${Array.from(astroImports).sort().join(', ')} } from 'astro:content';`);
+  }
+
   // Component imports
   for (const imp of Array.from(imports).sort()) {
     lines.push(`import ${astroComponentName(imp)} from './${imp}.astro';`);
@@ -236,6 +277,10 @@ function buildFrontmatter(
       const optional = 'default' in propDef && propDef.default !== undefined;
       lines.push(`  ${propName}${optional ? '?' : ''}: ${tsType};`);
     }
+    // CMS consumers receive the current entry as a `cms` prop
+    if (isCmsConsumer) {
+      lines.push('  cms?: any;');
+    }
     // Always include class prop for instance style support
     lines.push('  class?: string;');
     lines.push('}');
@@ -255,6 +300,10 @@ function buildFrontmatter(
       }
     }
 
+    // CMS consumers destructure the entry prop
+    if (isCmsConsumer) {
+      destructParts.push('cms');
+    }
     // Always include class prop (renamed to className to avoid reserved word)
     destructParts.push('class: className = ""');
 
@@ -289,6 +338,13 @@ function buildFrontmatter(
     lines.push(`};`);
   }
 
+  // Collection queries emitted by collection-sourced list nodes
+  // (e.g. `const blogList = await getCollection('blog')...`).
+  if (frontmatterLines && frontmatterLines.length > 0) {
+    lines.push('');
+    for (const line of frontmatterLines) lines.push(line);
+  }
+
   if (lines.length > 0) lines.push('');
   return lines.join('\n');
 }