meno-core 1.0.52 → 1.0.54

package/lib/server/ssr/ssrRenderer.ts

@@ -3,24 +3,68 @@
  * Converts JSON component structures to HTML strings for SEO-friendly initial page loads
  */
 
-import type { ComponentNode, ComponentDefinition, JSONPage, CMSItem, EmbedNode, LinkNode, LocaleListNode, CMSFilterCondition } from '../../shared/types';
+import type {
+  ComponentNode,
+  ComponentDefinition,
+  JSONPage,
+  CMSItem,
+  EmbedNode,
+  LinkNode,
+  LocaleListNode,
+  CMSFilterCondition,
+} from '../../shared/types';
 import type { TemplateContext, NestedCMSListConfig } from '../../shared/types/cms';
-import { processItemTemplate, processItemPropsTemplate, hasItemTemplates, buildTemplateContext, resolveItemsTemplate, resolveTemplateRawValue, addItemUrl, getNestedValue, type ValueResolver } from '../../shared/itemTemplateUtils';
+import {
+  processItemTemplate,
+  processItemPropsTemplate,
+  hasItemTemplates,
+  buildTemplateContext,
+  resolveItemsTemplate,
+  resolveTemplateRawValue,
+  addItemUrl,
+  getNestedValue,
+  type ValueResolver,
+} from '../../shared/itemTemplateUtils';
 import { singularize, isItemDraftForLocale } from '../../shared/types/cms';
 import type { ResponsiveStyleObject, StyleObject } from '../../shared/types';
 import type { BreakpointConfig } from '../../shared/breakpoints';
 import type { ResponsiveScales } from '../../shared/responsiveScaling';
-import { evaluateTemplate, processStructure, isResponsiveStyle, isHtmlMapping, resolveHtmlMapping } from '../../client/templateEngine';
+import {
+  evaluateTemplate,
+  processStructure,
+  isResponsiveStyle,
+  isHtmlMapping,
+  resolveHtmlMapping,
+} from '../../client/templateEngine';
 import { resolvePropsFromDefinition, isRichTextMarker, richTextMarkerToHtml } from '../../shared/propResolver';
 import { loadBreakpointConfig, loadI18nConfig } from '../jsonLoader';
 import { configService } from '../services/configService';
 import type { I18nConfig } from '../../shared/types/components';
-import { extractLocaleFromPath, DEFAULT_I18N_CONFIG, resolveI18nValue, buildLocalizedPath, isI18nValue } from '../../shared/i18n';
+import {
+  extractLocaleFromPath,
+  DEFAULT_I18N_CONFIG,
+  resolveI18nValue,
+  buildLocalizedPath,
+  isI18nValue,
+} from '../../shared/i18n';
 import { NODE_TYPE } from '../../shared/constants';
-import { isComponentNode, isHtmlNode, isLinkNode, isEmbedNode, isLocaleListNode, isListNode, markAsSlotContent, isBooleanMapping, hasIf, isSlotContent, hasChildren } from '../../shared/nodeUtils';
+import {
+  isComponentNode,
+  isHtmlNode,
+  isLinkNode,
+  isEmbedNode,
+  isLocaleListNode,
+  isListNode,
+  markAsSlotContent,
+  isBooleanMapping,
+  hasIf,
+  isSlotContent,
+  hasChildren,
+} from '../../shared/nodeUtils';
 import type { ListNode } from '../../shared/registry/nodeTypes/ListNodeType';
 import type { CMSService } from '../services/cmsService';
 import { extractAttributesFromNode, skipEmptyTemplateAttributes } from '../../shared/attributeNodeUtils';
+import { inlineSvgStyleRules } from '../../shared/inlineSvgStyleRules';
 import { mergeNodeStyles } from '../../shared/styleNodeUtils';
 import { SSRRegistry } from '../../shared/registry/SSRRegistry';
 import { mergeResponsiveStyles } from '../../shared/responsiveStyleUtils';
@@ -45,18 +89,31 @@ import { responsiveStylesToClasses } from '../../shared/utilityClassMapper';
 import { validateStyleCoverage } from '../validateStyleCoverage';
 import { generateElementClassName, type ElementClassContext } from '../../shared/elementClassName';
 import type { InteractiveStyles } from '../../shared/types/styles';
-import { extractInteractiveStyleMappings, resolveExtractedMappings, hasInteractiveStyleMappings } from '../../shared/interactiveStyleMappings';
+import {
+  extractInteractiveStyleMappings,
+  resolveExtractedMappings,
+  hasInteractiveStyleMappings,
+} from '../../shared/interactiveStyleMappings';
 import { isCurrentLink } from '../../shared/linkUtils';
 import type { SlugMap } from '../../shared/slugTranslator';
 import { buildSlugIndex, getLocaleLinks, translatePath } from '../../shared/slugTranslator';
 
 // Import from modularized files
 import { escapeHtml, buildAttributes, buildEditorAttrs, styleToString } from './attributeBuilder';
+import { logRuntimeError } from '../../shared/errorLogger';
+import { toFriendlyError } from '../../shared/friendlyError';
+import { rewriteViewportUnits } from '../../shared/viewportUnits';
 import { extractPageMeta, generateMetaTags } from './metaTagGenerator';
 import { collectComponentCSS } from './cssCollector';
 import { collectComponentJavaScript } from './jsCollector';
-import { CMSContext, processCMSTemplate, processCMSPropsTemplate, createI18nResolver, RAW_HTML_PREFIX } from './cmsSSRProcessor';
-import { ImageMetadataMap, DEFAULT_SIZES, buildImageMetadataMap, rewriteRichTextImages } from './imageMetadata';
+import {
+  type CMSContext,
+  processCMSTemplate,
+  processCMSPropsTemplate,
+  createI18nResolver,
+  RAW_HTML_PREFIX,
+} from './cmsSSRProcessor';
+import { type ImageMetadataMap, DEFAULT_SIZES, buildImageMetadataMap, rewriteRichTextImages } from './imageMetadata';
 
 /**
  * Image preload info for generating <link rel="preload"> tags in head
@@ -83,7 +140,7 @@ export type { CMSContext } from './cmsSSRProcessor';
 function resolveI18nAttrs<T extends Record<string, unknown>>(
   attrs: T,
   locale: string | undefined,
-  i18nConfig: I18nConfig | undefined
+  i18nConfig: I18nConfig | undefined,
 ): T {
   let mutated: Record<string, unknown> | null = null;
   const config = i18nConfig ?? DEFAULT_I18N_CONFIG;
@@ -166,6 +223,13 @@ interface SSRContext {
   cmsListPaths?: number[][];
   /** Name of the enclosing component instance (for data-parent-component on descendants) */
   parentComponentName?: string;
