@setzkasten-cms/astro-admin 0.6.0

package/src/init/template-patcher-v2.ts

@@ -0,0 +1,1957 @@
+/**
+ * AST-based template patcher for Astro components (v2).
+ *
+ * Key difference from v1: Repeated element groups are patched using
+ * pre-computed RepeatedGroup data from the analyzer. No own detection needed.
+ *
+ * Uses @astrojs/compiler to parse .astro files, then applies position-based
+ * edits to replace hardcoded content with CMS variable references and add
+ * data-sk-field attributes for live-preview binding.
+ */
+
+import { parse } from '@astrojs/compiler'
+import type { RepeatedGroup } from './analyzer-types.js'
+
+// AST node types from @astrojs/compiler (re-declared for clarity)
+interface AstNode {
+  type: string
+  position?: { start: { offset: number; line: number; column: number }; end?: { offset: number } }
+  children?: AstNode[]
+  attributes?: AstAttr[]
+  name?: string
+  value?: string
+}
+
+interface AstAttr {
+  type: 'attribute'
+  kind: 'quoted' | 'empty' | 'expression' | 'spread' | 'shorthand' | 'template-literal'
+  name: string
+  value: string
+  raw?: string
+  position?: { start: { offset: number } }
+}
+
+/** Collapse whitespace to single spaces for comparison. */
+const normalizeWs = (s: string) => s.replace(/\s+/g, ' ').trim()
+
+/**
+ * Find text in a string where the needle may have collapsed whitespace
+ * but the haystack preserves original whitespace (incl. newlines).
+ */
+function findNormalizedText(haystack: string, needle: string, startFrom: number): { start: number; end: number } | null {
+  // Try exact match first
+  const exactIdx = haystack.indexOf(needle, startFrom)
+  if (exactIdx !== -1) return { start: exactIdx, end: exactIdx + needle.length }
+
+  // Build regex: escape special chars, replace spaces with \s+
+  const normalized = normalizeWs(needle)
+  if (!normalized || normalized.length < 2) return null
+  const escaped = normalized.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/ /g, '\\s+')
+  const regex = new RegExp(escaped)
+  const match = regex.exec(haystack.slice(startFrom))
+  if (match) return { start: startFrom + match.index, end: startFrom + match.index + match[0].length }
+
+  return null
+}
+
+/** A position-based string edit. Applied in reverse offset order to maintain positions. */
+interface Edit {
+  offset: number
+  deleteCount: number
+  insert: string
+}
+
+export type PatchField = { key: string; type: string; defaultValue?: unknown }
+
+/**
+ * Patch an Astro component template using AST analysis.
+ *
+ * Replaces hardcoded content with CMS variable references
+ * and adds data-sk-field attributes for live-preview binding.
+ *
+ * Handles:
+ * - CMS-bound fields ({var?.field ?? 'fallback'}) — wraps in <span data-sk-field> if missing
+ * - Hardcoded text → replaced with CMS expression + data-sk-field
+ * - Hardcoded href → replaced with CMS expression
+ * - Array .map() patterns → adds index parameter + data-sk-field on first element
+ */
+export async function patchTemplateForFields(
+  source: string,
+  sectionKey: string,
+  fields: PatchField[],
+  repeatedGroups: RepeatedGroup[] = [],
+  options?: { mode?: 'component' | 'page' },
+): Promise<string> {
+  // Parse the AST
+  let result: Awaited<ReturnType<typeof parse>>
+  try {
+    result = await parse(source)
+  } catch (err) {
+    console.error('[setzkasten] template-patcher: parse() failed:', err)
+    return source // graceful fallback: return unpatched
+  }
+  const ast = result.ast as AstNode
+
+  // Convert all AST byte offsets to JS char offsets
+  const b2c = buildByteToCharMap(source)
+  convertAstPositions(ast, b2c)
+
+  // Find frontmatter and extract data variable name
+  const fmNode = ast.children?.find((c) => c.type === 'frontmatter')
+  if (!fmNode?.value) return source
+
+  let varName = extractVarName(fmNode.value)
+
+  // If no CMS variable exists yet, inject Props interface + data destructuring,
+  // then re-run patcher on the modified source so AST positions are correct.
+  // IMPORTANT: Keep old variable declarations during the recursive call so the
+  // patcher can detect variable expressions ({overline} etc.) and replace them.
+  // Remove old declarations only AFTER patching is complete.
+  if (!varName) {
+    // Use a safe variable name that won't collide with existing frontmatter vars
+    varName = 'skData'
+    const isPageMode = options?.mode === 'page'
+    let propsBlock: string
+    if (isPageMode) {
+      // Page-level: import getSection and call it directly
+      propsBlock = `\nimport { getSection } from 'setzkasten:content'\nconst ${varName} = getSection('${sectionKey}')\n`
+    } else {
+      // Component-level: use Astro.props destructuring
+      propsBlock = `\ninterface Props {\n  data: Record<string, any> | null\n}\nconst { data: ${varName} } = Astro.props\n`
+    }
+    const fmEnd = source.indexOf('---', source.indexOf('---') + 3)
+    if (fmEnd === -1) return source
+    const modifiedSource = source.slice(0, fmEnd) + propsBlock + source.slice(fmEnd)
+
+    // Adjust repeated group positions: the Props block shifts everything after fmEnd
+    const shift = propsBlock.length
+    // Adjust positions in-place on the original groups so mutations
+    // (like _class fields from makeDynamicClasses) are visible to the caller.
+    for (const g of repeatedGroups) {
+      for (const inst of g.instances) { inst.start += shift; inst.end += shift }
+      for (const f of g.fields) {
+        for (let i = 0; i < f.positions.length; i++) {
+          const p = f.positions[i]
+          if (p) p.offset += shift
+        }
+      }
+      if (g.classAttrs) {
+        for (const instAttrs of g.classAttrs) {
+          for (const a of instAttrs) a.sourceOffset += shift
+        }
+      }
+    }
+
+    // Patch expressions first (old vars still present → patcher detects them)
+    const patched = await patchTemplateForFields(modifiedSource, sectionKey, fields, repeatedGroups, options)
+
+    // Now remove old variable declarations from the patched result
+    return removeOldVarDeclarations(patched, fields, repeatedGroups, varName)
+  }
+
+  // Collect existing data-sk-field bindings
+  const existingBindings = new Set<string>()
+  walkAst(ast, (node) => {
+    if (isElement(node) && node.attributes) {
+      for (const attr of node.attributes) {
+        if (attr.name === 'data-sk-field' && attr.value) {
+          existingBindings.add(attr.value)
+        }
+      }
+    }
+  })
+
+  // Build set of frontmatter variable names (for detecting variable expressions)
+  const fmVarNames = new Set<string>()
+  const fmVarRegex = /(?:const|let)\s+(\w+)\s*=/g
+  let fmMatch: RegExpExecArray | null
+  while ((fmMatch = fmVarRegex.exec(fmNode.value)) !== null) {
+    fmVarNames.add(fmMatch[1]!)
+  }
+
+  // Collect interesting nodes in one walk
+  const cmsExpressions: Array<{ node: AstNode; parent: AstNode; fieldKey: string }> = []
+  const varExpressions: Array<{ node: AstNode; parent: AstNode; varName: string }> = []
+  const textNodes: Array<{ node: AstNode; parent: AstNode }> = []
+  const hrefAttrs: Array<{ attr: AstAttr; element: AstNode }> = []
+  const mapExpressions: Array<{ node: AstNode }> = []
+  const mixedElements: Array<{ node: AstNode; normalizedText: string }> = []
+
+  walkAst(ast, (node, parent) => {
+    if (!parent) return
+
+    // Collect elements with mixed content (text + inline child elements)
+    // These are rich text fields where the whole element is one CMS field.
+    if (isElement(node) && node.children && node.children.length > 1) {
+      const hasText = node.children.some(c => c.type === 'text' && c.value?.trim())
+      const hasChild = node.children.some(c => isElement(c) || c.type === 'expression')
+      if (hasText && hasChild) {
+        const fullText = normalizeWs(getElementTextContent(node))
+        if (fullText) mixedElements.push({ node, normalizedText: fullText })
+      }
+    }
+
+    // Expression nodes: check for CMS variables, frontmatter vars, or .map() patterns
+    if (node.type === 'expression' && node.children) {
+      const exprText = node.children
+        .filter((c) => c.type === 'text')
+        .map((c) => c.value ?? '')
+        .join('')
+
+      // CMS variable: {var?.fieldKey ...}
+      const cmsMatch = exprText.match(new RegExp(`${varName}\\?\\.\\s*(\\w+)`))
+      if (cmsMatch) {
+        cmsExpressions.push({ node, parent, fieldKey: cmsMatch[1]! })
+      }
+
+      // Simple frontmatter variable reference: {varName} (not .map, not ?.field)
+      const trimmedExpr = exprText.trim()
+      if (fmVarNames.has(trimmedExpr) && !trimmedExpr.includes('.') && !trimmedExpr.includes('(')) {
+        varExpressions.push({ node, parent, varName: trimmedExpr })
+      }
+
+      // .map() pattern
+      if (exprText.includes('.map(')) {
+        mapExpressions.push({ node })
+      }
+    }
+
+    // Text nodes with actual content
+    if (node.type === 'text' && node.value?.trim()) {
+      textNodes.push({ node, parent })
+    }
+
+    // Elements with href attributes
+    if (isElement(node) && node.attributes) {
+      for (const attr of node.attributes) {
+        if (attr.name === 'href' && attr.kind === 'quoted' && attr.value) {
+          hrefAttrs.push({ attr, element: node })
+        }
+      }
+    }
+  })
+
+  const edits: Edit[] = []
+
+  // --- Ensure root element has id="section-{sectionKey}" ---
+  patchSectionId(source, ast, sectionKey, edits, options)
+
+  // --- Repeated element groups: collapse N× <article> into .map() ---
+  // Must run BEFORE per-field loop since it handles inner fields itself.
+  const repeatedFieldKeys = new Set<string>()
+  if (repeatedGroups.length > 0) {
+    const repeatedEdits = patchRepeatedGroups(source, sectionKey, varName, repeatedGroups)
+    edits.push(...repeatedEdits)
+    for (const g of repeatedGroups) repeatedFieldKeys.add(g.fieldKey)
+
+    // Sync _classN defaultValues back into top-level array field's defaultValue.
+    // The patcher adds _classN fields to group.fields, but the analyzer already
+    // built the defaultValue array before patching. Without this sync, the
+    // content JSON (built from field.defaultValue) would be missing _classN values.
+    for (const g of repeatedGroups) {
+      const topField = fields.find(f => f.key === g.fieldKey)
+      if (!topField || !Array.isArray(topField.defaultValue)) continue
+      const items = topField.defaultValue as Array<Record<string, unknown>>
+      for (const innerField of g.fields) {
+        for (let ii = 0; ii < items.length && ii < innerField.defaultValues.length; ii++) {
+          const val = innerField.defaultValues[ii]
+          if (val != null && items[ii] && typeof items[ii] === 'object' && !(innerField.key in items[ii]!)) {
+            items[ii]![innerField.key] = val
+          }
+        }
+      }
+    }
+  }
+
+  for (const field of fields) {
+    // Skip fields that belong to a repeated group (already handled above)
+    if (repeatedFieldKeys.has(field.key)) continue
+    const bindingKey = `${sectionKey}.${field.key}`
+
+    // Skip if already has data-sk-field
+    if (existingBindings.has(bindingKey)) continue
+
+    // --- Array fields: patch .map() with indexed data-sk-field ---
+    if (field.type === 'array' && Array.isArray(field.defaultValue)) {
+      const editsBefore = edits.length
+      patchArrayField(source, sectionKey, field, varName, mapExpressions, edits)
+      if (edits.length === editsBefore) {
+        // No .map() expression found — try static <ul>/<li> conversion
+        patchStaticListField(source, sectionKey, field, varName, ast, edits)
+      }
+      continue
+    }
+
+    // --- CMS-bound fields (already has {var?.field} but no data-sk-field) ---
+    const cmsExpr = cmsExpressions.find((e) => e.fieldKey === field.key)
+    if (cmsExpr) {
+      patchCmsBoundField(source, sectionKey, field, cmsExpr, edits)
+      continue
+    }
+
+    // --- Frontmatter variable expressions ({varName} → {skData?.fieldKey ?? 'default'}) ---
+    const varExpr = varExpressions.find((e) => e.varName === field.key)
+    if (varExpr) {
+      patchVarExpression(source, sectionKey, field, varName, varExpr, edits)
+      continue
+    }
+
+    // Fields without string defaultValue can't be matched by content
+    if (!field.defaultValue || typeof field.defaultValue !== 'string') continue
+    if (field.defaultValue.length < 2) continue
+
+    // --- Link/URL fields: replace hardcoded href ---
+    if (/link|url|href/i.test(field.key)) {
+      const hrefMatch = hrefAttrs.find((h) => h.attr.value === field.defaultValue)
+      if (hrefMatch) {
+        patchHrefField(source, sectionKey, field, varName, hrefMatch, edits)
+        continue
+      }
+    }
+
+    // --- Text fields: replace hardcoded text content ---
+    const editsBefore = edits.length
+    patchTextField(source, sectionKey, field, varName, textNodes, edits)
+
+    // --- Fallback: mixed-content element → rich text field (set:html) ---
+    // If patchTextField couldn't find a matching text node, the text might be
+    // spread across child elements (e.g. <p>text <strong>bold</strong> more</p>).
+    // Treat the whole element as a rich text field with set:html for CMS rendering.
+    if (edits.length === editsBefore) {
+      const dv = field.defaultValue as string
+      const mixedMatch = mixedElements.find(m => m.normalizedText === normalizeWs(dv))
+      if (mixedMatch) {
+        patchMixedContentField(source, sectionKey, field, varName, mixedMatch.node, edits)
+      }
+    }
+  }
+
+  const patched = applyEdits(source, edits)
+  return convertToSetHtml(patched)
+}
+
+// ---------------------------------------------------------------------------
+// Post-processing: convert text bindings to set:html
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert data-sk-field elements with simple {expression} content to use set:html.
+ * This enables rich text (formatting:true) to work automatically — HTML from the
+ * CMS editor is rendered as HTML, not escaped text.
+ *
+ * Matches: <tag ...data-sk-field...>{skData?.field}</tag>
+ * Result:  <tag ...data-sk-field... set:html={skData?.field}></tag>
+ */
+function convertToSetHtml(source: string): string {
+  const marker = 'data-sk-field'
+  let result = source
+  let searchFrom = 0
+
+  while (true) {
+    const idx = result.indexOf(marker, searchFrom)
+    if (idx === -1) break
+    searchFrom = idx + marker.length
+
+    // Find the > that closes this opening tag (respecting brace depth for template literals)
+    let tagEnd = -1
+    let braceDepth = 0
+    for (let i = idx; i < result.length; i++) {
+      const ch = result[i]!
+      if (ch === '{') braceDepth++
+      else if (ch === '}') braceDepth--
+      else if (ch === '>' && braceDepth === 0) { tagEnd = i; break }
+    }
+    if (tagEnd === -1) continue
+
+    // Skip if already has set:html before the >
+    const tagSection = result.slice(idx, tagEnd)
+    if (tagSection.includes('set:html')) continue
+
+    // Check inner content after >: must be just {expression} with optional whitespace
+    const afterTag = result.slice(tagEnd + 1)
+    const innerMatch = afterTag.match(/^(\s*)\{([^{}]+)\}(\s*)<\/(\w+)>/)
+    if (!innerMatch) continue
+
+    // Only convert CMS bindings (skData?.field or item.field)
+    const expr = innerMatch[2]!
+    if (!/^(?:skData\?\.\w+|item\.\w+)$/.test(expr)) continue
+
+    const fullInnerLength = innerMatch[0]!.length
+    const closeTag = `</${innerMatch[4]}>`
+
+    // Insert set:html before > and replace inner content with empty
+    const insertion = ` set:html={${expr}}>${closeTag}`
+    result = result.slice(0, tagEnd) + insertion + result.slice(tagEnd + 1 + fullInnerLength)
+    searchFrom = tagEnd + insertion.length
+  }
+
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// Byte → Char offset conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a mapping function from UTF-8 byte offsets to JS string char indices.
+ * @astrojs/compiler (Go/WASM) returns byte offsets; JS strings use UTF-16 code units.
+ */
+function buildByteToCharMap(source: string): (byteOffset: number) => number {
+  const buf = Buffer.from(source, 'utf-8')
+  if (buf.length === source.length) {
+    // All ASCII — offsets are identical
+    return (offset) => offset
+  }
+
+  // Build byte→char mapping array
+  const map = new Array<number>(buf.length + 1)
+  let byteIdx = 0
+  for (let charIdx = 0; charIdx < source.length; charIdx++) {
+    const codePoint = source.codePointAt(charIdx)!
+    const charByteLen = codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4
+    for (let b = 0; b < charByteLen; b++) {
+      map[byteIdx + b] = charIdx
+    }
+    byteIdx += charByteLen
+    // Skip surrogate pair's second code unit
+    if (codePoint > 0xffff) charIdx++
+  }
+  map[byteIdx] = source.length
+
+  return (offset) => {
+    if (offset <= 0) return 0
+    if (offset >= map.length) return source.length
+    return map[offset]!
+  }
+}
+
+/** Convert all AST node positions from byte offsets to char offsets in-place. */
+function convertAstPositions(node: AstNode, b2c: (offset: number) => number): void {
+  if (node.position?.start) {
+    node.position.start.offset = b2c(node.position.start.offset)
+  }
+  if (node.position?.end) {
+    node.position.end.offset = b2c(node.position.end.offset)
+  }
+  if (node.attributes) {
+    for (const attr of node.attributes) {
+      if (attr.position?.start) {
+        attr.position.start.offset = b2c(attr.position.start.offset)
+      }
+    }
+  }
+  if (node.children) {
+    for (const child of node.children) {
+      convertAstPositions(child, b2c)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Source-level position helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the actual {…} expression bounds in the source for an expression node.
+ * AST expression positions can extend beyond the actual braces, so we search
+ * the source directly using the child text content as anchor.
+ */
+function findExpressionBounds(source: string, node: AstNode): { start: number; end: number } | null {
+  const approxStart = node.position?.start?.offset
+  if (approxStart == null) return null
+
+  // Get the expression text from children
+  const exprText = (node.children ?? [])
+    .filter((c) => c.type === 'text')
+    .map((c) => c.value ?? '')
+    .join('')
+  if (!exprText) return null
+
+  // Search for the opening { near the AST position (within ±10 chars)
+  const searchStart = Math.max(0, approxStart - 10)
+  const searchEnd = Math.min(source.length, approxStart + 10)
+  let braceStart = -1
+  for (let i = searchStart; i < searchEnd; i++) {
+    if (source[i] === '{') {
+      // Verify this { leads to our expression content
+      const afterBrace = source.slice(i + 1, i + 1 + exprText.length + 5)
+      if (afterBrace.trimStart().startsWith(exprText.trimStart().slice(0, 20))) {
+        braceStart = i
+        break
+      }
+    }
+  }
+  if (braceStart === -1) return null
+
+  // Find matching closing }
+  let depth = 1
+  let inStr: string | null = null
+  for (let i = braceStart + 1; i < source.length; i++) {
+    const ch = source[i]!
+    if (inStr) {
+      if (ch === inStr && source[i - 1] !== '\\') inStr = null
+      continue
+    }
+    if (ch === "'" || ch === '"' || ch === '`') { inStr = ch; continue }
+    if (ch === '{') depth++
+    if (ch === '}') {
+      depth--
+      if (depth === 0) return { start: braceStart, end: i + 1 }
+    }
+  }
+  return null
+}
+
+/**
+ * Find the actual text content position in the source for a text node.
+ * AST text node positions can extend beyond the actual text into adjacent elements.
+ * We locate the text value by searching near the AST position.
+ */
+function findTextBounds(source: string, node: AstNode): { start: number; end: number } | null {
+  const value = node.value
+  if (!value) return null
+  const trimmed = value.trim()
+  if (!trimmed) return null
+
+  const approxStart = node.position?.start?.offset
+  if (approxStart == null) return null
+
+  // Search for the trimmed text near the AST position
+  const searchStart = Math.max(0, approxStart - 20)
+  const idx = source.indexOf(trimmed, searchStart)
+  if (idx === -1 || idx > approxStart + 50) return null
+
+  // Include surrounding whitespace up to parent element boundaries
+  let start = idx
+  while (start > 0 && /\s/.test(source[start - 1]!) && source[start - 1] !== '>') {
+    start--
+  }
+  let end = idx + trimmed.length
+  while (end < source.length && /\s/.test(source[end]!) && source[end] !== '<') {
+    end++
+  }
+
+  return { start, end }
+}
+
+// ---------------------------------------------------------------------------
+// Individual patching strategies
+// ---------------------------------------------------------------------------
+
+/** Recursively get all text content from an element (including child elements). */
+function getElementTextContent(node: AstNode): string {
+  if (node.type === 'text') return node.value ?? ''
+  if (node.type === 'expression') {
+    return (node.children ?? []).filter(c => c.type === 'text').map(c => c.value ?? '').join('')
+  }
+  return (node.children ?? []).map(getElementTextContent).join('')
+}
+
+/**
+ * Patch a mixed-content element as a rich text field.
+ * Adds data-sk-field + set:html to the element, keeping original HTML as fallback.
+ * The live editor uses the RTE (contentEditable) for this field.
+ */
+function patchMixedContentField(
+  source: string,
+  sectionKey: string,
+  field: PatchField,
+  varName: string,
+  element: AstNode,
+  edits: Edit[],
+): void {
+  const bindingKey = `${sectionKey}.${field.key}`
+
+  // Skip if already has data-sk-field
+  if (element.attributes?.some(a => a.name === 'data-sk-field')) return
+
+  // Find the element's opening tag in source
+  const startOffset = element.position?.start?.offset
+  if (startOffset == null) return
+  const tagName = element.name
+  if (!tagName) return
+
+  const searchStart = Math.max(0, startOffset - 10)
+  const tagPattern = `<${tagName}`
+  const tagIdx = source.indexOf(tagPattern, searchStart)
+  if (tagIdx === -1 || tagIdx > startOffset + 10) return
+
+  // Find > of opening tag
+  const openTagEnd = findOpeningTagEnd(source, tagIdx)
+  if (openTagEnd === -1) return
+
+  // Find closing tag
+  const endOffset = element.position?.end?.offset
+  if (endOffset == null) return
+  const closeTag = `</${tagName}>`
+  const closeIdx = source.lastIndexOf(closeTag, endOffset)
+  if (closeIdx === -1 || closeIdx <= openTagEnd) return
+
+  // Get original innerHTML for the fallback
+  const innerStart = openTagEnd + 1
+  const innerHTML = source.slice(innerStart, closeIdx).trim()
+  const escapedHTML = innerHTML.replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+
+  // Add data-sk-field + set:html attributes
+  edits.push({
+    offset: openTagEnd,
+    deleteCount: 0,
+    insert: ` data-sk-field="${bindingKey}" set:html={${varName}?.${field.key} ?? \`${escapedHTML}\`}`,
+  })
+
+  // Remove inner content (set:html replaces it at render time)
+  edits.push({
+    offset: innerStart,
+    deleteCount: closeIdx - innerStart,
+    insert: '',
+  })
+}
+
+function patchCmsBoundField(
+  source: string,
+  sectionKey: string,
+  field: PatchField,
+  cmsExpr: { node: AstNode; parent: AstNode },
+  edits: Edit[],
+): void {
+  const bindingKey = `${sectionKey}.${field.key}`
+  const parentEl = cmsExpr.parent
+
+  // Check if parent already has data-sk-field
+  if (isElement(parentEl) && parentEl.attributes) {
+    for (const attr of parentEl.attributes) {
+      if (attr.name === 'data-sk-field') return
+    }
+
+    // If parent has only this expression + whitespace as children, add attr to parent
+    const meaningfulChildren = (parentEl.children ?? []).filter(
+      (c) => !(c.type === 'text' && !c.value?.trim()),
+    )
+    if (meaningfulChildren.length === 1 && meaningfulChildren[0] === cmsExpr.node) {
+      addAttributeToElement(source, parentEl, `data-sk-field="${bindingKey}"`, edits)
+      return
+    }
+  }
+
+  // Wrap expression in <span data-sk-field="...">
+  // Use source-level search to find actual {…} bounds (AST positions are unreliable)
+  const bounds = findExpressionBounds(source, cmsExpr.node)
+  if (!bounds) return
+
+  const exprSource = source.slice(bounds.start, bounds.end)
+  edits.push({
+    offset: bounds.start,
+    deleteCount: bounds.end - bounds.start,
+    insert: `<span data-sk-field="${bindingKey}">${exprSource}</span>`,
+  })
+}
+
+function patchTextField(
+  source: string,
+  sectionKey: string,
+  field: PatchField,
+  varName: string,
+  textNodes: Array<{ node: AstNode; parent: AstNode }>,
+  edits: Edit[],
+): void {
+  const defaultValue = field.defaultValue as string
+  const bindingKey = `${sectionKey}.${field.key}`
+  const cmsExpr = `{${varName}?.${field.key}}`
+
+  // Find ALL text nodes matching this field's default value (whitespace-normalized comparison).
+  // Multiple nodes can share the same value (e.g. h1 + breadcrumb span both showing "Architektur").
+  // All of them should be bound to the same CMS field.
+  const normalizedDefault = normalizeWs(defaultValue)
+  const matches = textNodes.filter((t) => normalizeWs(t.node.value ?? '') === normalizedDefault)
+  if (matches.length === 0) return
+
+  for (const match of matches) {
+    const textNode = match.node
+    const parentEl = match.parent
+
+    // Use source-level search to find actual text bounds
+    const bounds = findTextBounds(source, textNode)
+    if (!bounds) continue
+    const { start, end } = bounds
+
+    // Skip if this offset is already covered by a previous edit in this batch
+    if (edits.some((e) => e.offset === start)) continue
+
+    // Check if text is sole meaningful content of parent element
+    if (isElement(parentEl)) {
+      const meaningfulChildren = (parentEl.children ?? []).filter(
+        (c) => !(c.type === 'text' && !c.value?.trim()),
+      )
+      const isSoleContent = meaningfulChildren.length === 1 && meaningfulChildren[0] === textNode
+
+      if (isSoleContent) {
+        // Check parent doesn't already have data-sk-field
+        const hasBinding = parentEl.attributes?.some((a) => a.name === 'data-sk-field')
+        if (!hasBinding) {
+          addAttributeToElement(source, parentEl, `data-sk-field="${bindingKey}"`, edits)
+        }
+        // Replace text content with CMS expression (preserve surrounding whitespace)
+        const originalText = source.slice(start, end)
+        const leadingWs = originalText.match(/^(\s*)/)?.[1] ?? ''
+        const trailingWs = originalText.match(/(\s*)$/)?.[1] ?? ''
+        edits.push({
+          offset: start,
+          deleteCount: end - start,
+          insert: `${leadingWs}${cmsExpr}${trailingWs}`,
+        })
+        continue
+      }
+    }
+
+    // Mixed content: wrap text in <span data-sk-field="...">
+    const originalText = source.slice(start, end)
+    const leadingWs = originalText.match(/^(\s*)/)?.[1] ?? ''
+    const trailingWs = originalText.match(/(\s*)$/)?.[1] ?? ''
+    edits.push({
+      offset: start,
+      deleteCount: end - start,
+      insert: `${leadingWs}<span data-sk-field="${bindingKey}">${cmsExpr}</span>${trailingWs}`,
+    })
+  }
+}
+
+/**
+ * Replace a frontmatter variable expression {varName} with a CMS expression
+ * {skData?.fieldKey ?? 'defaultValue'} and add data-sk-field to the parent.
+ */
+function patchVarExpression(
+  source: string,
+  sectionKey: string,
+  field: PatchField,
+  cmsVarName: string,
+  varExpr: { node: AstNode; parent: AstNode },
+  edits: Edit[],
+): void {
+  const bindingKey = `${sectionKey}.${field.key}`
+  const bounds = findExpressionBounds(source, varExpr.node)
+  if (!bounds) return
+
+  // Build CMS expression (no fallback — CMS is the source of truth)
+  const cmsExpr = `{${cmsVarName}?.${field.key}}`
+
+  const parentEl = varExpr.parent
+
+  // If parent element has only this expression as meaningful content, add data-sk-field to parent
+  if (isElement(parentEl)) {
+    const meaningfulChildren = (parentEl.children ?? []).filter(
+      (c) => !(c.type === 'text' && !c.value?.trim()),
+    )
+    if (meaningfulChildren.length === 1 && meaningfulChildren[0] === varExpr.node) {
+      const hasBinding = parentEl.attributes?.some((a) => a.name === 'data-sk-field')
+      if (!hasBinding) {
+        addAttributeToElement(source, parentEl, `data-sk-field="${bindingKey}"`, edits)
+      }
+      edits.push({ offset: bounds.start, deleteCount: bounds.end - bounds.start, insert: cmsExpr })
+      return
+    }
+  }
+
+  // Mixed content: wrap in <span data-sk-field>
+  edits.push({
+    offset: bounds.start,
+    deleteCount: bounds.end - bounds.start,
+    insert: `<span data-sk-field="${bindingKey}">${cmsExpr}</span>`,
+  })
+}
+
+function patchHrefField(
+  source: string,
+  _sectionKey: string,
+  field: PatchField,
+  varName: string,
+  hrefMatch: { attr: AstAttr; element: AstNode },
+  edits: Edit[],
+): void {
+  const attr = hrefMatch.attr
+  const approxStart = attr.position?.start?.offset
+  if (approxStart == null) return
+
+  const rawAttr = attr.raw ?? `"${attr.value}"`
+  // Find the full href="..." in the source near the attribute position
+  const hrefStr = `href=${rawAttr}`
+  const searchStart = Math.max(0, approxStart - 20)
+  const actualOffset = source.indexOf(hrefStr, searchStart)
+  if (actualOffset === -1) return
+
+  edits.push({
+    offset: actualOffset,
+    deleteCount: hrefStr.length,
+    insert: `href={${varName}?.${field.key}}`,
+  })
+}
+
+function patchArrayField(
+  source: string,
+  sectionKey: string,
+  field: PatchField,
+  varName: string,
+  mapExpressions: Array<{ node: AstNode }>,
+  edits: Edit[],
+): void {
+  if (mapExpressions.length === 0) return
+
+  // Find the .map() expression that belongs to this field's data.
+  // With multiple inline arrays (e.g. packages + design-principles), always using
+  // mapExpressions[0] causes overlapping edits that corrupt both arrays.
+  // Match by looking for the field's first item value inside each expression's source.
+  let mapExpr = mapExpressions[0]!
+
+  if (mapExpressions.length > 1 && Array.isArray(field.defaultValue) && field.defaultValue.length > 0) {
+    const firstItem = field.defaultValue[0]
+    const searchStr = typeof firstItem === 'string'
+      ? firstItem.slice(0, 30)
+      : typeof firstItem === 'object' && firstItem !== null
+        ? Object.values(firstItem as Record<string, unknown>)
+            .find((v): v is string => typeof v === 'string' && v.length >= 3)
+            ?.slice(0, 30) ?? ''
+        : ''
+
+    if (searchStr.length >= 3) {
+      for (const expr of mapExpressions) {
+        const exprBounds = findExpressionBounds(source, expr.node)
+        if (!exprBounds) continue
+        const exprSrc = source.slice(exprBounds.start, exprBounds.end)
+        if (exprSrc.includes(searchStr)) {
+          mapExpr = expr
+          break
+        }
+      }
+    }
+  }
+
+  // Find actual expression bounds in source
+  const bounds = findExpressionBounds(source, mapExpr.node)
+  if (!bounds) return
+
+  const exprSource = source.slice(bounds.start, bounds.end)
+
+  // Parse callback parameters from .map((param) => or .map((param, index) =>
+  const mapParamRegex = /\.map\s*\(\s*\(?\s*(\w+)(\s*,\s*(\w+))?\s*\)?/
+  const paramMatch = exprSource.match(mapParamRegex)
+  if (!paramMatch) return
+
+  const itemParam = paramMatch[1]!
+  let indexParam = paramMatch[3]
+
+  // Add index parameter if missing
+  if (!indexParam) {
+    indexParam = '_i'
+    // Find the callback signature in the source and add index param
+    const sigRegex = new RegExp(`\\.map\\s*\\(\\s*\\(?\\s*${itemParam}(\\s*\\)?)`)
+    const sigMatch = exprSource.match(sigRegex)
+    if (sigMatch) {
+      const sigOffset = bounds.start + exprSource.indexOf(sigMatch[0])
+      const insertPoint = sigOffset + sigMatch[0].length - (sigMatch[1]?.length ?? 0)
+      edits.push({
+        offset: insertPoint,
+        deleteCount: 0,
+        insert: `, ${indexParam}`,
+      })
+    }
+  }
+
+  // Replace the array source with CMS variable (empty array fallback for .map() safety)
+  // Case 1: Inline array literal — ['a', 'b'].map(… → (var?.field ?? []).map(…
+  // Case 2: Variable reference — testimonials.map(… → (var?.field ?? []).map(…
+  const arrayAndMapRegex = /(\[[\s\S]*?\])\s*\.map\s*\(/
+  const arrayMatch = exprSource.match(arrayAndMapRegex)
+  if (arrayMatch) {
+    const arrayLiteral = arrayMatch[1]!
+    const arrayStartInExpr = exprSource.indexOf(arrayLiteral)
+    const arrayEndInExpr = arrayStartInExpr + arrayLiteral.length
+    const arrayStart = bounds.start + arrayStartInExpr
+    const arrayEnd = bounds.start + arrayEndInExpr
+
+    edits.push({
+      offset: arrayStart,
+      deleteCount: arrayEnd - arrayStart,
+      insert: `(${varName}?.${field.key} ?? [])`,
+    })
+  } else {
+    // Try variable reference: varName.map( → (cmsVar?.field ?? []).map(
+    const varMapRegex = new RegExp(`(\\w+)\\.map\\s*\\(`)
+    const varMapMatch = exprSource.match(varMapRegex)
+    if (varMapMatch) {
+      const varRef = varMapMatch[1]!
+      const varStartInExpr = exprSource.indexOf(varMapMatch[0])
+      const varEndInExpr = varStartInExpr + varRef.length
+      const varStart = bounds.start + varStartInExpr
+      const varEnd = bounds.start + varEndInExpr
+
+      edits.push({
+        offset: varStart,
+        deleteCount: varEnd - varStart,
+        insert: `(${varName}?.${field.key} ?? [])`,
+      })
+    }
+  }
+
+  // Find first child element inside the .map() expression and add data-sk-field
+  const firstChildElement = findFirstChildElement(mapExpr.node)
+  if (firstChildElement) {
+    const hasSkField = firstChildElement.attributes?.some((a) => a.name === 'data-sk-field')
+    if (!hasSkField) {
+      const skFieldExpr = `data-sk-field={\`${sectionKey}.${field.key}.\${${indexParam}}\`}`
+      addAttributeToElement(source, firstChildElement, skFieldExpr, edits)
+    }
+  }
+
+  // Add data-sk-field to inner elements that reference item properties (e.g. {t.quote})
+  // This enables live DOM patching for individual fields within array items.
+  patchArrayItemProperties(source, sectionKey, field, itemParam, indexParam, mapExpr.node, edits)
+}
+
+/**
+ * Convert a static <ul>/<ol> with hardcoded <li> items into a CMS-driven .map() loop.
+ * Matches the <ul> by comparing its <li> text content against field.defaultValue.
+ * Replaces all <li> children with a single {(...).map()} expression.
+ */
+function patchStaticListField(
+  source: string,
+  sectionKey: string,
+  field: PatchField,
+  varName: string,
+  ast: AstNode,
+  edits: Edit[],
+): void {
+  if (!Array.isArray(field.defaultValue) || field.defaultValue.length === 0) return
+  const items = field.defaultValue as string[]
+
+  // Find the <ul>/<ol> whose static <li> texts exactly match the field's defaultValue
+  let matchedUl: AstNode | null = null
+  walkAst(ast, (node) => {
+    if (matchedUl) return
+    if (node.type !== 'element') return
+    if (node.name !== 'ul' && node.name !== 'ol') return
+    // Skip if already has .map() inside
+    let hasMap = false
+    walkAst(node, (n) => {
+      if (hasMap) return
+      if (n.type === 'expression') {
+        const code = (n.children ?? []).map(c => c.value ?? '').join('')
+        if (/\.map\s*\(/.test(code)) hasMap = true
+      }
+    })
+    if (hasMap) return
+    // Compare <li> text content against field items.
+    // items[i] may contain HTML (if formatting: true) — strip tags for comparison.
+    const stripHtml = (s: string) => s.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim()
+    const liChildren = (node.children ?? []).filter(c => c.type === 'element' && c.name === 'li')
+    if (liChildren.length !== items.length) return
+    const allMatch = liChildren.every((li, i) => {
+      const text = getElementTextContent(li).replace(/\s+/g, ' ').trim()
+      return text === stripHtml(items[i]!)
+    })
+    if (allMatch) matchedUl = node
+  })
+
+  if (!matchedUl) return
+
+  const ulNode = matchedUl as AstNode
+  const liChildren = (ulNode.children ?? []).filter(
+    c => c.type === 'element' && c.name === 'li',
+  ) as AstNode[]
+  if (liChildren.length === 0) return
+
+  const firstLi = liChildren[0]!
+  const lastLi = liChildren[liChildren.length - 1]!
+  const rangeStart = firstLi.position?.start?.offset
+  const rangeEnd = lastLi.position?.end?.offset
+  if (rangeStart == null || rangeEnd == null) return
+
+  // Build the <li> template from the first <li>'s source
+  const firstLiEnd = firstLi.position?.end?.offset ?? rangeEnd
+  let liTemplate = source.slice(rangeStart, firstLiEnd)
+
+  // Add data-sk-field to the <li> opening tag (before the first `>`)
+  const liTagEnd = liTemplate.indexOf('>')
+  if (liTagEnd === -1) return
+  const bindingKey = `${sectionKey}.${field.key}`
+  liTemplate =
+    liTemplate.slice(0, liTagEnd) +
+    ` data-sk-field={\`${bindingKey}.\${_i}\`}>` +
+    liTemplate.slice(liTagEnd + 1)
+
+  // Replace the content span with set:html={item}.
+  // Handles both plain-text spans and spans with nested elements (<strong>, <em>, etc.).
+  // Bullet-dot spans (empty content) are left untouched.
+  liTemplate = liTemplate.replace(
+    /<span([^>]*)>([\s\S]*?)<\/span>/g,
+    (_m, attrs: string, content: string) => {
+      // Skip empty spans (bullet dots) and spans with CMS attributes already
+      if (!content.trim()) return _m
+      if (attrs.includes('set:html') || attrs.includes('data-sk-field')) return _m
+      return `<span${attrs} set:html={item}></span>`
+    },
+  )
+
+  // Build the fallback array literal.
+  // HTML items (formatting: true) are wrapped in backtick strings to avoid escaping issues.
+  const hasHtmlItems = items.some(s => /<[a-z]/.test(s))
+  const fallbackItems = hasHtmlItems
+    ? items.map(s => `\`${s.replace(/`/g, '\\`').replace(/\$/g, '\\$')}\``).join(', ')
+    : items.map(s => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`).join(', ')
+
+  // Determine indentation of the first <li> for formatting
+  const textBeforeFirstLi = source.slice(0, rangeStart)
+  const lastNewline = textBeforeFirstLi.lastIndexOf('\n')
+  const indent = lastNewline >= 0 ? textBeforeFirstLi.slice(lastNewline + 1).match(/^[ \t]*/)?.[0] ?? '' : ''
+
+  const replacement =
+    `{(${varName}?.${field.key} ?? [${fallbackItems}]).map((item, _i) => (\n` +
+    `${indent}${liTemplate}\n` +
+    `${indent}))}`
+
+  edits.push({
+    offset: rangeStart,
+    deleteCount: rangeEnd - rangeStart,
+    insert: replacement,
+  })
+}
+
+/**
+ * Walk the children of a .map() expression and add data-sk-field attributes
+ * to elements that contain property access expressions like {t.quote}.
+ * This enables live DOM patching for individual fields within array items.
+ */
+function patchArrayItemProperties(
+  source: string,
+  sectionKey: string,
+  field: PatchField,
+  itemParam: string,
+  indexParam: string,
+  mapNode: AstNode,
+  edits: Edit[],
+): void {
+  // Walk all nodes inside the .map() expression
+  walkAst(mapNode, (node, parent) => {
+    if (!parent || node.type !== 'expression' || !node.children) return
+
+    // Get expression text
+    const exprText = node.children
+      .filter((c) => c.type === 'text')
+      .map((c) => c.value ?? '')
+      .join('')
+      .trim()
+
+    // Check for nested .map() call: e.g. {section.items.map((item) => ...)}
+    // These need separate handling to add _j index + inner data-sk-field bindings.
+    const nestedMapMatch = exprText.match(new RegExp(`^${itemParam}\\.(\\w+)\\.map\\s*\\(`))
+    if (nestedMapMatch) {
+      const innerFieldKey = nestedMapMatch[1]!
+      patchNestedMap(source, sectionKey, field.key, innerFieldKey, indexParam, node, edits)
+      return
+    }
+
+    // Match property access: itemParam.propName or itemParam.nested.prop
+    // e.g. t.quote, t.author, t.address.street
+    const propMatch = exprText.match(new RegExp(`^${itemParam}\\.(\\w+(?:\\.\\w+)*)$`))
+    if (!propMatch) return
+
+    const propPath = propMatch[1]!
+    const bindingKey = `${sectionKey}.${field.key}.\${${indexParam}}.${propPath}`
+
+    // Check if parent element already has data-sk-field
+    if (!isElement(parent) || !parent.attributes) return
+    if (parent.attributes.some((a) => a.name === 'data-sk-field')) return
+
+    // If parent has only this expression (+ whitespace) as content, add attr to parent
+    const meaningfulChildren = (parent.children ?? []).filter(
+      (c) => !(c.type === 'text' && !c.value?.trim()),
+    )
+    if (meaningfulChildren.length === 1 && meaningfulChildren[0] === node) {
+      const skFieldExpr = `data-sk-field={\`${bindingKey}\`}`
+      addAttributeToElement(source, parent, skFieldExpr, edits)
+      return
+    }
+
+    // Mixed content: wrap expression in <span data-sk-field>
+    const bounds = findExpressionBounds(source, node)
+    if (!bounds) return
+    const exprSource = source.slice(bounds.start, bounds.end)
+    edits.push({
+      offset: bounds.start,
+      deleteCount: bounds.end - bounds.start,
+      insert: `<span data-sk-field={\`${bindingKey}\`}>${exprSource}</span>`,
+    })
+  })
+}
+
+/**
+ * Patch a nested .map() call inside an outer array map.
+ * Handles patterns like: {section.items.map((item) => (<a>...</a>))}
+ *
+ * Adds:
+ *   - _j index parameter to the inner .map() callback
+ *   - data-sk-field container binding on the first child element
+ *   - data-sk-field bindings on individual inner field elements
+ *
+ * Path format: sectionKey.outerField.${_i}.innerField.${_j}.propName
+ */
+function patchNestedMap(
+  source: string,
+  sectionKey: string,
+  outerFieldKey: string,
+  innerFieldKey: string,
+  outerIndexParam: string,
+  exprNode: AstNode,
+  edits: Edit[],
+): void {
+  const bounds = findExpressionBounds(source, exprNode)
+  if (!bounds) return
+  const exprSrc = source.slice(bounds.start, bounds.end)
+
+  // Parse inner .map() callback parameter
+  const mapParamRegex = /\.map\s*\(\s*\(?\s*(\w+)(\s*,\s*(\w+))?\s*\)?/
+  const paramMatch = exprSrc.match(mapParamRegex)
+  if (!paramMatch) return
+
+  const innerItemParam = paramMatch[1]!
+  let innerIndexParam = paramMatch[3]
+
+  // Add _j index if missing
+  if (!innerIndexParam) {
+    innerIndexParam = '_j'
+    const sigRegex = new RegExp(`\\.map\\s*\\(\\s*\\(?\\s*${innerItemParam}(\\s*\\)?)`)
+    const sigMatch = exprSrc.match(sigRegex)
+    if (sigMatch) {
+      const insertOffset =
+        bounds.start +
+        exprSrc.indexOf(sigMatch[0]) +
+        sigMatch[0].length -
+        (sigMatch[1]?.length ?? 0)
+      edits.push({ offset: insertOffset, deleteCount: 0, insert: `, ${innerIndexParam}` })
+    }
+  }
+
+  // Base path for inner item bindings
+  const basePath = `${sectionKey}.${outerFieldKey}.\${${outerIndexParam}}.${innerFieldKey}.\${${innerIndexParam}}`
+
+  // Add container data-sk-field to the first child element of the inner map
+  const firstChild = findFirstChildElement(exprNode)
+  if (firstChild) {
+    const hasSkField = firstChild.attributes?.some((a) => a.name === 'data-sk-field')
+    if (!hasSkField) {
+      addAttributeToElement(source, firstChild, `data-sk-field={\`${basePath}\`}`, edits)
+    }
+  }
+
+  // Walk inner map content and add data-sk-field to individual field elements
+  walkAst(exprNode, (node, parent) => {
+    if (!parent || node.type !== 'expression' || !node.children) return
+
+    const exprText = node.children
+      .filter((c) => c.type === 'text')
+      .map((c) => c.value ?? '')
+      .join('')
+      .trim()
+
+    const propMatch = exprText.match(new RegExp(`^${innerItemParam}\\.(\\w+(?:\\.\\w+)*)$`))
+    if (!propMatch) return
+
+    const propPath = propMatch[1]!
+    const bindingKey = `${basePath}.${propPath}`
+
+    if (!isElement(parent) || !parent.attributes) return
+    if (parent.attributes.some((a) => a.name === 'data-sk-field')) return
+
+    const meaningfulChildren = (parent.children ?? []).filter(
+      (c) => !(c.type === 'text' && !c.value?.trim()),
+    )
+    if (meaningfulChildren.length === 1 && meaningfulChildren[0] === node) {
+      addAttributeToElement(source, parent, `data-sk-field={\`${bindingKey}\`}`, edits)
+      return
+    }
+
+    // Mixed content: wrap the expression in a span with data-sk-field
+    const nodeBounds = findExpressionBounds(source, node)
+    if (!nodeBounds) return
+    const nodeSrc = source.slice(nodeBounds.start, nodeBounds.end)
+    edits.push({
+      offset: nodeBounds.start,
+      deleteCount: nodeBounds.end - nodeBounds.start,
+      insert: `<span data-sk-field={\`${bindingKey}\`}>${nodeSrc}</span>`,
+    })
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Repeated element group patching
+// ---------------------------------------------------------------------------
+
+/**
+ * Collapse repeated HTML elements (e.g. 3× <article>) into a single .map() loop.
+ *
+ * Uses pre-computed RepeatedGroup data from the analyzer — no own detection.
+ * For each group:
+ *   1. Extract template instance source (instance 0)
+ *   2. Replace inner field values with {item.fieldKey}
+ *   3. Rewrite nested .map() sources (e.g. starterFeatures → item.list)
+ *   4. Wrap optional fields in conditional rendering
+ *   5. Make differing CSS classes dynamic (item._classN)
+ *   6. Wrap in .map() with data-sk-field binding
+ *   7. Delete instances 1..N
+ */
+
+/**
+ * Detect CSS classes that differ between instances and collect edits.
+ * Uses AST-based classAttrs (collected by the analyzer) to match elements
+ * across instances by structural path. Adds edits to the innerEdits array
+ * so they're applied together with text edits in reverse order.
+ */
+function collectDynamicClassEdits(
+  innerEdits: Array<{ offset: number; deleteCount: number; insert: string }>,
+  source: string,
+  instances: Array<{ start: number; end: number }>,
+  tmpl: { start: number; end: number },
+  group: RepeatedGroup,
+): void {
+  const classAttrs = group.classAttrs
+  if (!classAttrs || classAttrs.length < 2 || instances.length < 2) return
+
+  const tmplAttrs = classAttrs[0]! // class attrs of template instance (instance 0)
+  if (tmplAttrs.length === 0) return
+
+  // Build lookup structures for each non-template instance
+  const otherInstAttrs = classAttrs.slice(1)
+
+  /** Find the best matching class attr in another instance for a given template attr.
+   *  All strategies validate with CSS overlap to handle optional elements
+   *  that shift positional indices (e.g. badge wrapper in Pro pricing card).
+   *
+   *  Key insight: a correct match ALWAYS shares at least 1 CSS class.
+   *  Zero overlap means the path matched a structurally different element
+   *  (an optional element shifted indices).
+   *
+   *  1. Exact path match — only if at least 1 shared class
+   *  2. Same tag-path (without indices) — pick best CSS overlap among candidates
+   *  If neither matches, the element doesn't exist in this instance → null (use template default)
+   */
+  function findMatch(
+    tmplAttr: { path: string; value: string },
+    instAttrs: Array<{ path: string; value: string }>,
+    claimed: Set<number>,
+  ): string | null {
+    const tmplParts = new Set(tmplAttr.value.split(/\s+/).filter(Boolean))
+
+    function sharedClassCount(instValue: string): number {
+      const instParts = new Set(instValue.split(/\s+/).filter(Boolean))
+      if (tmplParts.size === 0 && instParts.size === 0) return 1 // both empty = match
+      return [...tmplParts].filter(p => instParts.has(p)).length
+    }
+
+    // 1. Exact path — only accept if at least 1 CSS class is shared
+    for (let i = 0; i < instAttrs.length; i++) {
+      if (!claimed.has(i) && instAttrs[i]!.path === tmplAttr.path) {
+        if (sharedClassCount(instAttrs[i]!.value) > 0) {
+          claimed.add(i)
+          return instAttrs[i]!.value
+        }
+      }
+    }
+
+    // 2. Same tag-path (without indices) — pick the one with most shared classes
+    const stripIdx = (p: string) => p.split('/').map(s => s.replace(/:\d+$/, '')).join('/')
+    const tmplTagPath = stripIdx(tmplAttr.path)
+    let bestIdx = -1
+    let bestShared = 0
+    for (let i = 0; i < instAttrs.length; i++) {
+      if (claimed.has(i)) continue
+      if (stripIdx(instAttrs[i]!.path) !== tmplTagPath) continue
+      const shared = sharedClassCount(instAttrs[i]!.value)
+      if (shared > bestShared) { bestShared = shared; bestIdx = i }
+    }
+    if (bestIdx >= 0 && bestShared > 0) {
+      claimed.add(bestIdx)
+      return instAttrs[bestIdx]!.value
+    }
+
+    // No cross-tag fallback: if exact-path and tag-path don't match, the element
+    // likely doesn't exist in this instance (e.g. optional "/ Monat" span missing
+    // in Business). Return null → caller uses template value as default.
+    return null
+  }
+
+  // Build skip map: for each template class attr, which non-template instances
+  // should skip matching because the attr's element corresponds to an optional
+  // field that is missing in that instance.
+  // Without this, findMatch greedily grabs a wrong class attr (e.g. the description
+  // class for the missing "/ Monat" span), causing a cascade of misassignments.
+  const skipForInstance: Array<Set<number>> = tmplAttrs.map(() => new Set())
+  for (const field of group.fields) {
+    if (field.required) continue
+    const tmplPos = field.positions[0]
+    if (!tmplPos) continue // field not in template (injected from other instance)
+
+    // Find the template class attr on the same element as this field.
+    // Match by leaf tag (path ending) + smallest absolute distance.
+    // We can't rely on "class attr before text" because byte-to-char offset
+    // adjustments can put the class attr offset slightly after the text offset.
+    const fieldTag = field.tag
+    let bestAttrIdx = -1
+    let bestDist = Infinity
+    for (let ai = 0; ai < tmplAttrs.length; ai++) {
+      // Extract leaf tag from path: "div:0/div:0/span:1" → "span"
+      const pathParts = tmplAttrs[ai]!.path.split('/')
+      const leafTag = (pathParts[pathParts.length - 1] ?? '').replace(/:\d+$/, '')
+      // Root element (path="") has no leaf tag — skip unless field tag matches group tag
+      if (!leafTag && fieldTag !== group.tag) continue
+      if (leafTag && leafTag !== fieldTag) continue
+
+      const dist = Math.abs(tmplPos.offset - tmplAttrs[ai]!.sourceOffset)
+      if (dist < bestDist) {
+        bestDist = dist
+        bestAttrIdx = ai
+      }
+    }
+    if (bestAttrIdx < 0) continue
+
+    // For each non-template instance where this field is missing, skip matching
+    for (let instIdx = 1; instIdx < instances.length; instIdx++) {
+      if (!field.positions[instIdx]) {
+        skipForInstance[bestAttrIdx]!.add(instIdx - 1) // ii = instIdx - 1
+      }
+    }
+  }
+
+  // Find which template class attrs differ across instances
+  // Claimed sets track which instance attrs have already been matched (one per instance)
+  const claimedPerInstance = otherInstAttrs.map(() => new Set<number>())
+  let dynamicCount = 0
+
+  for (let ai = 0; ai < tmplAttrs.length; ai++) {
+    const tmplAttr = tmplAttrs[ai]!
+    const values: string[] = [tmplAttr.value]
+    let anyDiffers = false
+
+    for (let ii = 0; ii < otherInstAttrs.length; ii++) {
+      // Skip matching for instances where the optional field is missing
+      if (skipForInstance[ai]!.has(ii)) {
+        values.push(tmplAttr.value)
+        continue
+      }
+      const match = findMatch(tmplAttr, otherInstAttrs[ii]!, claimedPerInstance[ii]!)
+      if (match == null) {
+        values.push(tmplAttr.value)
+      } else {
+        values.push(match)
+        if (match !== tmplAttr.value) anyDiffers = true
+      }
+    }
+
+    if (!anyDiffers) continue
+
+    const relOffset = tmplAttr.sourceOffset - tmpl.start
+    if (relOffset < 0) continue
+
+    const fieldKey = `_class${dynamicCount++}`
+
+    group.fields.push({
+      key: fieldKey,
+      type: 'text',
+      tag: 'class',
+      required: true,
+      positions: instances.map(() => null),
+      defaultValues: values,
+    })
+
+    innerEdits.push({
+      offset: relOffset,
+      deleteCount: tmplAttr.sourceLength,
+      insert: `class={item.${fieldKey}}`,
+    })
+  }
+}
+
+function patchRepeatedGroups(
+  source: string,
+  sectionKey: string,
+  varName: string,
+  groups: RepeatedGroup[],
+): Edit[] {
+  const edits: Edit[] = []
+
+  for (const group of groups) {
+    const { tag, fieldKey, instances, fields } = group
+    if (instances.length < 2) continue
+
+    // Template instance = first one
+    const tmpl = instances[0]!
+    let templateSrc = source.slice(tmpl.start, tmpl.end)
+
+    // Apply inner field replacements to the template source.
+    // Work in reverse offset order (relative to template start) to keep positions stable.
+    const innerEdits: Array<{ offset: number; deleteCount: number; insert: string }> = []
+
+    // Add dynamic class replacements as inner edits (all edits applied together in reverse order)
+    collectDynamicClassEdits(innerEdits, source, instances, tmpl, group)
+
+    for (const field of fields) {
+      const pos = field.positions[0] // position in template instance
+      if (!pos) continue // field not present in template instance (optional, only in other instances)
+
+      const relOffset = pos.offset - tmpl.start
+      if (relOffset < 0 || relOffset >= templateSrc.length) continue
+
+      if (field.type === 'array' && pos.source) {
+        // Nested .map(): replace variable name with item.fieldKey
+        // e.g. "starterFeatures.map(" → "(item.list ?? []).map("
+        const mapPattern = `${pos.source}.map(`
+        const mapIdx = templateSrc.indexOf(mapPattern)
+        if (mapIdx !== -1) {
+          innerEdits.push({
+            offset: mapIdx,
+            deleteCount: mapPattern.length,
+            insert: `(item.${field.key} ?? []).map(`,
+          })
+        }
+      } else if (field.type === 'link') {
+        // Replace href value: href="/signup" → href={item.link}
+        const fieldSrc = templateSrc.slice(relOffset, relOffset + pos.length)
+        const hrefMatch = fieldSrc.match(/href\s*=\s*"([^"]*)"/)
+        if (hrefMatch) {
+          const hrefStart = relOffset + fieldSrc.indexOf(hrefMatch[0])
+          innerEdits.push({
+            offset: hrefStart,
+            deleteCount: hrefMatch[0].length,
+            insert: `href={item.${field.key}}`,
+          })
+        }
+      } else if (field.type === 'text') {
+        // Replace text content with {item.fieldKey} (whitespace-normalized search)
+        const defaultVal = field.defaultValues[0]
+        if (typeof defaultVal === 'string' && defaultVal.length >= 1) {
+          const searchFrom = relOffset > 10 ? relOffset - 10 : 0
+          const found = findNormalizedText(templateSrc, defaultVal, searchFrom)
+          if (found) {
+            innerEdits.push({
+              offset: found.start,
+              deleteCount: found.end - found.start,
+              insert: `{item.${field.key}}`,
+            })
+          }
+        }
+      }
+    }
+
+    // Handle optional fields: fields present in OTHER instances but not in template.
+    // These need to be injected into the template with conditional rendering.
+    for (const field of fields) {
+      if (field.required) continue
+      const pos = field.positions[0]
+      if (pos) continue // present in template, already handled above
+
+      // Find the first instance that HAS this field to get its source
+      let donorIdx = -1
+      let donorPos = null
+      for (let i = 1; i < instances.length; i++) {
+        if (field.positions[i]) {
+          donorIdx = i
+          donorPos = field.positions[i]!
+          break
+        }
+      }
+      if (!donorPos || donorIdx < 0) continue
+
+      // Extract the element source from the donor instance
+      const donorInst = instances[donorIdx]!
+      const donorSrc = source.slice(donorInst.start, donorInst.end)
+      const donorRelOffset = donorPos.offset - donorInst.start
+      let elementSrc = donorSrc.slice(donorRelOffset, donorRelOffset + donorPos.length)
+
+      // Check if the element has a parent wrapper that only exists in this donor
+      // (e.g. <div class="absolute -top-4 ..."> around a badge <span>).
+      // If so, include the wrapper in the conditional to preserve positioning.
+      const templateSrcForCheck = source.slice(tmpl.start, tmpl.end)
+      const beforeElement = donorSrc.slice(0, donorRelOffset).trimEnd()
+      const parentCloseMatch = beforeElement.match(/<(\w+)\s+[^>]*class="([^"]*)"[^>]*>\s*$/)
+      if (parentCloseMatch) {
+        const parentTag = parentCloseMatch[1]!
+        const parentClass = parentCloseMatch[2]!
+        // Check if this parent class exists in the template instance
+        if (!templateSrcForCheck.includes(`class="${parentClass}"`)) {
+          // Find the parent's opening tag start and its closing tag
+          const parentStart = beforeElement.lastIndexOf(`<${parentTag}`)
+          if (parentStart >= 0) {
+            const closingTag = `</${parentTag}>`
+            const afterElement = donorSrc.slice(donorRelOffset + donorPos.length)
+            const closingIdx = afterElement.indexOf(closingTag)
+            if (closingIdx >= 0) {
+              // Expand elementSrc to include parent wrapper
+              const wrapperEnd = donorRelOffset + donorPos.length + closingIdx + closingTag.length
+              elementSrc = donorSrc.slice(parentStart, wrapperEnd).trim()
+            }
+          }
+        }
+      }
+
+      // Replace content with item reference (whitespace-normalized search)
+      const defaultVal = field.defaultValues[donorIdx]
+      if (typeof defaultVal === 'string' && defaultVal.length >= 1) {
+        const found = findNormalizedText(elementSrc, defaultVal, 0)
+        if (found) {
+          elementSrc = elementSrc.slice(0, found.start) + `{item.${field.key}}` + elementSrc.slice(found.end)
+        }
+      }
+
+      // Wrap in conditional: {item.fieldKey && <element>...</element>}
+      const conditionalBlock = `{item.${field.key} && ${elementSrc}}`
+
+      // Insert after the opening tag of the template instance
+      const openTagEnd = templateSrc.indexOf('>', 0) + 1
+      if (openTagEnd > 0) {
+        innerEdits.push({
+          offset: openTagEnd,
+          deleteCount: 0,
+          insert: `\n        ${conditionalBlock}`,
+        })
+      }
+    }
+
+    // Apply inner edits in reverse order
+    innerEdits.sort((a, b) => b.offset - a.offset)
+    for (const edit of innerEdits) {
+      templateSrc = templateSrc.slice(0, edit.offset) + edit.insert + templateSrc.slice(edit.offset + edit.deleteCount)
+    }
+
+    // Add data-sk-field to the template element's opening tag (container binding)
+    const tagEndIdx = templateSrc.indexOf('>')
+    if (tagEndIdx !== -1) {
+      const skFieldAttr = ` data-sk-field={\`${sectionKey}.${fieldKey}.\${_i}\`}`
+      templateSrc = templateSrc.slice(0, tagEndIdx) + skFieldAttr + templateSrc.slice(tagEndIdx)
+    }
+
+    // Add data-sk-field to inner field elements (individual field bindings)
+    templateSrc = addInnerFieldBindings(templateSrc, sectionKey, fieldKey, fields)
+
+    // Wrap in .map()
+    const indent = detectIndent(source, tmpl.start)
+    const wrapped = `{(${varName}?.${fieldKey} ?? []).map((item, _i) => (\n${indent}  ${templateSrc}\n${indent}))}`
+
+    // Edit 1: Replace template instance with wrapped .map()
+    edits.push({
+      offset: tmpl.start,
+      deleteCount: tmpl.end - tmpl.start,
+      insert: wrapped,
+    })
+
+    // Edit 2: Delete instances 1..N (in reverse order to maintain positions)
+    for (let i = instances.length - 1; i >= 1; i--) {
+      const inst = instances[i]!
+      // Also remove surrounding whitespace/newlines
+      let deleteStart = inst.start
+      let deleteEnd = inst.end
+      // Extend backwards to eat preceding whitespace
+      while (deleteStart > 0 && /\s/.test(source[deleteStart - 1]!) && source[deleteStart - 1] !== '\n') {
+        deleteStart--
+      }
+      // Eat the preceding newline too
+      if (deleteStart > 0 && source[deleteStart - 1] === '\n') deleteStart--
+      edits.push({
+        offset: deleteStart,
+        deleteCount: deleteEnd - deleteStart,
+        insert: '',
+      })
+    }
+  }
+
+  return edits
+}
+
+/**
+ * Add data-sk-field attributes to inner field elements within a repeated group template.
+ * Searches for {item.fieldKey} references and adds bindings to their enclosing HTML elements.
+ */
+function addInnerFieldBindings(
+  templateSrc: string,
+  sectionKey: string,
+  groupFieldKey: string,
+  fields: Array<{ key: string; type: string }>,
+): string {
+  const inserts: Array<{ offset: number; text: string }> = []
+
+  for (const field of fields) {
+    // Skip arrays (nested .map loops) and links (bound via href attribute)
+    if (field.type === 'array' || field.type === 'link') continue
+
+    const itemRef = `{item.${field.key}}`
+    const idx = templateSrc.indexOf(itemRef)
+    if (idx === -1) continue
+
+    // Search backwards from the expression to find the enclosing opening tag
+    let tagStart = idx - 1
+    while (tagStart >= 0 && templateSrc[tagStart] !== '<') tagStart--
+    if (tagStart < 0 || templateSrc[tagStart + 1] === '/') continue // closing tag
+
+    // Find the > that closes this opening tag (between tagStart and idx)
+    let tagEnd = -1
+    let inQ: string | null = null
+    let inE = 0
+    for (let i = tagStart; i < idx; i++) {
+      const ch = templateSrc[i]!
+      if (inQ) { if (ch === inQ && templateSrc[i - 1] !== '\\') inQ = null; continue }
+      if (ch === '{') { inE++; continue }
+      if (ch === '}' && inE > 0) { inE--; continue }
+      if (inE > 0) continue
+      if (ch === '"' || ch === "'") { inQ = ch; continue }
+      if (ch === '>') tagEnd = i
+    }
+    if (tagEnd === -1) continue
+
+    // Skip if this tag already has data-sk-field
+    const tagStr = templateSrc.slice(tagStart, tagEnd + 1)
+    if (tagStr.includes('data-sk-field')) continue
+
+    inserts.push({
+      offset: tagEnd,
+      text: ` data-sk-field={\`${sectionKey}.${groupFieldKey}.\${_i}.${field.key}\`}`,
+    })
+  }
+
+  // Apply inserts in reverse order to maintain positions
+  inserts.sort((a, b) => b.offset - a.offset)
+  for (const ins of inserts) {
+    templateSrc = templateSrc.slice(0, ins.offset) + ins.text + templateSrc.slice(ins.offset)
+  }
+
+  return templateSrc
+}
+
+/** Detect the indentation level at a given source offset. */
+function detectIndent(source: string, offset: number): string {
+  let lineStart = offset
+  while (lineStart > 0 && source[lineStart - 1] !== '\n') lineStart--
+  return source.slice(lineStart, offset)
+}
+
+// ---------------------------------------------------------------------------
+// Section ID patching
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure the first element in the template body has id="section-{sectionKey}".
+ * Finds the first <section>, <div>, or any root element after frontmatter and adds
+ * the id attribute if not already present.
+ */
+function patchSectionId(
+  source: string,
+  ast: AstNode,
+  sectionKey: string,
+  edits: Edit[],
+  options?: { mode?: 'component' | 'page' },
+): void {
+  const templateChildren = (ast.children ?? []).filter((c) => c.type !== 'frontmatter')
+
+  let rootElement: AstNode | null = null
+
+  if (options?.mode === 'page') {
+    // Page mode: top-level element is often an Astro component (e.g. <BaseLayout>).
+    // The preview middleware looks for <section> elements, so we need to find the
+    // first real HTML element — even if it's nested inside a component.
+    function findFirstHtmlElement(nodes: AstNode[]): AstNode | null {
+      for (const child of nodes) {
+        if (!isElement(child)) continue
+        // Lowercase name = HTML element (section, div, main, …)
+        if (child.name && /^[a-z]/.test(child.name)) return child
+        // Uppercase = Astro component — recurse into its children (slot content)
+        const inner = findFirstHtmlElement(child.children ?? [])
+        if (inner) return inner
+      }
+      return null
+    }
+    rootElement = findFirstHtmlElement(templateChildren)
+  } else {
+    for (const child of templateChildren) {
+      if (isElement(child)) {
+        rootElement = child
+        break
+      }
+    }
+  }
+
+  if (!rootElement) return
+
+  // Check if it already has an id attribute
+  const hasId = rootElement.attributes?.some((a) => a.name === 'id')
+  if (hasId) return
+
+  // Add id="section-{sectionKey}"
+  addAttributeToElement(source, rootElement, `id="section-${sectionKey}"`, edits)
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Extract the CMS data variable name from Astro frontmatter. */
+function extractVarName(frontmatter: string): string | null {
+  // const { data: varName } = Astro.props
+  const propsMatch = frontmatter.match(/const\s*\{\s*data\s*:\s*(\w+)\s*\}/)
+  if (propsMatch) return propsMatch[1]!
+
+  // const varName = getSection('key')
+  const getSectionMatch = frontmatter.match(/(?:const|let)\s+(\w+)\s*=.*getSection/)
+  if (getSectionMatch) return getSectionMatch[1]!
+
+  return null
+}
+
+/** Type guard for element-like nodes (element, component, custom-element). */
+function isElement(node: AstNode): node is AstNode & { attributes: AstAttr[]; children: AstNode[] } {
+  return (
+    (node.type === 'element' || node.type === 'component' || node.type === 'custom-element') &&
+    Array.isArray(node.attributes)
+  )
+}
+
+/** Recursive AST walk with parent tracking. */
+function walkAst(node: AstNode, callback: (node: AstNode, parent: AstNode | null) => void, parent: AstNode | null = null): void {
+  callback(node, parent)
+  if (node.children) {
+    for (const child of node.children) {
+      walkAst(child, callback, node)
+    }
+  }
+}
+
+/** Find the first element node among an expression's children (recursively). */
+function findFirstChildElement(node: AstNode): (AstNode & { attributes: AstAttr[] }) | null {
+  if (!node.children) return null
+  for (const child of node.children) {
+    if (isElement(child)) return child
+    const deeper = findFirstChildElement(child)
+    if (deeper) return deeper
+  }
+  return null
+}
+
+/**
+ * Add an attribute string to an element's opening tag.
+ * Inserts before the closing `>` of the opening tag.
+ * Uses the element's tag name to locate it reliably in the source.
+ */
+function addAttributeToElement(source: string, element: AstNode, attrStr: string, edits: Edit[]): void {
+  const approxStart = element.position?.start?.offset
+  if (approxStart == null) return
+
+  // Find the actual `<tagName` near the AST position
+  const tagName = element.name
+  if (!tagName) return
+  const searchStart = Math.max(0, approxStart - 10)
+  const tagPattern = `<${tagName}`
+  const tagIdx = source.indexOf(tagPattern, searchStart)
+  if (tagIdx === -1 || tagIdx > approxStart + 10) return
+
+  // Find the `>` that closes the opening tag
+  const insertOffset = findOpeningTagEnd(source, tagIdx)
+  if (insertOffset === -1) return
+
+  edits.push({
+    offset: insertOffset,
+    deleteCount: 0,
+    insert: ` ${attrStr}`,
+  })
+}
+
+/**
+ * Find the offset of the `>` that closes an opening tag.
+ * Handles quoted attribute values and expression attributes correctly.
+ */
+function findOpeningTagEnd(source: string, startOffset: number): number {
+  let inQuote: string | null = null
+  let inExpr = 0
+  for (let i = startOffset; i < source.length; i++) {
+    const ch = source[i]!
+    if (inQuote) {
+      if (ch === inQuote && source[i - 1] !== '\\') inQuote = null
+      continue
+    }
+    if (ch === '{') { inExpr++; continue }
+    if (ch === '}' && inExpr > 0) { inExpr--; continue }
+    if (inExpr > 0) continue
+    if (ch === '"' || ch === "'") { inQuote = ch; continue }
+    if (ch === '>') return i
+  }
+  return -1
+}
+
+/** Apply edits in reverse offset order to maintain position correctness. */
+function applyEdits(source: string, edits: Edit[]): string {
+  if (edits.length === 0) return source
+
+  // Sort by offset descending so later edits don't shift earlier offsets
+  const sorted = [...edits].sort((a, b) => b.offset - a.offset)
+
+  let result = source
+  for (const edit of sorted) {
+    result = result.slice(0, edit.offset) + edit.insert + result.slice(edit.offset + edit.deleteCount)
+  }
+  return result
+}
+
+/**
+ * Remove old frontmatter variable declarations that match CMS field keys.
+ * Called AFTER expression patching so that variable references have already
+ * been replaced with CMS expressions.
+ */
+function removeOldVarDeclarations(source: string, fields: PatchField[], repeatedGroups?: RepeatedGroup[], cmsVarName = 'skData'): string {
+  const fmStart = source.indexOf('---')
+  if (fmStart === -1) return source
+  const fmEnd = source.indexOf('---', fmStart + 3)
+  if (fmEnd === -1) return source
+
+  let frontmatter = source.slice(fmStart + 4, fmEnd) // after "---\n", before closing "---"
+  const fieldKeys = new Set(fields.map((f) => f.key))
+
+  // Also remove frontmatter variables that were inner array sources in repeated groups
+  // (e.g. starterFeatures, proFeatures, businessFeatures → replaced by item.list)
+  if (repeatedGroups) {
+    for (const g of repeatedGroups) {
+      for (const f of g.fields) {
+        for (const pos of f.positions) {
+          if (pos?.source) fieldKeys.add(pos.source)
+        }
+      }
+    }
+  }
+
+  // Collect all ranges to remove (relative to frontmatter string)
+  const removals: Array<{ start: number; end: number }> = []
+  // Aliases that must be appended AFTER the cmsVarName (= skData) declaration to avoid TDZ
+  const aliases: string[] = []
+
+  const templatePart = source.slice(fmEnd + 3)
+
+  for (const key of fieldKeys) {
+    const varDeclRegex = new RegExp(`(?:const|let)\\s+${key}\\s*=\\s*`)
+    const declMatch = varDeclRegex.exec(frontmatter)
+    if (!declMatch) continue
+
+    // Never remove exported declarations (e.g. "export const prerender = true")
+    const lineStart = frontmatter.lastIndexOf('\n', declMatch.index) + 1
+    const linePrefix = frontmatter.slice(lineStart, declMatch.index).trim()
+    if (linePrefix === 'export') continue
+
+    const declStart = declMatch.index
+    const afterEquals = declStart + declMatch[0].length
+    const rhsRaw = frontmatter.slice(afterEquals)
+    const leadingWs = rhsRaw.length - rhsRaw.trimStart().length
+    const rhs = rhsRaw.trimStart()
+
+    let valueEnd: number // relative to afterEquals + leadingWs
+    if (rhs.startsWith('[') || rhs.startsWith('{')) {
+      // Multi-line: find matching bracket (handle strings to avoid false matches)
+      const open = rhs[0]!
+      const close = open === '[' ? ']' : '}'
+      let depth = 1
+      let inStr: string | null = null
+      let i = 1
+      for (; i < rhs.length && depth > 0; i++) {
+        const ch = rhs[i]!
+        if (inStr) {
+          if (ch === inStr && rhs[i - 1] !== '\\') inStr = null
+          continue
+        }
+        if (ch === "'" || ch === '"' || ch === '`') { inStr = ch; continue }
+        if (ch === open) depth++
+        if (ch === close) depth--
+      }
+      valueEnd = i
+    } else {
+      // Single-line: find end of line
+      const lineEnd = rhs.indexOf('\n')
+      valueEnd = lineEnd === -1 ? rhs.length : lineEnd
+    }
+
+    let end = afterEquals + leadingWs + valueEnd
+    // Include trailing semicolon + newline (e.g. "];\n" — the "]" is covered by valueEnd,
+    // but ";" and "\n" were previously left behind, causing stray ";" in the output)
+    if (end < frontmatter.length && frontmatter[end] === ';') end++
+    if (end < frontmatter.length && frontmatter[end] === '\n') end++
+
+    // If the template still references this variable (e.g. {fields.length}), add a
+    // CMS alias at the END of the frontmatter (after cmsVarName is defined) to avoid TDZ.
+    const stillReferenced = new RegExp(`\\b${key}[.([\\[]`).test(templatePart)
+    if (stillReferenced) {
+      aliases.push(`const ${key} = ${cmsVarName}?.${key} ?? []`)
+    }
+
+    removals.push({ start: declStart, end })
+  }
+
+  if (removals.length === 0) return source
+
+  // Apply removals in reverse order to preserve positions
+  removals.sort((a, b) => b.start - a.start)
+  for (const { start, end } of removals) {
+    frontmatter = frontmatter.slice(0, start) + frontmatter.slice(end)
+  }
+
+  // Append aliases after existing declarations (cmsVarName is already at end)
+  if (aliases.length > 0) {
+    frontmatter = frontmatter.trimEnd() + '\n' + aliases.join('\n') + '\n'
+  }
+
+  // Clean up: remove multiple consecutive blank lines
+  frontmatter = frontmatter.replace(/\n{3,}/g, '\n\n')
+
+  return source.slice(0, fmStart + 4) + frontmatter + source.slice(fmEnd)
+}
+
+// ---------------------------------------------------------------------------
+// stripTemplateFallbacks
+//
+// Removes ?? 'fallback' expressions from already-adopted templates where
+// content should live in the JSON file, not the template.
+//
+// Two patterns are handled:
+//   1. set:html={varName?.field ?? 'value'}          → set:html={varName?.field}
+//      set:html={varName?.field ?? `multi\nline`}    → set:html={varName?.field}
+//   2. (varName?.items ?? ['a', 'b']).map(           → (varName?.items ?? []).map(
+//
+// Returns the cleaned source and a map of fieldKey → extracted value.
+// The caller decides which values to write to JSON:
+//   - If the JSON already has a value for that field → just strip (JSON wins)
+//   - If the JSON has no value → use the extracted fallback
+// ---------------------------------------------------------------------------
+export function stripTemplateFallbacks(source: string): {
+  source: string
+  fallbacks: Record<string, unknown>
+} {
+  const fallbacks: Record<string, unknown> = {}
+  let result = source
+
+  // Pattern 1: set:html={varName?.fieldKey ?? `...`} or '...' or "..."
+  // The template literal variant may span multiple lines.
+  result = result.replace(
+    /set:html=\{(\w+)\?\.(\w+)\s*\?\?\s*(?:`([\s\S]*?)`|'([^']*)'|"([^"]*)")\}/g,
+    (_match, varName, fieldKey, tq, sq, dq) => {
+      const value = (tq ?? sq ?? dq ?? '').trim()
+      fallbacks[fieldKey] = value
+      return `set:html={${varName}?.${fieldKey}}`
+    },
+  )
+
+  // Pattern 2: (varName?.fieldKey ?? ['item1', `item2`, ...]).map(
+  // Items can be single-quoted, double-quoted, or backtick strings.
+  result = result.replace(
+    /\((\w+)\?\.(\w+)\s*\?\?\s*\[([^\]]*)\]\)\.map\(/gs,
+    (_match, varName, fieldKey, itemsRaw) => {
+      const items: string[] = []
+      const itemRe = /`([^`]*)`|'([^']*)'|"([^"]*)"/g
+      let m: RegExpExecArray | null
+      while ((m = itemRe.exec(itemsRaw)) !== null) {
+        items.push(m[1] ?? m[2] ?? m[3] ?? '')
+      }
+      if (items.length > 0) fallbacks[fieldKey] = items
+      return `(${varName}?.${fieldKey} ?? []).map(`
+    },
+  )
+
+  return { source: result, fallbacks }
+}