@nuasite/cms 0.8.0 → 0.8.3

package/package.json

@@ -14,7 +14,7 @@
     "directory": "packages/astro-cms"
   },
   "license": "Apache-2.0",
-  "version": "0.8.0",
+  "version": "0.8.3",
   "module": "src/index.ts",
   "types": "src/index.ts",
   "type": "module",

package/src/editor/components/bg-image-overlay.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks'
 import { Z_INDEX } from '../constants'
+import { isApplyingUndoRedo, recordChange } from '../history'
 import { cn } from '../lib/cn'
 import * as signals from '../signals'
 import { saveBgImageEditsToStorage } from '../storage'
@@ -410,6 +411,10 @@ function applyBgImageUpdate(
 	const change = signals.getPendingBgImageChange(cmsId)
 	if (!change) return
 
+	// Capture pre-mutation state for undo
+	const previousClassName = element.className
+	const previousStyleCssText = element.style.cssText
+
 	const newChange = { ...change }
 
 	// Apply bg image class change
@@ -451,6 +456,28 @@ function applyBgImageUpdate(
 		|| newChange.newBgPosition !== newChange.originalBgPosition
 		|| newChange.newBgRepeat !== newChange.originalBgRepeat
 
+	// Record undo action after DOM is mutated
+	if (!isApplyingUndoRedo) {
+		recordChange({
+			type: 'bgImage',
+			cmsId,
+			element,
+			previousClassName,
+			currentClassName: element.className,
+			previousStyleCssText,
+			currentStyleCssText: element.style.cssText,
+			previousBgImageClass: change.newBgImageClass,
+			currentBgImageClass: newChange.newBgImageClass,
+			previousBgSize: change.newBgSize,
+			currentBgSize: newChange.newBgSize,
+			previousBgPosition: change.newBgPosition,
+			currentBgPosition: newChange.newBgPosition,
+			previousBgRepeat: change.newBgRepeat,
+			currentBgRepeat: newChange.newBgRepeat,
+			wasDirty: change.isDirty,
+		})
+	}
+
 	signals.setPendingBgImageChange(cmsId, newChange)
 	saveBgImageEditsToStorage(signals.pendingBgImageChanges.value)
 }

package/src/editor/editor.ts

@@ -549,11 +549,9 @@ export function discardAllChanges(onStateChange?: () => void): void {
 	})
 
 	cleanupHighlightSystem()
-	signals.clearPendingChanges()
-	signals.clearPendingImageChanges()
-	signals.clearPendingColorChanges()
-	signals.clearPendingBgImageChanges()
-	signals.clearPendingAttributeChanges()
+	for (const entry of Object.values(signals.changeRegistry)) {
+		entry.mapSignal.value = new Map()
+	}
 	clearAllEditsFromStorage()
 	clearHistory()
 	stopEditMode(onStateChange)
