@nuasite/cms 0.25.0 → 0.27.0

package/package.json

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

package/src/build-processor.ts

@@ -10,7 +10,6 @@ import { extractComponentName, processHtml } from './html-processor'
 import type { ManifestWriter } from './manifest-writer'
 import { generateComponentPreviews } from './preview-generator'
 import {
-	clearCollectionTextIndex,
 	clearSourceFinderCache,
 	extractOpeningTagWithLine,
 	findCollectionSource,
@@ -777,7 +776,6 @@ export async function processBuildOutput(
 
 	// Clear caches from previous builds and initialize search index
 	clearSourceFinderCache()
-	clearCollectionTextIndex()
 
 	const htmlFiles = await findHtmlFiles(outDir)
 

package/src/collection-scanner.ts

@@ -454,12 +454,12 @@ function parseContentConfigReferences(
 	return result
 }
 
-/** Valid field type names exported by `field` helper from @nuasite/cms */
+/** Valid field type names exported by `n` helper from @nuasite/cms */
 const FIELD_HELPER_TYPES = new Set(['image', 'url', 'email', 'color', 'date', 'datetime', 'time', 'textarea'])
 
 /**
  * Parse the content config file to extract explicit field type hints:
- * - `field.image(...)`, `field.url(...)`, etc. from @nuasite/cms
+ * - `n.image()`, `n.url()`, etc. from @nuasite/cms
  * - `z.enum([...])` for select options
  *
  * Returns a map: collectionName → fieldName → { type, options? }
@@ -472,8 +472,8 @@ function parseContentConfigFieldTypes(
 	for (const { collectionName, schemaBody } of schemaBlocks) {
 		const fields = new Map<string, { type: FieldType; options?: string[] }>()
 
-		// Detect field.image(...), field.url(...), etc.
-		const fieldHelpers = schemaBody.matchAll(/(\w+)\s*:\s*field\.(\w+)\s*\(/g)
+		// Detect n.image(), n.url(), etc.
+		const fieldHelpers = schemaBody.matchAll(/(\w+)\s*:\s*n\.(\w+)/g)
 		for (const m of fieldHelpers) {
 			const fieldName = m[1]!
 			const helperName = m[2]!

package/src/dev-middleware.ts

@@ -17,10 +17,10 @@ import { processHtml } from './html-processor'
 import type { ManifestWriter } from './manifest-writer'
 import type { MediaStorageAdapter } from './media/types'
 import {
+	enhanceManifestWithSourceSnippets,
 	findCollectionSource,
 	findImageSourceLocation,
 	findSourceLocation,
-	initializeSearchIndex,
 	parseMarkdownContent,
 	reindexDirtyFiles,
 } from './source-finder'
@@ -302,6 +302,13 @@ export function createDevMiddleware(
 				return res.end(chunk, ...args)
 			}
 
+			// Skip CMS processing for internal preview pages
+			if (requestUrl.startsWith('/_nua/preview')) {
+				res.write = originalWrite
+				res.end = originalEnd
+				return (res.end as any)(chunk, ...args)
+			}
+
 			if (chunk) {
 				chunks!.push(Buffer.from(chunk))
 			}
@@ -424,7 +431,7 @@ async function markHtmlForDev(
  * Phase 2 (background): Resolve source locations, enhance snippets, populate
  * component props, and update the manifest. Runs after the HTML response is sent.
  */
-async function enhanceManifestInBackground(
+export async function enhanceManifestInBackground(
 	pagePath: string,
 	entries: Record<string, ManifestEntry>,
 	components: Record<string, ComponentInstance>,
@@ -541,31 +548,31 @@ async function enhanceManifestInBackground(
 			}
 		}
 
-		// Ensure the search index is initialized
-		await initializeSearchIndex()
+		const enhanced = await enhanceManifestWithSourceSnippets(entries, collectionDefinitions)
 
-		// Re-resolve sources with the search index
-		for (const entry of Object.values(entries)) {
+		// 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 imageSource = await findImageSourceLocation(entry.imageMetadata.src, entry.imageMetadata.srcSet)
-				if (imageSource) {
-					entry.sourcePath = imageSource.file
-					entry.sourceLine = imageSource.line
-					entry.sourceSnippet = imageSource.snippet
+				const loc = await findImageSourceLocation(entry.imageMetadata.src, entry.imageMetadata.srcSet)
+				if (loc) {
+					entry.sourcePath = loc.file
+					entry.sourceLine = loc.line
+					entry.sourceSnippet = loc.snippet
 				}
 			} else if (entry.text && entry.tag) {
-				const textSource = await findSourceLocation(entry.text, entry.tag)
-				if (textSource) {
-					entry.sourcePath = textSource.file
-					entry.sourceLine = textSource.line
-					entry.sourceSnippet = textSource.snippet
-					if (textSource.variableName) entry.variableName = textSource.variableName
+				const loc = await findSourceLocation(entry.text, entry.tag)
+				if (loc) {
+					entry.sourcePath = loc.file
+					entry.sourceLine = loc.line
+					entry.sourceSnippet = loc.snippet
+					if (loc.variableName) entry.variableName = loc.variableName
 				}
 			}
 		}
 
 		// Update the manifest with fully-resolved entries and component props
-		manifestWriter.addPage(pagePath, entries, components, collection, seo)
+		manifestWriter.addPage(pagePath, enhanced, components, collection, seo)
 	} catch (error) {
 		console.error('[cms] Background enhancement failed:', error)
 	}

package/src/editor/components/markdown-editor-overlay.tsx

@@ -4,10 +4,12 @@ import { slugify } from '../../shared'
 import { updateMarkdownPage } from '../api'
 import { STORAGE_KEYS, Z_INDEX } from '../constants'
 import { createMarkdownPage } from '../markdown-api'
+import { MDX_EXPR_PREFIX } from '../milkdown-mdx-plugin'
 import {
 	config,
 	currentMarkdownPage,
 	isMarkdownPreview,
+	manifest,
 	markdownEditorState,
 	pendingCollectionEntries,
 	resetMarkdownEditorState,
@@ -244,6 +246,41 @@ export function MarkdownEditorOverlay() {
 			try {
 				const view = editorInstanceRef.current.ctx.get(editorViewCtx)
 				el.innerHTML = view.dom.innerHTML
+
+				// Replace MDX block cards with rendered component previews
+				el.querySelectorAll('.mdx-block-card-wrapper[data-mdx-component]').forEach((wrapper) => {
+					const name = wrapper.getAttribute('data-mdx-component')
+					if (!name) return
+					const def = manifest.value?.componentDefinitions?.[name]
+					if (!def?.file) return
+
+					const propsJson = wrapper.getAttribute('data-mdx-props') || '{}'
+					const childrenText = wrapper.getAttribute('data-mdx-children') || ''
+					let props: Record<string, string> = {}
+					try {
+						props = JSON.parse(propsJson)
+					} catch {}
+
+					// Filter out expression props
+					const staticProps: Record<string, string> = {}
+					for (const [k, v] of Object.entries(props)) {
+						if (!v.startsWith(MDX_EXPR_PREFIX)) staticProps[k] = v
+					}
+
+					const params = new URLSearchParams({ file: def.file, props: JSON.stringify(staticProps) })
+					if (childrenText) params.set('children', childrenText)
+
+					const iframe = document.createElement('iframe')
+					iframe.src = `/_nua/preview?${params}`
+					iframe.style.cssText = 'width:100%;border:0;display:block;min-height:60px'
+					iframe.onload = () => {
+						try {
+							const h = iframe.contentDocument?.body?.scrollHeight
+							if (h) iframe.style.height = `${h + 16}px`
+						} catch {}
+					}
+					wrapper.replaceWith(iframe)
+				})
 			} catch (error) {
 				console.error('Failed to get editor HTML for preview:', error)
 				originalHTMLRef.current = null

package/src/editor/components/mdx-block-view.tsx

@@ -13,9 +13,12 @@ import {
 import { gfm, toggleStrikethroughCommand } from '@milkdown/preset-gfm'
 import { callCommand, insert, replaceAll } from '@milkdown/utils'
 import type { ComponentChildren } from 'preact'
-import { useCallback, useEffect, useRef, useState } from 'preact/hooks'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import { getComponentDefinition } from '../manifest'
 import { MDX_EXPR_PREFIX } from '../milkdown-mdx-plugin'
 import { type ActiveFormats, defaultActiveFormats, isInListType, setupFormatTracking, toggleHeading } from '../milkdown-utils'
+import { manifest, openMediaLibraryWithCallback } from '../signals'
+import type { ComponentProp } from '../types'
 
 const MDX_COMPONENT_ICON_PATH =
 	'M14 10l-2 1m0 0l-2-1m2 1v2.5M20 7l-2 1m2-1l-2-1m2 1v2.5M14 4l-2-1-2 1M4 7l2-1M4 7l2 1M4 7v2.5M12 21l-2-1m2 1l2-1m-2 1v-2.5M6 18l-2-1v-2.5M18 18l2-1v-2.5'
@@ -301,6 +304,101 @@ function InlineInput({ value, onChange, placeholder }: { value: string; onChange
 	)
 }
 
+const INLINE_INPUT_TYPES: Record<string, string> = {
+	number: 'number',
+	url: 'url',
+	date: 'date',
+	datetime: 'datetime-local',
+	time: 'time',
+	email: 'email',
+}
+const inputClass =
+	'w-full bg-white/5 border border-white/10 rounded-cms-sm px-2.5 py-1.5 text-[13px] text-white/80 placeholder:text-white/30 outline-none focus:border-white/25 transition-colors'
+
+function InlinePropField(
+	{ name, value, propDef, onChange }: { name: string; value: string; propDef?: ComponentProp; onChange: (v: string) => void },
+) {
+	const typeLower = propDef?.type.toLowerCase() ?? ''
+
+	if (typeLower === 'boolean') {
+		return (
+			<div class="flex items-center gap-2">
+				<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+				<label class="flex items-center gap-2 cursor-pointer py-1">
+					<input
+						type="checkbox"
+						checked={value === 'true'}
+						onChange={(e) => onChange((e.target as HTMLInputElement).checked ? 'true' : 'false')}
+						class="accent-cms-primary w-4 h-4 rounded"
+					/>
+					<span class="text-[12px] text-white/60">{value === 'true' ? 'Yes' : 'No'}</span>
+				</label>
+			</div>
+		)
+	}
+
+	if (typeLower === 'image') {
+		return (
+			<div class="flex items-center gap-2">
+				<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+				<div class="flex gap-1.5 flex-1">
+					<InlineInput value={value} onChange={onChange} placeholder="Select an image..." />
+					<button
+						type="button"
+						onClick={() => openMediaLibraryWithCallback((url: string) => onChange(url))}
+						class="px-2 py-1.5 bg-white/5 border border-white/10 text-white/50 hover:text-white hover:bg-white/10 rounded-cms-sm transition-colors shrink-0"
+						title="Browse media"
+					>
+						<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+							<path
+								stroke-linecap="round"
+								stroke-linejoin="round"
+								d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
+							/>
+						</svg>
+					</button>
+				</div>
+			</div>
+		)
+	}
+
+	if (typeLower === 'color') {
+		return (
+			<div class="flex items-center gap-2">
+				<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+				<div class="flex gap-1.5 flex-1 items-center">
+					<input
+						type="color"
+						value={value || '#000000'}
+						onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+						class="w-7 h-7 rounded-cms-sm border border-white/10 bg-transparent cursor-pointer shrink-0"
+					/>
+					<InlineInput value={value} onChange={onChange} placeholder="#000000" />
+				</div>
+			</div>
+		)
+	}
+
+	const htmlType = INLINE_INPUT_TYPES[typeLower]
+
+	return (
+		<div class="flex items-center gap-2">
+			<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+			{htmlType
+				? (
+					<input
+						type={htmlType}
+						value={value}
+						onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+						placeholder={`Enter ${name}...`}
+						class={inputClass}
+					/>
+				)
+				: <InlineInput value={value} onChange={onChange} placeholder={`Enter ${name}...`} />}
+		</div>
+	)
+}
+
 // ============================================================================
 // Block Card
 // ============================================================================
@@ -311,6 +409,14 @@ export function MdxBlockCard({ componentName, props, hasExpressions, slotContent
 	const expressionProps = propEntries.filter(([_, v]) => v.startsWith(MDX_EXPR_PREFIX))
 
 	const hasSlotContent = onSlotContentChange != null
+	const definition = getComponentDefinition(manifest.value, componentName)
+	const propTypes = useMemo(() => {
+		const map = new Map<string, ComponentProp>()
+		if (definition?.props) {
+			for (const p of definition.props) map.set(p.name, p)
+		}
+		return map
+	}, [definition])
 
 	const handlePropChange = (name: string, newValue: string) => {
 		if (onPropsChange) {
@@ -330,21 +436,23 @@ export function MdxBlockCard({ componentName, props, hasExpressions, slotContent
 					<span class="text-[13px] font-semibold text-white">{componentName}</span>
 					{hasExpressions && <span class="text-[10px] px-1.5 py-0.5 bg-amber-500/20 text-amber-300 rounded font-mono">expr</span>}
 				</div>
-				<button
-					type="button"
-					data-mdx-action="remove"
-					onClick={onRemove}
-					class="p-1.5 rounded-cms-sm text-white/50 hover:text-red-400 hover:bg-red-500/10 transition-colors"
-					title="Remove block"
-				>
-					<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-						<path
-							stroke-linecap="round"
-							stroke-linejoin="round"
-							d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
-						/>
-					</svg>
-				</button>
+				<div class="flex items-center gap-1">
+					<button
+						type="button"
+						data-mdx-action="remove"
+						onClick={onRemove}
+						class="p-1.5 rounded-cms-sm text-white/50 hover:text-red-400 hover:bg-red-500/10 transition-colors"
+						title="Remove block"
+					>
+						<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+							<path
+								stroke-linecap="round"
+								stroke-linejoin="round"
+								d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
+							/>
+						</svg>
+					</button>
+				</div>
 			</div>
 
 			{/* Slot content editor */}
@@ -361,14 +469,13 @@ export function MdxBlockCard({ componentName, props, hasExpressions, slotContent
 			{onPropsChange && editableProps.length > 0 && (
 				<div class="px-4 py-3 space-y-2" data-mdx-action="props">
 					{editableProps.map(([name, value]) => (
-						<div key={name} class="flex items-center gap-2">
-							<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
-							<InlineInput
-								value={value}
-								onChange={(v) => handlePropChange(name, v)}
-								placeholder={`Enter ${name}...`}
-							/>
-						</div>
+						<InlinePropField
+							key={name}
+							name={name}
+							value={value}
+							propDef={propTypes.get(name)}
+							onChange={(v) => handlePropChange(name, v)}
+						/>
 					))}
 				</div>
 			)}

package/src/editor/milkdown-mdx-plugin.tsx

@@ -240,6 +240,11 @@ export const mdxComponentView = $view(mdxComponentNode, () => {
 		const renderCard = (node: PmNode) => {
 			const componentName = node.attrs.componentName as string
 			const propsJson = node.attrs.props as string
+
+			// Store attrs on the wrapper so preview mode can read them from copied DOM
+			container.setAttribute('data-mdx-component', componentName)
+			container.setAttribute('data-mdx-props', propsJson)
+			container.setAttribute('data-mdx-children', (node.attrs.children as string) || '')
 			const props: Record<string, string> = JSON.parse(propsJson)
 			const hasExpressions = node.attrs.hasExpressions as boolean
 			const children = (node.attrs.children as string) || ''

package/src/field-types.ts

@@ -1,42 +1,47 @@
+import { z } from 'astro/zod'
+
 /**
- * Semantic field type wrappers for Zod schemas in content collections.
+ * Semantic field type schemas for content collections.
  *
- * These are identity functions — they return exactly what's passed in.
- * The CMS collection scanner detects them by name in the source and
- * renders the appropriate editor input.
+ * Each method returns a `z.string()` schema that Astro resolves
+ * statically (concrete return type, no generics). The CMS collection
+ * scanner detects them by name in the source and renders the
+ * appropriate editor input.
+ *
+ * Chain Zod methods as usual (`.optional()`, `.default()`, etc.).
  *
  * @example
  * ```ts
- * import { field } from '@nuasite/cms'
+ * import { n } from '@nuasite/cms'
  * import { z } from 'astro/zod'
  *
  * const schema = z.object({
- *   photo: field.image(z.string()),
- *   website: field.url(z.string()),
- *   contact: field.email(z.string()),
- *   accent: field.color(z.string()),
- *   publishedAt: field.date(z.string()),
- *   startsAt: field.datetime(z.string()),
- *   opensAt: field.time(z.string()),
- *   bio: field.textarea(z.string()),
+ *   photo: n.image(),
+ *   website: n.url().optional(),
+ *   contact: n.email(),
+ *   accent: n.color(),
+ *   publishedAt: n.date(),
+ *   startsAt: n.datetime(),
+ *   opensAt: n.time(),
+ *   bio: n.textarea(),
  * })
  * ```
  */
-export const field = {
+export const n = {
 	/** Image picker (opens media library) */
-	image: <T>(schema: T): T => schema,
+	image: () => z.string().describe('cms:image'),
 	/** URL input */
-	url: <T>(schema: T): T => schema,
+	url: () => z.string().describe('cms:url'),
 	/** Email input */
-	email: <T>(schema: T): T => schema,
+	email: () => z.string().describe('cms:email'),
 	/** Color picker */
-	color: <T>(schema: T): T => schema,
+	color: () => z.string().describe('cms:color'),
 	/** Date picker */
-	date: <T>(schema: T): T => schema,
+	date: () => z.string().describe('cms:date'),
 	/** Date + time picker */
-	datetime: <T>(schema: T): T => schema,
+	datetime: () => z.string().describe('cms:datetime'),
 	/** Time picker */
-	time: <T>(schema: T): T => schema,
+	time: () => z.string().describe('cms:time'),
 	/** Multiline textarea */
-	textarea: <T>(schema: T): T => schema,
+	textarea: () => z.string().describe('cms:textarea'),
 }

package/src/index.ts

@@ -119,10 +119,17 @@ export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
 	return {
 		name: '@nuasite/cms',
 		hooks: {
-			'astro:config:setup': async ({ updateConfig, command, injectScript, logger }) => {
+			'astro:config:setup': async ({ updateConfig, command, injectScript, injectRoute, logger }) => {
 				// CMS is only needed during dev — skip all setup during build
 				if (command !== 'dev') return
 
+				// Inject dev-only component preview route (prerender:false → SSR with query param access)
+				injectRoute({
+					pattern: '/_nua/preview',
+					entrypoint: new URL('./pages/component-preview.astro', import.meta.url).pathname,
+					prerender: false,
+				})
+
 				// --- CMS Marker setup ---
 				idCounter.value = 0
 				manifestWriter.reset()
@@ -200,13 +207,17 @@ export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
 					injectScript(
 						'page',
 						`
-						${configScript}
-						if (!document.querySelector('script[data-nuasite-cms]')) {
-							const s = document.createElement('script');
-							s.type = 'module';
-							s.src = ${JSON.stringify(editorSrc)};
-							s.dataset.nuasiteCms = '';
-							document.head.appendChild(s);
+						if (window.location.pathname.startsWith('/_nua/')) {
+							// Skip CMS editor on internal preview pages
+						} else {
+							${configScript}
+							if (!document.querySelector('script[data-nuasite-cms]')) {
+								const s = document.createElement('script');
+								s.type = 'module';
+								s.src = ${JSON.stringify(editorSrc)};
+								s.dataset.nuasiteCms = '';
+								document.head.appendChild(s);
+							}
 						}
 					`,
 					)
@@ -346,7 +357,7 @@ async function mergeRedirects(dir: URL, logger: { info: (msg: string) => void })
 	logger.info(`Merged ${lineCount} CMS redirect(s) into _redirects`)
 }
 
-export { field } from './field-types'
+export { n } from './field-types'
 export { createContemberStorageAdapter as contemberMedia } from './media/contember'
 export { createLocalStorageAdapter as localMedia } from './media/local'
 export { createS3StorageAdapter as s3Media } from './media/s3'

package/src/pages/component-preview.astro

@@ -0,0 +1,56 @@
+---
+// @ts-ignore — virtual module provided by CMS vite plugin
+import { components } from 'virtual:cms-component-preview'
+
+const componentFile = Astro.url.searchParams.get('file')
+const childrenMarkdown = Astro.url.searchParams.get('children')
+
+let props: Record<string, unknown> = {}
+const propsParam = Astro.url.searchParams.get('props')
+if (propsParam) {
+	try {
+		props = JSON.parse(propsParam)
+	} catch {}
+}
+
+const loader = componentFile ? components[componentFile] : undefined
+const Component = loader ? (await loader()).default : null
+
+// Render markdown children to HTML
+let childrenHtml = ''
+if (childrenMarkdown) {
+	try {
+		const { unified } = await import('unified')
+		const { default: remarkParse } = await import('remark-parse')
+		const { default: remarkRehype } = await import('remark-rehype')
+		const { default: rehypeStringify } = await import('rehype-stringify')
+		const result = await unified().use(remarkParse).use(remarkRehype).use(rehypeStringify).process(childrenMarkdown)
+		childrenHtml = String(result)
+	} catch {
+		childrenHtml = childrenMarkdown
+	}
+}
+
+// Import the project's global CSS so components render with correct styles.
+// Glob matches common CSS entry points — Vite resolves relative to project root.
+const globalStyles = import.meta.glob(['/src/styles/**/*.css', '/src/styles/**/*.scss'], { eager: true })
+---
+
+<html>
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<style>
+			html, body { margin: 0; padding: 0; background: white; }
+			body { padding: 8px; }
+		</style>
+	</head>
+	<body>
+		{Component
+			? childrenHtml
+				? <Component {...props}><Fragment set:html={childrenHtml} /></Component>
+				: <Component {...props} />
+			: <p style="color:#888;font-size:13px;margin:0">No preview available</p>
+		}
+	</body>
+</html>

package/src/source-finder/cache.ts

@@ -1,4 +1,4 @@
-import type { CachedParsedFile, ImageIndexEntry, SearchIndexEntry } from './types'
+import type { CachedParsedFile, ImageIndexEntry, SearchIndexEntry, SourceLocation } from './types'
 
 // ============================================================================
 // File Parsing Cache - Avoid re-parsing the same files
@@ -18,6 +18,9 @@ const textSearchIndex: SearchIndexEntry[] = []
 const imageSearchIndex: ImageIndexEntry[] = []
 let searchIndexInitialized = false
 
+/** Pre-built reverse index: normalizedText → SourceLocation[] (collection data files) */
+let collectionTextIndex: Map<string, SourceLocation[]> | null = null
+
 /** Files that changed since last indexing — tracked by Vite watcher */
 const dirtyFiles = new Set<string>()
 
@@ -61,6 +64,14 @@ export function addToImageSearchIndex(entry: ImageIndexEntry): void {
 	imageSearchIndex.push(entry)
 }
 
+export function getCollectionTextIndex(): Map<string, SourceLocation[]> | null {
+	return collectionTextIndex
+}
+
+export function setCollectionTextIndex(index: Map<string, SourceLocation[]> | null): void {
+	collectionTextIndex = index
+}
+
 // ============================================================================
 // Dirty File Tracking (incremental re-indexing)
 // ============================================================================
@@ -120,4 +131,5 @@ export function clearSourceFinderCache(): void {
 	textSearchIndex.length = 0
 	imageSearchIndex.length = 0
 	searchIndexInitialized = false
+	collectionTextIndex = null
 }