@nuasite/cms 0.23.0 → 0.24.0

package/package.json

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

package/src/build-processor.ts

@@ -24,7 +24,7 @@ import {
 } from './source-finder'
 import type { ComponentInstance } from './types'
 import type { CmsMarkerOptions, CollectionEntry } from './types'
-import { firstNonEmptyLine } from './utils'
+import { firstNonEmptyLine, resolveSourcePath } from './utils'
 
 // Concurrency limit for parallel processing
 const MAX_CONCURRENT = 10
@@ -425,9 +425,7 @@ async function processFile(
 
 			// Update attribute and colorClasses source information if we have an opening tag
 			if (sourceLocation.openingTagSnippet) {
-				const filePath = path.isAbsolute(sourceLocation.file)
-					? sourceLocation.file
-					: path.join(getProjectRoot(), sourceLocation.file)
+				const filePath = resolveSourcePath(sourceLocation.file)
 				try {
 					const content = await fs.readFile(filePath, 'utf-8')
 					const lines = content.split('\n')

package/src/content-invalidator.ts

@@ -0,0 +1,134 @@
+/**
+ * Vite SSR module cache invalidation + content-sync coordination.
+ *
+ * Astro's content layer chain (chokidar → glob loader → syncData → data store
+ * → fs.watch → invalidateModule) is racy and unreliable under several conditions:
+ *
+ *   - Native fs.watch on Linux dies after the first atomic rename of the watched
+ *     file (Astro writes data-store.json via writeFile-tmp + rename).
+ *   - Vite's bundled chokidar 3.6.0 misses the same atomic-write events.
+ *   - `invalidateModule(astro:data-layer-content)` alone does not propagate up
+ *     the import graph, so route modules that already cached `getCollection`
+ *     references keep returning stale data.
+ *
+ * This module exposes two things:
+ *
+ *   - `invalidateContentCache(server)` — walks the SSR module graph from
+ *     `astro:data-layer-content` upward and invalidates every transitive
+ *     importer, then broadcasts `full-reload` to the client.
+ *   - `notifyContentStoreUpdated` / `awaitNextContentStoreUpdate` — a shared
+ *     rendezvous between the fs.watch plugin (which observes data-store.json
+ *     writes) and the CMS API middleware (which needs to hold the HTTP
+ *     response until the store is fresh). Keeps invalidation on a single path.
+ */
+
+interface SsrModuleNode {
+	id: string | null
+	importers: Set<SsrModuleNode>
+}
+
+interface SsrModuleGraph {
+	getModuleById(id: string): SsrModuleNode | undefined
+	invalidateModule(
+		mod: SsrModuleNode,
+		seen?: Set<SsrModuleNode>,
+		timestamp?: number,
+		isHmr?: boolean,
+	): void
+}
+
+interface SsrEnvironment {
+	moduleGraph: SsrModuleGraph
+	hot: { send: (event: string, data?: unknown) => void }
+}
+
+interface ClientEnvironment {
+	hot: { send: (payload: { type: string; path: string }) => void }
+}
+
+export interface ViteServerLike {
+	environments: { ssr: SsrEnvironment; client: ClientEnvironment }
+}
+
+// Astro exposes the content data store as a virtual module whose resolved id
+// is `\0astro:data-layer-content` (see astro/dist/content/consts.js). Earlier
+// versions of this file used `\0astro:data-store`, which does not exist and
+// silently reduced `invalidateContentCache` to a no-op full-reload broadcast.
+const DATA_STORE_VIRTUAL_ID = '\0astro:data-layer-content'
+
+/**
+ * Invalidate the SSR `astro:data-layer-content` virtual module and every
+ * module that (transitively) imports it. After this returns, the next request
+ * that imports any of these modules will re-execute and read fresh content.
+ *
+ * Also broadcasts `full-reload` so any connected browser refreshes.
+ */
+export function invalidateContentCache(server: ViteServerLike): void {
+	const ssr = server.environments.ssr
+	const dataStoreMod = ssr.moduleGraph.getModuleById(DATA_STORE_VIRTUAL_ID)
+	if (dataStoreMod) {
+		const seen = new Set<SsrModuleNode>()
+		const ts = Date.now()
+		const walk = (mod: SsrModuleNode) => {
+			if (seen.has(mod)) return
+			seen.add(mod)
+			ssr.moduleGraph.invalidateModule(mod, seen, ts, true)
+			for (const importer of mod.importers) {
+				walk(importer)
+			}
+		}
+		walk(dataStoreMod)
+	}
+	ssr.hot.send('astro:content-changed', {})
+	server.environments.client.hot.send({ type: 'full-reload', path: '*' })
+}
+
+// ---------------------------------------------------------------------------
+// Content-sync rendezvous
+// ---------------------------------------------------------------------------
+//
+// The CMS API middleware writes a content file and then needs to hold the HTTP
+// response until Astro has actually re-synced the data store — otherwise the
+// browser reloads into a stale render. The fs.watch plugin is the component
+// that observes the data-store.json write, so it is also the component that
+// resolves these waiters.
+
+type StoreUpdateResolver = () => void
+const pendingStoreUpdateWaiters = new Set<StoreUpdateResolver>()
+
+/**
+ * Called by the data-store fs.watch plugin after it has invalidated the SSR
+ * module cache in response to a data-store.json write. Wakes every middleware
+ * caller currently parked in `awaitNextContentStoreUpdate`.
+ */
+export function notifyContentStoreUpdated(): void {
+	if (pendingStoreUpdateWaiters.size === 0) return
+	const resolvers = Array.from(pendingStoreUpdateWaiters)
+	pendingStoreUpdateWaiters.clear()
+	for (const resolve of resolvers) resolve()
+}
+
+/**
+ * Park until the next data-store.json write has been fully processed (store
+ * reloaded on disk, SSR module graph invalidated). Resolves with `true` on
+ * success or `false` if the timeout elapses first — callers should treat
+ * timeout as "best-effort, proceed anyway".
+ *
+ * The timeout fallback exists because some edits legitimately do not change
+ * the data store (e.g. whitespace-only edits are skipped by Astro's atomic
+ * write comparator), in which case no fs.watch event will ever fire.
+ */
+export function awaitNextContentStoreUpdate(timeoutMs: number): Promise<boolean> {
+	return new Promise((resolve) => {
+		const resolver = () => {
+			clearTimeout(timer)
+			pendingStoreUpdateWaiters.delete(resolver)
+			resolve(true)
+		}
+		const timer = setTimeout(() => {
+			pendingStoreUpdateWaiters.delete(resolver)
+			resolve(false)
+		}, timeoutMs)
+		pendingStoreUpdateWaiters.add(resolver)
+	})
+}

package/src/dev-middleware.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import path from 'node:path'
 import { getProjectRoot } from './config'
+import { awaitNextContentStoreUpdate } from './content-invalidator'
 import { handleCmsApiRoute } from './handlers/api-routes'
 import { buildMapPattern, detectArrayPattern, extractArrayElementProps, parseInlineArrayName } from './handlers/array-ops'
 import {
@@ -43,6 +44,7 @@ interface ViteDevServerLike {
 	watcher?: {
 		on: (event: string, listener: (...args: any[]) => void) => any
 		removeListener: (event: string, listener: (...args: any[]) => void) => any
+		emit: (event: string, ...args: any[]) => boolean
 	}
 }
 
@@ -100,6 +102,45 @@ export function createDevMiddleware(
 
 	// CMS API endpoints (local dev server backend)
 	if (options.enableCmsApi) {
+		const projectRoot = getProjectRoot()
+
+		/**
+		 * Hold the HTTP response for a `markdown/update` (or equivalent) call
+		 * until Astro's content layer has actually re-synced the edited file.
+		 *
+		 * The race we're fixing: handleUpdateMarkdown writes the file and
+		 * returns immediately, the editor then triggers a full-reload, and
+		 * the next page render reads a still-cached `astro:data-layer-content`
+		 * virtual module — so the user sees their edit disappear until Astro's
+		 * async chain (glob loader → syncData → 500 ms save debounce → atomic
+		 * write → fs.watch → invalidateModule) finally catches up.
+		 *
+		 * The fix, end to end:
+		 *
+		 *   1. `server.watcher.emit('change', fullPath)` kicks Astro's glob
+		 *      loader directly. It is registered on this exact watcher (see
+		 *      astro/dist/core/dev/dev.js — `viteServer.watcher` is handed to
+		 *      `globalContentLayer.init`), so synthetic change events fire its
+		 *      `onChange` handler and trigger `syncData`. This also works
+		 *      around Vite's bundled chokidar missing some edits.
+		 *   2. `awaitNextContentStoreUpdate` parks until the shared data-store
+		 *      watcher (in `vite-plugin.ts`) observes the resulting atomic
+		 *      write and finishes invalidating the SSR module graph.
+		 *   3. Only then do we return — so the subsequent full-reload lands
+		 *      on a page that will re-execute with fresh content.
+		 *
+		 * The timeout fallback covers edits that legitimately do not rewrite
+		 * the data store (Astro's MutableDataStore skips identical writes).
+		 * In that case no fs.watch event will ever fire, and 3 s is plenty of
+		 * budget before we give up and let the response through anyway.
+		 */
+		const notifyContentChanged = async (filePath: string): Promise<void> => {
+			const fullPath = path.resolve(projectRoot, filePath)
+			const waiter = awaitNextContentStoreUpdate(3000)
+			server.watcher?.emit('change', fullPath)
+			await waiter
+		}
+
 		server.middlewares.use((req, res, next) => {
 			const url = req.url || ''
 			if (!url.startsWith('/_nua/cms/')) {
@@ -111,7 +152,7 @@ export function createDevMiddleware(
 
 			const route = url.replace('/_nua/cms/', '').split('?')[0]!
 
-			handleCmsApiRoute(route, req, res, manifestWriter, config.contentDir, options.mediaAdapter)
+			handleCmsApiRoute(route, req, res, manifestWriter, config.contentDir, options.mediaAdapter, notifyContentChanged)
 				.catch((error) => {
 					console.error('[astro-cms] API error:', error)
 					sendError(res, 'Internal server error', 500)

package/src/editor/index.tsx

@@ -109,9 +109,8 @@ const CmsUI = () => {
 	// Re-fetch manifest on View Transitions navigation (astro:after-swap)
 	useEffect(() => {
 		const onNavigation = () => {
-			fetchManifest().then((manifest) => {
-				signals.setManifest(manifest)
-			}).catch(() => {})
+			postToParent({ type: 'cms-page-navigated', page: { pathname: window.location.pathname } })
+			fetchManifest().then((manifest) => signals.setManifest(manifest)).catch(() => {})
 		}
 		document.addEventListener('astro:after-swap', onNavigation)
 		return () => document.removeEventListener('astro:after-swap', onNavigation)

package/src/handlers/api-routes.ts

@@ -21,6 +21,15 @@ export interface RouteContext {
 	manifestWriter: ManifestWriter
 	contentDir: string
 	mediaAdapter?: MediaStorageAdapter
+	/**
+	 * Triggered after a content file (markdown / data collection) is written so
+	 * the dev middleware can synchronously refresh Astro's content layer and
+	 * invalidate Vite's SSR module cache before responding to the client.
+	 *
+	 * Awaiting this is important: returning success before the cache is fresh
+	 * causes the editor to reload the page into a stale render.
+	 */
+	notifyContentChanged?: (filePath: string) => Promise<void>
 }
 
 type RouteHandler = (ctx: RouteContext) => Promise<void>
@@ -104,9 +113,13 @@ const routeMap = new Map<string, RouteHandler>([
 		}
 		sendJson(res, result)
 	}),
-	custom('POST', 'markdown/update', async ({ req, res, manifestWriter }) => {
+	custom('POST', 'markdown/update', async ({ req, res, manifestWriter, notifyContentChanged }) => {
 		const body = await parseJsonBody<Parameters<typeof handleUpdateMarkdown>[0]>(req)
-		sendJson(res, await handleUpdateMarkdown(body, manifestWriter.getComponentDefinitions()))
+		const result = await handleUpdateMarkdown(body, manifestWriter.getComponentDefinitions())
+		if (result.success && notifyContentChanged) {
+			await notifyContentChanged(body.filePath)
+		}
+		sendJson(res, result)
 	}),
 	post('markdown/rename', (body: Parameters<typeof handleRenameMarkdown>[0]) => handleRenameMarkdown(body)),
 	postWithStatus('markdown/create', (body: Parameters<typeof handleCreateMarkdown>[0]) => handleCreateMarkdown(body)),
@@ -225,8 +238,9 @@ export async function handleCmsApiRoute(
 	manifestWriter: ManifestWriter,
 	contentDir: string,
 	mediaAdapter?: MediaStorageAdapter,
+	notifyContentChanged?: (filePath: string) => Promise<void>,
 ): Promise<void> {
-	const ctx: RouteContext = { req, res, route, manifestWriter, contentDir, mediaAdapter }
+	const ctx: RouteContext = { req, res, route, manifestWriter, contentDir, mediaAdapter, notifyContentChanged }
 
 	// Exact match lookup
 	const handler = routeMap.get(`${req.method}:${route}`)

package/src/source-finder/collection-finder.ts

@@ -575,6 +575,54 @@ export async function findFieldInCollectionEntry(
 	}
 }
 
+/**
+ * Find multiple fields by name in a specific collection entry's data file.
+ * Parses the YAML only once, unlike calling findFieldInCollectionEntry per field.
+ */
+export async function findFieldsInCollectionEntry(
+	fieldNames: Set<string>,
+	collectionName: string,
+	collectionSlug: string,
+	collectionDefinitions: Record<string, CollectionDefinition>,
+): Promise<Map<string, SourceLocation>> {
+	const def = collectionDefinitions[collectionName]
+	if (!def?.entries) return new Map()
+
+	const entry = def.entries.find((e) => e.slug === collectionSlug)
+	if (!entry) return new Map()
+
+	const info: CollectionInfo = { name: collectionName, slug: collectionSlug, file: entry.sourcePath }
+
+	try {
+		const filePath = path.join(getProjectRoot(), entry.sourcePath)
+		const cached = await getCachedMarkdownFile(filePath)
+		if (!cached) return new Map()
+
+		if (def.type === 'data') {
+			return findFieldsByNameInYaml(cached.content, 0, fieldNames, cached.lines, info)
+		}
+
+		// For markdown, search inside frontmatter only
+		const { lines } = cached
+		let fmStart = -1
+		let fmEnd = -1
+		for (let i = 0; i < lines.length; i++) {
+			if (lines[i]?.trim() === '---') {
+				if (fmStart === -1) fmStart = i
+				else {
+					fmEnd = i
+					break
+				}
+			}
+		}
+		if (fmEnd <= 0) return new Map()
+		const yamlStr = lines.slice(fmStart + 1, fmEnd).join('\n')
+		return findFieldsByNameInYaml(yamlStr, fmStart + 1, fieldNames, lines, info)
+	} catch {
+		return new Map()
+	}
+}
+
 /**
  * Walk a YAML AST to find a field by key name (regardless of its value).
  */
@@ -585,13 +633,30 @@ function findFieldByNameInYaml(
 	fileLines: string[],
 	collectionInfo: CollectionInfo,
 ): SourceLocation | undefined {
+	const results = findFieldsByNameInYaml(yamlStr, lineOffset, new Set([fieldName]), fileLines, collectionInfo)
+	return results.get(fieldName)
+}
+
+/**
+ * Walk a YAML AST to find multiple fields by key name in a single parse.
+ * Returns a map of fieldName → SourceLocation for all matched fields.
+ */
+function findFieldsByNameInYaml(
+	yamlStr: string,
+	lineOffset: number,
+	fieldNames: Set<string>,
+	fileLines: string[],
+	collectionInfo: CollectionInfo,
+): Map<string, SourceLocation> {
 	const lineCounter = new LineCounter()
 	const doc = parseDocument(yamlStr, { lineCounter })
-	if (!isMap(doc.contents)) return undefined
+	const results = new Map<string, SourceLocation>()
+	if (!isMap(doc.contents)) return results
 
 	for (const pair of doc.contents.items) {
 		if (!isPair(pair) || !isScalar(pair.key)) continue
-		if (String(pair.key.value) !== fieldName) continue
+		const key = String(pair.key.value)
+		if (!fieldNames.has(key)) continue
 		if (!isScalar(pair.value)) continue
 
 		const keyRange = (pair.key as any).range as [number, number, number] | undefined
@@ -600,17 +665,20 @@ function findFieldByNameInYaml(
 		const endLine = (valRange ? lineCounter.linePos(valRange[1]).line : startLine - lineOffset) + lineOffset
 
 		const snippet = fileLines.slice(startLine - 1, endLine).join('\n')
-		return {
+		results.set(key, {
 			file: collectionInfo.file,
 			line: startLine,
 			snippet,
 			type: 'collection',
-			variableName: fieldName,
+			variableName: key,
 			collectionName: collectionInfo.name,
 			collectionSlug: collectionInfo.slug,
-		}
+		})
+
+		// Early exit if all fields found
+		if (results.size === fieldNames.size) break
 	}
-	return undefined
+	return results
 }
 
 // ============================================================================

package/src/source-finder/cross-file-tracker.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 
 import { getProjectRoot } from '../config'
-import { escapeRegex } from '../utils'
+import { escapeRegex, resolveSourcePath } from '../utils'
 import { buildDefinitionPath, parseExpressionPath } from './ast-extractors'
 import { getCachedParsedFile } from './ast-parser'
 import { findComponentProp, findExpressionProp, findSpreadProp } from './element-finder'
@@ -384,9 +384,7 @@ export async function findAttributeSourceLocation(
 	// Get the property name (last part of the expression)
 	const propName = exprPath.includes('.') ? exprPath.split('.').pop()! : exprPath
 
-	const filePath = path.isAbsolute(sourceFilePath)
-		? sourceFilePath
-		: path.join(getProjectRoot(), sourceFilePath)
+	const filePath = resolveSourcePath(sourceFilePath)
 
 	const cached = await getCachedParsedFile(filePath)
 	if (!cached) return undefined

package/src/source-finder/snippet-utils.ts

@@ -4,10 +4,16 @@ import { parse as parseYaml } from 'yaml'
 
 import { getProjectRoot } from '../config'
 import type { Attribute, CollectionDefinition, ManifestEntry } from '../types'
-import { escapeRegex, generateSourceHash } from '../utils'
+import { escapeRegex, generateSourceHash, resolveSourcePath } from '../utils'
 import { buildDefinitionPath } from './ast-extractors'
 import { getCachedParsedFile } from './ast-parser'
-import { buildCollectionTextIndex, findFieldInCollectionEntry, findTextInAnyCollectionFrontmatter, lookupCollectionText } from './collection-finder'
+import {
+	buildCollectionTextIndex,
+	findFieldInCollectionEntry,
+	findFieldsInCollectionEntry,
+	findTextInAnyCollectionFrontmatter,
+	lookupCollectionText,
+} from './collection-finder'
 import { findAttributeSourceLocation, searchForExpressionProp, searchForPropInParents } from './cross-file-tracker'
 import { findImageElementNearLine, findImageSourceLocation } from './image-finder'
 import { initializeSearchIndex } from './search-index'
@@ -444,9 +450,7 @@ export async function extractSourceSnippet(
 	tag: string,
 ): Promise<string | undefined> {
 	try {
-		const filePath = path.isAbsolute(sourceFile)
-			? sourceFile
-			: path.join(getProjectRoot(), sourceFile)
+		const filePath = resolveSourcePath(sourceFile)
 
 		const content = await fs.readFile(filePath, 'utf-8')
 		const lines = content.split('\n')
@@ -583,9 +587,7 @@ export async function enhanceManifestWithSourceSnippets(
 
 				// Also update attribute and colorClasses source info from the opening tag
 				try {
-					const filePath = path.isAbsolute(imageLocation.file)
-						? imageLocation.file
-						: path.join(getProjectRoot(), imageLocation.file)
+					const filePath = resolveSourcePath(imageLocation.file)
 					const { lines } = await readFileWithCache(filePath)
 					const openingTagInfo = extractOpeningTagWithLine(lines, imageLocation.line - 1, entry.tag)
 
@@ -620,9 +622,7 @@ export async function enhanceManifestWithSourceSnippets(
 			// Fallback for expression-based src attributes (src={variable})
 			if (entry.sourcePath && entry.sourceLine) {
 				try {
-					const filePath = path.isAbsolute(entry.sourcePath)
-						? entry.sourcePath
-						: path.join(getProjectRoot(), entry.sourcePath)
+					const filePath = resolveSourcePath(entry.sourcePath)
 					const cached = await getCachedParsedFile(filePath)
 					if (cached) {
 						const nearbyImg = findImageElementNearLine(cached.ast, entry.sourceLine, cached.lines)
@@ -662,6 +662,18 @@ export async function enhanceManifestWithSourceSnippets(
 			return [id, entry] as const
 		}
 
+		// Collection text: resolve directly from the data file
+		if (entry.text?.trim() && entry.collectionName && entry.collectionSlug && collectionDefinitions) {
+			const textLocation = await resolveCollectionTextField(
+				entry,
+				collectionDefinitions,
+				referenceIndex,
+			)
+			if (textLocation) {
+				return [id, textLocation] as const
+			}
+		}
+
 		// Skip if already has sourceSnippet or missing source info
 		if (entry.sourceSnippet || !entry.sourcePath || !entry.sourceLine || !entry.tag) {
 			return [id, entry] as const
@@ -669,9 +681,7 @@ export async function enhanceManifestWithSourceSnippets(
 
 		// Read file once and extract both snippets
 		try {
-			const filePath = path.isAbsolute(entry.sourcePath)
-				? entry.sourcePath
-				: path.join(getProjectRoot(), entry.sourcePath)
+			const filePath = resolveSourcePath(entry.sourcePath)
 
 			const { content, lines } = await readFileWithCache(filePath)
 
@@ -973,36 +983,33 @@ async function resolveCollectionImageField(
 		return undefined
 	}
 
-	// Multiple image fields — try to match the rendered URL to a field value.
+	// Multiple image fields — fetch all in one YAML parse, then match by value
 	const imgSrc = entry.imageMetadata!.src
+	const allResults = await findFieldsInCollectionEntry(
+		new Set(imageFields.map(f => f.name)),
+		entry.collectionName!,
+		entry.collectionSlug!,
+		collectionDefinitions,
+	)
+
 	let firstFieldResult: SourceLocation | undefined
 	for (const field of imageFields) {
-		const fieldResult = await findFieldInCollectionEntry(
-			field.name,
-			entry.collectionName!,
-			entry.collectionSlug!,
-			collectionDefinitions,
-		)
+		const fieldResult = allResults.get(field.name)
 		if (!fieldResult?.snippet) continue
 
-		// Remember the first resolved field as fallback
 		firstFieldResult ??= fieldResult
 
-		// Check if the field's value matches the rendered URL (exact or after Astro processing)
-		const yamlKeyMatch = fieldResult.snippet.match(/^\s*[\w][\w-]*:\s*/)
-		if (yamlKeyMatch) {
-			try {
-				const parsed = parseYaml(fieldResult.snippet)
-				if (parsed && typeof parsed === 'object') {
-					const key = fieldResult.snippet.match(/^\s*([\w][\w-]*):/)?.[1]
-					const value = key ? (parsed as Record<string, unknown>)[key] : undefined
-					if (typeof value === 'string' && (value === imgSrc || imgSrc.includes(value) || value.includes(imgSrc))) {
-						return applyCollectionSource(entry, fieldResult, referenceIndex)
-					}
+		try {
+			const cleaned = fieldResult.snippet.replace(/,\s*$/, '')
+			const parsed = parseYaml(cleaned)
+			if (parsed && typeof parsed === 'object') {
+				const value = (parsed as Record<string, unknown>)[field.name]
+				if (typeof value === 'string' && (value === imgSrc || imgSrc.includes(value) || value.includes(imgSrc))) {
+					return applyCollectionSource(entry, fieldResult, referenceIndex)
 				}
-			} catch {
-				// Not valid YAML
 			}
+		} catch {
+			// Not valid YAML/JSON
 		}
 	}
 
@@ -1014,6 +1021,110 @@ async function resolveCollectionImageField(
 	return undefined
 }
 
+// ============================================================================
+// Collection Text Resolution
+// ============================================================================
+
+/**
+ * Resolve a collection text entry directly from the data file.
+ * Two strategies, tried in order:
+ *
+ * 1. **Source-map** — read the template expression (e.g., {post.data.title}),
+ *    extract the field name, look it up by name in the data file.
+ * 2. **Value match** — iterate over collection fields and compare rendered
+ *    text against field values. Handles static/hardcoded text that exists
+ *    in both the template and a collection data file.
+ */
+async function resolveCollectionTextField(
+	entry: ManifestEntry,
+	collectionDefinitions: Record<string, CollectionDefinition>,
+	referenceIndex?: Map<string, Array<{ collection: string; fieldName: string; isArray?: boolean }>>,
+): Promise<ManifestEntry | undefined> {
+	const colDef = collectionDefinitions[entry.collectionName!]
+	if (!colDef) return undefined
+
+	// Try template expression as source map (e.g., {post.data.title} → "title")
+	const fieldNames = await extractDataFieldNames(entry)
+	if (fieldNames.size === 1) {
+		const fieldResult = await findFieldInCollectionEntry(
+			fieldNames.values().next().value!,
+			entry.collectionName!,
+			entry.collectionSlug!,
+			collectionDefinitions,
+		)
+		if (fieldResult) {
+			return applyCollectionSource(entry, fieldResult, referenceIndex, { allowStyling: false })
+		}
+	} else if (fieldNames.size > 1) {
+		const result = await matchFieldByValue(entry, fieldNames, collectionDefinitions, referenceIndex)
+		if (result) return result
+	}
+
+	// Fallback: match rendered text against all non-image field values
+	const allFieldNames = new Set(colDef.fields.filter(f => f.type !== 'image').map(f => f.name))
+	if (allFieldNames.size > 0) {
+		return matchFieldByValue(entry, allFieldNames, collectionDefinitions, referenceIndex)
+	}
+
+	return undefined
+}
+
+/**
+ * Extract .data.fieldName references from the template expression at the entry's source location.
+ * Returns an empty set if the entry lacks source info or the template has no data field expressions.
+ */
+async function extractDataFieldNames(entry: ManifestEntry): Promise<Set<string>> {
+	const fieldNames = new Set<string>()
+	if (!entry.sourcePath || !entry.sourceLine || !entry.tag) return fieldNames
+
+	const cached = await getCachedParsedFile(resolveSourcePath(entry.sourcePath))
+	if (!cached) return fieldNames
+
+	const snippet = extractCompleteTagSnippet(cached.lines, entry.sourceLine - 1, entry.tag)
+	if (!snippet) return fieldNames
+
+	let match: RegExpExecArray | null
+	const pattern = /\.data\.(\w+)/g
+	while ((match = pattern.exec(snippet)) !== null) {
+		fieldNames.add(match[1]!)
+	}
+	return fieldNames
+}
+
+/** Match entry text against collection field values to find the source field. */
+async function matchFieldByValue(
+	entry: ManifestEntry,
+	fieldNames: Set<string>,
+	collectionDefinitions: Record<string, CollectionDefinition>,
+	referenceIndex?: Map<string, Array<{ collection: string; fieldName: string; isArray?: boolean }>>,
+): Promise<ManifestEntry | undefined> {
+	const normalizedText = normalizeText(entry.text!)
+	const fieldResults = await findFieldsInCollectionEntry(
+		fieldNames,
+		entry.collectionName!,
+		entry.collectionSlug!,
+		collectionDefinitions,
+	)
+
+	for (const [fieldName, fieldResult] of fieldResults) {
+		if (!fieldResult.snippet) continue
+
+		try {
+			const cleaned = fieldResult.snippet.replace(/,\s*$/, '')
+			const parsed = parseYaml(cleaned)
+			if (parsed && typeof parsed === 'object') {
+				const value = (parsed as Record<string, unknown>)[fieldName]
+				if (typeof value === 'string' && normalizeText(value) === normalizedText) {
+					return applyCollectionSource(entry, fieldResult, referenceIndex, { allowStyling: false })
+				}
+			}
+		} catch {
+			// Not valid YAML/JSON
+		}
+	}
+	return undefined
+}
+
 // ============================================================================
 // Image Expression Resolution
 // ============================================================================