+  /**
+   * Per-page counter of how many times each component name has been rendered so
+   * far. Used to stamp data-meno-component / data-meno-component-instance onto
+   * each component's outermost element so tooling (e.g. /screenshot) can target
+   * `[data-meno-component="PricingSection"][data-meno-component-instance="0"]`.
+   */
+  componentInstanceCounter?: Map<string, number>;
   /**
    * Element path of the current component instance's root, in the component's local
    * (reset) coordinate space. When ctx.elementPath deeply equals this, the element
@@ -233,47 +297,37 @@ function localizeHref(href: string, ctx: SSRContext): string {
  */
 function localizeRichTextLinks(html: string, ctx: SSRContext): string {
   if (ctx.templateMode || !ctx.locale || !ctx.i18nConfig) return html;
-  return html.replace(
-    /<a\b([^>]*?)href=(["'])([^"']*?)\2([^>]*?)>/gi,
-    (match, before, quote, href, after) => {
-      if (!href.startsWith('/') || href.startsWith('//')) return match;
-      const localized = localizeHref(href, ctx);
-      return localized === href ? match : `<a${before}href=${quote}${localized}${quote}${after}>`;
-    }
-  );
+  return html.replace(/<a\b([^>]*?)href=(["'])([^"']*?)\2([^>]*?)>/gi, (match, before, quote, href, after) => {
+    if (!href.startsWith('/') || href.startsWith('//')) return match;
+    const localized = localizeHref(href, ctx);
+    return localized === href ? match : `<a${before}href=${quote}${localized}${quote}${after}>`;
+  });
 }
 
 /**
  * Process style templates and convert to utility classes.
  * Handles {{item.field}} patterns within list contexts.
  */
-function processStyleToClasses(
-  style: StyleObject | ResponsiveStyleObject | undefined,
-  ctx: SSRContext
-): string[] {
+function processStyleToClasses(style: StyleObject | ResponsiveStyleObject | undefined, ctx: SSRContext): string[] {
   if (!style) return [];
 
   let processedStyle = style;
   const templateCtx = getTemplateContext(ctx);
   if (templateCtx && !ctx.templateMode) {
-    processedStyle = processItemPropsTemplate(
-      style as Record<string, unknown>,
-      templateCtx,
-      getI18nResolver(ctx)
-    ) as StyleObject | ResponsiveStyleObject;
+    processedStyle = processItemPropsTemplate(style as Record<string, unknown>, templateCtx, getI18nResolver(ctx)) as
+      | StyleObject
+      | ResponsiveStyleObject;
   }
 
   // Fluid container pattern: in fluid mode `responsiveStylesToClasses` rewrites
   // any tier whose `width === maxWidth` to use `calc(100% - var(--site-margin)*2)`
   // with auto margins.
-  const fluidActive =
-    ctx.responsiveScales?.enabled === true &&
-    ctx.responsiveScales?.mode === 'fluid';
+  const fluidActive = ctx.responsiveScales?.enabled === true && ctx.responsiveScales?.mode === 'fluid';
 
-  return responsiveStylesToClasses(
-    processedStyle as ResponsiveStyleObject,
-    { fluidActive, responsiveScales: ctx.responsiveScales }
-  );
+  return responsiveStylesToClasses(processedStyle as ResponsiveStyleObject, {
+    fluidActive,
+    responsiveScales: ctx.responsiveScales,
+  });
 }
 
 /**
@@ -334,50 +388,88 @@ function evaluateIfCondition(node: ComponentNode, ctx: SSRContext): boolean {
   return true;
 }
 
+/**
+ * Sentinel returned by resolveFilterValue when a {{...}} template value can't
+ * be resolved from the available scope. Lets resolveFilterTemplates tell
+ * "resolved to a real value" apart from "unresolvable" so the condition can be
+ * dropped from the CMS query instead of being sent as a literal template
+ * string — which would never match a real value and silently return nothing.
+ */
+const UNRESOLVED_FILTER_VALUE = Symbol('unresolved-filter-value');
+
 /**
  * Resolve a template value like "{{category.slug}}" from a flat scope.
- * Returns the original value if not a template or can't be resolved.
+ * Returns the original value for non-template values, and
+ * UNRESOLVED_FILTER_VALUE when a template can't be resolved.
  */
 function resolveFilterValue(value: unknown, scope: Record<string, unknown> | undefined): unknown {
-  if (!scope || typeof value !== 'string' || !value.startsWith('{{') || !value.endsWith('}}')) {
+  if (typeof value !== 'string' || !value.startsWith('{{') || !value.endsWith('}}')) {
     return value;
   }
   const path = value.slice(2, -2).trim();
-  const resolved = getNestedValue(scope, path);
-  return resolved !== undefined ? resolved : value;
+  const resolved = scope ? getNestedValue(scope, path) : undefined;
+  return resolved !== undefined ? resolved : UNRESOLVED_FILTER_VALUE;
 }
 
 /**
  * Resolve template values in CMS filter for nested cms-list support.
  * Handles filter values like "{{category.slug}}" against a flat scope built from
  * parent template context overlaid on host-component resolved props.
+ *
+ * Conditions whose template value can't be resolved are dropped from the query
+ * (a verbatim "{{x.y}}" string would match nothing) and surfaced via
+ * logRuntimeError — dropping a condition changes results, so users must be
+ * able to see why.
  */
 function resolveFilterTemplates(
   filter: CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown> | undefined,
-  scope: Record<string, unknown> | undefined
+  scope: Record<string, unknown> | undefined,
+  collection: string,
 ): CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown> | undefined {
-  if (!filter || !scope) return filter;
+  if (!filter) return filter;
+
+  const reportDropped = (field: unknown, template: unknown): void => {
+    logRuntimeError(
+      'ssrRenderer.resolveFilterTemplates',
+      new Error(`Unresolved filter template ${String(template)} — condition dropped from "${collection}" query`),
+      { collection, field: String(field), template: String(template) },
+    );
+  };
 
   // Handle array of conditions
   if (Array.isArray(filter)) {
-    return filter.map(cond => ({
-      ...cond,
-      value: resolveFilterValue(cond.value, scope)
-    }));
+    const conditions: CMSFilterCondition[] = [];
+    for (const cond of filter) {
+      const value = resolveFilterValue(cond.value, scope);
+      if (value === UNRESOLVED_FILTER_VALUE) {
+        reportDropped(cond.field, cond.value);
+        continue;
+      }
+      conditions.push({ ...cond, value } as CMSFilterCondition);
+    }
+    return conditions;
   }
 
   // Handle single condition object with field/value
   if ('field' in filter && 'value' in filter) {
-    return {
-      ...(filter as CMSFilterCondition),
-      value: resolveFilterValue((filter as CMSFilterCondition).value, scope)
-    };
+    const cond = filter as CMSFilterCondition;
+    const value = resolveFilterValue(cond.value, scope);
+    if (value === UNRESOLVED_FILTER_VALUE) {
+      reportDropped(cond.field, cond.value);
+      return undefined;
+    }
+    return { ...cond, value } as CMSFilterCondition;
   }
 
   // Handle simple object filter: { category: "{{category.slug}}" }
   const resolved: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(filter)) {
-    resolved[key] = resolveFilterValue(value, scope);
+    const resolvedValue = resolveFilterValue(value, scope);
+    if (resolvedValue === UNRESOLVED_FILTER_VALUE) {
+      reportDropped(key, value);
+      continue;
+    }
+    resolved[key] = resolvedValue;
   }
   return resolved;
 }
@@ -412,15 +504,16 @@ async function expandRichTextComponents(html: string, ctx: SSRContext): Promise<
         .replace(/&#039;/g, "'")
         .replace(/&amp;/g, '&');
       props = JSON.parse(propsStr);
-    } catch {
-      // ignore parse errors
+    } catch (error) {
+      // Malformed data-meno-props JSON: fall back to interface defaults so the
+      // marker never crashes the page, but surface the parse failure — the
+      // component silently losing its instance props is otherwise invisible.
+      logRuntimeError('ssrRenderer.expandRichTextComponents', error, { component: componentName });
     }
 
     // Render the component using SSR registry
     if (ssrComponentRegistry.has(componentName)) {
-      parts.push(
-        renderComponent(componentName, props, [], {}, ctx)
-      );
+      parts.push(renderComponent(componentName, props, [], {}, ctx));
     } else {
       // Keep marker for unknown components
       parts.push(match[0]);
@@ -460,8 +553,15 @@ export async function buildComponentHTML(
   cmsContext?: CMSContext,
   cmsService?: CMSService,
   isProductionBuild?: boolean,
-  injectEditorAttrs?: boolean
-): Promise<{ html: string; interactiveStylesMap: Map<string, InteractiveStyles>; preloadImages: PreloadImage[]; neededCollections: Set<string>; ssrFallbackCollector: Map<string, string>; processedRawHtmlCollector: Map<string, string> }> {
+  injectEditorAttrs?: boolean,
+): Promise<{
+  html: string;
+  interactiveStylesMap: Map<string, InteractiveStyles>;
+  preloadImages: PreloadImage[];
+  neededCollections: Set<string>;
+  ssrFallbackCollector: Map<string, string>;
+  processedRawHtmlCollector: Map<string, string>;
+}> {
   // Create map to collect interactive styles during render
   const interactiveStylesMap = new Map<string, InteractiveStyles>();
   // Create array to collect high-priority images for preloading
@@ -473,7 +573,15 @@ export async function buildComponentHTML(
   // Create map to collect raw-HTML → processed-HTML for Astro exporter parity
   const processedRawHtmlCollector = new Map<string, string>();
 
-  if (!node) return { html: '', interactiveStylesMap, preloadImages, neededCollections, ssrFallbackCollector, processedRawHtmlCollector };
+  if (!node)
+    return {
+      html: '',
+      interactiveStylesMap,
+      preloadImages,
+      neededCollections,
+      ssrFallbackCollector,
+      processedRawHtmlCollector,
+    };
 
   // Register components for this render
   ssrComponentRegistry.merge(globalComponents);
@@ -513,7 +621,14 @@ export async function buildComponentHTML(
 
   const html = await renderNode(node, ctx);
 
-  return { html, interactiveStylesMap, preloadImages, neededCollections, ssrFallbackCollector, processedRawHtmlCollector };
+  return {
+    html,
+    interactiveStylesMap,
+    preloadImages,
+    neededCollections,
+    ssrFallbackCollector,
+    processedRawHtmlCollector,
+  };
 }
 
 /**
@@ -521,10 +636,7 @@ export async function buildComponentHTML(
  * Used when parent list has emitTemplate: true.
  * The placeholder contains the configuration and template for MenoFilter to hydrate.
  */
-async function renderNestedListPlaceholder(
-  node: ListNode,
-  ctx: SSRContext
-): Promise<string> {
+async function renderNestedListPlaceholder(node: ListNode, ctx: SSRContext): Promise<string> {
   // Get source - handle both string and pre-resolved array sources
   const sourceValue = node.source || node.collection;
   const sourceStr = typeof sourceValue === 'string' ? sourceValue : '';
@@ -553,17 +665,37 @@ async function renderNestedListPlaceholder(
     templateContext: undefined, // Clear context for inner item templates
     nestedCMSListMode: false, // Reset for deeper nesting levels
   };
-  const templateContent = node.children
-    ? await renderChildrenAsync(node.children, childTemplateCtx)
-    : '';
+  const templateContent = node.children ? await renderChildrenAsync(node.children, childTemplateCtx) : '';
 
   // Escape config for attribute
   const configJson = escapeHtml(JSON.stringify(config));
 
   // Emit placeholder with embedded config and template
-  return `<div data-cms-list-nested="true" data-collection="${escapeHtml(sourceStr)}" data-cms-config="${configJson}"${editorAttrs(ctx, { isCMSListContainer: true })}>` +
+  return (
+    `<div data-cms-list-nested="true" data-collection="${escapeHtml(sourceStr)}" data-cms-config="${configJson}"${editorAttrs(ctx, { isCMSListContainer: true })}>` +
     `<template data-nested-template>${templateContent}</template>` +
-    `</div>`;
+    `</div>`
+  );
+}
+
+/**
+ * Graceful fallback for a node that threw during SSR. Keeps one bad section from
+ * taking down the whole page: in the editor preview (injectEditorAttrs) it emits
+ * a small, plain-language placeholder so the user can see which section failed;
+ * everywhere else (static builds, the published site) it renders nothing so real
+ * visitors never see an error. Carries no XRay-selectable attributes.
+ */
+function renderNodeFallback(ctx: SSRContext, error: unknown, label: string): string {
+  console.error(`❌ SSR render error in ${label}:`, error);
+  if (!ctx.injectEditorAttrs) return '';
+  const friendly = toFriendlyError(error);
+  const text = `${friendly.title} — ${friendly.friendlyMessage}`;
+  return (
+    `<div data-meno-render-error style="margin:8px 0;padding:12px 14px;` +
+    `border:1px dashed #e0a3a3;border-radius:6px;background:#fdf3f3;color:#9a3b3b;` +
+    `font:13px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;">` +
+    `⚠️ ${escapeHtml(text)}</div>`
+  );
 }
 
 /**
@@ -576,7 +708,7 @@ async function processList(node: ListNode, ctx: SSRContext): Promise<string> {
   // Determine source type (default to 'prop', but handle legacy 'cms-list' type)
   const nodeType = node.type as string;
   const isLegacyCMSList = nodeType === 'cms-list';
-  const sourceType = isLegacyCMSList ? 'collection' : (node.sourceType || 'prop');
+  const sourceType = isLegacyCMSList ? 'collection' : node.sourceType || 'prop';
 
   // For collection mode, check CMS service availability
   if (sourceType === 'collection' && !ctx.cmsService) {
@@ -627,6 +759,12 @@ async function processList(node: ListNode, ctx: SSRContext): Promise<string> {
     }
   }
 
+  // Defend against a source that resolved to null or a non-array (e.g. an unset
+  // CMS field, or an array-of-ID prop accidentally coerced to a string). Without
+  // this, the `items.length` check below throws
+  // "Cannot read properties of null (reading 'length')".
+  if (!Array.isArray(items)) items = [];
+
   // Apply shared options: offset and limit
   if (node.offset && sourceType === 'prop') {
     items = items.slice(node.offset);
@@ -640,26 +778,16 @@ async function processList(node: ListNode, ctx: SSRContext): Promise<string> {
   }
 
   // Get schema for URL computation (collection mode only)
-  const schema = sourceType === 'collection' && ctx.cmsService
-    ? ctx.cmsService.getSchema(source)
-    : undefined;
+  const schema = sourceType === 'collection' && ctx.cmsService ? ctx.cmsService.getSchema(source) : undefined;
 
   // Render children for each item
   const renderedItems: string[] = [];
 
   for (let i = 0; i < items.length; i++) {
     const rawItem = items[i] as Record<string, unknown>;
-    const item = schema
-      ? addItemUrl(rawItem as CMSItem, schema, ctx.locale, ctx.i18nConfig)
-      : rawItem;
-
-    const templateContext = buildTemplateContext(
-      variableName,
-      item as CMSItem,
-      i,
-      items.length,
-      ctx.templateContext
-    );
+    const item = schema ? addItemUrl(rawItem as CMSItem, schema, ctx.locale, ctx.i18nConfig) : rawItem;
+
+    const templateContext = buildTemplateContext(variableName, item as CMSItem, i, items.length, ctx.templateContext);
 
     const itemCtx: SSRContext = {
       ...ctx,
@@ -726,7 +854,7 @@ async function getCollectionItems(node: ListNode, source: string, ctx: SSRContex
           }
         }
         if (value !== null && value !== undefined) {
-          resolvedIds = Array.isArray(value) ? value.map(v => String(v)) : String(value);
+          resolvedIds = Array.isArray(value) ? value.map((v) => String(v)) : String(value);
         }
       } else {
         // Otherwise resolve from a merged scope: parent list loop variables (highest precedence)
@@ -750,14 +878,18 @@ async function getCollectionItems(node: ListNode, source: string, ctx: SSRContex
     }
     // Filter draft items from ID-based queries
     if (ctx.locale) {
-      items = items.filter(item => !isItemDraftForLocale(item, ctx.locale!));
+      items = items.filter((item) => !isItemDraftForLocale(item, ctx.locale!));
     }
   } else {
     // Build query from node props (resolve filter templates against parent loop variables
     // overlaid on host-component resolved props, with parent loop variables winning).
     const query = {
       collection: source,
-      filter: resolveFilterTemplates(node.filter as CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown> | undefined, buildListResolutionScope(ctx)),
+      filter: resolveFilterTemplates(
+        node.filter as CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown> | undefined,
+        buildListResolutionScope(ctx),
+        source,
+      ),
       sort: node.sort,
       limit: node.limit,
       offset: node.offset,
@@ -769,7 +901,7 @@ async function getCollectionItems(node: ListNode, source: string, ctx: SSRContex
   // Exclude current item if option is set and we have a current CMS context
   if (node.excludeCurrentItem && ctx.cmsContext?.cms?._id) {
     const currentId = ctx.cmsContext.cms._id as string;
-    items = items.filter(item => item._id !== currentId);
+    items = items.filter((item) => item._id !== currentId);
   }
 
   return items;
@@ -830,25 +962,21 @@ async function renderChildrenAsync(children: unknown[], ctx: SSRContext): Promis
  * Build element class name for a node based on its SSR context.
  * Used by embed, link, locale-list, and regular HTML nodes.
  */
-function buildNodeElementClass(
-  ctx: SSRContext,
-  label: string | undefined,
-  isSlotContent?: boolean
-): string {
+function buildNodeElementClass(ctx: SSRContext, label: string | undefined, isSlotContent?: boolean): string {
   const { pagePath } = ctx;
   // Slot content uses page context (defined in page, not component)
   const useComponentContext = !isSlotContent && Boolean(ctx.componentContext);
   const effectiveFileType = useComponentContext ? 'component' : 'page';
-  const effectiveFileName = useComponentContext ? ctx.componentContext : (pagePath
-    ? pagePath.replace(/^\//, '').replace(/\//g, '_') || 'index'
-    : 'page');
+  const effectiveFileName = useComponentContext
+    ? ctx.componentContext
+    : pagePath
+      ? pagePath.replace(/^\//, '').replace(/\//g, '_') || 'index'
+      : 'page';
 
   // Slice off the component-instance prefix so class hashes stay stable across
   // instances of the same component (mirrors ComponentBuilder.ts:678-680).
   const rawPath = ctx.elementPath || [];
-  const path = useComponentContext && ctx.componentRootPath
-    ? rawPath.slice(ctx.componentRootPath.length)
-    : rawPath;
+  const path = useComponentContext && ctx.componentRootPath ? rawPath.slice(ctx.componentRootPath.length) : rawPath;
 
   const elementClassCtx: ElementClassContext = {
     fileType: effectiveFileType,
@@ -866,7 +994,7 @@ function buildNodeElementClass(
 function registerInteractiveStyles(
   ctx: SSRContext,
   elementClass: string,
-  interactiveStyles: InteractiveStyles
+  interactiveStyles: InteractiveStyles,
 ): Record<string, string> {
   if (!ctx.interactiveStylesMap) return {};
 
@@ -887,7 +1015,8 @@ function registerInteractiveStyles(
 function buildCssVariableStyleAttr(cssVariables: Record<string, string>): string {
   if (Object.keys(cssVariables).length === 0) return '';
   const styleString = Object.entries(cssVariables)
-    .map(([k, v]) => `${k}: ${v}`)
+    // Route values through the viewport-unit rewriter — see viewportUnits.ts.
+    .map(([k, v]) => `${k}: ${rewriteViewportUnits(v)}`)
     .join('; ');
   return ` style="${escapeHtml(styleString)}"`;
 }
@@ -902,20 +1031,18 @@ function arraysEqual(a: number[] | undefined, b: number[] | undefined): boolean
  * Compute editor-only attributes for the current context.
  * Returns '' when injectEditorAttrs is off — preview-only feature.
  */
-function editorAttrs(
-  ctx: SSRContext,
-  opts: { isSlotContent?: boolean; isCMSListContainer?: boolean } = {}
-): string {
+function editorAttrs(ctx: SSRContext, opts: { isSlotContent?: boolean; isCMSListContainer?: boolean } = {}): string {
   if (!ctx.injectEditorAttrs) return '';
   // Component root: inside a component instance and at the path the instance was reset to.
-  const isComponentRoot = !!ctx.componentContext
-    && !opts.isSlotContent
-    && arraysEqual(ctx.elementPath, ctx.componentRootPath);
+  const isComponentRoot =
+    !!ctx.componentContext && !opts.isSlotContent && arraysEqual(ctx.elementPath, ctx.componentRootPath);
   // Mirror client semantics: at component root, parent is the outer component;
   // for descendants of a component, parent is the current component itself.
   const effectiveParent = opts.isSlotContent
     ? ctx.parentComponentName
-    : (isComponentRoot ? ctx.parentComponentName : (ctx.componentContext ?? ctx.parentComponentName));
+    : isComponentRoot
+      ? ctx.parentComponentName
+      : (ctx.componentContext ?? ctx.parentComponentName);
   return buildEditorAttrs({
     elementPath: ctx.elementPath,
     cmsItemIndexPath: ctx.cmsItemIndexPath,
@@ -933,12 +1060,19 @@ function editorAttrs(
  */
 async function renderNode(
   node: ComponentNode | ComponentNode[] | string | number | null | undefined,
-  ctx: SSRContext
+  ctx: SSRContext,
 ): Promise<string> {
   const { breakpoints, viewportWidth, locale, i18nConfig, slugMappings, pagePath } = ctx;
 
   if (node === null || node === undefined) return '';
 
+  // Verbatim-code markers ({ _code, expr }) from the meno-astro dialect carry arbitrary
+  // JS the model can't represent. They render natively in the Astro build; meno-core SSR
+  // has nothing to evaluate, so emit nothing rather than treating the marker as an element.
+  if (typeof node === 'object' && !Array.isArray(node) && (node as { _code?: unknown })._code === true) {
+    return '';
+  }
+
   if (typeof node === 'string' || typeof node === 'number') {
     let text = String(node);
 
@@ -984,10 +1118,14 @@ async function renderNode(
   }
 
   if (Array.isArray(node)) {
-    return (await Promise.all(node.map((child, index) => {
-      const childPath = ctx.elementPath ? [...ctx.elementPath.slice(0, -1), index] : [index];
-      return renderNode(child, { ...ctx, elementPath: childPath });
-    }))).join('');
+    return (
+      await Promise.all(
+        node.map((child, index) => {
+          const childPath = ctx.elementPath ? [...ctx.elementPath.slice(0, -1), index] : [index];
+          return renderNode(child, { ...ctx, elementPath: childPath });
+        }),
+      )
+    ).join('');
   }
 
   if (typeof node !== 'object') return '';
@@ -1001,10 +1139,7 @@ async function renderNode(
     const i18nResolveConfig = i18nConfig ?? DEFAULT_I18N_CONFIG;
     const i18nEffectiveLocale = locale || i18nResolveConfig.defaultLocale;
     const resolved = resolveI18nValue(node, i18nEffectiveLocale, i18nResolveConfig);
-    return renderNode(
-      resolved as ComponentNode | string | number | null | undefined,
-      ctx
-    );
+    return renderNode(resolved as ComponentNode | string | number | null | undefined, ctx);
   }
 
   // Check if condition - skip rendering if false
@@ -1015,12 +1150,18 @@ async function renderNode(
   // Handle List nodes (async operation - handles both prop and collection source types)
   // isListNode() also matches legacy 'cms-list' type for migration
   if (isListNode(node)) {
-    return await processList(node, ctx);
+    try {
+      return await processList(node, ctx);
+    } catch (error) {
+      // A list at page-root level isn't wrapped by renderComponent's catch, so
+      // guard it here too — one broken list shouldn't take down the whole page.
+      return renderNodeFallback(ctx, error, 'list');
+    }
   }
 
   const nodeType = 'type' in node ? node.type : undefined;
-  const nodeStyle = ('style' in node) ? node.style as StyleObject | ResponsiveStyleObject | undefined : undefined;
-  const children = ('children' in node) ? (node.children || []) : [];
+  const nodeStyle = 'style' in node ? (node.style as StyleObject | ResponsiveStyleObject | undefined) : undefined;
+  const children = 'children' in node ? node.children || [] : [];
 
   // Handle embed nodes - render custom HTML content
   if (isEmbedNode(node)) {
@@ -1056,11 +1197,202 @@ async function renderNode(
 
     // Sanitize HTML with allowlist for SVG, rich-text formatting, and common elements (same as client)
     const purify = getDOMPurify();
-    const sanitizedHtml = purify ? purify.sanitize(htmlContent, {
-      ALLOWED_TAGS: ['svg', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'g', 'text', 'tspan', 'image', 'defs', 'use', 'linearGradient', 'radialGradient', 'stop', 'clipPath', 'mask', 'pattern', 'marker', 'symbol', 'a', 'div', 'span', 'p', 'br', 'button', 'img', 'iframe', 'video', 'audio', 'source', 'canvas', 'b', 'i', 'u', 'strong', 'em', 'sub', 'sup', 'mark', 's', 'small', 'del', 'ins', 'q', 'abbr', 'code', 'pre', 'blockquote', 'ul', 'ol', 'li', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'style', 'animate', 'animateTransform', 'animateMotion', 'set'],
-      ALLOWED_ATTR: ['class', 'id', 'style', 'width', 'height', 'viewBox', 'xmlns', 'fill', 'stroke', 'stroke-width', 'stroke-linecap', 'stroke-linejoin', 'stroke-dasharray', 'stroke-dashoffset', 'd', 'cx', 'cy', 'r', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'points', 'href', 'src', 'alt', 'target', 'rel', 'data-*', 'aria-*', 'transform', 'opacity', 'fill-opacity', 'stroke-opacity', 'font-size', 'font-family', 'text-anchor', 'dominant-baseline', 'offset', 'stop-color', 'stop-opacity', 'frameborder', 'allowfullscreen', 'allow', 'title', 'attributeName', 'values', 'dur', 'begin', 'end', 'repeatCount', 'repeatDur', 'keyTimes', 'keySplines', 'calcMode', 'from', 'to', 'by', 'additive', 'accumulate', 'type', 'rotate', 'keyPoints', 'path'],
-      KEEP_CONTENT: true
-    }) : htmlContent;
+    const purifiedHtml = purify
+      ? purify.sanitize(htmlContent, {
+          ALLOWED_TAGS: [
+            'svg',
+            'path',
+            'circle',
+            'rect',
+            'line',
+            'polyline',
+            'polygon',
+            'g',
+            'text',
+            'tspan',
+            'image',
+            'defs',
+            'use',
+            'linearGradient',
+            'radialGradient',
+            'stop',
+            'clipPath',
+            'mask',
+            'pattern',
+            'marker',
+            'symbol',
+            'a',
+            'div',
+            'span',
+            'p',
+            'br',
+            'button',
+            'img',
+            'iframe',
+            'video',
+            'audio',
+            'source',
+            'canvas',
+            'b',
+            'i',
+            'u',
+            'strong',
+            'em',
+            'sub',
+            'sup',
+            'mark',
+            's',
+            'small',
+            'del',
+            'ins',
+            'q',
+            'abbr',
+            'code',
+            'pre',
+            'blockquote',
+            'ul',
+            'ol',
+            'li',
+            'h1',
+            'h2',
+            'h3',
+            'h4',
+            'h5',
+            'h6',
+            'style',
+            'animate',
+            'animateTransform',
+            'animateMotion',
+            'set',
+            'filter',
+            'feGaussianBlur',
+            'feOffset',
+            'feMerge',
+            'feMergeNode',
+            'feColorMatrix',
+            'feComposite',
+            'feFlood',
+            'feMorphology',
+            'feBlend',
+            'feDropShadow',
+            'feTurbulence',
+            'feDisplacementMap',
+            'foreignObject',
+          ],
+          ALLOWED_ATTR: [
+            'class',
+            'id',
+            'style',
+            'width',
+            'height',
+            'viewBox',
+            'xmlns',
+            'xmlns:xlink',
+            'xlink:href',
+            'fill',
+            'stroke',
+            'stroke-width',
+            'stroke-linecap',
+            'stroke-linejoin',
+            'stroke-dasharray',
+            'stroke-dashoffset',
+            'd',
+            'cx',
+            'cy',
+            'r',
+            'x',
+            'y',
+            'x1',
+            'y1',
+            'x2',
+            'y2',
+            'points',
+            'href',
+            'src',
+            'alt',
+            'target',
+            'rel',
+            'data-*',
+            'aria-*',
+            'transform',
+            'opacity',
+            'fill-opacity',
+            'fill-rule',
+            'clip-rule',
+            'clip-path',
+            'clipPathUnits',
+            'mask',
+            'mask-type',
+            'maskUnits',
+            'maskContentUnits',
+            'patternUnits',
+            'patternContentUnits',
+            'patternTransform',
+            'gradientUnits',
+            'gradientTransform',
+            'spreadMethod',
+            'preserveAspectRatio',
+            'marker-start',
+            'marker-mid',
+            'marker-end',
+            'markerUnits',
+            'markerWidth',
+            'markerHeight',
+            'refX',
+            'refY',
+            'orient',
+            'paint-order',
+            'vector-effect',
+            'filter',
+            'filterUnits',
+            'primitiveUnits',
+            'in',
+            'in2',
+            'result',
+            'stdDeviation',
+            'flood-color',
+            'flood-opacity',
+            'stroke-opacity',
+            'font-size',
+            'font-family',
+            'font-weight',
+            'font-style',
+            'text-anchor',
+            'dominant-baseline',
+            'offset',
+            'stop-color',
+            'stop-opacity',
+            'frameborder',
+            'allowfullscreen',
+            'allow',
+            'title',
+            'attributeName',
+            'values',
+            'dur',
+            'begin',
+            'end',
+            'repeatCount',
+            'repeatDur',
+            'keyTimes',
+            'keySplines',
+            'calcMode',
+            'from',
+            'to',
+            'by',
+            'additive',
+            'accumulate',
+            'type',
+            'rotate',
+            'keyPoints',
+            'path',
+          ],
+          KEEP_CONTENT: true,
+        })
+      : htmlContent;
+    // Inline simple SVG <style> rules as style="" attributes — class-scoped
+    // declarations don't survive the editor preview's HMR `innerHTML` reparse
+    // path (`htmlGenerator.ts:574`), but inline attributes always render.
+    const sanitizedHtml = inlineSvgStyleRules(purifiedHtml);
     const optimizedHtml = ctx.imageMetadataMap
       ? rewriteRichTextImages(sanitizedHtml, ctx.imageMetadataMap, ctx.imageFormat)
       : sanitizedHtml;
@@ -1090,7 +1422,7 @@ async function renderNode(
         embedCssVariables = registerInteractiveStyles(ctx, elementClass, embedInteractiveStyles);
       }
 
-      let embedStyleAttr = buildCssVariableStyleAttr(embedCssVariables);
+      const embedStyleAttr = buildCssVariableStyleAttr(embedCssVariables);
 
       // Add attribute className if present
       const attrClassName = (nodeAttributes.className || nodeAttributes.class || '') as string;
@@ -1137,7 +1469,11 @@ async function renderNode(
         // Link object - extract href and target
         // Unwrap nested link objects (e.g., {href: {href: "/path"}} from double-wrapped list item templates)
         let linkObj = rawValue as { href: unknown; target?: string };
-        while (typeof linkObj.href === 'object' && linkObj.href !== null && 'href' in (linkObj.href as Record<string, unknown>)) {
+        while (
+          typeof linkObj.href === 'object' &&
+          linkObj.href !== null &&
+          'href' in (linkObj.href as Record<string, unknown>)
+        ) {
           const nested = linkObj.href as { href: unknown; target?: string };
           if (!linkObj.target && nested.target) linkObj = { ...linkObj, target: nested.target };
           linkObj = { ...linkObj, href: nested.href };
@@ -1208,11 +1544,18 @@ async function renderNode(
     const classAttr = ` class="${escapeHtml(classNames.filter(Boolean).join(' '))}"`;
 
     const childrenHTML = Array.isArray(children)
-      ? (await Promise.all(children.map((child, index) => {
-          const childPath = ctx.elementPath ? [...ctx.elementPath, index] : [index];
-          return renderNode(child, { ...ctx, elementPath: childPath });
-        }))).join('')
-      : await renderNode(children as ComponentNode | string | number | null | undefined, { ...ctx, elementPath: ctx.elementPath ? [...ctx.elementPath, 0] : [0] });
+      ? (
+          await Promise.all(
+            children.map((child, index) => {
+              const childPath = ctx.elementPath ? [...ctx.elementPath, index] : [index];
+              return renderNode(child, { ...ctx, elementPath: childPath });
+            }),
+          )
+        ).join('')
+      : await renderNode(children as ComponentNode | string | number | null | undefined, {
+          ...ctx,
+          elementPath: ctx.elementPath ? [...ctx.elementPath, 0] : [0],
+        });
 
     return `<a href="${escapeHtml(String(href))}"${classAttr}${olinkStyleAttr}${attrs}${editorAttrs(ctx, { isSlotContent: isSlotContent(node) })}>${childrenHTML}</a>`;
   }
@@ -1223,9 +1566,9 @@ async function renderNode(
   }
 
   // Extract tag or component name based on node type
-  let tag = isHtmlNode(node) ? node.tag : undefined;
+  const tag = isHtmlNode(node) ? node.tag : undefined;
   const componentName = isComponentNode(node) ? node.component : undefined;
-  let nodeProps = isComponentNode(node) ? (node.props || {}) : {};
+  let nodeProps = isComponentNode(node) ? node.props || {} : {};
 
   // Process CMS templates in props
   if (ctx.cmsContext?.cms && Object.keys(nodeProps).length > 0) {
@@ -1248,18 +1591,29 @@ async function renderNode(
 
   // Process CMS templates in attributes (e.g., href="{{cms.link}}")
   if (ctx.cmsContext?.cms && Object.keys(nodeAttributes).length > 0) {
-    nodeAttributes = processCMSPropsTemplate(nodeAttributes as Record<string, unknown>, ctx.cmsContext.cms, locale, i18nConfig) as Record<string, string | number | boolean>;
+    nodeAttributes = processCMSPropsTemplate(
+      nodeAttributes as Record<string, unknown>,
+      ctx.cmsContext.cms,
+      locale,
+      i18nConfig,
+    ) as Record<string, string | number | boolean>;
   }
 
   // Process item templates in attributes (for CMSList context)
   // Skip when in templateMode to preserve {{item.field}} placeholders
   if (!ctx.templateMode && templateCtx && Object.keys(nodeAttributes).length > 0) {
-    nodeAttributes = processItemPropsTemplate(nodeAttributes, templateCtx, i18nResolver) as Record<string, string | number | boolean>;
+    nodeAttributes = processItemPropsTemplate(nodeAttributes, templateCtx, i18nResolver) as Record<
+      string,
+      string | number | boolean
+    >;
   }
 
   // Auto-skip attributes that were entirely template expressions and resolved to ""
   if (Object.keys(nodeAttributes).length > 0) {
-    nodeAttributes = skipEmptyTemplateAttributes(originalAttributes, nodeAttributes) as Record<string, string | number | boolean>;
+    nodeAttributes = skipEmptyTemplateAttributes(originalAttributes, nodeAttributes) as Record<
+      string,
+      string | number | boolean
+    >;
   }
 
   if (!tag && !componentName) return '';
@@ -1273,7 +1627,8 @@ async function renderNode(
   // result. This matches the client (ComponentBuilder.mergeNodeStyles) so that
   // an instance override of e.g. marginBottom actually replaces the structure's
   // marginBottom instead of fighting it as a same-specificity utility class.
-  const isCustomComponentNode = nodeType === NODE_TYPE.COMPONENT && isComponentNode(node) && ssrComponentRegistry.has(node.component);
+  const isCustomComponentNode =
+    nodeType === NODE_TYPE.COMPONENT && isComponentNode(node) && ssrComponentRegistry.has(node.component);
   let deferredComponentStyle: StyleObject | ResponsiveStyleObject | undefined;
 
   if (nodeStyle) {
@@ -1289,16 +1644,23 @@ async function renderNode(
   } else if (nodeProps.style) {
     // If no node.style but props have style, keep it for backward compatibility
     if (isResponsiveStyle(nodeProps.style) && breakpoints && viewportWidth) {
-      resolvedStyle = mergeResponsiveStyles(nodeProps.style as ResponsiveStyleObject, 'viewport', viewportWidth, breakpoints);
+      resolvedStyle = mergeResponsiveStyles(
+        nodeProps.style as ResponsiveStyleObject,
+        'viewport',
+        viewportWidth,
+        breakpoints,
+      );
     } else {
       resolvedStyle = nodeProps.style as StyleObject;
     }
   }
 
   // Generate element-specific class if node has interactive styles or generateElementClass flag
-  const nodeInteractiveStyles = 'interactiveStyles' in node ? node.interactiveStyles as InteractiveStyles | undefined : undefined;
-  const nodeGenerateElementClass = 'generateElementClass' in node ? node.generateElementClass as boolean | undefined : undefined;
-  const nodeLabel = 'label' in node ? node.label as string | undefined : undefined;
+  const nodeInteractiveStyles =
+    'interactiveStyles' in node ? (node.interactiveStyles as InteractiveStyles | undefined) : undefined;
+  const nodeGenerateElementClass =
+    'generateElementClass' in node ? (node.generateElementClass as boolean | undefined) : undefined;
+  const nodeLabel = 'label' in node ? (node.label as string | undefined) : undefined;
   let elementClass = '';
 
   if ((nodeInteractiveStyles && nodeInteractiveStyles.length > 0) || nodeGenerateElementClass) {
@@ -1333,7 +1695,9 @@ async function renderNode(
     ...(mergedClassName ? { className: mergedClassName } : {}),
     ...(deferredComponentStyle
       ? { style: deferredComponentStyle }
-      : Object.keys(resolvedStyle).length > 0 ? { style: resolvedStyle } : {})
+      : Object.keys(resolvedStyle).length > 0
+        ? { style: resolvedStyle }
+        : {}),
   };
 
   // Check if this is a custom component
@@ -1352,13 +1716,11 @@ async function renderNode(
     return renderLinkNode(propsWithStyleAndAttrs, children, ctx);
   }
 
-  // Regular HTML element (must have tag)
-  if (!tag) {
-    console.error('Missing tag for HTML element in SSR');
-    return '';
-  }
-
-  return renderHtmlElement(tag, propsWithStyleAndAttrs, children, ctx);
+  // Regular HTML element. `tag` is necessarily set here: the `!tag &&
+  // !componentName` case returned at the top of this section, and every
+  // `componentName` path has already returned (isComponentNode ⇒ type ===
+  // 'component', which the two component branches above handle exhaustively).
+  return renderHtmlElement(tag as string, propsWithStyleAndAttrs, children, ctx);
 }
 
 /**
@@ -1369,7 +1731,7 @@ async function renderComponent(
   propsWithStyleAndAttrs: Record<string, unknown>,
   children: unknown,
   nodeAttributes: Record<string, unknown>,
-  ctx: SSRContext
+  ctx: SSRContext,
 ): Promise<string> {
   const { locale, i18nConfig, pagePath } = ctx;
   const componentDef = ssrComponentRegistry.get(componentName);
@@ -1385,7 +1747,7 @@ async function renderComponent(
       propsWithStyleAndAttrs,
       children as Array<ComponentNode | string> | string | ComponentNode | null | undefined,
       locale,
-      i18nConfig
+      i18nConfig,
     );
 
     // Process the structure with resolved props
@@ -1393,27 +1755,47 @@ async function renderComponent(
     // Use preserveResponsiveStyles: true to keep responsive styles intact for SSR rendering
     // Mark children as slot content so they use page context for element class generation
     // Pass parent template context (itemContext) for nested cms-list template resolution
-    const markedChildren = children ? markAsSlotContent(children as ComponentNode | ComponentNode[] | string | number | null | undefined) : undefined;
+    const markedChildren = children
+      ? markAsSlotContent(children as ComponentNode | ComponentNode[] | string | number | null | undefined)
+      : undefined;
 
     const processedStructure = processStructure(
       structuredComponentDef.structure,
-      { props: resolvedProps, componentDef: structuredComponentDef, itemContext: ctx.templateContext },
+      {
+        props: resolvedProps,
+        componentDef: structuredComponentDef,
+        itemContext: ctx.templateContext,
+        // Host (outer) component's resolved props — used as fallback scope
+        // for `{{x}}` templates the child's interface doesn't declare. At
+        // this point `ctx.componentResolvedProps` still belongs to the
+        // outer component; it's only swapped to `resolvedProps` below when
+        // we recurse via `renderNode`.
+        parentProps: ctx.componentResolvedProps,
+      },
       undefined,
       markedChildren,
-      true
+      true,
     );
 
     if (!processedStructure) return '';
 
     // Type guard: ensure processedStructure is a ComponentNode
-    if (typeof processedStructure === 'string' || typeof processedStructure === 'number' || Array.isArray(processedStructure)) {
+    if (
+      typeof processedStructure === 'string' ||
+      typeof processedStructure === 'number' ||
+      Array.isArray(processedStructure)
+    ) {
       return await renderNode(processedStructure as string | number | ComponentNode[], ctx);
     }
 
     // Merge instance style overrides, className, and attributes
     // processedStructure is typically an HTML node (the component's root element)
     // Handle component nodes, HTML nodes, and Link nodes (Link and HTML share top-level style/attributes)
-    const rootNode = processedStructure as ComponentNode & { props?: Record<string, unknown>; style?: any; attributes?: Record<string, string | number | boolean> };
+    const rootNode = processedStructure as ComponentNode & {
+      props?: Record<string, unknown>;
+      style?: any;
+      attributes?: Record<string, string | number | boolean>;
+    };
     if (isComponentNode(rootNode) || isHtmlNode(rootNode) || isLinkNode(rootNode)) {
       if (!rootNode.props) {
         rootNode.props = {};
@@ -1435,7 +1817,7 @@ async function renderComponent(
           const existingClass = (rootNode.attributes.class || '') as string;
           rootNode.attributes.class = existingClass
             ? `${existingClass} ${propsWithStyleAndAttrs.className}`
-            : propsWithStyleAndAttrs.className as string;
+            : (propsWithStyleAndAttrs.className as string);
         } else {
           const existingClassName = rootNode.props.className || '';
           rootNode.props.className = existingClassName
@@ -1463,9 +1845,7 @@ async function renderComponent(
       // Add defineVars data attributes for JS prop injection
       const defineVars = structuredComponentDef.defineVars;
       if (defineVars && componentName) {
-        const varsToExpose = defineVars === true
-          ? Object.keys(structuredComponentDef.interface || {})
-          : defineVars;
+        const varsToExpose = defineVars === true ? Object.keys(structuredComponentDef.interface || {}) : defineVars;
 
         const propsForJS: Record<string, unknown> = {};
         for (const varName of varsToExpose) {
@@ -1479,22 +1859,40 @@ async function renderComponent(
         if (!processedRoot.attributes) {
           processedRoot.attributes = {};
         }
-        const existingComponent = (processedRoot.attributes?.['data-component'] as string)
-          || (processedRoot.props?.['data-component'] as string)
-          || '';
+        const existingComponent =
+          (processedRoot.attributes?.['data-component'] as string) ||
+          (processedRoot.props?.['data-component'] as string) ||
+          '';
         processedRoot.attributes['data-component'] = existingComponent
           ? `${existingComponent} ${componentName}`
           : componentName;
 
         let existingPropsMap: Record<string, unknown> = {};
-        const existingPropsStr = (processedRoot.attributes?.['data-props'] as string)
-          || (processedRoot.props?.['data-props'] as string);
+        const existingPropsStr =
+          (processedRoot.attributes?.['data-props'] as string) || (processedRoot.props?.['data-props'] as string);
         if (existingPropsStr) {
-          try { existingPropsMap = JSON.parse(existingPropsStr); } catch {}
+          try {
+            existingPropsMap = JSON.parse(existingPropsStr);
+          } catch {}
         }
         existingPropsMap[componentName] = propsForJS;
         processedRoot.attributes['data-props'] = JSON.stringify(existingPropsMap);
       }
+
+      // Stamp every component instance with data-meno-component(+ -instance) so
+      // tooling can address it by name (e.g. /screenshot pricing PricingSection).
+      // Only applies to HTML / Link roots — nested-component roots inherit via
+      // their own outermost element when this recurses.
+      if (componentName && (isHtmlNode(rootNode) || isLinkNode(rootNode))) {
+        if (!rootNode.attributes) rootNode.attributes = {};
+        if (!ctx.componentInstanceCounter) {
+          ctx.componentInstanceCounter = new Map<string, number>();
+        }
+        const instanceIndex = ctx.componentInstanceCounter.get(componentName) ?? 0;
+        ctx.componentInstanceCounter.set(componentName, instanceIndex + 1);
+        rootNode.attributes['data-meno-component'] = componentName;
+        rootNode.attributes['data-meno-component-instance'] = String(instanceIndex);
+      }
     }
 
     // Render the processed component structure with component context.
@@ -1502,7 +1900,11 @@ async function renderComponent(
     // data-element-path values match XRay's tree paths. componentRootPath captures
     // the page-level path of this instance so buildNodeElementClass can slice it
     // off to keep class hashes component-relative across instances.
-    return await renderNode(processedStructure, {
+    // At this point the string/number/array branches have already returned
+    // (see the type guard above) and processedStructure has been handled as a
+    // ComponentNode (rootNode). Cast to narrow the residual
+    // `Record<string, unknown>` union member — purely type-level, no runtime change.
+    return await renderNode(processedStructure as ComponentNode, {
       ...ctx,
       // The previously-active component (if any) becomes the parent for editor attrs
       parentComponentName: ctx.componentContext,
@@ -1510,10 +1912,8 @@ async function renderComponent(
       componentRootPath: ctx.elementPath,
       componentResolvedProps: resolvedProps,
     });
-
   } catch (error) {
-    console.error(`❌ SSR Error rendering component ${componentName}:`, error);
-    return '';
+    return renderNodeFallback(ctx, error, `component ${componentName}`);
   }
 }
 
@@ -1523,7 +1923,7 @@ async function renderComponent(
 async function renderLinkNode(
   propsWithStyleAndAttrs: Record<string, unknown>,
   children: unknown,
-  ctx: SSRContext
+  ctx: SSRContext,
 ): Promise<string> {
   const to = 'to' in propsWithStyleAndAttrs ? propsWithStyleAndAttrs.to : undefined;
   const restProps: Record<string, unknown> = { ...propsWithStyleAndAttrs };
@@ -1532,17 +1932,22 @@ async function renderLinkNode(
   const href = localizeHref(rawHref, ctx);
 
   // Build class attribute from utility classes
-  const linkClassAttr = restProps.className
-    ? ` class="${escapeHtml(String(restProps.className))}"`
-    : '';
+  const linkClassAttr = restProps.className ? ` class="${escapeHtml(String(restProps.className))}"` : '';
 
   const attrs = buildAttributes(restProps, ['style', 'className', 'to']);
   const childrenHTML = Array.isArray(children)
-    ? (await Promise.all((children as (ComponentNode | string)[]).map((child, index) => {
-        const childPath = ctx.elementPath ? [...ctx.elementPath, index] : [index];
-        return renderNode(child, { ...ctx, elementPath: childPath });
-      }))).join('')
-    : await renderNode(children as ComponentNode, { ...ctx, elementPath: ctx.elementPath ? [...ctx.elementPath, 0] : [0] });
+    ? (
+        await Promise.all(
+          (children as (ComponentNode | string)[]).map((child, index) => {
+            const childPath = ctx.elementPath ? [...ctx.elementPath, index] : [index];
+            return renderNode(child, { ...ctx, elementPath: childPath });
+          }),
+        )
+      ).join('')
+    : await renderNode(children as ComponentNode, {
+        ...ctx,
+        elementPath: ctx.elementPath ? [...ctx.elementPath, 0] : [0],
+      });
 
   return `<a href="${escapeHtml(String(href))}"${linkClassAttr}${attrs}${editorAttrs(ctx)}>${childrenHTML}</a>`;
 }
@@ -1554,7 +1959,7 @@ async function renderHtmlElement(
   tag: string,
   propsWithStyleAndAttrs: Record<string, unknown>,
   children: unknown,
-  ctx: SSRContext
+  ctx: SSRContext,
 ): Promise<string> {
   // Build class attribute from utility classes
   let classValue = propsWithStyleAndAttrs.className ? String(propsWithStyleAndAttrs.className) : '';
@@ -1581,9 +1986,7 @@ async function renderHtmlElement(
 
   // For img tags, exclude image-specific props (handled specially in renderImageElement)
   const imageProps = ['src', 'alt', 'loading', 'width', 'height', 'sizes', 'srcset', 'fetchpriority'];
-  const excludeProps = tag.toLowerCase() === 'img'
-    ? ['style', 'className', ...imageProps]
-    : ['style', 'className'];
+  const excludeProps = tag.toLowerCase() === 'img' ? ['style', 'className', ...imageProps] : ['style', 'className'];
   const attrs = buildAttributes(propsWithStyleAndAttrs, excludeProps);
   // `<style>` and `<script>` are HTML "raw text" elements: their content is
   // not parsed for entities or child elements. Running text children through
@@ -1600,22 +2003,55 @@ async function renderHtmlElement(
       if (typeof node === 'string') return node;
       if (typeof node === 'number') return String(node);
       if (Array.isArray(node)) return node.map(flatten).join('');
+      // Verbatim-code markers ({ _code, expr }) are silent by design — they
+      // render natively in the Astro build and have nothing to emit in
+      // meno-core SSR (mirrors the renderNode top-level handling).
+      if ((node as { _code?: unknown })._code === true) return '';
+      // Raw-text elements can't contain child elements, so any other object
+      // child is dropped from the output — correct per HTML semantics, but
+      // authored content vanishing should be visible, so surface the drop.
+      logRuntimeError(
+        'ssrRenderer.renderHtmlElement',
+        new Error(`Element child dropped inside <${tag}> — raw-text elements render only string content`),
+        { tag, droppedNodeType: String((node as { type?: unknown }).type ?? typeof node) },
+      );
       return '';
     };
     childrenHTML = flatten(children as any);
   } else {
     childrenHTML = Array.isArray(children)
-      ? (await Promise.all((children as (ComponentNode | string)[]).map((child, index) => {
-          const childPath = ctx.elementPath ? [...ctx.elementPath, index] : [index];
-          return renderNode(child, { ...ctx, elementPath: childPath });
-        }))).join('')
-      : await renderNode(children as ComponentNode, { ...ctx, elementPath: ctx.elementPath ? [...ctx.elementPath, 0] : [0] });
+      ? (
+          await Promise.all(
+            (children as (ComponentNode | string)[]).map((child, index) => {
+              const childPath = ctx.elementPath ? [...ctx.elementPath, index] : [index];
+              return renderNode(child, { ...ctx, elementPath: childPath });
+            }),
+          )
+        ).join('')
+      : await renderNode(children as ComponentNode, {
+          ...ctx,
+          elementPath: ctx.elementPath ? [...ctx.elementPath, 0] : [0],
+        });
   }
 
   const ea = editorAttrs(ctx);
 
   // Self-closing tags
-  const voidElements = ['img', 'input', 'br', 'hr', 'meta', 'link', 'area', 'base', 'col', 'embed', 'source', 'track', 'wbr'];
+  const voidElements = [
+    'img',
+    'input',
+    'br',
+    'hr',
+    'meta',
+    'link',
+    'area',
+    'base',
+    'col',
+    'embed',
+    'source',
+    'track',
+    'wbr',
+  ];
   if (voidElements.includes(tag.toLowerCase())) {
     // Special handling for img tags - inject srcset and render as <picture> when AVIF available
     if (tag.toLowerCase() === 'img') {
@@ -1636,7 +2072,7 @@ function renderImageElement(
   classAttr: string,
   styleAttr: string,
   attrs: string,
-  ctx: SSRContext
+  ctx: SSRContext,
 ): string {
   const imgProps = propsWithStyleAndAttrs;
   const src = imgProps.src as string | undefined;
@@ -1644,8 +2080,8 @@ function renderImageElement(
   const loading = imgProps.loading as string | undefined;
   const sizes = imgProps.sizes as string | undefined;
   const fetchpriority = imgProps.fetchpriority as string | undefined;
-  let width = imgProps.width as string | number | undefined;
-  let height = imgProps.height as string | number | undefined;
+  const width = imgProps.width as string | number | undefined;
+  const height = imgProps.height as string | number | undefined;
 
   // Get image metadata from manifest
   const metadata = src ? ctx.imageMetadataMap?.get(src) : undefined;
@@ -1684,14 +2120,23 @@ function renderImageElement(
   if (width !== undefined) imgAttrs += ` width="${escapeHtml(String(width))}"`;
   if (height !== undefined) imgAttrs += ` height="${escapeHtml(String(height))}"`;
 
-
   // Render as <picture> element if AVIF is available and imageFormat is 'avif'
   // Layout classes go on <picture> (block container), image-specific classes on <img>
   if (metadata?.avifSrcset && ctx.imageFormat !== 'webp') {
     // Image-specific class prefixes that should stay on <img>
     const imgClassPrefixes = [
-      'objf-', 'objp-', 'flt-', 'tm-', 'bs-',
-      'br-', 'bt-', 'bb-', 'bl-', 'border-r-', 'bc-', 'b-'
+      'objf-',
+      'objp-',
+      'flt-',
+      'tm-',
+      'bs-',
+      'br-',
+      'bt-',
+      'bb-',
+      'bl-',
+      'border-r-',
+      'bc-',
+      'b-',
     ];
     // Opacity classes (o-NUMBER) go on img, but overflow (o-h, o-a, o-s, o-v) stays on picture
     const opacityPattern = /^o-\d/;
@@ -1703,25 +2148,23 @@ function renderImageElement(
     const pictureClasses: string[] = [];
 
     for (const cls of allClasses) {
-      if (imgClassPrefixes.some(prefix => cls.startsWith(prefix)) || opacityPattern.test(cls)) {
+      if (imgClassPrefixes.some((prefix) => cls.startsWith(prefix)) || opacityPattern.test(cls)) {
         imgClasses.push(cls);
       } else {
         pictureClasses.push(cls);
       }
     }
 
-    const pictureClassAttr = pictureClasses.length > 0
-      ? ` class="${escapeHtml(pictureClasses.join(' '))}"`
-      : '';
-    const imgClassAttr = imgClasses.length > 0
-      ? ` class="${escapeHtml(imgClasses.join(' '))}"`
-      : '';
+    const pictureClassAttr = pictureClasses.length > 0 ? ` class="${escapeHtml(pictureClasses.join(' '))}"` : '';
+    const imgClassAttr = imgClasses.length > 0 ? ` class="${escapeHtml(imgClasses.join(' '))}"` : '';
 
-    return `<picture${pictureClassAttr}${styleAttr}>` +
+    return (
+      `<picture${pictureClassAttr}${styleAttr}>` +
       `<source type="image/avif" srcset="${escapeHtml(metadata.avifSrcset)}" sizes="${escapeHtml(sizesAttr)}" />` +
       `<source type="image/webp" srcset="${escapeHtml(metadata.srcset)}" sizes="${escapeHtml(sizesAttr)}" />` +
       `<img${imgClassAttr}${imgAttrs}${attrs} />` +
-      `</picture>`;
+      `</picture>`
+    );
   }
 
   // Fallback: regular img with WebP srcset
@@ -1757,8 +2200,7 @@ function renderLocaleList(node: import('../../shared/types').LocaleListNode, ctx
     }
 
     const localeStyleOpts = {
-      fluidActive:
-        ctx.responsiveScales?.enabled === true && ctx.responsiveScales?.mode === 'fluid',
+      fluidActive: ctx.responsiveScales?.enabled === true && ctx.responsiveScales?.mode === 'fluid',
       responsiveScales: ctx.responsiveScales,
     };
 
@@ -1784,18 +2226,14 @@ function renderLocaleList(node: import('../../shared/types').LocaleListNode, ctx
       localeListStyleAttr = buildCssVariableStyleAttr(localeListCssVariables);
     }
 
-    const containerClassAttr = containerClasses.length > 0
-      ? ` class="${escapeHtml(containerClasses.join(' '))}"`
-      : '';
+    const containerClassAttr = containerClasses.length > 0 ? ` class="${escapeHtml(containerClasses.join(' '))}"` : '';
 
     // Convert item styles to utility classes
     let itemClasses: string[] = [];
     if (node.itemStyle) {
       itemClasses = responsiveStylesToClasses(node.itemStyle as ResponsiveStyleObject, localeStyleOpts);
     }
-    const itemClassAttr = itemClasses.length > 0
-      ? ` class="${escapeHtml(itemClasses.join(' '))}"`
-      : '';
+    const itemClassAttr = itemClasses.length > 0 ? ` class="${escapeHtml(itemClasses.join(' '))}"` : '';
 
     // Convert active item styles to utility classes
     let activeItemClasses: string[] = [];
@@ -1808,24 +2246,19 @@ function renderLocaleList(node: import('../../shared/types').LocaleListNode, ctx
     if (node.separatorStyle) {
       separatorClasses = responsiveStylesToClasses(node.separatorStyle as ResponsiveStyleObject, localeStyleOpts);
     }
-    const separatorClassAttr = separatorClasses.length > 0
-      ? ` class="${escapeHtml(separatorClasses.join(' '))}"`
-      : '';
+    const separatorClassAttr = separatorClasses.length > 0 ? ` class="${escapeHtml(separatorClasses.join(' '))}"` : '';
 
     // Convert flag styles to utility classes
     let flagClasses: string[] = [];
     if (node.flagStyle) {
       flagClasses = responsiveStylesToClasses(node.flagStyle as ResponsiveStyleObject, localeStyleOpts);
     }
-    const flagClassAttr = flagClasses.length > 0
-      ? ` class="${escapeHtml(flagClasses.join(' '))}"`
-      : '';
+    const flagClassAttr = flagClasses.length > 0 ? ` class="${escapeHtml(flagClasses.join(' '))}"` : '';
 
     // Current item gets both itemStyle + activeItemStyle (additive/override)
     const currentItemClasses = [...itemClasses, ...activeItemClasses];
-    const currentItemClassAttr = currentItemClasses.length > 0
-      ? ` class="${escapeHtml(currentItemClasses.join(' '))}"`
-      : '';
+    const currentItemClassAttr =
+      currentItemClasses.length > 0 ? ` class="${escapeHtml(currentItemClasses.join(' '))}"` : '';
 
     // Build links HTML
     const links: string[] = [];
@@ -1858,13 +2291,13 @@ function renderLocaleList(node: import('../../shared/types').LocaleListNode, ctx
       }
       linkContent += `<div>${escapeHtml(displayText)}</div>`;
 
-      links.push(`<a href="${escapeHtml(link.path)}"${hreflangAttr}${currentAttr} data-locale="${escapeHtml(link.locale)}"${classAttrForLink}>${linkContent}</a>`);
+      links.push(
+        `<a href="${escapeHtml(link.path)}"${hreflangAttr}${currentAttr} data-locale="${escapeHtml(link.locale)}"${classAttrForLink}>${linkContent}</a>`,
+      );
     }
 
     // Join links with separator (empty span styled via separatorStyle) or concatenate directly
-    const linksHTML = showSeparator
-      ? links.join(`<span${separatorClassAttr}></span>`)
-      : links.join('');
+    const linksHTML = showSeparator ? links.join(`<span${separatorClassAttr}></span>`) : links.join('');
 
     // Extract attributes from node
     const nodeAttributes = resolveI18nAttrs(extractAttributesFromNode(node), locale, i18nConfig);
@@ -1897,8 +2330,20 @@ export async function renderPageSSR(
   cmsContext?: CMSContext,
   cmsService?: CMSService,
   isProductionBuild?: boolean,
-  injectEditorAttrs?: boolean
-): Promise<{ html: string; meta: string; title: string; javascript: string; componentCSS?: string; locale: string; interactiveStylesMap: Map<string, InteractiveStyles>; preloadImages: PreloadImage[]; neededCollections: Set<string>; ssrFallbackCollector: Map<string, string>; processedRawHtmlCollector: Map<string, string> }> {
+  injectEditorAttrs?: boolean,
+): Promise<{
+  html: string;
+  meta: string;
+  title: string;
+  javascript: string;
+  componentCSS?: string;
+  locale: string;
+  interactiveStylesMap: Map<string, InteractiveStyles>;
+  preloadImages: PreloadImage[];
+  neededCollections: Set<string>;
+  ssrFallbackCollector: Map<string, string>;
+  processedRawHtmlCollector: Map<string, string>;
+}> {
   // Extract page content
   const rootNode = pageData?.root || undefined;
   if (!rootNode) {
@@ -1906,7 +2351,7 @@ export async function renderPageSSR(
   }
 
   // Load i18n config if not provided
-  const config = i18nConfig || await loadI18nConfig();
+  const config = i18nConfig || (await loadI18nConfig());
 
   // Extract locale from path if not explicitly provided
   const { locale: pathLocale, pathWithoutLocale } = extractLocaleFromPath(pagePath, config);
@@ -1926,7 +2371,13 @@ export async function renderPageSSR(
       meta = { ...meta, ogTitle: processCMSTemplate(meta.ogTitle, cmsContext.cms, effectiveLocale, config) };
     }
     if (typeof meta.ogDescription === 'string') {
-      meta = { ...meta, ogDescription: processCMSTemplate(meta.ogDescription, cmsContext.cms, effectiveLocale, config) };
+      meta = {
+        ...meta,
+        ogDescription: processCMSTemplate(meta.ogDescription, cmsContext.cms, effectiveLocale, config),
+      };
+    }
+    if (typeof meta.ogImage === 'string') {
+      meta = { ...meta, ogImage: processCMSTemplate(meta.ogImage, cmsContext.cms, effectiveLocale, config) };
     }
   }
 
@@ -1934,9 +2385,27 @@ export async function renderPageSSR(
 
   // Render the component tree to HTML with i18n and CMS support
   // Also collect interactive styles, preload images, and needed collections during render
-  const { html: contentHTML, interactiveStylesMap, preloadImages, neededCollections, ssrFallbackCollector, processedRawHtmlCollector } = rootNode
-    ? await buildComponentHTML(rootNode, globalComponents, pageComponents, effectiveLocale, config, slugMappings, pagePath, cmsContext, cmsService, isProductionBuild, injectEditorAttrs)
-    : { html: '', interactiveStylesMap: new Map<string, InteractiveStyles>(), preloadImages: [], neededCollections: new Set<string>(), ssrFallbackCollector: new Map<string, string>(), processedRawHtmlCollector: new Map<string, string>() };
+  // (rootNode is guaranteed non-null — the guard at the top of this function throws otherwise)
+  const {
+    html: contentHTML,
+    interactiveStylesMap,
+    preloadImages,
+    neededCollections,
+    ssrFallbackCollector,
+    processedRawHtmlCollector,
+  } = await buildComponentHTML(
+    rootNode,
+    globalComponents,
+    pageComponents,
+    effectiveLocale,
+    config,
+    slugMappings,
+    pagePath,
+    cmsContext,
+    cmsService,
+    isProductionBuild,
+    injectEditorAttrs,
+  );
 
   // Collect JavaScript and CSS from all components
   const javascript = await collectComponentJavaScript(globalComponents, pageComponents);