@nuasite/cms 0.39.0 → 0.39.1

package/dist/editor.js

@@ -381,7 +381,7 @@ function WS(t, e) {
 function KS(t, e) {
   return typeof e == "function" ? e(t) : e;
 }
-const v3 = "0.39.0", k3 = v3, nt = {
+const v3 = "0.39.1", k3 = v3, nt = {
   /** Highlight overlay for hovered elements */
   HIGHLIGHT: 2147483644,
   /** Hover outline for elements/components */

package/package.json

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

package/src/build-processor.ts

@@ -5,7 +5,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { getProjectRoot } from './config'
 import { detectArrayPattern, extractArrayElementProps } from './handlers/array-ops'
-import { extractPropsFromSource, findComponentInvocationLine, findFrontmatterEnd } from './handlers/component-ops'
+import { extractPropsFromSource, findComponentInvocationLine, findFrontmatterEnd, getPageFileCandidates } from './handlers/component-ops'
 import { extractComponentName, processHtml } from './html-processor'
 import type { ManifestWriter } from './manifest-writer'
 import { generateComponentPreviews } from './preview-generator'
@@ -374,13 +374,27 @@ async function processFile(
 		}
 	}
 
+	const pageFiles = getPageFileCandidates(pagePath)
+
 	// Process entries in parallel for better performance
 	const entryLookups = Object.values(result.entries).map(async (entry) => {
 		// Handle image entries specially - always search by image src
 		// The sourcePath from HTML attributes may point to a shared Image component
 		// rather than the file that actually uses the component with the src value
 		if (entry.imageMetadata?.src) {
-			const imageSource = await findImageSourceLocation(entry.imageMetadata.src, entry.imageMetadata.srcSet)
+			const preferredLocation = entry.sourcePath
+				? {
+					file: entry.sourcePath,
+					line: entry.sourceLine,
+					srcOccurrence: entry.imageMetadata.srcOccurrence,
+				}
+				: undefined
+			const imageSource = await findImageSourceLocation(
+				entry.imageMetadata.src,
+				entry.imageMetadata.srcSet,
+				pageFiles,
+				preferredLocation,
+			)
 			if (imageSource) {
 				entry.sourcePath = imageSource.file
 				entry.sourceLine = imageSource.line
@@ -412,7 +426,7 @@ async function processFile(
 		}
 
 		// Fall back to searching Astro files
-		const sourceLocation = await findSourceLocation(entry.text, entry.tag)
+		const sourceLocation = await findSourceLocation(entry.text, entry.tag, pageFiles)
 		if (sourceLocation) {
 			entry.sourcePath = sourceLocation.file
 			entry.sourceLine = sourceLocation.line

package/src/dev-middleware.ts

@@ -591,20 +591,33 @@ export async function enhanceManifestInBackground(
 			}
 		}
 
-		const enhanced = await enhanceManifestWithSourceSnippets(entries, collectionDefinitions)
+		const pageFiles = getPageFileCandidates(pagePath)
+		const enhanced = await enhanceManifestWithSourceSnippets(entries, collectionDefinitions, pageFiles)
 
 		// Fallback for entries without sourcePath — search index can still find them
 		for (const entry of Object.values(enhanced)) {
 			if (entry.sourceSnippet || entry.sourcePath) continue
 			if (entry.imageMetadata?.src) {
-				const loc = await findImageSourceLocation(entry.imageMetadata.src, entry.imageMetadata.srcSet)
+				const preferredLocation = entry.sourcePath
+					? {
+						file: entry.sourcePath,
+						line: entry.sourceLine,
+						srcOccurrence: entry.imageMetadata.srcOccurrence,
+					}
+					: undefined
+				const loc = await findImageSourceLocation(
+					entry.imageMetadata.src,
+					entry.imageMetadata.srcSet,
+					pageFiles,
+					preferredLocation,
+				)
 				if (loc) {
 					entry.sourcePath = loc.file
 					entry.sourceLine = loc.line
 					entry.sourceSnippet = loc.snippet
 				}
 			} else if (entry.text && entry.tag) {
-				const loc = await findSourceLocation(entry.text, entry.tag)
+				const loc = await findSourceLocation(entry.text, entry.tag, pageFiles)
 				if (loc) {
 					entry.sourcePath = loc.file
 					entry.sourceLine = loc.line

package/src/html-processor.ts

@@ -662,6 +662,12 @@ export async function processHtml(
 		sourceLine?: number
 	}
 	const imageEntries = new Map<string, ImageEntry>()
+	// Per (sourceFile, src) DOM-order occurrence counter. When the same image
+	// URL appears N times rendered from the same source file, this lets us
+	// map each rendered `<img>` to the Nth index entry for that (file, src)
+	// — disambiguating cases where data-astro-source-loc alone doesn't (e.g.
+	// when only a wrapper element carries the source attribution).
+	const srcOccurrenceCounts = new Map<string, number>()
 	root.querySelectorAll('img').forEach((node) => {
 		// Skip if already marked
 		if (node.getAttribute(attributeName)) return
@@ -682,12 +688,17 @@ export async function processHtml(
 
 		const { sourceFile, sourceLine } = findAncestorSourceLocation(node)
 
+		const occurrenceKey = `${sourceFile ?? ''}\0${src}`
+		const srcOccurrence = srcOccurrenceCounts.get(occurrenceKey) ?? 0
+		srcOccurrenceCounts.set(occurrenceKey, srcOccurrence + 1)
+
 		// Build image metadata
 		const metadata: ImageMetadata = {
 			src,
 			alt: node.getAttribute('alt') || '',
 			srcSet: node.getAttribute('srcset') || undefined,
 			sizes: node.getAttribute('sizes') || undefined,
+			srcOccurrence,
 		}
 
 		// Store image info for manifest

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

@@ -141,21 +141,28 @@ function parseSrcsetUrls(srcSet: string): string[] {
  * Also checks srcset URLs as fallback when src doesn't match (e.g., when src
  * is a local upload path but srcset contains CDN-transformed original URLs).
  * Uses pre-built search index for fast lookups.
+ *
+ * `pageFiles` disambiguates the same image URL across pages.
+ * `preferredLocation` disambiguates the same image URL within one page —
+ * pass the manifest entry's Astro attribution and the lookup will return the
+ * matching per-occurrence index entry when one exists.
  */
 export async function findImageSourceLocation(
 	imageSrc: string,
 	imageSrcSet?: string,
+	pageFiles?: readonly string[],
+	preferredLocation?: { file: string; line?: number; srcOccurrence?: number },
 ): Promise<SourceLocation | undefined> {
 	// Use index if available (much faster)
 	if (isSearchIndexInitialized()) {
-		const result = findInImageIndex(imageSrc)
+		const result = findInImageIndex(imageSrc, pageFiles, preferredLocation)
 		if (result) return result
 
 		// Fallback: try URLs extracted from srcset
 		if (imageSrcSet) {
 			const srcsetUrls = parseSrcsetUrls(imageSrcSet)
 			for (const url of srcsetUrls) {
-				const srcsetResult = findInImageIndex(url)
+				const srcsetResult = findInImageIndex(url, pageFiles, preferredLocation)
 				if (srcsetResult) return srcsetResult
 			}
 		}

package/src/source-finder/search-index.ts

@@ -24,7 +24,7 @@ import {
 	setSearchIndexInitialized,
 } from './cache'
 import { extractAstroImageOriginalUrl, extractImageSnippet, extractInnerHtmlFromSnippet, normalizeText } from './snippet-utils'
-import type { CachedParsedFile, SearchIndexEntry, SourceLocation } from './types'
+import type { CachedParsedFile, ImageIndexEntry, SearchIndexEntry, SourceLocation } from './types'
 
 /** Collection data files live under this path — used to prefer them over templates */
 const CONTENT_DIR_PREFIX = 'src/content/'
@@ -1268,6 +1268,37 @@ function textEntryToLocation(entry: SearchIndexEntry): SourceLocation {
 	}
 }
 
+/** Helper to build SourceLocation from an image index entry */
+function imageEntryToLocation(entry: ImageIndexEntry): SourceLocation {
+	return {
+		file: entry.file,
+		line: entry.line,
+		snippet: entry.snippet,
+		type: 'static',
+	}
+}
+
+/**
+ * Classify a candidate result by file priority and stash it into the right
+ * bucket. Returns the result if it's a collection-file match (caller should
+ * return immediately — collection data files are always authoritative).
+ */
+interface RankedMatches {
+	page?: SourceLocation
+	other?: SourceLocation
+}
+function rankAndStash(
+	file: string,
+	result: SourceLocation,
+	pageFiles: readonly string[] | undefined,
+	matches: RankedMatches,
+): SourceLocation | undefined {
+	if (isCollectionFile(file)) return result
+	if (pageFiles?.includes(file)) matches.page ??= result
+	else matches.other ??= result
+	return undefined
+}
+
 /**
  * Look up an i18n dictionary entry by its literal key (e.g. `nav.prague4`),
  * preferring the match whose value equals `normalizedText` so the right locale
@@ -1325,55 +1356,56 @@ function toProjectRelativePath(file: string): string {
 }
 
 /**
- * Fast text lookup using pre-built index
+ * Fast text lookup using pre-built index.
+ *
+ * Priority order: collection data files > entries in `pageFiles` > anything
+ * else. Translation-tag (i18n dictionary) hits beat non-collection template
+ * matches — a dictionary entry is an authoritative translatable signal
+ * whereas a same-text template hit is often coincidental.
  */
-export function findInTextIndex(textContent: string, tag: string): SourceLocation | undefined {
+export function findInTextIndex(
+	textContent: string,
+	tag: string,
+	pageFiles?: readonly string[],
+): SourceLocation | undefined {
 	const normalizedSearch = normalizeText(textContent)
 	const tagLower = tag.toLowerCase()
 	const index = getTextSearchIndex()
-
-	// Single pass for exact matches: collect the best same-tag template hit
-	// *and* any i18n dictionary hit at once. A JSON dictionary entry is an
-	// authoritative translatable signal, so it beats a non-collection
-	// template match (which is often a coincidental same-text element).
-	let bestMatch: SourceLocation | undefined
+	const matches: RankedMatches = {}
 	let translationHit: SourceLocation | undefined
+
 	for (const entry of index) {
 		if (entry.normalizedText !== normalizedSearch) continue
 		if (entry.tag === tagLower) {
-			const result = textEntryToLocation(entry)
-			if (isCollectionFile(entry.file)) return result
-			bestMatch ??= result
+			const collectionHit = rankAndStash(entry.file, textEntryToLocation(entry), pageFiles, matches)
+			if (collectionHit) return collectionHit
 		} else if (entry.tag === TRANSLATION_TAG_MARKER) {
 			translationHit ??= textEntryToLocation(entry)
 		}
 	}
 	if (translationHit) return translationHit
-	if (bestMatch) return bestMatch
+	const sameTag = matches.page ?? matches.other
+	if (sameTag) return sameTag
 
-	// Then try partial match for longer text — prefer collection data files
 	if (normalizedSearch.length > 10) {
 		const textPreview = normalizedSearch.slice(0, Math.min(30, normalizedSearch.length))
 		for (const entry of index) {
-			if (entry.tag === tagLower && entry.normalizedText.includes(textPreview)) {
-				const result = textEntryToLocation(entry)
-				if (isCollectionFile(entry.file)) return result
-				bestMatch ??= result
-			}
+			if (entry.tag !== tagLower) continue
+			if (!entry.normalizedText.includes(textPreview)) continue
+			const collectionHit = rankAndStash(entry.file, textEntryToLocation(entry), pageFiles, matches)
+			if (collectionHit) return collectionHit
 		}
-		if (bestMatch) return bestMatch
+		const partial = matches.page ?? matches.other
+		if (partial) return partial
 	}
 
-	// Try any tag match — prefer collection data files
 	for (const entry of index) {
-		if (entry.normalizedText === normalizedSearch) {
-			const result = textEntryToLocation(entry)
-			if (isCollectionFile(entry.file)) return result
-			bestMatch ??= result
-		}
+		if (entry.normalizedText !== normalizedSearch) continue
+		const collectionHit = rankAndStash(entry.file, textEntryToLocation(entry), pageFiles, matches)
+		if (collectionHit) return collectionHit
 	}
 
-	return bestMatch
+	return matches.page ?? matches.other
 }
 
 /**
@@ -1388,34 +1420,57 @@ function extractPathname(src: string): string {
 }
 
 /**
- * Fast image lookup using pre-built index
+ * Fast image lookup using pre-built index.
+ *
+ * Priority order:
+ *   1. `preferredLocation` (file, srcOccurrence) — Nth index entry for
+ *      (src, file). Deterministic per-DOM-order; preferred over `line` because
+ *      Astro's `data-astro-source-loc` often points at a common ancestor and
+ *      collides for multiple imgs sharing the same src.
+ *   2. `preferredLocation` (file, line) exact match — used when occurrence
+ *      isn't provided (Astro's stamping happens to be precise enough).
+ *   3. Collection data files (always authoritative).
+ *   4. Entries in `pageFiles` — disambiguates same image across multiple pages.
+ *   5. Any other match.
  */
-export function findInImageIndex(imageSrc: string): SourceLocation | undefined {
+export function findInImageIndex(
+	imageSrc: string,
+	pageFiles?: readonly string[],
+	preferredLocation?: { file: string; line?: number; srcOccurrence?: number },
+): SourceLocation | undefined {
 	const index = getImageSearchIndex()
 
 	// Dev-mode optimized URLs (`/_image?href=...`, `/@image/...?f=...`) embed the source
 	// path; try both the raw URL and the decoded path so callers don't need to pre-decode.
 	const decoded = extractAstroImageOriginalUrl(imageSrc)
 	const candidates = decoded && decoded !== imageSrc ? [imageSrc, decoded] : [imageSrc]
-
-	// Exact match — prefer collection data files (src/content/) over templates.
-	// The same image URL can appear in both a collection data file and a template
-	// that statically renders the collection. The data file is the authoritative source.
-	let bestMatch: SourceLocation | undefined
+	// Astro stamps absolute paths in `data-astro-source-file`; the index uses
+	// project-relative paths. Normalize before comparing.
+	const preferredFile = preferredLocation ? toProjectRelativePath(preferredLocation.file) : undefined
+	const preferredLine = preferredLocation?.line
+	const preferredOccurrence = preferredLocation?.srcOccurrence
+
+	const matches: RankedMatches = {}
+	let occurrenceCounter = 0
+	let occurrenceMatch: SourceLocation | undefined
+	let lineMatch: SourceLocation | undefined
 	for (const entry of index) {
 		if (!candidates.includes(entry.src)) continue
-		const result: SourceLocation = {
-			file: entry.file,
-			line: entry.line,
-			snippet: entry.snippet,
-			type: 'static',
-		}
-		if (isCollectionFile(entry.file)) {
-			return result // Collection data file — always preferred
+		if (preferredFile && entry.file === preferredFile) {
+			if (preferredOccurrence !== undefined && occurrenceCounter++ === preferredOccurrence) {
+				occurrenceMatch ??= imageEntryToLocation(entry)
+			}
+			if (preferredLine !== undefined && entry.line === preferredLine) {
+				lineMatch ??= imageEntryToLocation(entry)
+			}
 		}
-		bestMatch ??= result // Keep first non-collection match as fallback
+		const collectionHit = rankAndStash(entry.file, imageEntryToLocation(entry), pageFiles, matches)
+		if (collectionHit) return collectionHit
 	}
-	if (bestMatch) return bestMatch
+	if (occurrenceMatch) return occurrenceMatch
+	if (lineMatch) return lineMatch
+	const exact = matches.page ?? matches.other
+	if (exact) return exact
 
 	// Fallback: path suffix matching for CDN-transformed URLs
 	// e.g., rendered src "/cdn-cgi/image/.../assets/photo.webp" should match
@@ -1423,19 +1478,11 @@ export function findInImageIndex(imageSrc: string): SourceLocation | undefined {
 	const targetPath = extractPathname(imageSrc)
 	for (const entry of index) {
 		const entryPath = extractPathname(entry.src)
-		if (entryPath.length > 5 && (targetPath.endsWith(entryPath) || entryPath.endsWith(targetPath))) {
-			const result: SourceLocation = {
-				file: entry.file,
-				line: entry.line,
-				snippet: entry.snippet,
-				type: 'static',
-			}
-			if (isCollectionFile(entry.file)) {
-				return result
-			}
-			bestMatch ??= result
-		}
+		if (entryPath.length <= 5) continue
+		if (!targetPath.endsWith(entryPath) && !entryPath.endsWith(targetPath)) continue
+		const collectionHit = rankAndStash(entry.file, imageEntryToLocation(entry), pageFiles, matches)
+		if (collectionHit) return collectionHit
 	}
 
-	return bestMatch
+	return matches.page ?? matches.other
 }

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

@@ -629,6 +629,7 @@ function resolveTranslationKeyFromSnippet(
 export async function enhanceManifestWithSourceSnippets(
 	entries: Record<string, ManifestEntry>,
 	collectionDefinitions?: Record<string, CollectionDefinition>,
+	pageFiles?: readonly string[],
 ): Promise<Record<string, ManifestEntry>> {
 	// Ensure the search index is ready (returns immediately if already built,
 	// otherwise waits for the in-flight initialization or triggers a new one).
@@ -750,7 +751,19 @@ export async function enhanceManifestWithSourceSnippets(
 			}
 
 			// ── Non-collection images: find via search index / AST ──
-			const imageLocation = await findImageSourceLocation(entry.imageMetadata.src, entry.imageMetadata.srcSet)
+			const preferredLocation = entry.sourcePath
+				? {
+					file: entry.sourcePath,
+					line: entry.sourceLine,
+					srcOccurrence: entry.imageMetadata.srcOccurrence,
+				}
+				: undefined
+			const imageLocation = await findImageSourceLocation(
+				entry.imageMetadata.src,
+				entry.imageMetadata.srcSet,
+				pageFiles,
+				preferredLocation,
+			)
 			if (imageLocation) {
 				const sourceHash = generateSourceHash(imageLocation.snippet || entry.imageMetadata.src)
 				const updated: ManifestEntry = {
@@ -862,7 +875,7 @@ export async function enhanceManifestWithSourceSnippets(
 				? findVariableHitInFile(trimmedEntryText, entry.tag, entry.sourcePath)
 				: undefined
 			const noCoords = !entry.sourcePath || !entry.sourceLine
-			const winner = sameFileHit ?? (noCoords ? findInTextIndex(trimmedEntryText, entry.tag) : undefined)
+			const winner = sameFileHit ?? (noCoords ? findInTextIndex(trimmedEntryText, entry.tag, pageFiles) : undefined)
 
 			if (winner) {
 				if (isTranslationFilePath(winner.file)) {
@@ -1059,7 +1072,7 @@ export async function enhanceManifestWithSourceSnippets(
 
 					// Last resort — consult the text index (covers i18n JSON dictionaries
 					// and any other indexed text that shares no tag with the rendered element).
-					const indexHit = findInTextIndex(trimmedText, entry.tag)
+					const indexHit = findInTextIndex(trimmedText, entry.tag, pageFiles)
 					if (indexHit && indexHit.file !== entry.sourcePath) {
 						const resolved = await applyTranslationSource(entry, indexHit, attributes, colorClasses)
 						return [id, resolved] as const

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

@@ -17,14 +17,18 @@ import type { SourceLocation } from './types'
 /**
  * Find source file and line number for text content.
  * Uses pre-built search index for fast lookups.
+ *
+ * `pageFiles` disambiguates when the same text appears on multiple pages —
+ * the lookup prefers index entries whose file is one of the candidates.
  */
 export async function findSourceLocation(
 	textContent: string,
 	tag: string,
+	pageFiles?: readonly string[],
 ): Promise<SourceLocation | undefined> {
 	// Use index if available (much faster)
 	if (isSearchIndexInitialized()) {
-		const indexHit = findInTextIndex(textContent, tag)
+		const indexHit = findInTextIndex(textContent, tag, pageFiles)
 		if (indexHit) return indexHit
 		// Fall through to slow search on miss — covers cases the per-file
 		// indexer can't pre-emit, like a child component's `.map()` over a

package/src/types.ts

@@ -70,6 +70,10 @@ export interface ImageMetadata {
 	srcSet?: string
 	/** Image sizes attribute */
 	sizes?: string
+	/** 0-based DOM-order index of this `<img>` among same-(src, sourceFile)
+	 *  occurrences on the page. Disambiguates source location when the same
+	 *  image URL appears multiple times in the same source file. */
+	srcOccurrence?: number
 }
 
 /** Identifies the (collection, entry, field) destination for an editor upload. */