@@ -701,7 +699,7 @@ export async function saveAllChanges(
 						sourcePath: bestSourcePath ?? entry?.sourcePath ?? '',
 						sourceLine: bestSourceLine ?? entry?.sourceLine ?? 0,
 						sourceSnippet: bestSourceSnippet ?? entry?.sourceSnippet ?? '',
-						colorChange: {
+						styleChange: {
 							oldClass: origAttr?.value || '',
 							newClass: newAttr.value,
 							type: classType,
@@ -740,7 +738,7 @@ export async function saveAllChanges(
 					sourcePath: entry?.sourcePath ?? '',
 					sourceLine: entry?.sourceLine ?? 0,
 					sourceSnippet: entry?.sourceSnippet ?? '',
-					colorChange: {
+					styleChange: {
 						oldClass: bgChange.oldClass,
 						newClass: bgChange.newClass,
 						type: bgChange.type,

package/src/editor/history.ts

@@ -1,6 +1,12 @@
 import { computed, signal } from '@preact/signals'
 import * as signals from './signals'
-import { saveAttributeEditsToStorage, saveColorEditsToStorage, saveEditsToStorage, saveImageEditsToStorage } from './storage'
+import {
+	saveAttributeEditsToStorage,
+	saveBgImageEditsToStorage,
+	saveColorEditsToStorage,
+	saveEditsToStorage,
+	saveImageEditsToStorage,
+} from './storage'
 import type { Attribute, UndoAction, UndoTextAction } from './types'
 
 // ============================================================================
@@ -159,52 +165,104 @@ function scrollToElement(element: HTMLElement): void {
 	}
 }
 
-function applyReverse(action: UndoAction): void {
-	switch (action.type) {
-		case 'text':
+/** Registry of undo/redo handlers keyed by action type.
+ *  Adding a new UndoAction variant forces a TypeScript error until its handlers are added here. */
+type UndoHandlers = {
+	[K in UndoAction['type']]: {
+		applyReverse: (action: Extract<UndoAction, { type: K }>) => void
+		applyForward: (action: Extract<UndoAction, { type: K }>) => void
+	}
+}
+
+const undoRegistry: UndoHandlers = {
+	text: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
 			applyTextState(action.cmsId, action.element, action.previousHTML, action.previousText, action.wasDirty)
-			break
-		case 'image':
+		},
+		applyForward: (action) => {
+			scrollToElement(action.element)
+			applyTextState(action.cmsId, action.element, action.currentHTML, action.currentText, true)
+		},
+	},
+	image: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
 			applyImageState(action.cmsId, action.element, action.previousSrc, action.previousAlt, action.wasDirty)
-			break
-		case 'color':
+		},
+		applyForward: (action) => {
+			scrollToElement(action.element)
+			applyImageState(action.cmsId, action.element, action.currentSrc, action.currentAlt, true)
+		},
+	},
+	color: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
 			applyColorState(action.cmsId, action.element, action.previousClassName, action.previousStyleCssText, action.previousClasses, action.wasDirty)
-			break
-		case 'attribute':
+		},
+		applyForward: (action) => {
 			scrollToElement(action.element)
-			applyAttributeState(action.cmsId, action.element, action.previousAttributes, action.wasDirty)
-			break
-		case 'seo':
-			applySeoState(action.cmsId, action.previousValue, action.originalValue, action.wasDirty)
-			break
-	}
-}
-
-function applyForward(action: UndoAction): void {
-	switch (action.type) {
-		case 'text':
+			applyColorState(action.cmsId, action.element, action.currentClassName, action.currentStyleCssText, action.currentClasses, true)
+		},
+	},
+	bgImage: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
-			applyTextState(action.cmsId, action.element, action.currentHTML, action.currentText, true)
-			break
-		case 'image':
+			applyBgImageState(
+				action.cmsId,
+				action.element,
+				action.previousClassName,
+				action.previousStyleCssText,
+				action.previousBgImageClass,
+				action.previousBgSize,
+				action.previousBgPosition,
+				action.previousBgRepeat,
+				action.wasDirty,
+			)
+		},
+		applyForward: (action) => {
 			scrollToElement(action.element)
-			applyImageState(action.cmsId, action.element, action.currentSrc, action.currentAlt, true)
-			break
-		case 'color':
+			applyBgImageState(
+				action.cmsId,
+				action.element,
+				action.currentClassName,
+				action.currentStyleCssText,
+				action.currentBgImageClass,
+				action.currentBgSize,
+				action.currentBgPosition,
+				action.currentBgRepeat,
+				true,
+			)
+		},
+	},
+	attribute: {
+		applyReverse: (action) => {
 			scrollToElement(action.element)
-			applyColorState(action.cmsId, action.element, action.currentClassName, action.currentStyleCssText, action.currentClasses, true)
-			break
-		case 'attribute':
+			applyAttributeState(action.cmsId, action.element, action.previousAttributes, action.wasDirty)
+		},
+		applyForward: (action) => {
 			scrollToElement(action.element)
 			applyAttributeState(action.cmsId, action.element, action.currentAttributes, true)
-			break
-		case 'seo':
+		},
+	},
+	seo: {
+		applyReverse: (action) => {
+			applySeoState(action.cmsId, action.previousValue, action.originalValue, action.wasDirty)
+		},
+		applyForward: (action) => {
 			applySeoState(action.cmsId, action.currentValue, action.originalValue, true)
-			break
-	}
+		},
+	},
+}
+
+function applyReverse(action: UndoAction): void {
+	const handlers = undoRegistry[action.type] as UndoHandlers[typeof action.type]
+	handlers.applyReverse(action as any)
+}
+
+function applyForward(action: UndoAction): void {
+	const handlers = undoRegistry[action.type] as UndoHandlers[typeof action.type]
+	handlers.applyForward(action as any)
 }
 
 // ============================================================================
