meno-core 1.0.52 → 1.0.53

package/entries/client-router.tsx

@@ -1,180 +1,21 @@
 import { createElement as h } from "react";
 import { createRoot } from "react-dom/client";
 import { Router, type RouterProps } from "../lib/client/routing/Router";
+import { setupCssHmrListeners } from "../lib/client/hmrCssReload";
 import type { PrefetchConfig } from "../lib/shared/types/prefetch";
 
-// Extend Window interface for HMR state and config
+// Extend Window interface for config
 declare global {
   interface Window {
-    __hmrColorsInitialized?: boolean;
-    __hmrVariablesInitialized?: boolean;
     __MENO_CONFIG__?: {
       prefetch?: Partial<PrefetchConfig>;
     };
   }
 }
 
-// Setup HMR colors update listener immediately on app load
-function setupColorsHMR() {
-  if (typeof window === 'undefined') return;
-
-  // Mark as initialized
-  if (window.__hmrColorsInitialized) return;
-  window.__hmrColorsInitialized = true;
-
-  // Listen for color updates from HMR
-  document.addEventListener('hmr-colors-update', async () => {
-    await injectUpdatedThemeCSS();
-  });
-}
-
-// Fetch and inject updated theme CSS
-async function injectUpdatedThemeCSS() {
-  try {
-    // Fetch the theme config
-    const themesResponse = await fetch('/api/themes');
-    if (!themesResponse.ok) return;
-
-    const themesData = await themesResponse.json() as {
-      themes: Array<{ name: string; label: string }>;
-      default: string;
-    };
-
-    // Fetch colors for each theme
-    const themeColors: Record<string, any> = {};
-    for (const theme of themesData.themes) {
-      const colorResponse = await fetch(
-        `/api/colors?theme=${encodeURIComponent(theme.name)}`
-      );
-      if (colorResponse.ok) {
-        themeColors[theme.name] = (await colorResponse.json()).colors;
-      }
-    }
-
-    // Also get default theme colors
-    const defaultResponse = await fetch('/api/colors');
-    if (defaultResponse.ok) {
-      themeColors['default'] = (await defaultResponse.json()).colors;
-    }
-
-    // Generate CSS
-    let css = '';
-
-    // Default theme in :root
-    if (themeColors['default']) {
-      const vars = Object.entries(themeColors['default'])
-        .map(([name, value]) => `  --${name}: ${value};`)
-        .join('\n');
-      css += `:root {\n${vars}\n}\n\n`;
-    }
-
-    // Each theme in [theme="..."]
-    for (const theme of themesData.themes) {
-      if (themeColors[theme.name]) {
-        const vars = Object.entries(themeColors[theme.name])
-          .map(([name, value]) => `  --${name}: ${value};`)
-          .join('\n');
-        css += `[theme="${theme.name}"] {\n${vars}\n}\n\n`;
-      }
-    }
-
-    // Find or create style tag
-    let styleTag = document.getElementById('hmr-theme-variables');
-    if (!styleTag) {
-      styleTag = document.createElement('style');
-      styleTag.id = 'hmr-theme-variables';
-      document.head.appendChild(styleTag);
-    }
-
-    styleTag.textContent = css;
-  } catch (error) {
-    // Silently fail - not critical if CSS injection doesn't work
-  }
-}
-
-// Setup HMR variables update listener immediately on app load
-function setupVariablesHMR() {
-  if (typeof window === 'undefined') return;
-
-  if (window.__hmrVariablesInitialized) return;
-  window.__hmrVariablesInitialized = true;
-
-  document.addEventListener('hmr-variables-update', async () => {
-    await injectUpdatedVariablesCSS();
-  });
-}
-
-// Fetch and inject updated variables CSS
-async function injectUpdatedVariablesCSS() {
-  try {
-    const response = await fetch('/api/variables-css');
-    if (!response.ok) return;
-
-    const css = await response.text();
-
-    let styleTag = document.getElementById('hmr-css-variables');
-    if (!styleTag) {
-      styleTag = document.createElement('style');
-      styleTag.id = 'hmr-css-variables';
-      document.head.appendChild(styleTag);
-    }
-
-    styleTag.textContent = css;
-  } catch (error) {
-    // Silently fail - not critical if CSS injection doesn't work
-  }
-}
-
-// Setup HMR fonts update listener immediately on app load
-function setupFontsHMR() {
-  if (typeof window === 'undefined') return;
-
-  if ((window as any).__hmrFontsCSSInitialized) return;
-  (window as any).__hmrFontsCSSInitialized = true;
-
-  document.addEventListener('hmr-fonts-update', async () => {
-    await injectUpdatedFontsCSS();
-  });
-}
-
-// Fetch and inject updated fonts CSS
-async function injectUpdatedFontsCSS() {
-  try {
-    const response = await fetch('/api/fonts-css');
-    if (!response.ok) return;
-
-    const css = await response.text();
-
-    let styleTag = document.getElementById('hmr-fonts-css');
-    if (!styleTag) {
-      styleTag = document.createElement('style');
-      styleTag.id = 'hmr-fonts-css';
-      document.head.appendChild(styleTag);
-    }
-
-    styleTag.textContent = css;
-  } catch (error) {
-    // Silently fail
-  }
-}
-
-// Setup HMR libraries update listener - triggers full page reload
-function setupLibrariesHMR() {
-  if (typeof window === 'undefined') return;
-
-  if ((window as any).__hmrLibrariesInitialized) return;
-  (window as any).__hmrLibrariesInitialized = true;
-
-  document.addEventListener('hmr-libraries-update', () => {
-    location.reload();
-  });
-}
-
-// Initialize HMR listeners
-setupColorsHMR();
-setupVariablesHMR();
-setupFontsHMR();
-setupLibrariesHMR();
+// Wire CSS/asset hot-reload listeners (colors, variables, fonts, libraries).
+// Shared with the editor preview router — see lib/client/hmrCssReload.ts.
+setupCssHmrListeners();
 
 // Render app with HMR support and prefetching enabled
 const rootElement = document.getElementById('root');
