@meistrari/tela-build 1.26.0 → 1.27.1

package/components/tela/menubar/menubar-item.vue

@@ -22,7 +22,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits)
     <MenubarItem
         v-bind="forwarded"
         :class="cn(
-            'relative flex cursor-pointer select-none items-center rounded-xl px-3 py-1.5 text-body-14-medium font-460 outline-none focus:bg-gray-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-40',
+            'relative flex cursor-pointer select-none items-center rounded-xl px-3 py-1.5 text-body-14-medium font-460 outline-none focus:bg-muted data-[disabled]:pointer-events-none data-[disabled]:opacity-40',
             inset && 'pl-8',
             props.class,
         )"

package/components/tela/menubar/menubar-trigger.vue

@@ -17,7 +17,7 @@ const forwardedProps = useForwardProps(delegatedProps)
         v-bind="forwardedProps"
         :class="
             cn(
-                'flex items-center gap-2 cursor-pointer select-none px-2 py-1.5 text-sm font-medium outline-none rounded-lg hover:bg-gray-200 data-[state=open]:bg-gray-200',
+                'flex items-center gap-2 cursor-pointer select-none px-2 py-1.5 text-sm font-medium outline-none rounded-lg hover:bg-lowered data-[state=open]:bg-lowered',
                 props.class,
             )
         "

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/components/tela/sidebar/sidebar-content.vue

@@ -0,0 +1,10 @@
+<template>
+    <div
+        flex flex-col h-full overflow-y-auto no-scrollbar
+        class="[mask-image:linear-gradient(to_bottom,transparent,black_20px,black_calc(100%_-_20px),transparent)]"
+    >
+        <nav flex flex-col items-center gap-14px h-full px-10px pt-12px mb-48px>
+            <slot />
+        </nav>
+    </div>
+</template>

package/components/tela/sidebar/sidebar-footer.vue

@@ -0,0 +1,5 @@
+<template>
+    <footer flex flex-col items-center justify-center gap-22px pb-24px>
+        <slot />
+    </footer>
+</template>

package/components/tela/sidebar/sidebar-header.vue

@@ -0,0 +1,5 @@
+<template>
+    <header sticky top-0 z-10 flex flex-col items-center justify-center gap-24px pt-24px pb-12px>
+        <slot />
+    </header>
+</template>

package/components/tela/sidebar/sidebar-item.vue

@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { NuxtLink } from '#components'
+
+const props = defineProps<{
+    icon: string
+    label: string
+    to?: string
+    onClick?: () => void
+    isActive: boolean
+}>()
+
+const iconName = computed(() => props.isActive ? `${props.icon}-fill` : props.icon)
+</script>
+
+<template>
+    <component
+        :is="to ? NuxtLink : 'button'"
+        :to="to"
+        :type="!to ? 'button' : undefined"
+        class="group"
+        flex="~ col" items-center justify-center gap-2px outline-none
+        :data-active="isActive"
+        v-bind="!to && onClick ? { onClick } : {}"
+    >
+        <div relative size-40px flex items-center justify-center rounded-10px>
+            <TelaIcon
+                :name="iconName"
+                size="20px"
+                relative z-1
+                :color="isActive ? 'icon' : 'icon-tertiary duration-150 ease-out group-hover:icon group-focus-within:icon'"
+            />
+            <div
+                :class="cn(
+                    'absolute inset-0 size-full rounded-[14px] z-0 border-[0.5px] border-transparent',
+                    isActive ? 'bg-neutral-200 group-focus-within:border-strong' : 'bg scale-10 opacity-0 duration-150 ease-out origin-center group-hover:border-strong group-hover:scale-100 group-hover:opacity-100 group-focus-within:border-strong group-focus-within:scale-100 group-focus-within:opacity-100',
+                )"
+            />
+        </div>
+        <p
+            :class="cn(
+                'text-[11px] leading-[12px] -tracking-0.2px',
+                isActive ? 'text-primary font-550' : 'font-460 text-tertiary duration-150 ease-out group-hover:text-primary group-focus-within:text-primary',
+            )"
+        >
+            {{ label }}
+        </p>
+    </component>
+</template>

package/components/tela/sidebar/sidebar-logo.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { NuxtLink } from '#components'
+
+defineProps<{
+    src?: string
+    alt: string
+    to?: string
+}>()
+</script>
+
+<template>
+    <component
+        :is="to ? NuxtLink : 'div'"
+        :to="to"
+        class="rounded-12px overflow-hidden outline-none focus-within:ring-0.5px focus-within:ring-border-strong"
+    >
+        <img v-if="src" :src="src" :alt="alt" w-40px h-40px object-cover>
+        <TelaInitials v-else-if="alt" size="md" :word="alt" />
+        <div v-else w-40px h-40px bg-black />
+    </component>
+</template>

