@meistrari/chat-nuxt 3.6.0 → 3.8.0

package/README.md

@@ -211,6 +211,7 @@ import type {
 | `loadingMessagesMode` | `'ordered' \| 'random' \| null` | `'ordered'` | Show custom messages sequentially or randomly |
 | `customComponents` | `Record<string, Component>` | `undefined` | Custom markdown renderers keyed by markdown node or tag name |
 | `customHtmlTags` | `readonly string[]` | `undefined` | Extra HTML tags allowed by the markdown renderer |
+| `citations` | `ChatCitationsConfig \| null` | `undefined` | Enables `cite://` citations in assistant messages (see Citations below) |
 | `feedbackConfig` | `MessageFeedbackConfig \| null` | `undefined` | Enables 👍/👎 feedback on assistant messages; providing the prop (even `{}`) shows the controls |
 | `messageFeedback` | `Record<string, MessageFeedbackRating> \| null` | `undefined` | Host-persisted votes keyed by message id; when provided, it is the single source of truth for the selected thumbs |
 
@@ -232,6 +233,31 @@ Scoped embeds only see conversations created with the same scope. Unscoped embed
 />
 ```
 
+**Citations (`cite://`):**
+
+Hosts whose agents cite retrievable documents can teach them (via prompt) the notation
+
+```
+[visible text](cite://<namespace>/<id>[#q=<term>&n=<nth>&p=<page>])
+```
+
+and pass `citations` to enable it. The lib detects the notation in assistant messages (markdown links and bare tokens), renders each citation as a chip with a metadata popover, and — when `getDocument` is provided — opens a built-in side panel that shows the document with the cited term highlighted (`#q`, nth occurrence via `#n`). What a namespace means, and every data access, belongs to the host: callbacks run against the host's own backend, carrying the viewing user's authorization. A citation that fails to resolve renders as "unverified" — an agent cannot fabricate a trusted-looking reference, and a viewer without access to a document learns nothing from a citation to it.
+
+```vue
+<MeistrariChatEmbed
+    tela-agent-id="agent_123"
+    :citations="{
+        resolve: ref => $fetch(`/api/citations/${ref.namespace}/${encodeURIComponent(ref.id)}`).catch(() => null),
+        getDocument: ref => $fetch(`/api/citations/${ref.namespace}/${encodeURIComponent(ref.id)}/document`).catch(() => null),
+        locate: (ref, term) => $fetch(`/api/citations/${ref.namespace}/${encodeURIComponent(ref.id)}/occurrences`, { query: { term } }).catch(() => null),
+    }"
+/>
+```
+
+`ref.id` arrives percent-decoded (natural identifiers may carry pipes, spaces, accents or slashes) — re-encode it when building URLs, as above.
+
+`ChatCitationsConfig` (exported from `@meistrari/chat-nuxt/types/citations`): `resolve` maps a citation to display metadata (`null` = unverified); `getDocument` enables the document panel; `locate` returns precise term offsets for highlighting (omit it for a client-side, accent-sensitive fallback); `component` replaces the built-in chip; `onOpen` takes over the click entirely. Without the `citations` prop nothing changes: `cite://` hrefs keep rendering as plain links.
+
 **Events:**
 
 | Event | Payload | Description |

package/dist/module.d.mts

@@ -6,6 +6,8 @@ type ChatNuxtConfigValidationMode = false | 'warn' | 'error';
 interface ChatNuxtModuleOptions {
     /** Dedicated Chat API base URL used by Nuxt server routes. */
     chatApiUrl?: string;
+    /** Host app identifier reported to the chat-api (e.g. `'chat-app'`). */
+    source?: string;
     /**
      * Whether to fail fast (`'error'`), warn (`'warn'`), or skip (`false`) when
      * required runtime config keys are unset.

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@meistrari/chat-nuxt",
   "configKey": "chatNuxt",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -149,9 +149,10 @@ function resolveWorkspaceSettingsResolverEntry(srcDir, fallbackResolverBase) {
 }
 
 const _chatNuxtRequire = createRequire(import.meta.url);
+const _chatNuxtPackageVersion = _chatNuxtRequire("../package.json").version;
 const VUE_COMPONENT_EXTENSIONS = [".vue"];
-const FEATURE_DIRS = ["conversations", "embed", "files", "messages", "rendering", "shared", "usage", "workspace"];
-const FULL_NAME_COMPONENT_DIRS = ["conversations", "embed", "files", "messages", "usage"];
+const FEATURE_DIRS = ["citations", "conversations", "embed", "files", "messages", "rendering", "shared", "usage", "workspace"];
+const FULL_NAME_COMPONENT_DIRS = ["citations", "conversations", "embed", "files", "messages", "usage"];
 const PATH_PREFIX_COMPONENT_DIRS = ["rendering", "shared"];
 const DYNAMIC_ICON_SAFELIST = [
   "i-ph-folder-minus",
@@ -358,7 +359,9 @@ const module$1 = defineNuxtModule({
     rc.public = rc.public || {};
     const existingChatNuxtRuntimeConfig = rc.chatNuxt;
     rc.chatNuxt = {
-      chatApiUrl: existingChatNuxtRuntimeConfig?.chatApiUrl || rc.chatApiUrl
+      chatApiUrl: existingChatNuxtRuntimeConfig?.chatApiUrl || rc.chatApiUrl,
+      source: options.source || existingChatNuxtRuntimeConfig?.source,
+      clientVersion: _chatNuxtPackageVersion
     };
     validateRuntimeConfig(rc, options.validateConfig ?? false);
     nuxt.options.css = nuxt.options.css || [];

package/dist/runtime/citations/citation-links.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The `cite://` notation: `[visible text](cite://<namespace>/<id>[#q=<term>&n=<nth>&p=<page>])`.
+ *
+ * Agents are taught (via prompt) to emit this scheme when citing a document they actually
+ * retrieved. The lib only parses the shape — what a namespace means and how a citation is
+ * resolved belongs to the host app through `ChatCitationsConfig`. The id is expected to be
+ * an identifier the agent could only know from a real retrieval, so a citation that fails
+ * to resolve is rendered as unverified instead of trusted.
+ */
+/**
+ * Bare cite tokens in prose; markdown link targets (`](cite://...`) are left to the link
+ * renderer. Unlike VAULT_REGEX, `_` is allowed: source namespaces use it (`stf_sumulas`).
+ */
+export declare const CITE_REGEX: RegExp;
+export type CitationLocator = {
+    /** Exact term whose occurrence the citation points at, for in-document highlight. */
+    term?: string;
+    /** 1-based nth occurrence of `term`; defaults to the first when absent. */
+    occurrence?: number;
+    /** 1-based page at the original source; only meaningful for paginated originals. */
+    page?: number;
+};
+export type CitationRef = {
+    namespace: string;
+    id: string;
+    locator?: CitationLocator;
+    raw: string;
+};
+export declare function isCitationUrl(url: string): boolean;
+export declare function parseCitationUrl(url: string): CitationRef | null;
+/** Cache key for resolution state: the locator addresses a spot inside the same document. */
+export declare function citationCacheKey(ref: Pick<CitationRef, 'namespace' | 'id'>): string;

package/dist/runtime/citations/citation-links.js

@@ -0,0 +1,56 @@
+const CITE_SCHEME = "cite://";
+export const CITE_REGEX = /(?<!\]\()cite:\/\/[^\s"'<>`\[\]()*~]+/gi;
+const NAMESPACE_PATTERN = /^[a-z0-9_-]+$/i;
+export function isCitationUrl(url) {
+  return url.toLowerCase().startsWith(CITE_SCHEME);
+}
+export function parseCitationUrl(url) {
+  if (!isCitationUrl(url))
+    return null;
+  const hashIndex = url.indexOf("#");
+  const body = hashIndex === -1 ? url.slice(CITE_SCHEME.length) : url.slice(CITE_SCHEME.length, hashIndex);
+  const separatorIndex = body.indexOf("/");
+  if (separatorIndex === -1)
+    return null;
+  const namespace = body.slice(0, separatorIndex);
+  const id = safeDecodeURIComponent(body.slice(separatorIndex + 1));
+  if (!namespace || !NAMESPACE_PATTERN.test(namespace) || !id)
+    return null;
+  const locator = hashIndex === -1 ? void 0 : parseCitationLocator(url.slice(hashIndex + 1));
+  return {
+    namespace: namespace.toLowerCase(),
+    id,
+    ...locator ? { locator } : {},
+    raw: url
+  };
+}
+function parseCitationLocator(hash) {
+  const params = new URLSearchParams(hash);
+  const locator = {};
+  const term = params.get("q")?.trim();
+  if (term)
+    locator.term = term;
+  const occurrence = parsePositiveInt(params.get("n"));
+  if (occurrence !== void 0)
+    locator.occurrence = occurrence;
+  const page = parsePositiveInt(params.get("p"));
+  if (page !== void 0)
+    locator.page = page;
+  return Object.keys(locator).length > 0 ? locator : void 0;
+}
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+function parsePositiveInt(value) {
+  if (!value || !/^\d+$/.test(value))
+    return void 0;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
+export function citationCacheKey(ref) {
+  return `${ref.namespace}/${ref.id}`;
+}

package/dist/runtime/citations/components/chat-citation.d.vue.ts

@@ -0,0 +1,9 @@
+import type { CitationRef } from '../citation-links.js';
+type __VLS_Props = {
+    citation: CitationRef;
+    /** Visible text when the citation came from a markdown link. */
+    label?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/citations/components/chat-citation.vue

@@ -0,0 +1,186 @@
+<script setup>
+import { onClickOutside } from "@vueuse/core";
+import { useEmbedConfig } from "../../embed/composables/embed-config";
+import { useCitationPanel } from "../composables/citation-panel";
+import { useCitations } from "../composables/citations";
+const props = defineProps({
+  citation: { type: Object, required: true },
+  label: { type: String, required: false }
+});
+const embedConfig = useEmbedConfig();
+const config = computed(() => embedConfig?.citations.value);
+const { resolveCitation, retryCitation } = useCitations();
+const { openCitationDocument } = useCitationPanel();
+const entry = shallowRef(null);
+watchEffect(() => {
+  if (!entry.value && config.value)
+    entry.value = resolveCitation(config.value, props.citation);
+});
+const status = computed(() => entry.value?.status.value ?? "loading");
+const meta = computed(() => entry.value?.meta.value ?? null);
+const displayLabel = computed(() => props.label?.trim() || meta.value?.identifier || meta.value?.title || "Documento");
+const rootEl = ref(null);
+const popoverOpen = ref(false);
+onClickOutside(rootEl, () => {
+  popoverOpen.value = false;
+});
+function togglePopover() {
+  if (status.value === "loading")
+    return;
+  popoverOpen.value = !popoverOpen.value;
+}
+function retry() {
+  if (!config.value)
+    return;
+  entry.value = retryCitation(config.value, props.citation);
+  popoverOpen.value = false;
+}
+const canOpenDocument = computed(() => Boolean(config.value?.onOpen || config.value?.getDocument));
+function openDocument() {
+  popoverOpen.value = false;
+  const activeConfig = config.value;
+  if (!activeConfig)
+    return;
+  if (activeConfig.onOpen) {
+    activeConfig.onOpen(props.citation, meta.value);
+    return;
+  }
+  openCitationDocument(props.citation, meta.value);
+}
+const safeSourceUrl = computed(() => {
+  const url = meta.value?.url;
+  return url && /^https?:\/\//i.test(url) ? url : null;
+});
+const formattedDate = computed(() => {
+  if (!meta.value?.date)
+    return null;
+  const parsed = new Date(meta.value.date);
+  if (Number.isNaN(parsed.getTime()))
+    return meta.value.date;
+  return parsed.toLocaleDateString("pt-BR", { timeZone: "UTC" });
+});
+const chipIcon = computed(() => {
+  if (status.value === "loading")
+    return "i-ph-spinner animate-spin text-neutral-400";
+  if (status.value === "unresolved")
+    return "i-ph-warning-circle text-amber-600";
+  return "i-ph-file-text text-neutral-500";
+});
+const BADGE_TONE_CLASSES = {
+  neutral: "bg-neutral-100 text-neutral-700",
+  warning: "bg-amber-100 text-amber-800",
+  danger: "bg-red-100 text-red-700"
+};
+const badgeClasses = computed(() => BADGE_TONE_CLASSES[meta.value?.badge?.tone ?? "neutral"]);
+</script>
+
+<template>
+    <component
+        :is="config.component"
+        v-if="config?.component"
+        :citation="citation"
+        :label="label"
+        :status="status"
+        :meta="meta"
+    />
+    <span
+        v-else
+        ref="rootEl"
+        class="citation-ref"
+    >
+        <button
+            type="button"
+            class="citation-ref-anchor"
+            :class="{
+  'citation-ref-anchor--loading': status === 'loading',
+  'citation-ref-anchor--unresolved': status === 'unresolved'
+}"
+            :aria-expanded="popoverOpen"
+            @click="togglePopover"
+        ><span :class="chipIcon" class="citation-ref-icon" />{{ displayLabel }}</button>
+
+        <div
+            v-if="popoverOpen"
+            absolute bottom-full left-0 mb-6px z-50
+            w-300px
+            bg-white
+            border-0.5px border-solid border-neutral-300
+            rounded-12px p-12px
+            shadow-lg
+            cursor-default
+            flex="~ col" gap-8px
+        >
+            <template v-if="status === 'unresolved'">
+                <div flex items-start gap-6px>
+                    <span i-ph-warning-circle text-14px text-amber-600 mt-2px flex-shrink-0 />
+                    <p text-12px leading-16px text-neutral-700>
+                        Não foi possível verificar esta referência. Ela pode não existir ou não estar disponível para o seu perfil.
+                    </p>
+                </div>
+                <button
+                    type="button"
+                    self-start text-12px leading-16px text-neutral-700 underline cursor-pointer
+                    @click="retry"
+                >
+                    Tentar novamente
+                </button>
+            </template>
+
+            <template v-else-if="meta">
+                <div flex="~ col" gap-2px>
+                    <p text-13px leading-18px font-580 text-neutral-900>
+                        {{ meta.title }}
+                    </p>
+                    <p v-if="meta.sourceLabel || meta.identifier" text-12px leading-16px text-neutral-600>
+                        {{ [meta.sourceLabel, meta.identifier].filter(Boolean).join(" \xB7 ") }}
+                    </p>
+                    <p v-if="formattedDate" text-12px leading-16px text-neutral-500>
+                        {{ meta.dateLabel ? `${meta.dateLabel}: ` : "" }}{{ formattedDate }}
+                    </p>
+                </div>
+
+                <span
+                    v-if="meta.badge"
+                    self-start px-6px py-1px rounded-4px text-11px leading-15px font-580
+                    :class="badgeClasses"
+                >
+                    {{ meta.badge.label }}
+                </span>
+
+                <p v-if="meta.snippet" text-12px leading-17px text-neutral-600 line-clamp-3>
+                    {{ meta.snippet }}
+                </p>
+
+                <div v-if="canOpenDocument || safeSourceUrl" flex items-center gap-12px pt-2px>
+                    <button
+                        v-if="canOpenDocument"
+                        type="button"
+                        inline-flex items-center gap-4px
+                        text-12px leading-16px font-580 text-neutral-900
+                        cursor-pointer hover:underline
+                        @click="openDocument"
+                    >
+                        <span i-ph-file-magnifying-glass text-13px />
+                        Ver documento
+                    </button>
+                    <a
+                        v-if="safeSourceUrl"
+                        :href="safeSourceUrl"
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        inline-flex items-center gap-4px
+                        text-12px leading-16px text-neutral-600
+                        hover:underline
+                    >
+                        <span i-ph-arrow-square-out text-13px />
+                        Abrir na fonte
+                    </a>
+                </div>
+            </template>
+        </div>
+    </span>
+</template>
+
+<style scoped>
+.citation-ref{display:inline;position:relative}.citation-ref-anchor{background:transparent;border:0;border-radius:5px;color:inherit;cursor:pointer;display:inline;font:inherit;margin:0 -2px;padding:1px 3px;text-decoration:underline;text-decoration-color:#a3a3a3;text-decoration-style:dotted;text-decoration-thickness:1px;text-underline-offset:3px;transition:background-color .15s ease,text-decoration-color .15s ease}.citation-ref-anchor:hover{background-color:#f5f5f5;text-decoration-color:#525252}.citation-ref-anchor--loading{cursor:default;opacity:.6;text-decoration-color:#d4d4d4}.citation-ref-anchor--unresolved{text-decoration-color:#f59e0b}.citation-ref-anchor--unresolved:hover{background-color:#fffbeb}.citation-ref-icon{display:inline-block;font-size:.85em;margin-right:.25em;vertical-align:-.08em}
+</style>

package/dist/runtime/citations/components/chat-citation.vue.d.ts

@@ -0,0 +1,9 @@
+import type { CitationRef } from '../citation-links.js';
+type __VLS_Props = {
+    citation: CitationRef;
+    /** Visible text when the citation came from a markdown link. */
+    label?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/citations/components/citation-document-panel.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/citations/components/citation-document-panel.vue

@@ -0,0 +1,217 @@
+<script setup>
+import { useMagicKeys } from "@vueuse/core";
+import { useEmbedConfig } from "../../embed/composables/embed-config";
+import { useCitationPanel } from "../composables/citation-panel";
+import { locateTermClientSide, splitContentByOccurrences } from "../document-highlight";
+const { isOpen, active, closeCitationDocument } = useCitationPanel();
+const embedConfig = useEmbedConfig();
+const config = computed(() => embedConfig?.citations.value);
+const isLoading = ref(false);
+const loadFailed = ref(false);
+const documentData = ref(null);
+const occurrences = ref([]);
+const contentEl = ref(null);
+let loadToken = 0;
+const { escape } = useMagicKeys();
+watch(() => escape?.value, (pressed) => {
+  if (pressed && isOpen.value)
+    closeCitationDocument();
+});
+watch([isOpen, active], () => {
+  void load();
+}, { immediate: true });
+async function load() {
+  if (!isOpen.value || !active.value)
+    return;
+  const activeConfig = config.value;
+  if (!activeConfig?.getDocument)
+    return;
+  const token = ++loadToken;
+  const citation = active.value.citation;
+  isLoading.value = true;
+  loadFailed.value = false;
+  documentData.value = null;
+  occurrences.value = [];
+  try {
+    const loaded = await activeConfig.getDocument(citation);
+    if (token !== loadToken)
+      return;
+    documentData.value = loaded;
+    loadFailed.value = loaded === null;
+    const term = citation.locator?.term;
+    if (loaded && term) {
+      let located = null;
+      if (activeConfig.locate) {
+        try {
+          located = await activeConfig.locate(citation, term);
+        } catch {
+          located = null;
+        }
+      }
+      if (token !== loadToken)
+        return;
+      occurrences.value = located ?? locateTermClientSide(loaded.content, term);
+    }
+  } catch {
+    if (token === loadToken)
+      loadFailed.value = true;
+  } finally {
+    if (token === loadToken)
+      isLoading.value = false;
+  }
+  if (token !== loadToken)
+    return;
+  await nextTick();
+  scrollToTargetOccurrence();
+}
+const highlightSegments = computed(() => {
+  if (!documentData.value)
+    return [];
+  return splitContentByOccurrences(documentData.value.content, occurrences.value);
+});
+const totalOccurrences = computed(() => highlightSegments.value.filter((segment) => segment.occurrence !== void 0).length);
+const targetOccurrence = computed(() => {
+  if (totalOccurrences.value === 0)
+    return 0;
+  const wanted = active.value?.citation.locator?.occurrence ?? 1;
+  return Math.min(wanted, totalOccurrences.value);
+});
+const termNotFound = computed(() => Boolean(
+  !isLoading.value && documentData.value && active.value?.citation.locator?.term && totalOccurrences.value === 0
+));
+function scrollToTargetOccurrence() {
+  if (targetOccurrence.value === 0)
+    return;
+  const target = contentEl.value?.querySelector(`[data-occurrence="${targetOccurrence.value}"]`);
+  target?.scrollIntoView({ block: "center" });
+}
+const meta = computed(() => active.value?.meta ?? null);
+const subtitle = computed(() => [meta.value?.sourceLabel, meta.value?.identifier].filter(Boolean).join(" \xB7 "));
+const safeSourceUrl = computed(() => {
+  const url = meta.value?.url;
+  return url && /^https?:\/\//i.test(url) ? url : null;
+});
+</script>
+
+<template>
+    <Transition name="slide-panel">
+        <div
+            v-if="isOpen && active"
+            class="h-full w-full flex flex-col bg-neutral-50 b-l='.5px neutral-300'"
+            style="box-shadow: 0px 12px 20px 0px rgba(163, 163, 163, 0.06);"
+        >
+            <div
+                relative flex items-start gap-8px
+                pl-18px pr-56px py-12px
+                flex-shrink-0
+            >
+                <span i-ph-file-text text-16px text-neutral-600 mt-2px flex-shrink-0 />
+                <div flex="~ col" gap-2px min-w-0>
+                    <p
+                        text-13px font-580 text-secondary leading-17px
+                        :title="meta?.title ?? 'Documento'"
+                    >
+                        {{ meta?.title ?? "Documento" }}
+                    </p>
+                    <p v-if="subtitle" text-12px leading-16px text-neutral-500 truncate>
+                        {{ subtitle }}
+                    </p>
+                </div>
+
+                <div class="absolute top-8px right-12px flex items-center gap-4px">
+                    <a
+                        v-if="safeSourceUrl"
+                        :href="safeSourceUrl"
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        title="Abrir na fonte original"
+                        class="flex items-center justify-center w-28px h-28px rounded-8px hover:bg-neutral-200 transition-colors"
+                    >
+                        <span class="i-ph-arrow-square-out text-16px text-gray-700" />
+                    </a>
+                    <button
+                        type="button"
+                        title="Fechar"
+                        class="flex items-center justify-center w-28px h-28px rounded-8px hover:bg-neutral-200 transition-colors"
+                        @click="closeCitationDocument"
+                    >
+                        <span class="i-ph-x text-16px text-gray-700" />
+                    </button>
+                </div>
+            </div>
+
+            <div
+                v-if="documentData?.truncated || termNotFound"
+                flex="~ col" gap-6px px-18px pb-8px flex-shrink-0
+            >
+                <div
+                    v-if="termNotFound"
+                    flex items-start gap-6px
+                    px-10px py-8px rounded-8px
+                    bg-amber-50 border-0.5px border-solid border-amber-200
+                >
+                    <span i-ph-warning-circle text-13px text-amber-600 mt-1px flex-shrink-0 />
+                    <p text-12px leading-16px text-amber-800>
+                        Trecho citado não localizado neste documento.
+                    </p>
+                </div>
+                <div
+                    v-if="documentData?.truncated"
+                    flex items-start gap-6px
+                    px-10px py-8px rounded-8px
+                    bg-neutral-100 border-0.5px border-solid border-neutral-200
+                >
+                    <span i-ph-info text-13px text-neutral-500 mt-1px flex-shrink-0 />
+                    <p text-12px leading-16px text-neutral-600>
+                        Documento exibido parcialmente.
+                    </p>
+                </div>
+            </div>
+
+            <div
+                v-if="isLoading"
+                flex-1 flex items-center justify-center
+            >
+                <span i-ph-spinner animate-spin text-24px text-neutral-400 />
+            </div>
+
+            <div
+                v-else-if="loadFailed"
+                flex-1 flex="~ col" items-center justify-center gap-4px px-24px
+            >
+                <span i-ph-file-x text-24px text-neutral-400 />
+                <p text-13px leading-18px text-neutral-700 text-center>
+                    Documento não disponível.
+                </p>
+                <p text-12px leading-16px text-neutral-500 text-center>
+                    Ele pode não existir ou não estar acessível para o seu perfil.
+                </p>
+            </div>
+
+            <div
+                v-else-if="documentData"
+                ref="contentEl"
+                flex-1 overflow-y-auto
+                px-18px py-14px
+            >
+                <p text-13px leading-20px text-neutral-800 whitespace-pre-wrap break-words>
+                    <template v-for="(segment, index) in highlightSegments" :key="index">
+                        <mark
+                            v-if="segment.occurrence !== void 0"
+                            :data-occurrence="segment.occurrence"
+                            rounded-2px
+                            :class="segment.occurrence === targetOccurrence ? 'bg-amber-300' : 'bg-amber-100'"
+                        >{{ segment.text }}</mark>
+                        <template v-else>
+                            {{ segment.text }}
+                        </template>
+                    </template>
+                </p>
+            </div>
+        </div>
+    </Transition>
+</template>
+
+<style scoped>
+.slide-panel-enter-active,.slide-panel-leave-active{transition:all .2s ease}.slide-panel-enter-from,.slide-panel-leave-to{opacity:0;transform:translateX(100%)}
+</style>

package/dist/runtime/citations/components/citation-document-panel.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/citations/composables/citation-panel.d.ts

@@ -0,0 +1,8 @@
+import type { CitationRef } from '../citation-links.js';
+import type { CitationMeta } from '../types.js';
+export declare function useCitationPanel(): {
+    isOpen: any;
+    active: any;
+    openCitationDocument: (citation: CitationRef, meta: CitationMeta | null) => void;
+    closeCitationDocument: () => void;
+};

package/dist/runtime/citations/composables/citation-panel.js

@@ -0,0 +1,17 @@
+const isOpen = ref(false);
+const active = ref(null);
+export function useCitationPanel() {
+  function openCitationDocument(citation, meta) {
+    active.value = { citation, meta };
+    isOpen.value = true;
+  }
+  function closeCitationDocument() {
+    isOpen.value = false;
+  }
+  return {
+    isOpen: readonly(isOpen),
+    active: readonly(active),
+    openCitationDocument,
+    closeCitationDocument
+  };
+}

package/dist/runtime/citations/composables/citations.d.ts

@@ -0,0 +1,17 @@
+import type { Ref } from 'vue';
+import { type CitationRef } from '../citation-links.js';
+import type { ChatCitationsConfig, CitationMeta, CitationStatus } from '../types.js';
+export type CitationEntry = {
+    status: Ref<CitationStatus>;
+    meta: Ref<CitationMeta | null>;
+};
+/**
+ * Resolution cache shared by every chip in the session: one `resolve` call per document,
+ * no matter how many times (or with which locators) it is cited. Keyed by config identity
+ * so embeds with different resolvers (different backends/authorization scopes) never
+ * reuse each other's results.
+ */
+export declare function useCitations(): {
+    resolveCitation: (config: ChatCitationsConfig, citation: CitationRef) => CitationEntry;
+    retryCitation: (config: ChatCitationsConfig, citation: CitationRef) => CitationEntry;
+};