@nuasite/cms 0.7.3 → 0.8.2

package/src/editor/signals.ts

@@ -27,6 +27,7 @@ import type {
 	MediaItem,
 	MediaLibraryState,
 	PendingAttributeChange,
+	PendingBackgroundImageChange,
 	PendingChange,
 	PendingColorChange,
 	PendingComponentInsert,
@@ -231,6 +232,9 @@ export const pendingImageChanges = signal<Map<string, PendingImageChange>>(
 export const pendingColorChanges = signal<Map<string, PendingColorChange>>(
 	new Map(),
 )
+export const pendingBgImageChanges = signal<Map<string, PendingBackgroundImageChange>>(
+	new Map(),
+)
 export const manifest = signal<CmsManifest>({
 	entries: {},
 	components: {},
@@ -252,6 +256,7 @@ const _pendingComponentChangesHelpers = createMapHelpers(pendingComponentChanges
 const _pendingInsertsHelpers = createMapHelpers(pendingInserts)
 const _pendingImageChangesHelpers = createMapHelpers(pendingImageChanges)
 const _pendingColorChangesHelpers = createMapHelpers(pendingColorChanges)
+const _pendingBgImageChangesHelpers = createMapHelpers(pendingBgImageChanges)
 
 // ============================================================================
 // AI State Signals
@@ -491,13 +496,37 @@ let toastIdCounter = 0
 // Computed Values - Dirty Tracking
 // ============================================================================
 
+/** All change categories that participate in dirty tracking.
+ *  Adding a new category forces a TypeScript error until it's added to changeRegistry. */
+type ChangeCategory = 'text' | 'image' | 'color' | 'bgImage' | 'seo' | 'attribute'
+
+interface ChangeRegistryEntry {
+	mapSignal: Signal<Map<string, any>>
+	dirtyCount: ReturnType<typeof computed<number>>
+	hasDirty: ReturnType<typeof computed<boolean>>
+}
+
 // Use factory for dirty tracking to reduce duplication
 const _pendingChangesDirty = createDirtyTracking(pendingChanges)
 const _pendingImageChangesDirty = createDirtyTracking(pendingImageChanges)
 const _pendingColorChangesDirty = createDirtyTracking(pendingColorChanges)
+const _pendingBgImageChangesDirty = createDirtyTracking(pendingBgImageChanges)
 const _pendingSeoChangesDirty = createDirtyTracking(pendingSeoChanges)
 const _pendingAttributeChangesDirty = createDirtyTracking(pendingAttributeChanges)
 
+export const changeRegistry: Record<ChangeCategory, ChangeRegistryEntry> = {
+	text: { mapSignal: pendingChanges, dirtyCount: _pendingChangesDirty.dirtyCount, hasDirty: _pendingChangesDirty.hasDirty },
+	image: { mapSignal: pendingImageChanges, dirtyCount: _pendingImageChangesDirty.dirtyCount, hasDirty: _pendingImageChangesDirty.hasDirty },
+	color: { mapSignal: pendingColorChanges, dirtyCount: _pendingColorChangesDirty.dirtyCount, hasDirty: _pendingColorChangesDirty.hasDirty },
+	bgImage: { mapSignal: pendingBgImageChanges, dirtyCount: _pendingBgImageChangesDirty.dirtyCount, hasDirty: _pendingBgImageChangesDirty.hasDirty },
+	seo: { mapSignal: pendingSeoChanges, dirtyCount: _pendingSeoChangesDirty.dirtyCount, hasDirty: _pendingSeoChangesDirty.hasDirty },
+	attribute: {
+		mapSignal: pendingAttributeChanges,
+		dirtyCount: _pendingAttributeChangesDirty.dirtyCount,
+		hasDirty: _pendingAttributeChangesDirty.hasDirty,
+	},
+}
+
 export const dirtyChangesCount = _pendingChangesDirty.dirtyCount
 export const dirtyChanges = _pendingChangesDirty.dirtyItems
 export const hasDirtyChanges = _pendingChangesDirty.hasDirty
@@ -510,6 +539,10 @@ export const dirtyColorChangesCount = _pendingColorChangesDirty.dirtyCount
 export const dirtyColorChanges = _pendingColorChangesDirty.dirtyItems
 export const hasDirtyColorChanges = _pendingColorChangesDirty.hasDirty
 
+export const dirtyBgImageChangesCount = _pendingBgImageChangesDirty.dirtyCount
+export const dirtyBgImageChanges = _pendingBgImageChangesDirty.dirtyItems
+export const hasDirtyBgImageChanges = _pendingBgImageChangesDirty.hasDirty
+
 export const dirtySeoChangesCount = _pendingSeoChangesDirty.dirtyCount
 export const dirtySeoChanges = _pendingSeoChangesDirty.dirtyItems
 export const hasDirtySeoChanges = _pendingSeoChangesDirty.hasDirty
@@ -518,16 +551,11 @@ export const dirtyAttributeChangesCount = _pendingAttributeChangesDirty.dirtyCou
 export const dirtyAttributeChanges = _pendingAttributeChangesDirty.dirtyItems
 export const hasDirtyAttributeChanges = _pendingAttributeChangesDirty.hasDirty
 
-export const totalDirtyCount = computed(
-	() =>
-		dirtyChangesCount.value + dirtyImageChangesCount.value + dirtyColorChangesCount.value + dirtySeoChangesCount.value
-		+ dirtyAttributeChangesCount.value,
-)
+const _registryEntries = Object.values(changeRegistry)
 
-export const hasAnyDirtyChanges = computed(
-	() =>
-		hasDirtyChanges.value || hasDirtyImageChanges.value || hasDirtyColorChanges.value || hasDirtySeoChanges.value || hasDirtyAttributeChanges.value,
-)
+export const totalDirtyCount = computed(() => _registryEntries.reduce((sum, entry) => sum + entry.dirtyCount.value, 0))
+
+export const hasAnyDirtyChanges = computed(() => _registryEntries.some((entry) => entry.hasDirty.value))
 
 // Navigation index for cycling through dirty elements
 export const changeNavigationIndex = signal<number>(0)
@@ -615,6 +643,13 @@ export const deletePendingColorChange = _pendingColorChangesHelpers.delete
 export const clearPendingColorChanges = _pendingColorChangesHelpers.clear
 export const getPendingColorChange = _pendingColorChangesHelpers.get
 
+// Background image changes mutations - using helpers
+export const setPendingBgImageChange = _pendingBgImageChangesHelpers.set
+export const updatePendingBgImageChange = _pendingBgImageChangesHelpers.update
+export const deletePendingBgImageChange = _pendingBgImageChangesHelpers.delete
+export const clearPendingBgImageChanges = _pendingBgImageChangesHelpers.clear
+export const getPendingBgImageChange = _pendingBgImageChangesHelpers.get
+
 // SEO changes mutations - using helpers
 export const setPendingSeoChange = _pendingSeoChangesHelpers.set
 export const updatePendingSeoChange = _pendingSeoChangesHelpers.update
@@ -1327,13 +1362,12 @@ export function resetAllState(): void {
 		showingOriginal.value = false
 		currentEditingId.value = null
 		currentComponentId.value = null
-		pendingChanges.value = new Map()
+		for (const entry of Object.values(changeRegistry)) {
+			entry.mapSignal.value = new Map()
+		}
+		// Non-dirty-tracked maps still cleared individually
 		pendingComponentChanges.value = new Map()
 		pendingInserts.value = new Map()
-		pendingImageChanges.value = new Map()
-		pendingColorChanges.value = new Map()
-		pendingSeoChanges.value = new Map()
-		pendingAttributeChanges.value = new Map()
 		manifest.value = { entries: {}, components: {}, componentDefinitions: {} }
 		aiState.value = createInitialAIState()
 		blockEditorState.value = createInitialBlockEditorState()

package/src/editor/storage.ts

@@ -2,10 +2,12 @@ import { STORAGE_KEYS } from './constants'
 import type {
 	CmsSettings,
 	PendingAttributeChange,
+	PendingBackgroundImageChange,
 	PendingChange,
 	PendingColorChange,
 	PendingImageChange,
 	SavedAttributeEdits,
+	SavedBackgroundImageEdits,
 	SavedColorEdits,
 	SavedEdits,
 	SavedImageEdits,
@@ -180,6 +182,53 @@ export function clearAttributeEditsFromStorage(): void {
 	}
 }
 
+// ============================================================================
+// Background Image Edits
+// ============================================================================
+
+export function saveBgImageEditsToStorage(pendingBgImageChanges: Map<string, PendingBackgroundImageChange>): void {
+	const edits: SavedBackgroundImageEdits = {}
+
+	pendingBgImageChanges.forEach((change, cmsId) => {
+		if (change.isDirty) {
+			edits[cmsId] = {
+				originalBgImageClass: change.originalBgImageClass,
+				newBgImageClass: change.newBgImageClass,
+				originalBgSize: change.originalBgSize,
+				newBgSize: change.newBgSize,
+				originalBgPosition: change.originalBgPosition,
+				newBgPosition: change.newBgPosition,
+				originalBgRepeat: change.originalBgRepeat,
+				newBgRepeat: change.newBgRepeat,
+			}
+		}
+	})
+
+	try {
+		sessionStorage.setItem(STORAGE_KEYS.PENDING_BG_IMAGE_EDITS, JSON.stringify(edits))
+	} catch (e) {
+		console.warn('[CMS] Failed to save bg image edits to storage:', e)
+	}
+}
+
+export function loadBgImageEditsFromStorage(): SavedBackgroundImageEdits {
+	try {
+		const stored = sessionStorage.getItem(STORAGE_KEYS.PENDING_BG_IMAGE_EDITS)
+		return stored ? JSON.parse(stored) : {}
+	} catch (e) {
+		console.warn('[CMS] Failed to load bg image edits from storage:', e)
+		return {}
+	}
+}
+
+export function clearBgImageEditsFromStorage(): void {
+	try {
+		sessionStorage.removeItem(STORAGE_KEYS.PENDING_BG_IMAGE_EDITS)
+	} catch (e) {
+		console.warn('[CMS] Failed to clear bg image edits from storage:', e)
+	}
+}
+
 // ============================================================================
 // Settings
 // ============================================================================
@@ -287,4 +336,5 @@ export function clearAllEditsFromStorage(): void {
 	clearImageEditsFromStorage()
 	clearColorEditsFromStorage()
 	clearAttributeEditsFromStorage()
+	clearBgImageEditsFromStorage()
 }

package/src/editor/types.ts

@@ -5,6 +5,7 @@ export type {
 	Attribute,
 	AvailableColors,
 	AvailableTextStyles,
+	BackgroundImageMetadata,
 	CanonicalUrl,
 	CmsManifest,
 	CollectionDefinition,
@@ -94,6 +95,28 @@ export interface PendingColorChange {
 	isDirty: boolean
 }
 
+export interface PendingBackgroundImageChange {
+	element: HTMLElement
+	cmsId: string
+	/** Original bg-[url()] class */
+	originalBgImageClass: string
+	/** Current bg-[url()] class */
+	newBgImageClass: string
+	/** Original bg-size class (or empty) */
+	originalBgSize: string
+	/** Current bg-size class */
+	newBgSize: string
+	/** Original bg-position class (or empty) */
+	originalBgPosition: string
+	/** Current bg-position class */
+	newBgPosition: string
+	/** Original bg-repeat class (or empty) */
+	originalBgRepeat: string
+	/** Current bg-repeat class */
+	newBgRepeat: string
+	isDirty: boolean
+}
+
 export interface ColorEditorState {
 	isOpen: boolean
 	targetElementId: string | null
@@ -132,14 +155,42 @@ export interface SavedColorEdits {
 	[cmsId: string]: SavedColorEdit
 }
 
-/** Color change details for updating element color classes */
-export interface ColorChangePayload {
-	/** The color class to replace (e.g., 'bg-blue-500') */
+export interface SavedBackgroundImageEdit {
+	originalBgImageClass: string
+	newBgImageClass: string
+	originalBgSize: string
+	newBgSize: string
+	originalBgPosition: string
+	newBgPosition: string
+	originalBgRepeat: string
+	newBgRepeat: string
+}
+
+export interface SavedBackgroundImageEdits {
+	[cmsId: string]: SavedBackgroundImageEdit
+}
+
+/** Style change details for updating element classes (colors, text styles, bg images) */
+export interface StyleChangePayload {
+	/** The class to replace (e.g., 'bg-blue-500') */
 	oldClass: string
-	/** The new color class (e.g., 'bg-red-500') */
+	/** The new class (e.g., 'bg-red-500') */
 	newClass: string
-	/** Type of color/style change */
-	type: 'bg' | 'text' | 'border' | 'hoverBg' | 'hoverText' | 'fontWeight' | 'fontStyle' | 'textDecoration' | 'fontSize'
+	/** Type of style change */
+	type:
+		| 'bg'
+		| 'text'
+		| 'border'
+		| 'hoverBg'
+		| 'hoverText'
+		| 'fontWeight'
+		| 'fontStyle'
+		| 'textDecoration'
+		| 'fontSize'
+		| 'bgImage'
+		| 'bgSize'
+		| 'bgPosition'
+		| 'bgRepeat'
 	/** Path to the source file where the color class is defined */
 	sourcePath?: string
 	/** Line number where the color class is defined */
@@ -169,8 +220,8 @@ export interface ChangePayload {
 		newSrc: string
 		newAlt?: string
 	}
-	/** Color class change (for buttons, etc.) */
-	colorChange?: ColorChangePayload
+	/** Style class change (colors, text styles, bg images) */
+	styleChange?: StyleChangePayload
 	/** Attribute changes (for links, forms, etc.) */
 	attributeChanges?: AttributeChangePayload[]
 }
@@ -579,12 +630,32 @@ export interface UndoSeoAction {
 	wasDirty: boolean
 }
 
+export interface UndoBgImageAction {
+	type: 'bgImage'
+	cmsId: string
+	element: HTMLElement
+	previousClassName: string
+	currentClassName: string
+	previousStyleCssText: string
+	currentStyleCssText: string
+	previousBgImageClass: string
+	currentBgImageClass: string
+	previousBgSize: string
+	currentBgSize: string
+	previousBgPosition: string
+	currentBgPosition: string
+	previousBgRepeat: string
+	currentBgRepeat: string
+	wasDirty: boolean
+}
+
 export type UndoAction =
 	| UndoTextAction
 	| UndoImageAction
 	| UndoColorAction
 	| UndoAttributeAction
 	| UndoSeoAction
+	| UndoBgImageAction
 
 declare global {
 	interface Window {

package/src/handlers/source-writer.ts

@@ -1,53 +1,11 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import { getProjectRoot } from '../config'
+import type { AttributeChangePayload, ChangePayload, SaveBatchRequest } from '../editor/types'
 import type { ManifestWriter } from '../manifest-writer'
 import type { CmsManifest, ManifestEntry } from '../types'
 import { acquireFileLock, escapeReplacement, normalizePagePath, resolveAndValidatePath } from '../utils'
 
-export interface ColorChangePayload {
-	oldClass: string
-	newClass: string
-	type: 'bg' | 'text' | 'border' | 'hoverBg' | 'hoverText' | 'fontWeight' | 'fontStyle' | 'textDecoration' | 'fontSize'
-	sourcePath?: string
-	sourceLine?: number
-	sourceSnippet?: string
-}
-
-export interface ImageChangePayload {
-	newSrc: string
-	newAlt: string
-}
-
-export interface AttributeChangePayload {
-	attributeName: string
-	oldValue: string | undefined
-	newValue: string | undefined
-	sourcePath?: string
-	sourceLine?: number
-	sourceSnippet?: string
-}
-
-export interface ChangePayload {
-	cmsId: string
-	newValue: string
-	originalValue: string
-	sourcePath: string
-	sourceLine: number
-	sourceSnippet: string
-	htmlValue?: string
-	childCmsIds?: string[]
-	hasStyledContent?: boolean
-	colorChange?: ColorChangePayload
-	imageChange?: ImageChangePayload
-	attributeChanges?: AttributeChangePayload[]
-}
-
-export interface SaveBatchRequest {
-	changes: ChangePayload[]
-	meta: { source: string; url: string }
-}
-
 export interface SaveBatchResponse {
 	updated: number
 	errors?: Array<{ cmsId: string; error: string }>
@@ -157,8 +115,8 @@ function applyChanges(
 			continue
 		}
 
-		// Handle color class changes
-		if (change.colorChange) {
+		// Handle style class changes (colors, text styles, bg images)
+		if (change.styleChange) {
 			const result = applyColorChange(newContent, change)
 			if (result.success) {
 				newContent = result.content
@@ -323,10 +281,10 @@ function applyColorChange(
 	content: string,
 	change: ChangePayload,
 ): { success: true; content: string } | { success: false; error: string } {
-	const { oldClass, newClass } = change.colorChange!
-	// Prefer colorChange's own sourceLine (points to the class attribute)
+	const { oldClass, newClass } = change.styleChange!
+	// Prefer styleChange's own sourceLine (points to the class attribute)
 	// over the outer change.sourceLine (may point to a data declaration)
-	const sourceLine = change.colorChange!.sourceLine ?? change.sourceLine
+	const sourceLine = change.styleChange!.sourceLine ?? change.sourceLine
 
 	// When oldClass is empty, we're adding a new color class (not replacing)
 	if (!oldClass) {
@@ -346,10 +304,12 @@ function replaceClassInAttribute(
 	newClass: string,
 	sourceLine?: number,
 ): { success: true; content: string } | { success: false; error: string } {
-	const classAttrPattern = /(class\s*=\s*)(["'])([^"']*)\2/
-
 	const replaceOnLine = (line: string): string | null => {
-		const match = line.match(classAttrPattern)
+		// Build pattern dynamically to only exclude the actual quote character used,
+		// so bg-[url('/path')] works inside class="..." (single quotes allowed in double-quoted attr)
+		const dqMatch = line.match(/(class\s*=\s*)(")([^"]*)"/)
+		const sqMatch = line.match(/(class\s*=\s*)(')([^']*)'/)
+		const match = dqMatch || sqMatch
 		if (!match) return null
 
 		const prefix = match[1]!
@@ -365,7 +325,7 @@ function replaceClassInAttribute(
 		} else {
 			classes.splice(idx, 1)
 		}
-		return line.replace(classAttrPattern, `${prefix}${quote}${classes.join(' ')}${quote}`)
+		return line.replace(match[0], `${prefix}${quote}${classes.join(' ')}${quote}`)
 	}
 
 	if (sourceLine) {
@@ -403,12 +363,23 @@ function appendClassToAttribute(
 	newClass: string,
 	sourceLine?: number,
 ): { success: true; content: string } | { success: false; error: string } {
-	const appendPattern = /(class\s*=\s*["'])([^"']*)(["'])/
+	// Match class attribute with either quote, only excluding the actual quote used
+	// so bg-[url('/path')] works inside class="..."
+	const matchClassAttr = (line: string) => {
+		return line.match(/(class\s*=\s*")(([^"]*))(")/)
+			|| line.match(/(class\s*=\s*')(([^']*))(')/)
+	}
 
-	const doAppend = (_: string, open: string, classes: string, close: string) => {
+	const doAppendOnLine = (line: string): string | null => {
+		const match = matchClassAttr(line)
+		if (!match) return null
+		const open = match[1]!
+		const classes = match[2]!
+		const close = match[4]!
 		const trimmed = classes.trimEnd()
 		const separator = trimmed ? ' ' : ''
-		return `${open}${trimmed}${separator}${escapeReplacement(newClass)}${close}`
+		const replacement = `${open}${trimmed}${separator}${escapeReplacement(newClass)}${close}`
+		return line.replace(match[0], replacement)
 	}
 
 	if (sourceLine) {
@@ -416,9 +387,9 @@ function appendClassToAttribute(
 		const lineIndex = sourceLine - 1
 
 		if (lineIndex >= 0 && lineIndex < lines.length) {
-			const line = lines[lineIndex]!
-			if (appendPattern.test(line)) {
-				lines[lineIndex] = line.replace(appendPattern, doAppend)
+			const result = doAppendOnLine(lines[lineIndex]!)
+			if (result !== null) {
+				lines[lineIndex] = result
 				return { success: true, content: lines.join('\n') }
 			}
 			return { success: false, error: `No class attribute found on line ${sourceLine}` }
@@ -426,10 +397,13 @@ function appendClassToAttribute(
 		return { success: false, error: `Invalid source line ${sourceLine}` }
 	}
 
-	if (appendPattern.test(content)) {
-		return {
-			success: true,
-			content: content.replace(appendPattern, doAppend),
+	// Fallback: find the first class attribute in the content
+	const lines = content.split('\n')
+	for (let i = 0; i < lines.length; i++) {
+		const result = doAppendOnLine(lines[i]!)
+		if (result !== null) {
+			lines[i] = result
+			return { success: true, content: lines.join('\n') }
 		}
 	}
 	return { success: false, error: 'No class attribute found in source file' }
@@ -520,7 +494,7 @@ function applyAttributeChanges(
 	return { content: newContent, appliedCount: attrApplied, failedChanges }
 }
 
-function applyTextChange(
+export function applyTextChange(
 	content: string,
 	change: ChangePayload,
 	manifest: CmsManifest,
@@ -530,7 +504,14 @@ function applyTextChange(
 	let newText = htmlValue ?? newValue
 	newText = resolveCmsPlaceholders(newText, manifest)
 
-	if (!sourceSnippet || !originalValue) {
+	// Resolve CMS placeholders in originalValue too — when a parent element has
+	// child CMS elements, originalValue contains {{cms:cms-N}} placeholders but
+	// the sourceSnippet contains the actual HTML for those children.
+	const resolvedOriginal = originalValue
+		? resolveCmsPlaceholders(originalValue, manifest)
+		: originalValue
+
+	if (!sourceSnippet || !resolvedOriginal) {
 		if (change.attributeChanges && change.attributeChanges.length > 0) {
 			return { success: true, content }
 		}
@@ -541,19 +522,30 @@ function applyTextChange(
 		return { success: false, error: 'Source snippet not found in file' }
 	}
 
-	// Replace originalValue with newText WITHIN the sourceSnippet
-	const updatedSnippet = sourceSnippet.replace(originalValue, newText)
+	// Replace resolvedOriginal with newText WITHIN the sourceSnippet
+	const updatedSnippet = sourceSnippet.replace(resolvedOriginal, newText)
 
 	if (updatedSnippet === sourceSnippet) {
-		// originalValue wasn't found in snippet - try HTML entity handling
-		const matchedText = findTextInSnippet(sourceSnippet, originalValue)
+		// resolvedOriginal wasn't found in snippet - try HTML entity handling
+		const matchedText = findTextInSnippet(sourceSnippet, resolvedOriginal)
 		if (matchedText) {
 			const updatedWithEntity = sourceSnippet.replace(matchedText, newText)
 			return { success: true, content: content.replace(sourceSnippet, updatedWithEntity) }
 		}
+		// Try inner content replacement for text spanning inline HTML elements
+		// (e.g., <h3>text part 1 <span class="...">text part 2</span></h3>)
+		const innerMatch = sourceSnippet.match(/^(\s*<(\w+)\b[^>]*>)([\s\S]*)(<\/\2>\s*)$/)
+		if (innerMatch) {
+			const [, openTag, , innerContent, closeTag] = innerMatch
+			const textOnly = innerContent!.replace(/<[^>]+>/g, '')
+			if (textOnly === resolvedOriginal) {
+				return { success: true, content: content.replace(sourceSnippet, openTag + newText + closeTag) }
+			}
+		}
+
 		return {
 			success: false,
-			error: `Original text "${originalValue.substring(0, 50)}..." not found in source snippet`,
+			error: `Original text "${resolvedOriginal.substring(0, 50)}..." not found in source snippet`,
 		}
 	}
 

package/src/html-processor.ts

@@ -1,8 +1,8 @@
 import { type HTMLElement as ParsedHTMLElement, parse } from 'node-html-parser'
 import { processSeoFromHtml } from './seo-processor'
 import { enhanceManifestWithSourceSnippets } from './source-finder'
-import { extractColorClasses, extractTextStyleClasses } from './tailwind-colors'
-import type { Attribute, ComponentInstance, ImageMetadata, ManifestEntry, PageSeoData, SeoOptions } from './types'
+import { extractBackgroundImageClasses, extractColorClasses, extractTextStyleClasses } from './tailwind-colors'
+import type { Attribute, BackgroundImageMetadata, ComponentInstance, ImageMetadata, ManifestEntry, PageSeoData, SeoOptions } from './types'
 import { generateStableId } from './utils'
 
 /** Type for parsed HTML element nodes from node-html-parser */
@@ -612,6 +612,68 @@ export async function processHtml(
 		})
 	})
 
+	// Background image detection pass: mark elements with bg-[url()] classes
+	interface BgImageEntry {
+		metadata: BackgroundImageMetadata
+		sourceFile?: string
+		sourceLine?: number
+	}
+	const bgImageEntries = new Map<string, BgImageEntry>()
+	root.querySelectorAll('*').forEach((node) => {
+		// Skip already-marked elements
+		if (node.getAttribute(attributeName)) return
+
+		// Skip elements inside markdown wrapper
+		if (isInsideMarkdownWrapper(node)) return
+
+		const classAttr = node.getAttribute('class')
+		const bgMeta = extractBackgroundImageClasses(classAttr)
+		if (!bgMeta) return
+
+		// When skipMarkdownContent is true, only mark elements with source file attributes
+		if (skipMarkdownContent) {
+			let hasSourceAttr = false
+			let current: HTMLNode | null = node
+			while (current) {
+				if (current.getAttribute?.('data-astro-source-file')) {
+					hasSourceAttr = true
+					break
+				}
+				current = current.parentNode as HTMLNode | null
+			}
+			if (!hasSourceAttr) return
+		}
+
+		const id = getNextId()
+		node.setAttribute(attributeName, id)
+		node.setAttribute('data-cms-bg-img', 'true')
+
+		// Try to get source location from the element itself or ancestors
+		let sourceFile: string | undefined
+		let sourceLine: number | undefined
+		let current: HTMLNode | null = node
+		while (current && !sourceFile) {
+			const file = current.getAttribute?.('data-astro-source-file')
+			const line = current.getAttribute?.('data-astro-source-loc') || current.getAttribute?.('data-astro-source-line')
+			if (file) {
+				sourceFile = file
+				if (line) {
+					const lineNum = parseInt(line.split(':')[0] ?? '1', 10)
+					if (!Number.isNaN(lineNum)) {
+						sourceLine = lineNum
+					}
+				}
+			}
+			current = current.parentNode as HTMLNode | null
+		}
+
+		bgImageEntries.set(id, {
+			metadata: bgMeta,
+			sourceFile,
+			sourceLine,
+		})
+	})
+
 	// Third pass: collect candidate text elements (don't mark yet)
 	// We collect candidates first to filter out pure containers before marking
 	interface TextCandidate {
@@ -826,12 +888,18 @@ export async function processHtml(
 			const imageInfo = imageEntries.get(id)
 			const isImage = !!imageInfo
 
+			// Check if this is a background image entry
+			const bgImageInfo = bgImageEntries.get(id)
+			// Also extract bg image classes fresh for elements marked for other reasons
+			const bgImageClassAttr = node.getAttribute('class')
+			const bgImageMetadata = bgImageInfo?.metadata ?? extractBackgroundImageClasses(bgImageClassAttr)
+
 			// Check if this is the collection wrapper
 			const isCollectionWrapper = id === collectionWrapperId
 
 			const entryText = isImage ? (imageInfo.metadata.alt || imageInfo.metadata.src) : textWithPlaceholders.trim()
-			// For images, use the source file we captured from ancestors if not in sourceLocationMap
-			const entrySourcePath = sourceLocation?.file || imageInfo?.sourceFile || sourcePath
+			// For images/bg-images, use the source file we captured from ancestors if not in sourceLocationMap
+			const entrySourcePath = sourceLocation?.file || imageInfo?.sourceFile || bgImageInfo?.sourceFile || sourcePath
 
 			// Generate stable ID based on content and context
 			const stableId = generateStableId(tag, entryText, entrySourcePath)
@@ -854,7 +922,7 @@ export async function processHtml(
 				html: htmlContent,
 				sourcePath: entrySourcePath,
 				childCmsIds: childCmsIds.length > 0 ? childCmsIds : undefined,
-				sourceLine: sourceLocation?.line ?? imageInfo?.sourceLine,
+				sourceLine: sourceLocation?.line ?? imageInfo?.sourceLine ?? bgImageInfo?.sourceLine,
 				sourceSnippet: undefined,
 				variableName: undefined,
 				parentComponentId,
@@ -866,6 +934,8 @@ export async function processHtml(
 				stableId,
 				// Image metadata for image entries
 				imageMetadata: imageInfo?.metadata,
+				// Background image metadata for bg-[url()] elements
+				backgroundImage: bgImageMetadata,
 				// Color and text style classes for buttons/styled elements
 				colorClasses: allTrackedClasses,
 				// All attributes with resolved values (isStatic will be updated later from source)