@@ -323,6 +381,34 @@ function applySeoState(
 	})
 }
 
+function applyBgImageState(
+	cmsId: string,
+	element: HTMLElement,
+	className: string,
+	styleCssText: string,
+	bgImageClass: string,
+	bgSize: string,
+	bgPosition: string,
+	bgRepeat: string,
+	isDirty: boolean,
+): void {
+	if (element.isConnected) {
+		element.className = className
+		element.style.cssText = styleCssText
+	}
+
+	signals.updatePendingBgImageChange(cmsId, (c) => ({
+		...c,
+		newBgImageClass: bgImageClass,
+		newBgSize: bgSize,
+		newBgPosition: bgPosition,
+		newBgRepeat: bgRepeat,
+		isDirty,
+	}))
+
+	saveBgImageEditsToStorage(signals.pendingBgImageChanges.value)
+}
+
 // ============================================================================
 // Clear History
 // ============================================================================

package/src/editor/signals.ts

@@ -496,6 +496,16 @@ 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)
@@ -504,6 +514,19 @@ 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
@@ -528,17 +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 + dirtyBgImageChangesCount.value + dirtySeoChangesCount.value
-		+ dirtyAttributeChangesCount.value,
-)
+const _registryEntries = Object.values(changeRegistry)
 
-export const hasAnyDirtyChanges = computed(
-	() =>
-		hasDirtyChanges.value || hasDirtyImageChanges.value || hasDirtyColorChanges.value || hasDirtyBgImageChanges.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)
@@ -1345,14 +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()
-		pendingBgImageChanges.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/types.ts

@@ -170,13 +170,13 @@ export interface SavedBackgroundImageEdits {
 	[cmsId: string]: SavedBackgroundImageEdit
 }
 
-/** Color change details for updating element color classes */
-export interface ColorChangePayload {
-	/** The color class to replace (e.g., 'bg-blue-500') */
+/** 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 of style change */
 	type:
 		| 'bg'
 		| 'text'
@@ -220,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[]
 }
