meno-core 1.0.52 → 1.0.53

package/lib/server/astro/nodeToAstro.ts

@@ -32,6 +32,7 @@ import type { BreakpointConfig } from '../../shared/breakpoints';
 import type { ResponsiveScales } from '../../shared/responsiveScaling';
 import { generateElementClassName, type ElementClassContext } from '../../shared/elementClassName';
 import { isVoidElement, hasIf, hasChildren, isSlotContent as isSlotContentNode } from '../../shared/nodeUtils';
+import { deepMergeStyles } from '../../shared/styleNodeUtils';
 import { NODE_TYPE, RAW_HTML_PREFIX } from '../../shared/constants';
 import { extractInteractiveStyleMappings, hasInteractiveStyleMappings } from '../../shared/interactiveStyleMappings';
 import type { ImageMetadataMap } from '../ssr/imageMetadata';
@@ -94,6 +95,18 @@ export interface AstroEmitContext {
   cmsSchema?: CMSSchema;
   /** Wrap function name for i18n resolution (e.g., 'r') */
   cmsWrapFn?: string;
+  /**
+   * Names of components that consume the CMS entry. When emitting an instance
+   * of one of these inside a CMS context, thread `cms={<entry binding>}` so the
+   * component (which has an isolated Astro scope) can resolve `{{cms.*}}`.
+   */
+  cmsConsumers?: Set<string>;
+  /**
+   * collectionId → JS template literal (over entry `e`) for an item's `_url`,
+   * used when flattening `sourceType: 'collection'` lists so list items expose
+   * a usable link (`{{item._url}}`).
+   */
+  collectionUrlExpr?: Map<string, string>;
   /** Default locale for i18n resolver (used in component defs) */
   defaultLocale?: string;
   /** Set to true during emission when an i18n object is encountered in a component def */
@@ -139,6 +152,16 @@ function ind(ctx: AstroEmitContext): string {
   return '  '.repeat(ctx.indent);
 }
 
+/**
+ * Build the runtime href expression for a link-typed value. A link value may be
+ * an object `{ href, target? }` or a bare string URL — the prop validator
+ * coerces strings to `{ href }`, so collection lists and CMS fields legitimately
+ * pass a string (e.g. `post._url`). Mirror that coercion at render time.
+ */
+function linkHrefExpr(expr: string): string {
+  return `(typeof ${expr} === 'string' ? ${expr} : ${expr}?.href) ?? "#"`;
+}
+
 function localizeHref(href: string, ctx: AstroEmitContext): string {
   if (!href.startsWith('/') || href.startsWith('//')) return href;
   const { locale, i18nDefaultLocale, slugMappings } = ctx;
@@ -505,6 +528,70 @@ function buildElementClass(
   });
 }
 