@@ -203,4 +44,3 @@ if (rootElement) {
 if (import.meta.hot) {
   import.meta.hot.accept();
 }
-

package/lib/client/ErrorBoundary.test.tsx

@@ -64,10 +64,9 @@ describe("ErrorBoundary - Error catching", () => {
         root.render(errorBoundary);
         await wait(10); // Wait for React to process error
 
-        // Verify fallback UI is displayed with error message
-        expect(container.textContent).toContain("Component Error");
+        // Verify friendly fallback UI is displayed with the component name
+        expect(container.textContent).toContain("This section ran into a problem");
         expect(container.textContent).toContain("TestComponent");
-        expect(container.textContent).toContain("Test render error");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -91,7 +90,7 @@ describe("ErrorBoundary - Error catching", () => {
         // Should render the safe content
         expect(container.textContent).toContain("Safe content");
         // Should NOT show error UI
-        expect(container.textContent).not.toContain("Component Error");
+        expect(container.textContent).not.toContain("This section ran into a problem");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -148,8 +147,9 @@ describe("ErrorBoundary - Error catching", () => {
         root.render(errorBoundary);
         await wait(10);
 
-        // Should show page-level error UI
-        expect(container.textContent).toContain("Page Rendering Error");
+        // Should show friendly page-level error UI
+        expect(container.textContent).toContain("This section ran into a problem");
+        // Raw message is preserved in the collapsible technical details.
         expect(container.textContent).toContain("Page rendering failed");
       } finally {
         root.unmount();
@@ -171,7 +171,7 @@ describe("ErrorBoundary - Error catching", () => {
         await wait(10);
 
         expect(container.textContent).toContain("Page content");
-        expect(container.textContent).not.toContain("Page Rendering Error");
+        expect(container.textContent).not.toContain("This section ran into a problem");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -200,7 +200,7 @@ describe("ErrorBoundary - Error catching", () => {
         // Should show custom fallback
         expect(container.textContent).toContain("Custom fallback: Custom error");
         // Should NOT show default error UI
-        expect(container.textContent).not.toContain("Component Error");
+        expect(container.textContent).not.toContain("This section ran into a problem");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -250,7 +250,8 @@ describe("ErrorBoundary - Error display", () => {
         root.render(errorBoundary);
         await wait(10);
 
-        expect(container.textContent).toContain("Specific error message");
+        // Component-level shows friendly copy; the raw message is dev-only.
+        expect(container.textContent).toContain("This section ran into a problem");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -271,7 +272,7 @@ describe("ErrorBoundary - Error display", () => {
         await wait(10);
 
         // Should still show error UI even without message
-        expect(container.textContent).toContain("Component Error");
+        expect(container.textContent).toContain("This section ran into a problem");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -295,6 +296,7 @@ describe("ErrorBoundary - Error display", () => {
         await wait(10);
 
         expect(container.textContent).toContain("MyCustomComponent");
+        expect(container.textContent).toContain("This section ran into a problem");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -314,7 +316,7 @@ describe("ErrorBoundary - Error display", () => {
         root.render(errorBoundary);
         await wait(10);
 
-        expect(container.textContent).toContain("Component Error");
+        expect(container.textContent).toContain("This section ran into a problem");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -336,10 +338,10 @@ describe("ErrorBoundary - Error display", () => {
         root.render(errorBoundary);
         await wait(10);
 
-        // Component-level shows "Component Error"
-        expect(container.textContent).toContain("Component Error");
-        // Should NOT show page-level error
-        expect(container.textContent).not.toContain("Page Rendering Error");
+        // Component-level shows the friendly title...
+        expect(container.textContent).toContain("This section ran into a problem");
+        // ...but NOT the page-level "Reload Page" affordance.
+        expect(container.textContent).not.toContain("Reload Page");
       } finally {
         root.unmount();
         cleanupContainer(container);
@@ -483,8 +485,7 @@ describe("ErrorBoundary - Error types", () => {
       root.render(errorBoundary);
       await wait(10);
 
-      expect(container.textContent).toContain("Type mismatch");
-      expect(container.textContent).toContain("Component Error");
+      expect(container.textContent).toContain("This section ran into a problem");
     } finally {
       root.unmount();
       cleanupContainer(container);
@@ -504,7 +505,8 @@ describe("ErrorBoundary - Error types", () => {
       root.render(errorBoundary);
       await wait(10);
 
-      expect(container.textContent).toContain("undefined variable");
+      // Raw message is dev-only for component-level; friendly title always shows.
+      expect(container.textContent).toContain("This section ran into a problem");
     } finally {
       root.unmount();
       cleanupContainer(container);
@@ -524,7 +526,8 @@ describe("ErrorBoundary - Error types", () => {
       root.render(errorBoundary);
       await wait(10);
 
-      expect(container.textContent).toContain("Invalid component definition: Missing structure");
+      // Friendly, plain-language copy replaces the raw JS message for end users.
+      expect(container.textContent).toContain("This section ran into a problem");
     } finally {
       root.unmount();
       cleanupContainer(container);
@@ -556,7 +559,7 @@ describe("ErrorBoundary - Multiple instances", () => {
       await wait(10);
 
       // Both should be in the DOM
-      expect(container.textContent).toContain("Component Error");
+      expect(container.textContent).toContain("This section ran into a problem");
       expect(container.textContent).toContain("Safe content");
     } finally {
       root.unmount();
@@ -582,11 +585,10 @@ describe("ErrorBoundary - Multiple instances", () => {
       root.render(app);
       await wait(10);
 
-      // Inner boundary should catch the error
-      expect(container.textContent).toContain("Component Error");
-      expect(container.textContent).toContain("Inner error");
-      // Should NOT show page-level error since inner boundary caught it
-      expect(container.textContent).not.toContain("Page Rendering Error");
+      // Inner (component-level) boundary catches it: friendly title shows,
+      // and the page-level "Reload Page" affordance does not.
+      expect(container.textContent).toContain("This section ran into a problem");
+      expect(container.textContent).not.toContain("Reload Page");
     } finally {
       root.unmount();
       cleanupContainer(container);

package/lib/client/ErrorBoundary.tsx

@@ -4,6 +4,7 @@
  */
 
 import { Component, createElement as h, ReactNode } from 'react';
+import { toFriendlyError } from '../shared/friendlyError';
 
 interface ErrorBoundaryProps {
   children?: ReactNode;
@@ -67,6 +68,12 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
         return fallback(error, errorInfo);
       }
 
+      // Plain-language version of the raw error. Backticks (used for code spans
+      // in the overlay) are stripped for plain-text rendering here.
+      const friendly = toFriendlyError(error);
+      const friendlyMessage = friendly.friendlyMessage.replace(/`/g, '');
+      const friendlyHint = friendly.hint?.replace(/`/g, '');
+
       // Default fallback UI
       if (level === 'page') {
         return h('div', {
@@ -92,7 +99,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
                 fontSize: '24px',
                 fontWeight: '600',
               }
-            }, '⚠️ Page Rendering Error'),
+            }, `⚠️ ${friendly.title}`),
             h('p', {
               style: {
                 margin: '0 0 16px 0',
@@ -100,21 +107,8 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
                 fontSize: '16px',
                 lineHeight: '1.5',
               }
-            }, 'An error occurred while rendering this page. Please check your JSON configuration.'),
-            h('div', {
-              style: {
-                background: '#fff',
-                border: '1px solid #ddd',
-                borderRadius: '4px',
-                padding: '16px',
-                marginBottom: '16px',
-                fontFamily: 'monospace',
-                fontSize: '14px',
-                color: '#c00',
-                overflowX: 'auto',
-              }
-            }, error.message),
-            process.env.NODE_ENV === 'development' && errorInfo?.componentStack && h('details', {
+            }, friendlyHint ? `${friendlyMessage} ${friendlyHint}` : friendlyMessage),
+            h('details', {
               style: {
                 marginTop: '16px',
                 fontSize: '14px',
@@ -127,8 +121,21 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
                   fontWeight: '600',
                   marginBottom: '8px',
                 }
-              }, 'Stack Trace'),
-              h('pre', {
+              }, 'Technical details'),
+              h('div', {
+                style: {
+                  background: '#fff',
+                  border: '1px solid #ddd',
+                  borderRadius: '4px',
+                  padding: '16px',
+                  margin: '8px 0',
+                  fontFamily: 'monospace',
+                  fontSize: '14px',
+                  color: '#c00',
+                  overflowX: 'auto',
+                }
+              }, error.message),
+              process.env.NODE_ENV === 'development' && errorInfo?.componentStack && h('pre', {
                 style: {
                   background: '#f5f5f5',
                   border: '1px solid #ddd',
@@ -187,10 +194,18 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
               color: '#c00',
               fontSize: '14px',
             }
-          }, `Component Error${componentName ? `: ${componentName}` : ''}`)
+          }, `${friendly.title}${componentName ? ` (${componentName})` : ''}`)
         ),
         h('div', {
           style: {
+            fontSize: '13px',
+            color: '#666',
+            lineHeight: '1.5',
+          }
+        }, friendlyHint ? `${friendlyMessage} ${friendlyHint}` : friendlyMessage),
+        process.env.NODE_ENV === 'development' && h('div', {
+          style: {
+            marginTop: '8px',
             fontSize: '12px',
             color: '#666',
             fontFamily: 'monospace',

package/lib/client/core/ComponentBuilder.ts

@@ -318,6 +318,14 @@ export class ComponentBuilder {
 
     if (!node) return null;
 
+    // Verbatim-code markers ({ _code, expr }) come from the meno-astro dialect for
+    // arbitrary JS the model can't represent as a binding. They render natively in the
+    // Astro build; the editor preview has nothing to evaluate, so render nothing (the
+    // marker must never reach the element dispatch below, which would treat it as a tag).
+    if (typeof node === 'object' && (node as { _code?: unknown })._code === true) {
+      return null;
+    }
+
     // Resolve `_i18n` value objects to a single string before node-shape
     // dispatch. Authors can write a localized string anywhere `children` is
     // accepted — on raw `type: "node"` elements as well as component props.
@@ -824,7 +832,12 @@ export class ComponentBuilder {
       key = 0, elementPath = [0], parentComponentName = null, viewportWidth = 1920,
       componentContext = null, locale, i18nConfig, cmsContext = null, cmsLocale = null,
       collectionItemsMap = {}, itemContext = null, cmsItemIndexPath = null,
-      cmsListPaths = null, templateContext = null
+      cmsListPaths = null, templateContext = null,
+      // The host (outer) component's resolved props. Forwarded to
+      // `processStructure` as `parentProps` so a `{{x}}` in this
+      // component's structure falls back to the host's `x` when this
+      // component's interface doesn't declare it.
+      componentResolvedProps: parentResolvedProps = null
     } = options;
 
     const componentDef = this.componentRegistry.get(componentName);
@@ -870,7 +883,11 @@ export class ComponentBuilder {
       const markedChildren = typedChildren ? markAsSlotContent(typedChildren) : undefined;
       const processedStructure = processStructure(
         structuredComponentDef.structure,
-        { props: resolvedProps, componentDef: structuredComponentDef },
+        {
+          props: resolvedProps,
+          componentDef: structuredComponentDef,
+          parentProps: parentResolvedProps ?? undefined,
+        },
         viewportWidth,
         markedChildren
       );

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

@@ -15,6 +15,7 @@ import { InteractiveStylesRegistry } from "../../InteractiveStylesRegistry";
 import { hasInteractiveStyleMappings, extractInteractiveStyleMappings, resolveExtractedMappings } from "../../../shared/interactiveStyleMappings";
 import { UtilityClassCollector } from "../../styles/UtilityClassCollector";
 import DOMPurify from "isomorphic-dompurify";
+import { inlineSvgStyleRules } from "../../../shared/inlineSvgStyleRules";
 import type { ElementRegistry } from "../../elementRegistry";
 import type { BuilderContext } from "./types";
 import { hasItemTemplates, processItemTemplate, processItemPropsTemplate, type ValueResolver } from "../../../shared/itemTemplateUtils";
@@ -39,8 +40,8 @@ export interface EmbedBuilderDeps {
  * Script tags and event handlers are still removed for security
  */
 const SANITIZE_CONFIG = {
-  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'],
+  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
 };
 
@@ -75,8 +76,11 @@ export function buildEmbed(
     htmlContent = processCMSTemplate(htmlContent, ctx.cmsContext, effectiveLocale);
   }
 
-  // Sanitize HTML with allowlist
-  const sanitizedHtml = DOMPurify.sanitize(htmlContent, SANITIZE_CONFIG);
+  // Sanitize HTML with allowlist, then inline simple SVG <style> rules so
+  // class-scoped declarations survive `innerHTML` reparses (editor preview's
+  // HMR `smartUpdate` fallback in `ssr/htmlGenerator.ts:574` strips CSSOM
+  // registration for SVG <style> elements re-inserted that way).
+  const sanitizedHtml = inlineSvgStyleRules(DOMPurify.sanitize(htmlContent, SANITIZE_CONFIG));
   const effectiveParentComponentName = deps.getEffectiveParentComponentName(componentContext, parentComponentName);
 
   // Extract attributes from node

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

@@ -80,6 +80,20 @@ export function buildList(
     containerProps['data-source'] = source || (sourceIsResolved ? 'resolved' : '');
   }
 
+  // When this list is itself rendered inside an outer list iteration, stamp
+  // the outer iteration context onto its container so the click handler and
+  // selection overlay can disambiguate the N sibling duplicates (one per
+  // outer item). Mirrors ComponentBuilder's write so both stay consistent.
+  if (cmsItemIndexPath && cmsItemIndexPath.length > 0) {
+    containerProps['data-cms-item-index'] = cmsItemIndexPath.join('.');
+    if (cmsListPaths && cmsListPaths.length === cmsItemIndexPath.length) {
+      containerProps['data-cms-context'] = JSON.stringify({
+        itemIndexPath: cmsItemIndexPath,
+        listPaths: cmsListPaths,
+      });
+    }
+  }
+
   // Add extracted attributes
   if (Object.keys(extractedAttributes).length > 0) {
     Object.assign(containerProps, extractedAttributes);
@@ -209,20 +223,25 @@ export function buildList(
       componentResolvedProps
     });
 
-    // Add children directly (no wrapper div)
+    // Add children directly (no wrapper div).
+    // Use a stable identifier (CMS `_id` or `_filename`) as the React key
+    // instead of the loop index, so reordering / filtering moves DOM nodes
+    // rather than unmounting & re-mounting every row. Falls back to index
+    // for prop-mode lists whose items lack those fields.
+    const cmsItem = item as Partial<CMSItem> | undefined;
+    const itemKey = cmsItem?._id ?? cmsItem?._filename ?? index;
     if (itemChildren === null) continue;
     if (Array.isArray(itemChildren)) {
-      // Add unique keys by combining original key with item index
       for (const child of itemChildren) {
         if (typeof child === 'object' && child !== null && 'key' in child) {
-          renderedItems.push({ ...child, key: `${child.key}-item-${index}` } as ReactElement);
+          renderedItems.push({ ...child, key: `${child.key}-item-${itemKey}` } as ReactElement);
         } else {
           renderedItems.push(child);
         }
       }
     } else if (typeof itemChildren === 'object' && itemChildren !== null && 'key' in itemChildren) {
       // Single child - ensure unique key
-      renderedItems.push({ ...itemChildren, key: `${(itemChildren as ReactElement).key}-item-${index}` } as ReactElement);
+      renderedItems.push({ ...itemChildren, key: `${(itemChildren as ReactElement).key}-item-${itemKey}` } as ReactElement);
     } else {
       renderedItems.push(itemChildren);
     }

package/lib/client/fontFamiliesService.test.ts

@@ -0,0 +1,76 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
+import {
+  fetchFontFamilies,
+  getCachedFontFamilies,
+  invalidateFontFamilies,
+} from './fontFamiliesService';
+
+const realFetch = globalThis.fetch;
+
+function mockFetchOnce(response: any) {
+  globalThis.fetch = mock(async () => ({
+    ok: true,
+    json: async () => response,
+  })) as any;
+}
+
+describe('fontFamiliesService', () => {
+  beforeEach(() => {
+    invalidateFontFamilies();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+  });
+
+  test('getCachedFontFamilies returns empty array before fetch', () => {
+    expect(getCachedFontFamilies()).toEqual([]);
+  });
+
+  test('fetchFontFamilies extracts explicit family names', async () => {
+    mockFetchOnce({ fonts: [{ family: 'Inter' }, { family: 'Geomanist' }] });
+    const families = await fetchFontFamilies();
+    expect(families).toEqual(['Inter', 'Geomanist']);
+    expect(getCachedFontFamilies()).toEqual(['Inter', 'Geomanist']);
+  });
+
+  test('fetchFontFamilies dedupes families that repeat across weights/unicode-ranges', async () => {
+    mockFetchOnce({
+      fonts: [
+        { family: 'Fraunces', weight: 400 },
+        { family: 'Fraunces', weight: 700 },
+        { family: 'Inter' },
+      ],
+    });
+    const families = await fetchFontFamilies();
+    expect(families).toEqual(['Fraunces', 'Inter']);
+  });
+
+  test('fetchFontFamilies derives a family name from path when family is missing', async () => {
+    mockFetchOnce({
+      fonts: [{ path: '/fonts/roboto-mono-regular.ttf' }],
+    });
+    const families = await fetchFontFamilies();
+    expect(families).toEqual(['Roboto Mono Regular']);
+  });
+
+  test('fetchFontFamilies handles empty fonts array', async () => {
+    mockFetchOnce({ fonts: [] });
+    const families = await fetchFontFamilies();
+    expect(families).toEqual([]);
+  });
+
+  test('fetchFontFamilies handles config without fonts key', async () => {
+    mockFetchOnce({});
+    const families = await fetchFontFamilies();
+    expect(families).toEqual([]);
+  });
+
+  test('invalidateFontFamilies clears the cache', async () => {
+    mockFetchOnce({ fonts: [{ family: 'Inter' }] });
+    await fetchFontFamilies();
+    expect(getCachedFontFamilies()).toEqual(['Inter']);
+    invalidateFontFamilies();
+    expect(getCachedFontFamilies()).toEqual([]);
+  });
+});