@@ -630,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) {
@@ -536,16 +494,13 @@ function applyAttributeChanges(
 	return { content: newContent, appliedCount: attrApplied, failedChanges }
 }
 
-function applyTextChange(
+export function applyTextChange(
 	content: string,
 	change: ChangePayload,
 	manifest: CmsManifest,
 ): { success: true; content: string } | { success: false; error: string } {
 	const { sourceSnippet, originalValue, newValue, htmlValue } = change
 
-	let newText = htmlValue ?? newValue
-	newText = resolveCmsPlaceholders(newText, manifest)
-
 	if (!sourceSnippet || !originalValue) {
 		if (change.attributeChanges && change.attributeChanges.length > 0) {
 			return { success: true, content }
@@ -557,22 +512,103 @@ 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)
+	const newText = htmlValue ?? newValue
+
+	// When originalValue contains CMS placeholders (child elements like {{cms:cms-5}}),
+	// replace only the text segments between placeholders directly in the sourceSnippet.
+	// This avoids resolving placeholders via child sourceSnippets, which can be incorrect
+	// when multiple inline children share the same source line (extractCompleteTagSnippet
+	// returns the entire line, not just the individual child tag).
+	const placeholderPattern = /\{\{cms:[^}]+\}\}/g
+	if (placeholderPattern.test(originalValue)) {
+		return applyTextChangeWithPlaceholders(content, sourceSnippet, originalValue, newText)
+	}
+
+	// No placeholders — resolve and match directly
+	const resolvedNewText = resolveCmsPlaceholders(newText, manifest)
+	const resolvedOriginal = resolveCmsPlaceholders(originalValue, manifest)
+
+	// Replace resolvedOriginal with resolvedNewText WITHIN the sourceSnippet
+	const updatedSnippet = sourceSnippet.replace(resolvedOriginal, resolvedNewText)
 
 	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)
+			const updatedWithEntity = sourceSnippet.replace(matchedText, resolvedNewText)
 			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 + resolvedNewText + 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`,
+		}
+	}
+
+	return { success: true, content: content.replace(sourceSnippet, updatedSnippet) }
+}
+
+/**
+ * Apply text change when originalValue contains CMS placeholders.
+ * Splits by placeholder boundaries and replaces only the changed text segments.
+ */
+function applyTextChangeWithPlaceholders(
+	content: string,
+	sourceSnippet: string,
+	originalValue: string,
+	newText: string,
+): { success: true; content: string } | { success: false; error: string } {
+	const placeholderPattern = /\{\{cms:[^}]+\}\}/g
+
+	const originalParts = originalValue.split(placeholderPattern)
+	const newParts = newText.split(placeholderPattern)
+
+	if (originalParts.length !== newParts.length) {
+		return { success: false, error: 'Placeholder structure mismatch between original and new values' }
+	}
+
+	let updatedSnippet = sourceSnippet
+	let anyChange = false
+
+	for (let i = 0; i < originalParts.length; i++) {
+		const oldPart = originalParts[i]!
+		let newPart = newParts[i]!
+
+		if (oldPart === newPart || oldPart.length === 0) {
+			continue
+		}
+
+		// Try direct match first, then entity-aware match
+		const matchedText = findTextInSnippet(updatedSnippet, oldPart)
+		if (matchedText) {
+			// When entity-aware matching was needed, encode the same entities in the replacement
+			if (matchedText !== oldPart) {
+				newPart = encodeEntitiesLike(newPart, matchedText)
+			}
+			updatedSnippet = updatedSnippet.replace(matchedText, newPart)
+			anyChange = true
+		} else {
+			return {
+				success: false,
+				error: `Text segment "${oldPart.substring(0, 50)}..." not found in source snippet`,
+			}
 		}
 	}
 
+	if (!anyChange) {
+		return { success: false, error: 'No text changes detected between original and new values' }
+	}
+
 	return { success: true, content: content.replace(sourceSnippet, updatedSnippet) }
 }
 
@@ -616,6 +652,32 @@ function findTextInSnippet(snippet: string, decodedText: string): string | null
 	return brMatch && brMatch[0] !== decodedText ? brMatch[0] : null
 }
 
+/**
+ * Encode HTML entities in text to match the encoding used in a reference string.
+ * When entity-aware matching found entities in the source, the replacement text
+ * needs the same encoding to preserve valid HTML.
+ */
+function encodeEntitiesLike(text: string, reference: string): string {
+	let result = text
+	// & must be encoded first to avoid double-encoding other entities
+	if (reference.includes('&amp;')) {
+		result = result.replace(/&/g, '&amp;')
+	}
+	if (reference.includes('&lt;')) {
+		result = result.replace(/</g, '&lt;')
+	}
+	if (reference.includes('&gt;')) {
+		result = result.replace(/>/g, '&gt;')
+	}
+	if (reference.includes('&quot;')) {
+		result = result.replace(/"/g, '&quot;')
+	}
+	if (reference.includes('&#39;') || reference.includes('&apos;')) {
+		result = result.replace(/'/g, '&#39;')
+	}
+	return result
+}
+
 /**
  * Resolve CMS placeholders like {{cms:cms-96}} in text.
  */