package/components/tela/sidebar/sidebar-user.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+defineProps<{
+    image?: string
+    name: string
+    email: string
+    actions: {
+        label: string
+        icon: string
+        color: 'positive' | 'caution' | 'negative'
+        onClick: () => void
+    }[]
+}>()
+</script>
+
+<template>
+    <TelaDropdownMenuRoot>
+        <TelaDropdownMenuTrigger as-child>
+            <button
+                :class="cn('group', image ? 'ring-transparent focus-within:ring-border-strong' : 'ring-border-strong focus-within:ring-border-accent')"
+                rounded-full overflow-hidden ring-0.5px
+            >
+                <img v-if="image" :src="image" :alt="name" w-32px h-32px object-cover>
+                <div v-else w-32px h-32px bg />
+            </button>
+        </TelaDropdownMenuTrigger>
+        <TelaDropdownMenuContent align="start" side="top" class="min-w-200px!">
+            <div px-12px py-8px>
+                <h5 heading-h5-semibold text-primary mb-2px>
+                    {{ name }}
+                </h5>
+                <p body-12-regular text-secondary>
+                    {{ email }}
+                </p>
+            </div>
+            <TelaDropdownMenuSeparator />
+            <TelaDropdownMenuItem
+                v-for="action in actions"
+                :key="action.label"
+                :icon="action.icon"
+                :color="action.color"
+                @click="action.onClick"
+            >
+                {{ action.label }}
+            </TelaDropdownMenuItem>
+        </TelaDropdownMenuContent>
+    </TelaDropdownMenuRoot>
+</template>

package/components/tela/sidebar/sidebar.mdx

@@ -0,0 +1,175 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as SidebarStories from './sidebar.stories.ts';
+
+<Meta of={SidebarStories} />
+
+# TelaSidebar
+
+A composable sidebar navigation system built from focused sub-components. Fixed 80px wide and full-height, designed for icon-based navigation with labels.
+
+## Examples
+
+### Full Sidebar
+
+```vue
+<TelaSidebar>
+    <TelaSidebarHeader>
+        <TelaSidebarLogo src="/tela-logo-black.svg" alt="Tela Logo" />
+    </TelaSidebarHeader>
+
+    <TelaSidebarContent>
+        <TelaSidebarItem
+            v-for="item in items"
+            :key="item.label"
+            :icon="item.icon"
+            :label="item.label"
+            :to="item.path"
+            :is-active="isItemActive(item)"
+            :on-click="item.onClick"
+        />
+    </TelaSidebarContent>
+
+    <TelaSidebarFooter>
+        <TelaSidebarItem
+            icon="i-ph-bell"
+            label="Activity"
+            :is-active="route.path === '/activity'"
+        />
+        <TelaSidebarUser
+            :image="user.image"
+            :name="user.name"
+            :email="user.email"
+            :actions="[
+                { label: 'Logout', icon: 'i-ph-sign-out', color: 'negative', onClick: handleLogout },
+            ]"
+        />
+    </TelaSidebarFooter>
+</TelaSidebar>
+```
+
+<Canvas of={SidebarStories.Default} />
+
+### Activity Active
+
+<Canvas of={SidebarStories.ActivityActive} />
+
+### No Active Item
+
+<Canvas of={SidebarStories.NoActiveItem} />
+
+### Individual Item States
+
+<Canvas of={SidebarStories.SingleItem} />
+
+## Components
+
+### `<TelaSidebar>`
+
+Root wrapper. Renders as an `<aside>` with fixed 80px width, full height, and a right border. Place `TelaSidebarHeader`, `TelaSidebarContent`, and `TelaSidebarFooter` as direct children.
+
+### `<TelaSidebarHeader>`
+
+Top section of the sidebar. Stacks children vertically with 24px gap and vertical padding. Use for logos or workspace switchers.
+
+### `<TelaSidebarLogo>`
+
+Displays a logo or fallback inside the header. When `src` is provided, renders an image. When only `alt` is provided, falls back to `TelaInitials`. If neither is set, renders a placeholder div.
+
+```typescript
+interface TelaSidebarLogoProps {
+    src?: string  // Image source URL or path — when provided, renders an <img>
+    alt: string   // Accessible alt text — used as the word for TelaInitials fallback
+    to?: string   // Optional link — wraps the content in a NuxtLink when provided
+}
+```
+
+### `<TelaSidebarContent>`
+
+Middle section that grows to fill available space. Scrollable with hidden scrollbar and a fade mask at the top and bottom edges for a smooth overflow effect. Place nav items directly as children — they stack vertically with 14px gap.
+
+### `<TelaSidebarItem>`
+
+An individual navigation item with an icon and label. Renders as a `NuxtLink` when `to` is provided, otherwise as a `<button>`.
+
+```typescript
+interface TelaSidebarItemProps {
+    icon: string          // Iconify class (e.g. "i-ph-house")
+    label: string         // Text label shown below the icon
+    isActive: boolean     // Highlights the item as the current route
+    to?: string           // Route path — renders as a link
+    onClick?: () => void  // Click handler when not using `to`
+}
+```
+
+<ArgTypes of={SidebarStories} />
+
+### `<TelaSidebarFooter>`
+
+Bottom section of the sidebar. Always contains `TelaSidebarUser` for account controls. Optionally add secondary `TelaSidebarItem` actions (e.g. activity, notifications) above it.
+
+Default — user only:
+
+```vue
+<TelaSidebarFooter>
+    <TelaSidebarUser
+        :avatar-url="user.avatarUrl"
+        :username="user.name"
+        :email="user.email"
+        :options="[
+            { label: 'Logout', icon: 'i-ph-sign-out', color: 'negative', onClick: handleLogout },
+        ]"
+    />
+</TelaSidebarFooter>
+```
+
+With secondary actions:
+
+```vue
+<TelaSidebarFooter>
+    <TelaSidebarItem
+        icon="i-ph-bell"
+        label="Activity"
+        :is-active="route.path === '/activity'"
+        to="/activity"
+    />
+    <TelaSidebarUser
+        :avatar-url="user.avatarUrl"
+        :username="user.name"
+        :email="user.email"
+        :options="[
+            { label: 'Logout', icon: 'i-ph-sign-out', color: 'negative', onClick: handleLogout },
+        ]"
+    />
+</TelaSidebarFooter>
+```
+
+### `<TelaSidebarUser>`
+
+User account button in the footer. Clicking opens a dropdown menu with the user's name, email, and configurable action items.
+
+```typescript
+interface TelaSidebarUserProps {
+    image?: string  // Optional — falls back to a placeholder if not provided
+    name: string
+    email: string
+    actions: {
+        label: string
+        icon: string
+        color: 'positive' | 'caution' | 'negative'
+        onClick: () => void
+    }[]
+}
+```
+
+Example:
+
+```vue
+<TelaSidebarUser
+    image="https://example.com/avatar.jpg"
+    name="Jane Doe"
+    email="jane@example.com"
+    :actions="[
+        { label: 'Logout', icon: 'i-ph-sign-out', color: 'negative', onClick: handleLogout },
+    ]"
+/>
+```

