@meistrari/tela-build 1.27.0 → 1.27.1

package/components/tela/preview/preview.mdx

@@ -330,3 +330,139 @@ This is useful when you want to prevent fullscreen functionality in certain moda
 - Labels and placeholders support screen readers
 - PDF controls (zoom, page, fullscreen) are keyboard-accessible
 - Error and loading states are communicated in the content area
+
+## Citation Highlighting
+
+When a user clicks on a field in a structured output, the PDF preview navigates to the correct page and highlights the exact text that the LLM cited as the source.
+
+- `resolveCitationReferences(citations, files)` — resolves `attachment_index` to file URLs
+- `useCitationNavigation({ citations })` — manages highlight state
+- `usePdfLoader()` — creates PDF document handle for rendering
+- `CitationTarget` interface — `{ file, page, literal?, rationale? }`
+
+### Citation Data Flow
+
+```
+LLM returns raw citations (attachment_index + page + literal)
+    ↓
+resolveCitationReferences(rawCitations, files)
+    → replaces attachment_index with file URL from files array
+    ↓
+useCitationNavigation({ citations: resolvedCitations })
+    → provides navigateToCitation(path, value), clearCitation()
+    → exposes reactive refs: highlightText, highlightPage, highlightExact, activeFile
+    ↓
+User clicks a field with citation
+    → navigateToCitation("fieldPath")
+    → sets activeFile, highlightPage (page + 1), highlightText (literal), highlightExact (true)
+    ↓
+TelaPreview receives highlight props
+    → renders PDF page with yellow highlight on matching text
+```
+
+### Raw Citation Format (from LLM)
+
+```json
+{
+  "companyName": {
+    "attachment_index": 0,
+    "page": 0,
+    "literal": "ACME Corporation Ltd."
+  },
+  "items": [
+    {
+      "attachment_index": 0,
+      "page": 2,
+      "literal": "Five year term agreement"
+    }
+  ]
+}
+```
+
+- `attachment_index`: 0-based index into the files array
+- `page`: 0-based page index (first page = 0)
+- `literal`: exact text span copied from the source document
+
+### Citation Usage Example
+
+```vue
+<script setup lang="ts">
+import { resolveCitationReferences } from '@meistrari/tela-build/utils/citations'
+
+// 1. Resolve citations: map attachment_index → file URL
+const files = ['vault://abc-123', 'vault://def-456']
+const citations = resolveCitationReferences(rawCitations, files)
+
+// 2. Setup composables
+const { pdfLoader } = usePdfLoader()
+const {
+  highlightText,
+  highlightPage,
+  highlightExact,
+  activeFile,
+  navigateToCitation,
+  clearCitation,
+} = useCitationNavigation({
+  citations: computed(() => citations),
+})
+
+// 3. Compute active citation for the preview
+const activeCitation = computed(() => {
+  if (!activeFile.value || highlightPage.value == null)
+    return null
+  return {
+    file: activeFile.value,
+    page: highlightPage.value,
+    text: highlightText.value ?? undefined,
+  }
+})
+
+// 4. Switch to the cited file when a citation is clicked
+watch(activeCitation, (citation) => {
+  if (!citation) return
+  const match = fileOptions.find(opt => opt.value === citation.file)
+  if (match)
+    selectedVariable.value = match.variable
+})
+
+// 5. Handle citation clicks from your output viewer
+function onCitationClick(path: string, value?: any) {
+  navigateToCitation(path, value)
+}
+</script>
+
+<template>
+  <TelaPreview
+    :model-value="selectedVariable"
+    :file-options="fileOptions"
+    :current-file="currentFile"
+    :pdf-loader="pdfLoader"
+    :highlight-text="activeCitation?.text ?? null"
+    :highlight-page="activeCitation?.page ?? null"
+    :highlight-exact="!!activeCitation"
+    @update:model-value="onVariableChange"
+  />
+</template>
+```
+
+### How the Highlight Works Internally
+
+Two modes in the PDF text layer renderer:
+
+**Exact mode** (citations, `highlightExact = true`):
+1. Concatenates all PDF text items on the page into a single string
+2. Normalizes both the literal and the concatenated text (lowercase, strip accents, collapse whitespace, strip invisible Unicode)
+3. Searches for the literal as a contiguous substring
+4. If exact match fails (PDF text extraction lost characters), falls back to a sliding window of 3 consecutive words
+5. Highlights matching text items with yellow background
+
+**Fuzzy mode** (search, `highlightExact = false`):
+1. Splits highlight text into words (>= 3 chars)
+2. Each text item that contains or is contained by any word gets highlighted
+
+### Citation Key Details
+
+- **Page numbering**: `page` in citations is 0-based. `useCitationNavigation` adds 1 internally for the 1-based PDF viewer.
+- **`path` format**: dot-separated path matching the citations structure. Examples: `"companyName"`, `"items.0"`, `"nested.field.name"`.
+- **Clearing**: call `clearCitation()` when switching context (e.g. changing tasks, closing modals).
+- **File matching**: the `file` value after resolution must match what `TelaPreview` uses to identify files in `fileOptions`.