+function isResponsiveStyleObject(
+  style: StyleObject | ResponsiveStyleObject
+): style is ResponsiveStyleObject {
+  return 'base' in style || 'tablet' in style || 'mobile' in style;
+}
+
+/**
+ * The style on a component's root element — `node.style` for HTML/embed/list/
+ * link roots, or `props.style` for a component/link-instance root. Used to
+ * replicate SSR's per-breakpoint merge of an instance override into the root.
+ */
+function getComponentRootStyle(
+  def: ComponentDefinition | undefined
+): StyleObject | ResponsiveStyleObject | undefined {
+  const root = def?.component?.structure as
+    | { style?: unknown; props?: { style?: unknown } }
+    | undefined;
+  if (!root || typeof root !== 'object') return undefined;
+  const s = (root.style ?? root.props?.style);
+  return s && typeof s === 'object' ? (s as StyleObject | ResponsiveStyleObject) : undefined;
+}
+
+/**
+ * True when a flat style has any property, or any responsive branch
+ * (base/tablet/mobile/custom breakpoint) is non-empty. Guards against emitting
+ * an empty `.class {}` rule / dangling `class=""` for the common empty override
+ * shape `{ base:{}, tablet:{}, mobile:{} }`.
+ */
+function hasNonEmptyStyle(style: StyleObject | ResponsiveStyleObject): boolean {
+  if (isResponsiveStyleObject(style)) {
+    return Object.values(style).some(
+      (branch) => !!branch && typeof branch === 'object' && Object.keys(branch as object).length > 0
+    );
+  }
+  return Object.keys(style).length > 0;
+}
+
+/**
+ * Drop properties whose value is a `{{...}}` template expression — these can't
+ * be serialized to static CSS. Recurses into responsive branches. Template-
+ * expression instance overrides are a pre-existing unsupported case; this just
+ * avoids emitting invalid CSS like `padding: {{x}}`.
+ */
+function stripTemplateExpressionStyle<T extends StyleObject | ResponsiveStyleObject>(style: T): T {
+  const cleanFlat = (s: Record<string, unknown>): Record<string, unknown> => {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(s)) {
+      if (typeof v === 'string' && hasTemplates(v)) continue;
+      out[k] = v;
+    }
+    return out;
+  };
+  if (isResponsiveStyleObject(style)) {
+    const out: Record<string, unknown> = {};
+    for (const [bp, branch] of Object.entries(style as Record<string, unknown>)) {
+      out[bp] = branch && typeof branch === 'object'
+        ? cleanFlat(branch as Record<string, unknown>)
+        : branch;
+    }
+    return out as T;
+  }
+  return cleanFlat(style as Record<string, unknown>) as T;
+}
+
 
 /**
  * Build HTML attributes string from node attributes
@@ -529,7 +616,7 @@ function buildAttributesString(
           if (ctx.listIndexVar) expr = replaceItemMetaVars(expr, ctx.listIndexVar, ctx.listSourceVar);
           const propDef = ctx.componentProps[expr];
           if (propDef && propDef.type === 'link') {
-            parts.push(`${key}={${expr}?.href ?? "#"}`);
+            parts.push(`${key}={${linkHrefExpr(expr)}}`);
           } else {
             parts.push(`${key}={${expr} || undefined}`);
           }
@@ -540,7 +627,7 @@ function buildAttributesString(
             if (ctx.listItemBinding) trimmed = rewriteItemVar(trimmed, ctx.listItemBinding);
             if (ctx.listIndexVar) trimmed = replaceItemMetaVars(trimmed, ctx.listIndexVar, ctx.listSourceVar);
             const pd = ctx.componentProps[trimmed];
-            return pd?.type === 'link' ? `\${${trimmed}?.href ?? "#"}` : `\${${trimmed}}`;
+            return pd?.type === 'link' ? `\${${linkHrefExpr(trimmed)}}` : `\${${trimmed}}`;
           });
           parts.push(`${key}={\`${resolved}\`}`);
         }
@@ -1310,11 +1397,54 @@ function emitComponentInstance(node: ComponentInstanceNode, ctx: AstroEmitContex
     }
   }
 
-  // Instance-level style overrides as className (Tailwind)
-  if (node.style) {
-    const { classes: instanceClasses } = responsiveStylesToTailwind(node.style as StyleObject | ResponsiveStyleObject, ctx.breakpoints, ctx.responsiveScales);
-    if (instanceClasses.length > 0) {
-      propParts.push(`class="${instanceClasses.join(' ')}"`);
+  // Thread the CMS entry into consumer components. Astro components have
+  // isolated scopes, so a component referencing `{{cms.*}}` can't see the
+  // page's `entry`/`cms` binding unless we pass it explicitly. The binding is
+  // `entry` at the CMS page level and `cms` inside a consumer component, so
+  // this also forwards correctly through nested consumers.
+  if (ctx.cmsMode && ctx.cmsConsumers?.has(node.component) && !('cms' in (node.props ?? {}))) {
+    propParts.push(`cms={${ctx.cmsEntryBinding || 'entry'}}`);
+  }
+
+  // Instance-level style overrides (+ interactive styles) via element-class CSS.
+  // Route them through the same machinery the export uses for hover styles: an
+  // UNLAYERED `<style is:global>` rule, which beats Tailwind v4's `@layer
+  // utilities` deterministically — so the instance override wins over the
+  // component's base utilities. This mirrors live SSR, which deep-merges the
+  // instance style into the component root. (The previous approach appended the
+  // override as more utility classes at equal specificity, so CSS output order
+  // decided the winner and the override frequently lost.)
+  {
+    const instanceStyle = node.style as StyleObject | ResponsiveStyleObject | undefined;
+    const instanceInteractive = node.interactiveStyles as InteractiveStyles | undefined;
+    const hasStyle = !!instanceStyle && hasNonEmptyStyle(instanceStyle);
+    const hasInteractive = Array.isArray(instanceInteractive) && instanceInteractive.length > 0;
+
+    if ((hasStyle || hasInteractive) && ctx.collectedInteractiveStyles) {
+      const elementClass = buildElementClass(ctx, node.label);
+      const rules: InteractiveStyles = [];
+      if (hasStyle) {
+        // Per-breakpoint merge the component's root style UNDER the instance
+        // override (mirrors SSR's mergeNodeStyles). This keeps the component's
+        // own responsive breakpoint values for properties the instance only sets
+        // at `base`, so a base override doesn't leak past tablet/mobile. The
+        // merged rule is unlayered, so it fully shadows the component's own
+        // (layered) root utilities. `_mapping`/`{{…}}` values carried in from the
+        // root are dropped downstream (styleObjectToCSS skips mappings) /
+        // stripped here, falling back to the component's own emission.
+        const rootStyle = getComponentRootStyle(ctx.globalComponents[node.component]);
+        const merged = (rootStyle
+          ? deepMergeStyles(rootStyle, instanceStyle!)
+          : instanceStyle!) as StyleObject | ResponsiveStyleObject;
+        const cssSafe = stripTemplateExpressionStyle(merged);
+        if (hasNonEmptyStyle(cssSafe)) rules.push({ style: cssSafe }); // no prefix/postfix → `.cls {…}`
+      }
+      if (hasInteractive) rules.push(...instanceInteractive!); // fold hover/etc. into the same class
+      if (rules.length > 0) {
+        const existing = ctx.collectedInteractiveStyles.get(elementClass);
+        ctx.collectedInteractiveStyles.set(elementClass, existing ? [...existing, ...rules] : rules);
+        propParts.push(`class="${elementClass}"`);
+      }
     }
   }
 
@@ -1461,8 +1591,8 @@ function emitLinkNode(node: LinkNode, ctx: AstroEmitContext): string {
   if (isLinkMapping(nodeHref)) {
     if (ctx.isComponentDef) {
       const propRef = (nodeHref as LinkMapping).prop;
-      // Link props are objects with {href, target?}
-      hrefAttr = ` href={${propRef}?.href ?? "#"}`;
+      // Link props are objects with {href, target?} — or a coerced string URL
+      hrefAttr = ` href={${linkHrefExpr(propRef)}}`;
     } else {
       hrefAttr = ' href="#"';
     }
@@ -1476,7 +1606,7 @@ function emitLinkNode(node: LinkNode, ctx: AstroEmitContext): string {
         if (ctx.listIndexVar) expr = replaceItemMetaVars(expr, ctx.listIndexVar, ctx.listSourceVar);
         const propDef = ctx.componentProps[expr];
         if (propDef && propDef.type === 'link') {
-          hrefAttr = ` href={${expr}?.href ?? "#"}`;
+          hrefAttr = ` href={${linkHrefExpr(expr)}}`;
         } else {
           hrefAttr = ` href={${expr}}`;
         }
@@ -1486,7 +1616,7 @@ function emitLinkNode(node: LinkNode, ctx: AstroEmitContext): string {
           if (ctx.listItemBinding) trimmed = rewriteItemVar(trimmed, ctx.listItemBinding);
           if (ctx.listIndexVar) trimmed = replaceItemMetaVars(trimmed, ctx.listIndexVar, ctx.listSourceVar);
           const pd = ctx.componentProps[trimmed];
-          return pd?.type === 'link' ? `\${${trimmed}?.href ?? "#"}` : `\${${trimmed}}`;
+          return pd?.type === 'link' ? `\${${linkHrefExpr(trimmed)}}` : `\${${trimmed}}`;
         });
         hrefAttr = ` href={\`${resolved}\`}`;
       }
@@ -1742,6 +1872,14 @@ function emitCollectionListNode(node: ListNode, ctx: AstroEmitContext): string {
     queryChain += `.then(items => items.slice(${start}${end !== undefined ? `, ${end}` : ''}))`;
   }
 
+  // Flatten content-collection entries ({ id, data: {...} }) into the flat item
+  // shape the templates expect ({{item.field}} → item.field), and synthesize the
+  // `_url`/`_id` meta the CMS data model exposes. Filter/sort above operate on the
+  // raw entries (e.data.*); this map runs last so it sees the final set.
+  const urlExpr = ctx.collectionUrlExpr?.get(source)
+    ?? `\`/${source}/\${e.data.slug ?? e.id}\``;
+  queryChain += `.then(items => items.map((e) => ({ ...e.data, _id: e.id, _url: ${urlExpr} })))`;
+
   ctx.frontmatterLines.push(`const ${collectionVar} = ${queryChain};`);
 
   // Build children with item binding

package/lib/server/astro/normalizeOrphanTemplateProps.test.ts

@@ -0,0 +1,264 @@
+import { test, expect, describe } from "bun:test";
+import { normalizeOrphanTemplateProps } from "./normalizeOrphanTemplateProps";
+import type { ComponentDefinition } from "../../shared/types";
+
+describe("normalizeOrphanTemplateProps", () => {
+  test("lifts an orphan {{x}} onto the component's interface as a string default", () => {
+    const components: Record<string, ComponentDefinition> = {
+      ArrowLink: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "span",
+            children: ["{{ctaText}}"]
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    const arrowIface = out.ArrowLink.component!.interface!;
+    expect(arrowIface.ctaText).toBeDefined();
+    expect((arrowIface.ctaText as any).type).toBe("string");
+    expect((arrowIface.ctaText as any).default).toBe("");
+  });
+
+  test("forwards lifted props on an instance ref when the host declares the prop", () => {
+    const components: Record<string, ComponentDefinition> = {
+      ArrowLink: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "span",
+            children: ["{{ctaText}}"]
+          }
+        }
+      },
+      Card: {
+        component: {
+          interface: {
+            ctaText: { type: "string", default: "Click" } as any
+          },
+          structure: {
+            type: "node",
+            tag: "div",
+            children: [
+              { type: "component", component: "ArrowLink" } as any
+            ]
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    const cardChildren = (out.Card.component!.structure as any).children;
+    expect(cardChildren[0].props).toBeDefined();
+    expect(cardChildren[0].props.ctaText).toBe("{{ctaText}}");
+  });
+
+  test("does NOT forward when the host doesn't declare the same prop", () => {
+    const components: Record<string, ComponentDefinition> = {
+      ArrowLink: {
+        component: {
+          interface: {},
+          structure: { type: "node", tag: "span", children: ["{{ctaText}}"] }
+        }
+      },
+      // Page-level wrapper that doesn't know about ctaText.
+      Wrapper: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "div",
+            children: [{ type: "component", component: "ArrowLink" } as any]
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    const wrapperChildren = (out.Wrapper.component!.structure as any).children;
+    // No forward — would have made Wrapper produce a new orphan ref.
+    expect(wrapperChildren[0].props).toBeUndefined();
+  });
+
+  test("does not override an instance prop the host already passes", () => {
+    const components: Record<string, ComponentDefinition> = {
+      ArrowLink: {
+        component: {
+          interface: {},
+          structure: { type: "node", tag: "span", children: ["{{ctaText}}"] }
+        }
+      },
+      Card: {
+        component: {
+          interface: {
+            ctaText: { type: "string", default: "Click" } as any
+          },
+          structure: {
+            type: "node",
+            tag: "div",
+            children: [
+              {
+                type: "component",
+                component: "ArrowLink",
+                props: { ctaText: "Explicit value" }
+              } as any
+            ]
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    const cardChildren = (out.Card.component!.structure as any).children;
+    expect(cardChildren[0].props.ctaText).toBe("Explicit value");
+  });
+
+  test("ignores cms.*, item.*, page.* refs (already namespaced)", () => {
+    const components: Record<string, ComponentDefinition> = {
+      Title: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "h1",
+            children: ["{{cms.title}} - {{page.slug}}"]
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    expect(Object.keys(out.Title.component!.interface!)).toHaveLength(0);
+  });
+
+  test("ignores list loop variables", () => {
+    const components: Record<string, ComponentDefinition> = {
+      List: {
+        component: {
+          interface: {
+            items: { type: "list", default: [], itemSchema: {} } as any
+          },
+          structure: {
+            type: "list",
+            sourceType: "prop",
+            source: "items",
+            itemAs: "row",
+            children: [
+              { type: "node", tag: "div", children: ["{{row.label}}"] }
+            ]
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    // `row` is the loop var — must NOT be auto-lifted as a string prop.
+    expect((out.List.component!.interface as any).row).toBeUndefined();
+  });
+
+  test("ignores expressions with operators (not a bare ident)", () => {
+    const components: Record<string, ComponentDefinition> = {
+      Cmp: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "div",
+            children: ["{{a + b}} {{x ? y : z}}"]
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    // Don't lift `a`, `b`, `x`, `y`, `z` from compound expressions — too
+    // risky to guess types or what's actually intended.
+    expect(Object.keys(out.Cmp.component!.interface!)).toHaveLength(0);
+  });
+
+  test("does not mutate the input component definitions", () => {
+    const components: Record<string, ComponentDefinition> = {
+      ArrowLink: {
+        component: {
+          interface: {},
+          structure: { type: "node", tag: "span", children: ["{{ctaText}}"] }
+        }
+      }
+    };
+    const before = JSON.stringify(components);
+    normalizeOrphanTemplateProps(components);
+    expect(JSON.stringify(components)).toBe(before);
+  });
+
+  test("lifts a prop ref from a style _mapping object", () => {
+    const components: Record<string, ComponentDefinition> = {
+      Cmp: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "div",
+            style: {
+              base: {
+                color: {
+                  _mapping: true,
+                  prop: "variant",
+                  values: { default: "black", featured: "white" }
+                }
+              }
+            }
+          } as any
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    expect((out.Cmp.component!.interface as any).variant).toBeDefined();
+    expect((out.Cmp.component!.interface as any).variant.type).toBe("string");
+  });
+
+  test("lifts a prop ref from an if boolean mapping", () => {
+    const components: Record<string, ComponentDefinition> = {
+      Cmp: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "span",
+            if: {
+              _mapping: true,
+              prop: "showBadge",
+              values: { true: true, false: false }
+            }
+          } as any
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    expect((out.Cmp.component!.interface as any).showBadge).toBeDefined();
+  });
+
+  test("dotted ref {{link.href}} lifts the base name", () => {
+    const components: Record<string, ComponentDefinition> = {
+      Anchor: {
+        component: {
+          interface: {},
+          structure: {
+            type: "node",
+            tag: "a",
+            attributes: { href: "{{link.href}}" }
+          }
+        }
+      }
+    };
+
+    const out = normalizeOrphanTemplateProps(components);
+    expect((out.Anchor.component!.interface as any).link).toBeDefined();
+  });
+});

package/lib/server/astro/normalizeOrphanTemplateProps.ts

@@ -0,0 +1,184 @@
+/**
+ * Normalize orphan template props for Astro emission.
+ *
+ * Each Meno component becomes its own `.astro` file. Templates like
+ * `{{ctaText}}` are emitted as `{ctaText}` — a JSX reference to a destructured
+ * `Astro.props` variable. If the component's `interface` doesn't declare the
+ * prop, the variable isn't in scope and Astro errors at build time.
+ *
+ * SSR/Next.js handles this at runtime via `processStructure`'s `parentProps`
+ * fallback (see templateEngine.ts). Astro can't fall back at runtime — each
+ * .astro file is its own scope — so we normalize the component graph before
+ * emission:
+ *
+ *   1. For each component, find orphan `{{x}}` refs in its structure (not
+ *      declared in the interface, not item/cms/page namespaced, not a list
+ *      loop var) and add them as optional string props with `default: ""`.
+ *
+ *   2. For each component-instance ref `<X />` inside any host's structure,
+ *      forward each of X's auto-lifted props by writing
+ *      `props.x = "{{x}}"` on the instance — but ONLY when the host itself
+ *      already declares `x`. This mirrors the SSR cascade's one-level scope:
+ *      the cascade fixes the single-step host→child case, never the leap to
+ *      a grandparent.
+ *
+ * Multi-level chains (host doesn't have the prop either) gracefully degrade
+ * to the lifted default ("") instead of failing the build — same outcome as
+ * the SSR cascade for that shape.
+ */
+
+import type { ComponentDefinition, PropDefinition } from '../../shared/types';
+
+// Bare or dotted identifier inside `{{...}}`, with whitespace allowed around
+// the body. Skips anything containing operators, calls, ternaries, etc. —
+// liftable refs are *only* simple prop reads.
+const BARE_IDENT_BODY = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\s*\.\s*[a-zA-Z_$][a-zA-Z0-9_$]*)*\s*$/;
+
+// Namespaces and meta-vars that are never component-instance props.
+const RESERVED_BASES = new Set([
+  'cms', 'item', 'page',
+  'itemIndex', 'itemFirst', 'itemLast',
+]);
+
+function recordRef(
+  base: string,
+  declared: Set<string>,
+  listVars: Set<string>,
+  out: Set<string>
+): void {
+  if (RESERVED_BASES.has(base)) return;
+  if (listVars.has(base)) return;
+  if (declared.has(base)) return;
+  out.add(base);
+}
+
+function findOrphanRefs(value: unknown, declared: Set<string>, listVars: Set<string>, out: Set<string>): void {
+  if (value == null) return;
+  if (typeof value === 'string') {
+    const re = /\{\{([^}]+)\}\}/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(value)) !== null) {
+      const body = m[1];
+      const idMatch = body.match(BARE_IDENT_BODY);
+      if (!idMatch) continue; // expressions, operators, calls — skip
+      recordRef(idMatch[1], declared, listVars, out);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) findOrphanRefs(v, declared, listVars, out);
+    return;
+  }
+  if (typeof value !== 'object') return;
+  const obj = value as Record<string, unknown>;
+
+  // Mapping objects (`{ _mapping: true, prop: "variant", values: {...} }`)
+  // reference a component prop by name. The Astro emitter turns these into
+  // bare identifier references like `String(variant) === "default"`, so the
+  // `prop` field is just as much a binding site as a `{{variant}}` template.
+  // Used for style mappings, link mappings, HTML mappings, and `if` boolean
+  // mappings — all share the same shape.
+  if (obj._mapping === true && typeof obj.prop === 'string') {
+    recordRef(obj.prop, declared, listVars, out);
+    // Keep walking — `values` may contain nested templates too (rare, but
+    // not impossible).
+  }
+
+  // A `list` node introduces a new loop variable into the scope of its
+  // children (the template instance). Default name is `item` when
+  // `itemAs` is omitted.
+  let nextListVars = listVars;
+  if (obj.type === 'list') {
+    const itemAs = typeof obj.itemAs === 'string' && obj.itemAs ? obj.itemAs : 'item';
+    nextListVars = new Set(listVars);
+    nextListVars.add(itemAs);
+  }
+
+  for (const key of Object.keys(obj)) {
+    // Don't peek into a nested component instance's `props` — those refs
+    // are resolved in the host's scope, not the target's. We handle them
+    // when walking the host itself.
+    if (obj.type === 'component' && key === 'props') continue;
+    findOrphanRefs(obj[key], declared, nextListVars, out);
+  }
+}
+
+/**
+ * Walk a host's structure and forward each target component's lifted props
+ * from the host's scope. Only forwards props the host itself declares — see
+ * the module docstring for why.
+ */
+function forwardLiftedPropsOnInstances(
+  structure: unknown,
+  hostProps: Set<string>,
+  liftedByComp: ReadonlyMap<string, ReadonlySet<string>>
+): void {
+  if (structure == null || typeof structure !== 'object') return;
+  if (Array.isArray(structure)) {
+    for (const s of structure) forwardLiftedPropsOnInstances(s, hostProps, liftedByComp);
+    return;
+  }
+  const obj = structure as Record<string, unknown>;
+  if (obj.type === 'component' && typeof obj.component === 'string') {
+    const lifted = liftedByComp.get(obj.component);
+    if (lifted && lifted.size > 0) {
+      const props = (obj.props as Record<string, unknown> | undefined) ?? {};
+      let changed = false;
+      for (const propName of lifted) {
+        if (propName in props) continue;
+        if (!hostProps.has(propName)) continue;
+        props[propName] = `{{${propName}}}`;
+        changed = true;
+      }
+      if (changed) obj.props = props;
+    }
+  }
+  for (const key of Object.keys(obj)) {
+    forwardLiftedPropsOnInstances(obj[key], hostProps, liftedByComp);
+  }
+}
+
+/**
+ * Produce a normalized copy of the component map suitable for Astro emission.
+ * The input map is not mutated.
+ */
+export function normalizeOrphanTemplateProps(
+  components: Record<string, ComponentDefinition>
+): Record<string, ComponentDefinition> {
+  const next: Record<string, ComponentDefinition> = {};
+  const liftedByComp = new Map<string, Set<string>>();
+
+  // Pass 1: clone every component and lift orphan refs onto its interface.
+  for (const [name, def] of Object.entries(components)) {
+    // structuredClone preserves Map/Set/Date but plain JSON deep-clone is
+    // enough here — component defs are JSON-serializable by construction.
+    const cloned = structuredClone(def) as ComponentDefinition;
+    next[name] = cloned;
+
+    const comp = cloned.component;
+    if (!comp || !comp.structure) continue;
+    const iface = (comp.interface ?? {}) as Record<string, PropDefinition>;
+    const declared = new Set(Object.keys(iface));
+    const orphans = new Set<string>();
+    findOrphanRefs(comp.structure, declared, new Set(), orphans);
+    if (orphans.size === 0) continue;
+
+    const augmented: Record<string, PropDefinition> = { ...iface };
+    for (const propName of orphans) {
+      augmented[propName] = { type: 'string', default: '' } as PropDefinition;
+    }
+    comp.interface = augmented;
+    liftedByComp.set(name, orphans);
+  }
+
+  // Pass 2: forward lifted props from each host where the host declares the
+  // same prop. Mutates the cloned structures in `next`.
+  for (const [, hostDef] of Object.entries(next)) {
+    const comp = hostDef.component;
+    if (!comp || !comp.structure) continue;
+    const hostProps = new Set(Object.keys(comp.interface ?? {}));
+    forwardLiftedPropsOnInstances(comp.structure, hostProps, liftedByComp);
+  }
+
+  return next;
+}