package/components/tela/sidebar/sidebar.stories.ts

@@ -0,0 +1,190 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import TelaSidebar from './sidebar.vue'
+import TelaSidebarHeader from './sidebar-header.vue'
+import TelaSidebarContent from './sidebar-content.vue'
+import TelaSidebarLogo from './sidebar-logo.vue'
+import TelaSidebarItem from './sidebar-item.vue'
+import TelaSidebarFooter from './sidebar-footer.vue'
+import TelaSidebarUser from './sidebar-user.vue'
+
+const meta: Meta<typeof TelaSidebar> = {
+    title: 'Patterns/Sidebar',
+    component: TelaSidebar,
+    parameters: {
+        layout: 'fullscreen',
+        docs: {
+            description: {
+                component: 'A composable sidebar navigation system built from focused sub-components. Fixed 80px wide and full-height, designed for icon-based navigation with labels. Compose `TelaSidebarHeader`, `TelaSidebarContent`, and `TelaSidebarFooter` inside the root `TelaSidebar` to build the full layout.',
+            },
+        },
+    },
+}
+
+export default meta
+
+type Story = StoryObj<typeof TelaSidebar>
+
+const navItems = [
+    { icon: 'i-ph-house', label: 'Home', path: '/' },
+    { icon: 'i-ph-graph', label: 'Workflows', path: '/workflows' },
+    { icon: 'i-ph-database', label: 'Data', path: '/data' },
+    { icon: 'i-ph-gear', label: 'Settings', path: '/settings' },
+]
+
+const userActions = [
+    { label: 'Logout', icon: 'i-ph-sign-out', color: 'negative' as const, onClick: () => {} },
+]
+
+const components = {
+    TelaSidebar,
+    TelaSidebarHeader,
+    TelaSidebarLogo,
+    TelaSidebarContent,
+    TelaSidebarItem,
+    TelaSidebarFooter,
+    TelaSidebarUser,
+}
+
+export const Default: Story = {
+    render: () => ({
+        components,
+        setup() {
+            const items = navItems
+            const activePath = '/workflows'
+            const isItemActive = (item: { path: string }) => activePath === item.path
+            return { items, isItemActive, userActions }
+        },
+        template: `
+            <TelaSidebar>
+                <TelaSidebarHeader>
+                    <TelaSidebarLogo src="/tela-logo-black.svg" alt="Tela Logo" />
+                </TelaSidebarHeader>
+
+                <TelaSidebarContent>
+                    <TelaSidebarItem
+                        v-for="item in items"
+                        :key="item.label"
+                        :icon="item.icon"
+                        :label="item.label"
+                        :to="item.path"
+                        :is-active="isItemActive(item)"
+                    />
+                    <TelaSidebarItem
+                        icon="i-ph-bell"
+                        label="Activity"
+                        :is-active="false"
+                    />
+                </TelaSidebarContent>
+
+                <TelaSidebarFooter>
+                    <TelaSidebarUser
+                        name="Username"
+                        email="user@example.com"
+                        :actions="userActions"
+                    />
+                </TelaSidebarFooter>
+            </TelaSidebar>
+        `,
+    }),
+}
+
+export const NoActiveItem: Story = {
+    render: () => ({
+        components,
+        setup() {
+            return { items: navItems, userActions }
+        },
+        template: `
+            <TelaSidebar>
+                <TelaSidebarHeader>
+                    <TelaSidebarLogo src="/tela-logo-black.svg" alt="Tela Logo" />
+                </TelaSidebarHeader>
+
+                <TelaSidebarContent>
+                    <TelaSidebarItem
+                        v-for="item in items"
+                        :key="item.label"
+                        :icon="item.icon"
+                        :label="item.label"
+                        :to="item.path"
+                        :is-active="false"
+                    />
+                    <TelaSidebarItem
+                        icon="i-ph-bell"
+                        label="Activity"
+                        :is-active="false"
+                    />
+                </TelaSidebarContent>
+
+                <TelaSidebarFooter>
+                    <TelaSidebarUser
+                        name="Username"
+                        email="user@example.com"
+                        :actions="userActions"
+                    />
+                </TelaSidebarFooter>
+            </TelaSidebar>
+        `,
+    }),
+}
+
+export const ActivityActive: Story = {
+    render: () => ({
+        components,
+        setup() {
+            return { items: navItems, userActions }
+        },
+        template: `
+            <TelaSidebar>
+                <TelaSidebarHeader>
+                    <TelaSidebarLogo src="/tela-logo-black.svg" alt="Tela Logo" />
+                </TelaSidebarHeader>
+
+                <TelaSidebarContent>
+                    <TelaSidebarItem
+                        v-for="item in items"
+                        :key="item.label"
+                        :icon="item.icon"
+                        :label="item.label"
+                        :to="item.path"
+                        :is-active="false"
+                    />
+                    <TelaSidebarItem
+                        icon="i-ph-bell"
+                        label="Activity"
+                        :is-active="true"
+                    />
+                </TelaSidebarContent>
+
+                <TelaSidebarFooter>
+                    <TelaSidebarUser
+                        name="Username"
+                        email="user@example.com"
+                        :actions="userActions"
+                    />
+                </TelaSidebarFooter>
+            </TelaSidebar>
+        `,
+    }),
+}
+
+export const SingleItem: Story = {
+    parameters: {
+        layout: 'centered',
+        docs: {
+            description: {
+                story: 'Individual `TelaSidebarItem` in active and inactive states.',
+            },
+        },
+    },
+    render: () => ({
+        components: { TelaSidebarItem },
+        template: `
+            <div style="display: flex; gap: 24px; align-items: center;">
+                <TelaSidebarItem icon="i-ph-house" label="Home" :is-active="false" />
+                <TelaSidebarItem icon="i-ph-graph" label="Workflows" :is-active="true" />
+                <TelaSidebarItem icon="i-ph-bell" label="Activity" :is-active="false" />
+            </div>
+        `,
+    }),
+}

package/components/tela/sidebar/sidebar.vue

@@ -0,0 +1,5 @@
+<template>
+    <aside flex flex-col items-center w-80px h-screen bg border-r-0.5px border>
+        <slot />
+    </aside>
+</template>

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.26.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/unocss.config.ts

@@ -1,8 +1,19 @@
 import transformerDirectives from '@unocss/transformer-directives'
 import { defineConfig, toEscapedSelector } from 'unocss'
+import type { Extractor } from 'unocss'
 import { DT } from './utils/design-tokens'
 
+/* Enables fill variants for Phosphor icons used as a dynamic suffix (e.g. `${icon}-fill`)
+* in components, which UnoCSS can't detect through static scanning */
+const phosphorFillExtractor: Extractor = {
+    name: 'phosphor-fill-icons',
+    extract: ({ code }) => new Set(
+        [...code.matchAll(/['"`](i-ph-[\w-]+)['"`]/g)].map(([, icon]) => `${icon}-fill`),
+    ),
+}
+
 export default defineConfig({
+    extractors: [phosphorFillExtractor],
     theme: {
         ...DT,
         animation: {

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
+}