package/composables/citation-navigation.ts

@@ -1,4 +1,4 @@
-import type { MaybeRefOrGetter, Ref } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
 import { nextTick, ref, toValue } from 'vue'
 
 export interface CitationTarget {
@@ -61,7 +61,7 @@ export function useCitationNavigation(options: {
         highlightExact.value = false
         activeFile.value = null
 
-        nextTick(() => {
+        void nextTick(() => {
             activeFile.value = citation.file
             highlightPage.value = citation.page + 1
             highlightText.value = citation.literal
@@ -78,10 +78,10 @@ export function useCitationNavigation(options: {
     }
 
     return {
-        highlightText: highlightText as Ref<string | null>,
-        highlightPage: highlightPage as Ref<number | null>,
-        highlightExact: highlightExact as Ref<boolean>,
-        activeFile: activeFile as Ref<string | null>,
+        highlightText,
+        highlightPage,
+        highlightExact,
+        activeFile,
         lookupCitation,
         navigateToCitation,
         clearCitation,

package/composables/use-pdf-loader.ts

@@ -0,0 +1,56 @@
+import { onUnmounted, ref } from 'vue'
+import type { PdfDocumentHandle } from '../components/tela/preview/types'
+import { usePdf } from './use-pdf'
+
+export function usePdfLoader() {
+    const pdfUrlRef = ref('')
+    const { loadPdf, renderPage, getPageDimensions } = usePdf(pdfUrlRef)
+    let currentPdfDoc: Awaited<ReturnType<typeof loadPdf>> = null
+
+    async function pdfLoader(url: string): Promise<PdfDocumentHandle | null> {
+        if (currentPdfDoc) {
+            void currentPdfDoc.destroy()
+            currentPdfDoc = null
+        }
+
+        pdfUrlRef.value = url
+
+        const doc = await loadPdf()
+
+        if (!doc)
+            return null
+
+        currentPdfDoc = doc
+
+        const capturedDoc = doc
+        return {
+            numPages: doc.numPages,
+            async renderPage(opts: {
+                pageNum: number
+                canvas: HTMLCanvasElement
+                scale: number
+                textLayer?: HTMLDivElement | null
+                highlight?: string | null
+                highlightPage?: number | null
+                highlightExact?: boolean
+            }) {
+                return await renderPage(opts)
+            },
+            async getPageDimensions(opts: { pageNum: number, scale: number }) {
+                return await getPageDimensions(opts)
+            },
+            destroy() {
+                if (capturedDoc === currentPdfDoc) {
+                    void capturedDoc.destroy()
+                    currentPdfDoc = null
+                }
+            },
+        }
+    }
+
+    onUnmounted(() => {
+        currentPdfDoc = null
+    })
+
+    return { pdfLoader }
+}

package/composables/use-pdf.ts

@@ -0,0 +1,385 @@
+import * as pdfjsLib from 'pdfjs-dist'
+import type { PDFDocumentProxy, PDFPageProxy, RenderTask } from 'pdfjs-dist'
+import type { Ref } from 'vue'
+import { markRaw, onUnmounted, reactive, watch } from 'vue'
+
+if (!pdfjsLib.GlobalWorkerOptions.workerSrc) {
+    pdfjsLib.GlobalWorkerOptions.workerSrc = `https://unpkg.com/pdfjs-dist@${pdfjsLib.version}/build/pdf.worker.min.mjs`
+}
+
+function normalizeForMatch(text: string): string {
+    return text
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036F]/gu, '')
+        .replace(/[\0\u00AD\u200B\uFEFF]/g, '')
+        .replace(/[\u200C\u200D]/gu, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+}
+
+export interface PdfState {
+    pdfDoc: PDFDocumentProxy | null
+    totalPages: number
+    isLoading: boolean
+    loadError: string | null
+}
+
+export interface RenderPageOptions {
+    pageNum: number
+    canvas: HTMLCanvasElement
+    textLayer?: HTMLDivElement | null
+    scale: number
+    highlight?: string | null
+    highlightPage?: number | null
+    /** When true, uses exact matching instead of fuzzy word-based matching */
+    highlightExact?: boolean
+}
+
+export function usePdf(url: Ref<string>) {
+    const state = reactive<PdfState>({
+        pdfDoc: null,
+        totalPages: 0,
+        isLoading: true,
+        loadError: null,
+    })
+
+    let isUnmounted = false
+    const activeRenderTasks = new Map<number, RenderTask>()
+    let isExplicitlyLoading = false
+    const activeCanvasRenders = new WeakMap<
+        HTMLCanvasElement,
+        {
+            promise: Promise<void>
+            cancel: () => void
+            pageNum: number
+            scale: number
+            hasTextLayer: boolean
+            highlight: string | null
+            highlightPage: number | null
+            highlightExact: boolean
+        }
+    >()
+
+    async function loadPdf(): Promise<PDFDocumentProxy | null> {
+        isExplicitlyLoading = true
+        if (isUnmounted)
+            return null
+
+        state.isLoading = true
+        state.loadError = null
+
+        try {
+            const loadingTask = pdfjsLib.getDocument(url.value)
+            const doc = await loadingTask.promise
+
+            if (isUnmounted) {
+                void doc.destroy()
+                return null
+            }
+
+            state.pdfDoc = markRaw(doc)
+            state.totalPages = doc.numPages
+            state.isLoading = false
+            isExplicitlyLoading = false
+
+            return doc
+        }
+        catch (err: any) {
+            isExplicitlyLoading = false
+            if (isUnmounted)
+                return null
+
+            console.error('PDF load error:', err)
+            state.loadError = err?.message || 'Failed to load PDF'
+            state.isLoading = false
+
+            return null
+        }
+    }
+
+    async function renderPage(options: RenderPageOptions): Promise<void> {
+        if (isUnmounted || !state.pdfDoc)
+            return
+
+        const { pageNum, canvas, textLayer, scale, highlight, highlightPage, highlightExact } = options
+        let currentRenderPromise: Promise<void> | null = null
+
+        try {
+            const previousTask = activeRenderTasks.get(pageNum)
+            if (previousTask) {
+                previousTask.cancel()
+                activeRenderTasks.delete(pageNum)
+            }
+
+            const page = await state.pdfDoc.getPage(pageNum)
+
+            if (isUnmounted)
+                return
+
+            const viewport = page.getViewport({ scale })
+            const context = canvas.getContext('2d')
+            if (!context)
+                return
+
+            const existingRender = activeCanvasRenders.get(canvas)
+            if (existingRender) {
+                if (
+                    existingRender.pageNum === pageNum
+                    && existingRender.scale === scale
+                    && existingRender.hasTextLayer === Boolean(textLayer)
+                    && existingRender.highlight === (highlight ?? null)
+                    && existingRender.highlightPage === (highlightPage ?? null)
+                    && existingRender.highlightExact === Boolean(highlightExact)
+                ) {
+                    await existingRender.promise
+                    return
+                }
+
+                existingRender.cancel()
+                try {
+                    await existingRender.promise
+                }
+                catch {
+                    // Expected when we cancel an obsolete render for the same canvas.
+                }
+            }
+
+            canvas.height = viewport.height
+            canvas.width = viewport.width
+
+            const renderTask = page.render({
+                canvasContext: context,
+                viewport,
+            })
+            activeRenderTasks.set(pageNum, renderTask)
+
+            try {
+                await renderTask.promise
+            }
+            finally {
+                if (activeRenderTasks.get(pageNum) === renderTask) {
+                    activeRenderTasks.delete(pageNum)
+                }
+            }
+
+            currentRenderPromise = (async () => {
+                await renderTask.promise
+
+                if (isUnmounted)
+                    return
+
+                if (textLayer) {
+                    if (highlight) {
+                        await renderTextLayer(page, viewport, textLayer, highlight, highlightPage, pageNum, highlightExact)
+                    }
+                    else {
+                        textLayer.innerHTML = ''
+                    }
+                }
+            })()
+
+            activeCanvasRenders.set(canvas, {
+                promise: currentRenderPromise,
+                cancel: () => renderTask.cancel(),
+                pageNum,
+                scale,
+                hasTextLayer: Boolean(textLayer),
+                highlight: highlight ?? null,
+                highlightPage: highlightPage ?? null,
+                highlightExact: Boolean(highlightExact),
+            })
+
+            await currentRenderPromise
+        }
+        catch (err) {
+            if ((err as Error)?.name === 'RenderingCancelledException') {
+                return
+            }
+
+            if (!isUnmounted) {
+                console.error('Error rendering page:', err)
+            }
+        }
+        finally {
+            const activeRender = activeCanvasRenders.get(canvas)
+            if (currentRenderPromise && activeRender?.promise === currentRenderPromise) {
+                activeCanvasRenders.delete(canvas)
+            }
+        }
+    }
+
+    async function renderTextLayer(
+        page: PDFPageProxy,
+        viewport: any,
+        textLayer: HTMLDivElement,
+        highlight?: string | null,
+        highlightPage?: number | null,
+        pageNum?: number,
+        exact?: boolean,
+    ): Promise<void> {
+        if (isUnmounted)
+            return
+
+        textLayer.innerHTML = ''
+        textLayer.style.width = `${viewport.width}px`
+        textLayer.style.height = `${viewport.height}px`
+
+        const textContent = await page.getTextContent()
+
+        if (isUnmounted)
+            return
+
+        const textItems = textContent.items as Array<{ str: string, transform: number[], width: number, height: number }>
+
+        const searchWords: string[] = []
+        const shouldHighlight = highlight && (!highlightPage || highlightPage === pageNum)
+
+        let exactMatchedIndices: Set<number> | null = null
+
+        if (shouldHighlight && highlight) {
+            if (exact) {
+                const normalizedSearch = normalizeForMatch(highlight)
+
+                const ranges: { start: number, end: number }[] = []
+                let concat = ''
+                for (const item of textItems) {
+                    const normalized = normalizeForMatch(item.str)
+                    if (concat.length > 0 && normalized.length > 0)
+                        concat += ' '
+                    const start = concat.length
+                    concat += normalized
+                    ranges.push({ start, end: concat.length })
+                }
+
+                exactMatchedIndices = new Set<number>()
+                let searchFrom = 0
+                while (normalizedSearch.length > 0 && searchFrom <= concat.length - normalizedSearch.length) {
+                    const idx = concat.indexOf(normalizedSearch, searchFrom)
+                    if (idx === -1)
+                        break
+                    const matchEnd = idx + normalizedSearch.length
+                    for (let i = 0; i < ranges.length; i++) {
+                        if (ranges[i]!.end > idx && ranges[i]!.start < matchEnd)
+                            exactMatchedIndices.add(i)
+                    }
+                    searchFrom = idx + 1
+                }
+
+                // Fallback: PDF text extraction can lose characters (e.g. \u0000 replacing
+                // letters), so the full literal won't match as a substring. Use a sliding
+                // window of consecutive words — windows without corrupted words still match.
+                if (exactMatchedIndices.size === 0) {
+                    const words = normalizedSearch.split(/\s+/)
+                    const windowSize = Math.min(3, words.length)
+                    for (let w = 0; w <= words.length - windowSize; w++) {
+                        const segment = words.slice(w, w + windowSize).join(' ')
+                        if (segment.length < 4)
+                            continue
+                        let segFrom = 0
+                        while (segFrom <= concat.length - segment.length) {
+                            const idx = concat.indexOf(segment, segFrom)
+                            if (idx === -1)
+                                break
+                            const matchEnd = idx + segment.length
+                            for (let i = 0; i < ranges.length; i++) {
+                                if (ranges[i]!.end > idx && ranges[i]!.start < matchEnd)
+                                    exactMatchedIndices.add(i)
+                            }
+                            segFrom = idx + 1
+                        }
+                    }
+                }
+            }
+            else {
+                const normalized = normalizeForMatch(highlight).replace(/[^\w\s]/g, ' ')
+
+                normalized.split(/\s+/).forEach((word) => {
+                    if (word.length >= 3)
+                        searchWords.push(word)
+                })
+
+                if (normalized.length >= 3)
+                    searchWords.push(normalized)
+            }
+        }
+
+        for (let itemIndex = 0; itemIndex < textItems.length; itemIndex++) {
+            if (isUnmounted)
+                return
+
+            const item = textItems[itemIndex]!
+            const div = document.createElement('span')
+            const tx = pdfjsLib.Util.transform(viewport.transform, item.transform)
+            const fontHeight = Math.hypot(tx[2], tx[3])
+
+            div.textContent = item.str
+            div.style.position = 'absolute'
+            div.style.left = `${tx[4]}px`
+            div.style.top = `${tx[5] - fontHeight}px`
+            div.style.fontSize = `${fontHeight}px`
+            div.style.fontFamily = 'sans-serif'
+            div.style.color = 'transparent'
+            div.style.whiteSpace = 'nowrap'
+
+            if (item.str.trim()) {
+                let isMatch = false
+
+                if (exact && exactMatchedIndices !== null) {
+                    isMatch = exactMatchedIndices.has(itemIndex)
+                }
+                else if (searchWords.length > 0) {
+                    const itemText = normalizeForMatch(item.str)
+
+                    if (itemText.length >= 2) {
+                        isMatch = searchWords.some(word => word.includes(itemText) || itemText.includes(word))
+                    }
+                }
+
+                if (isMatch) {
+                    div.style.backgroundColor = 'rgba(255, 235, 59, 0.7)'
+                    div.style.borderRadius = '2px'
+                }
+            }
+
+            textLayer.appendChild(div)
+        }
+    }
+
+    async function getPageDimensions(options: { pageNum: number, scale: number }): Promise<{ width: number, height: number } | null> {
+        if (isUnmounted || !state.pdfDoc)
+            return null
+        const page = await state.pdfDoc.getPage(options.pageNum)
+        const viewport = page.getViewport({ scale: options.scale })
+        return { width: viewport.width, height: viewport.height }
+    }
+
+    function cleanup() {
+        isUnmounted = true
+
+        activeRenderTasks.forEach(task => task.cancel())
+        activeRenderTasks.clear()
+
+        if (state.pdfDoc) {
+            void state.pdfDoc.destroy()
+            state.pdfDoc = null
+        }
+    }
+
+    watch(url, () => {
+        if (!isExplicitlyLoading)
+            void loadPdf()
+    })
+
+    onUnmounted(() => {
+        cleanup()
+    })
+
+    return {
+        state,
+        loadPdf,
+        renderPage,
+        getPageDimensions,
+        cleanup,
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-build",
-  "version": "1.27.0",
+  "version": "1.27.1",
   "type": "module",
   "files": [
     "app.config.ts",
@@ -60,6 +60,7 @@
     "ts-morph": "22.0.0",
     "typescript": "5.8.2",
     "unocss": "66.5.12",
+    "pdfjs-dist": "4.10.38",
     "vue": "3.5.13",
     "vue-component-meta": "3.0.8",
     "vue-docgen-api": "4.78.0",

package/utils/citations.ts

@@ -0,0 +1,30 @@
+function resolveAttachment(value: Record<string, any>, files: (string | null)[]): Record<string, any> {
+    const file = files[value.attachment_index] ?? undefined
+    const { attachment_index: _, ...rest } = value
+    return { ...rest, file }
+}
+
+export function resolveCitationReferences(citations: Record<string, any>, files: (string | null)[]): Record<string, any> {
+    const resolved: Record<string, any> = {}
+    for (const [key, value] of Object.entries(citations)) {
+        if (Array.isArray(value)) {
+            resolved[key] = value.map((item) => {
+                if (typeof item !== 'object' || item === null)
+                    return item
+                if ('attachment_index' in item)
+                    return resolveAttachment(item, files)
+                return resolveCitationReferences(item, files)
+            })
+        }
+        else if (value && typeof value === 'object' && 'attachment_index' in value) {
+            resolved[key] = resolveAttachment(value, files)
+        }
+        else if (value && typeof value === 'object') {
+            resolved[key] = resolveCitationReferences(value, files)
+        }
+        else {
+            resolved[key] = value
+        }
+    }
+    return resolved
+}