@deepcitation/deepcitation-js 1.0.9 → 1.1.1

package/README.md

@@ -107,7 +107,7 @@ function Response({ citations, verifications }) {
       Revenue grew by
       <CitationComponent
         citation={citations["1"]}
-        foundCitation={verifications["1"]}
+        verification={verifications["1"]}
       />
       this quarter.
     </p>
@@ -163,7 +163,7 @@ import {
 ```typescript
 import type {
   Citation,
-  FoundHighlightLocation,
+  Verification,
   SearchState,
   SearchStatus,
 } from "@deepcitation/deepcitation-js";

package/lib/client/DeepCitation.d.ts

@@ -154,7 +154,7 @@ export declare class DeepCitation {
      * const citations = getAllCitationsFromLlmOutput(llmResponse);
      * const verified = await dc.verifyCitations(fileId, citations);
      *
-     * for (const [key, result] of Object.entries(verified.foundHighlights)) {
+     * for (const [key, result] of Object.entries(verified.verifications)) {
      *   console.log(key, result.searchState?.status);
      *   // "found", "partial_text_found", "not_found", etc.
      * }
@@ -175,7 +175,7 @@ export declare class DeepCitation {
      *   fileDataParts, // From prepareFiles()
      * });
      *
-     * for (const [key, result] of Object.entries(result.foundHighlights)) {
+     * for (const [key, result] of Object.entries(result.verifications)) {
      *   console.log(key, result.searchState?.status);
      * }
      * ```

package/lib/client/DeepCitation.js

@@ -237,13 +237,19 @@ export class DeepCitation {
             return { fileDataParts: [], deepTextPromptPortion: [] };
         }
         // Upload all files in parallel
-        const uploadPromises = files.map(({ file, filename, fileId }) => this.uploadFile(file, { filename, fileId }));
-        const results = await Promise.all(uploadPromises);
-        // Extract file data parts and file deep texts
-        const fileDataParts = results.map((result) => ({
+        const uploadPromises = files.map(({ file, filename, fileId }) => this.uploadFile(file, { filename, fileId }).then((result) => ({
+            result,
+            filename,
+        })));
+        const uploadResults = await Promise.all(uploadPromises);
+        // Extract file data parts with deepTextPromptPortion included (single source of truth)
+        const fileDataParts = uploadResults.map(({ result, filename }) => ({
             fileId: result.fileId,
+            deepTextPromptPortion: result.deepTextPromptPortion,
+            filename: filename || result.metadata?.filename,
         }));
-        const deepTextPromptPortion = results.map((result) => result.deepTextPromptPortion);
+        // Also return separate array for backwards compatibility (deprecated)
+        const deepTextPromptPortion = fileDataParts.map((part) => part.deepTextPromptPortion);
         return { fileDataParts, deepTextPromptPortion };
     }
     /**
@@ -261,7 +267,7 @@ export class DeepCitation {
      * const citations = getAllCitationsFromLlmOutput(llmResponse);
      * const verified = await dc.verifyCitations(fileId, citations);
      *
-     * for (const [key, result] of Object.entries(verified.foundHighlights)) {
+     * for (const [key, result] of Object.entries(verified.verifications)) {
      *   console.log(key, result.searchState?.status);
      *   // "found", "partial_text_found", "not_found", etc.
      * }
@@ -328,7 +334,7 @@ export class DeepCitation {
      *   fileDataParts, // From prepareFiles()
      * });
      *
-     * for (const [key, result] of Object.entries(result.foundHighlights)) {
+     * for (const [key, result] of Object.entries(result.verifications)) {
      *   console.log(key, result.searchState?.status);
      * }
      * ```
@@ -340,7 +346,7 @@ export class DeepCitation {
             citations = getAllCitationsFromLlmOutput(llmOutput);
         // If no citations found, return empty result
         if (Object.keys(citations).length === 0) {
-            return { foundHighlights: {} };
+            return { verifications: {} };
         }
         // Group citations by fileId
         const citationsByFile = new Map();
@@ -361,8 +367,8 @@ export class DeepCitation {
         const results = await Promise.all(verificationPromises);
         const allHighlights = {};
         for (const result of results) {
-            Object.assign(allHighlights, result.foundHighlights);
+            Object.assign(allHighlights, result.verifications);
         }
-        return { foundHighlights: allHighlights };
+        return { verifications: allHighlights };
     }
 }

package/lib/client/types.d.ts

@@ -1,4 +1,4 @@
-import type { Citation, FoundHighlightLocation } from "../types/index.js";
+import type { Citation, Verification } from "../types/index.js";
 /**
  * Configuration options for the DeepCitation client
  */
@@ -51,7 +51,7 @@ export interface UploadFileOptions {
  */
 export interface VerifyCitationsResponse {
     /** Map of citation keys to their verification results */
-    foundHighlights: Record<string, FoundHighlightLocation>;
+    verifications: Record<string, Verification>;
 }
 /**
  * Options for citation verification
@@ -81,14 +81,22 @@ export interface FileInput {
 export interface FileDataPart {
     /** The file ID assigned by DeepCitation */
     fileId: string;
+    /** The formatted text content for LLM prompts (with page markers and line IDs) */
+    deepTextPromptPortion: string;
+    /** Optional filename for display purposes */
+    filename?: string;
 }
 /**
  * Result from prepareFiles
  */
 export interface PrepareFilesResult {
-    /** Array of file references for verification */
+    /** Array of file references for verification (includes deepTextPromptPortion for each file) */
     fileDataParts: FileDataPart[];
-    /** Array of formatted text content for LLM prompts (with page markers and line IDs) */
+    /**
+     * Array of formatted text content for LLM prompts (with page markers and line IDs).
+     * @deprecated Use fileDataParts[].deepTextPromptPortion instead for single source of truth.
+     * This is kept for backwards compatibility but will be removed in a future version.
+     */
     deepTextPromptPortion: string[];
 }
 /**

package/lib/index.d.ts

@@ -9,8 +9,8 @@ export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeC
 export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
 export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./types/citation.js";
 export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
-export type { FoundHighlightLocation } from "./types/foundHighlight.js";
-export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./types/foundHighlight.js";
+export type { Verification } from "./types/verification.js";
+export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, deterministicIdFromVerification, } from "./types/verification.js";
 export type { SearchState, SearchStatus, SearchMethod, SearchAttempt, } from "./types/search.js";
 export type { ScreenBox, PdfSpaceItem, IVertex } from "./types/boxes.js";
 export { sha1Hash } from "./utils/sha.js";

package/lib/index.js

@@ -9,7 +9,7 @@ export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCi
 export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeCitation.js";
 export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
 export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
-export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./types/foundHighlight.js";
+export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, deterministicIdFromVerification, } from "./types/verification.js";
 // Utilities
 export { sha1Hash } from "./utils/sha.js";
 export { generateCitationKey } from "./react/utils.js";

package/lib/parsing/parseCitation.d.ts

@@ -1,12 +1,12 @@
-import { type FoundHighlightLocation } from "../types/foundHighlight.js";
+import { type Verification } from "../types/verification.js";
 import { type Citation, type CitationStatus } from "../types/citation.js";
 /**
  * Calculates the verification status of a citation based on the found highlight and search state.
  *
- * @param foundHighlight - The found highlight location, or null/undefined if not found
+ * @param verification - The found highlight location, or null/undefined if not found
  * @returns An object containing boolean flags for verification status
  */
-export declare function getCitationStatus(foundHighlight: FoundHighlightLocation | null | undefined): CitationStatus;
+export declare function getCitationStatus(verification: Verification | null | undefined): CitationStatus;
 export declare const parseCitation: (fragment: string, mdAttachmentId?: string | null, citationCounterRef?: any | null, isVerbose?: boolean) => {
     beforeCite: string;
     afterCite: string;

package/lib/parsing/parseCitation.js

@@ -48,11 +48,11 @@ function parseLineIds(lineIdsString) {
 /**
  * Calculates the verification status of a citation based on the found highlight and search state.
  *
- * @param foundHighlight - The found highlight location, or null/undefined if not found
+ * @param verification - The found highlight location, or null/undefined if not found
  * @returns An object containing boolean flags for verification status
  */
-export function getCitationStatus(foundHighlight) {
-    const searchState = foundHighlight?.searchState;
+export function getCitationStatus(verification) {
+    const searchState = verification?.searchState;
     const isMiss = searchState?.status === "not_found";
     const isFullMatchWithMissedValue = searchState?.status === "found_phrase_missed_value";
     const isFoundValueMissedFullMatch = searchState?.status === "found_value_only";

package/lib/react/CitationComponent.d.ts

@@ -1,6 +1,6 @@
 import React, { type ReactNode } from "react";
 import { type CitationStatus } from "../types/citation.js";
-import type { FoundHighlightLocation } from "../types/foundHighlight.js";
+import type { Verification } from "../types/verification.js";
 import type { BaseCitationProps, CitationEventHandlers, CitationRenderProps, CitationVariant } from "./types.js";
 import "./styles.css";
 export type { CitationVariant } from "./types.js";
@@ -11,7 +11,7 @@ export type { CitationVariant } from "./types.js";
  * ```tsx
  * <CitationComponent
  *   citation={{ citationNumber: 1, fullPhrase: "Revenue grew by 25%" }}
- *   foundCitation={verificationResult}
+ *   verification={verificationResult}
  * />
  * // Renders: [1✓] with blue text
  * ```
@@ -20,7 +20,7 @@ export type { CitationVariant } from "./types.js";
  * ```tsx
  * <CitationComponent
  *   citation={{ citationNumber: 1, value: "25% growth" }}
- *   foundCitation={verificationResult}
+ *   verification={verificationResult}
  *   variant="numeric"
  * />
  * // Renders: 1✓
@@ -30,7 +30,7 @@ export type { CitationVariant } from "./types.js";
  * ```tsx
  * <CitationComponent
  *   citation={{ citationNumber: 1, value: "25% growth" }}
- *   foundCitation={verificationResult}
+ *   verification={verificationResult}
  *   variant="text"
  * />
  * // Renders: 25% growth✓
@@ -40,7 +40,7 @@ export type { CitationVariant } from "./types.js";
  * ```tsx
  * <CitationComponent
  *   citation={citation}
- *   foundCitation={verificationResult}
+ *   verification={verificationResult}
  *   variant="minimal"
  * />
  * // Renders: Revenue grew...✓
@@ -50,7 +50,7 @@ export type { CitationVariant } from "./types.js";
  * ```tsx
  * <CitationComponent
  *   citation={citation}
- *   foundCitation={verificationResult}
+ *   verification={verificationResult}
  *   variant="indicator"
  * />
  * // Renders: ✓
@@ -60,7 +60,7 @@ export type { CitationVariant } from "./types.js";
  * ```tsx
  * <CitationComponent
  *   citation={citation}
- *   foundCitation={verificationResult}
+ *   verification={verificationResult}
  *   popoverPosition="hidden"
  * />
  * ```
@@ -70,7 +70,7 @@ export interface CitationComponentProps extends BaseCitationProps {
      * Verification result from the DeepCitation API.
      * Contains match snippet, page number, and verification image.
      */
-    foundCitation?: FoundHighlightLocation | null;
+    verification?: Verification | null;
     /**
      * Display variant for the citation.
      * - `brackets`: Shows value/number in brackets, blue text styling (default)
@@ -110,7 +110,7 @@ export interface CitationComponentProps extends BaseCitationProps {
      */
     renderPopoverContent?: (props: {
         citation: BaseCitationProps["citation"];
-        foundCitation: FoundHighlightLocation | null;
+        verification: Verification | null;
         status: CitationStatus;
     }) => ReactNode;
 }

package/lib/react/CitationComponent.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { forwardRef, memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { forwardRef, memo, useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
 import { CheckIcon, WarningIcon } from "./icons.js";
-import { classNames, generateCitationInstanceId, generateCitationKey, getCitationDisplayText } from "./utils.js";
+import { classNames, generateCitationInstanceId, generateCitationKey, getCitationDisplayText, } from "./utils.js";
 import { getCitationStatus } from "../parsing/parseCitation.js";
 import "./styles.css";
 const TWO_DOTS_THINKING_CONTENT = "..";
@@ -74,13 +74,13 @@ function getFoundStatusClass(status) {
  * Status tooltip content for miss/partial states.
  * Shows explanation when hovering over citations with issues.
  */
-const StatusTooltipContent = ({ citation, status, foundCitation, isExpanded, onToggleExpand, }) => {
+const StatusTooltipContent = ({ citation, status, verification, isExpanded, onToggleExpand, }) => {
     const { isMiss, isPartialMatch } = status;
     if (!isMiss && !isPartialMatch)
         return null;
-    // Get search attempts from foundCitation
-    const searchAttempts = foundCitation?.searchState?.searchAttempts;
-    const failedAttempts = searchAttempts?.filter(a => !a.success) || [];
+    // Get search attempts from verification
+    const searchAttempts = verification?.searchState?.searchAttempts;
+    const failedAttempts = searchAttempts?.filter((a) => !a.success) || [];
     // Collect all unique phrases tried
     const allPhrases = [];
     const seenPhrases = new Set();
@@ -105,8 +105,10 @@ const StatusTooltipContent = ({ citation, status, foundCitation, isExpanded, onT
     }
     if (isPartialMatch) {
         const expectedText = citation.fullPhrase || citation.value || "";
-        const actualText = foundCitation?.matchSnippet || "";
-        const truncatedExpected = expectedText.length > 100 ? expectedText.slice(0, 100) + "…" : expectedText;
+        const actualText = verification?.matchSnippet || "";
+        const truncatedExpected = expectedText.length > 100
+            ? expectedText.slice(0, 100) + "…"
+            : expectedText;
         const truncatedActual = actualText.length > 100 ? actualText.slice(0, 100) + "…" : actualText;
         return (_jsxs("span", { className: "dc-status-tooltip", role: "tooltip", children: [_jsxs("span", { className: "dc-status-header dc-status-header--partial", children: [_jsx(WarningIcon, {}), _jsx("span", { children: "Partial match" })] }), _jsx("span", { className: "dc-status-description", children: "Text differs from citation." }), truncatedExpected && (_jsxs("span", { className: "dc-status-searched", children: [_jsx("span", { className: "dc-status-label", children: "Expected" }), _jsx("span", { className: "dc-status-text", children: truncatedExpected })] })), truncatedActual && (_jsxs("span", { className: "dc-status-searched", children: [_jsx("span", { className: "dc-status-label", children: "Found" }), _jsx("span", { className: "dc-status-text", children: truncatedActual })] }))] }));
     }
@@ -116,7 +118,7 @@ const StatusTooltipContent = ({ citation, status, foundCitation, isExpanded, onT
  * Full-size image overlay component.
  * Uses portal to render at document body level.
  */
-const ImageOverlay = ({ src, alt, onClose }) => {
+const ImageOverlay = ({ src, alt, onClose, }) => {
     const handleBackdropClick = useCallback((e) => {
         if (e.target === e.currentTarget) {
             onClose();
@@ -138,28 +140,28 @@ const ImageOverlay = ({ src, alt, onClose }) => {
  * Default popover content component.
  * Shows verification image if available, otherwise shows text info.
  */
-const DefaultPopoverContent = ({ foundCitation, status, onImageClick, }) => {
-    const hasImage = foundCitation?.verificationImageBase64;
+const DefaultPopoverContent = ({ verification, status, onImageClick, }) => {
+    const hasImage = verification?.verificationImageBase64;
     const handleImageClick = useCallback((e) => {
         e.preventDefault();
         e.stopPropagation();
         if (hasImage && onImageClick) {
-            onImageClick(foundCitation.verificationImageBase64);
+            onImageClick(verification.verificationImageBase64);
         }
-    }, [hasImage, foundCitation?.verificationImageBase64, onImageClick]);
+    }, [hasImage, verification?.verificationImageBase64, onImageClick]);
     // If we have a verification image, show only the image
     if (hasImage) {
-        return (_jsx("button", { type: "button", className: "dc-popover-image-button", onClick: handleImageClick, "aria-label": "Click to view full size", children: _jsx("img", { src: foundCitation.verificationImageBase64, alt: "Citation verification", className: "dc-popover-image", loading: "lazy" }) }));
+        return (_jsx("button", { type: "button", className: "dc-popover-image-button", onClick: handleImageClick, "aria-label": "Click to view full size", children: _jsx("img", { src: verification.verificationImageBase64, alt: "Citation verification", className: "dc-popover-image", loading: "lazy" }) }));
     }
     // No image - show text info
     const statusLabel = getStatusLabel(status);
     const statusClass = getPopoverStatusClass(status);
-    const hasSnippet = foundCitation?.matchSnippet;
-    const pageNumber = foundCitation?.pageNumber;
+    const hasSnippet = verification?.matchSnippet;
+    const pageNumber = verification?.pageNumber;
     if (!hasSnippet && !statusLabel) {
         return null;
     }
-    return (_jsxs(_Fragment, { children: [statusLabel && _jsx("span", { className: classNames("dc-popover-status", statusClass), children: statusLabel }), hasSnippet && _jsxs("span", { className: "dc-popover-snippet", children: ["\"", foundCitation.matchSnippet, "\""] }), pageNumber && pageNumber > 0 && _jsxs("span", { className: "dc-popover-page", children: ["Page ", pageNumber] })] }));
+    return (_jsxs(_Fragment, { children: [statusLabel && (_jsx("span", { className: classNames("dc-popover-status", statusClass), children: statusLabel })), hasSnippet && (_jsxs("span", { className: "dc-popover-snippet", children: ["\"", verification.matchSnippet, "\""] })), pageNumber && pageNumber > 0 && (_jsxs("span", { className: "dc-popover-page", children: ["Page ", pageNumber] }))] }));
 };
 // =============================================================================
 // MAIN COMPONENT
@@ -180,7 +182,7 @@ const DefaultPopoverContent = ({ foundCitation, status, onImageClick, }) => {
  * This means partial matches have blue text (because they were found) but
  * an orange indicator (because they didn't match exactly).
  */
-export const CitationComponent = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, foundCitation, variant = "brackets", eventHandlers, isMobile = false, renderIndicator, renderContent, popoverPosition = "top", renderPopoverContent, }, ref) => {
+export const CitationComponent = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, verification, variant = "brackets", eventHandlers, isMobile = false, renderIndicator, renderContent, popoverPosition = "top", renderPopoverContent, }, ref) => {
     const containerRef = useRef(null);
     const wrapperRef = useRef(null);
     const [expandedImageSrc, setExpandedImageSrc] = useState(null);
@@ -195,14 +197,15 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
     const handleTogglePhrases = useCallback((e) => {
         e?.preventDefault();
         e?.stopPropagation();
-        setIsPhrasesExpanded(prev => !prev);
+        setIsPhrasesExpanded((prev) => !prev);
     }, []);
     // Handle click outside to close expanded tooltip
     useEffect(() => {
         if (!isTooltipExpanded)
             return;
         const handleClickOutside = (event) => {
-            if (wrapperRef.current && !wrapperRef.current.contains(event.target)) {
+            if (wrapperRef.current &&
+                !wrapperRef.current.contains(event.target)) {
                 setIsTooltipExpanded(false);
             }
         };
@@ -232,7 +235,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         e.preventDefault();
         e.stopPropagation();
         // If we have a verification image
-        if (foundCitation?.verificationImageBase64) {
+        if (verification?.verificationImageBase64) {
             if (expandedImageSrc) {
                 // Image is open - close it and unpin
                 setExpandedImageSrc(null);
@@ -240,7 +243,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
             }
             else if (isTooltipExpanded) {
                 // Already pinned - second click expands image
-                setExpandedImageSrc(foundCitation.verificationImageBase64);
+                setExpandedImageSrc(verification.verificationImageBase64);
             }
             else {
                 // First click - just pin the popover open
@@ -249,19 +252,19 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         }
         else {
             // No image - toggle phrases expansion for miss/partial tooltips
-            setIsTooltipExpanded(prev => !prev);
-            setIsPhrasesExpanded(prev => !prev);
+            setIsTooltipExpanded((prev) => !prev);
+            setIsPhrasesExpanded((prev) => !prev);
         }
         eventHandlers?.onClick?.(citation, citationKey, e);
     }, [
         eventHandlers,
         citation,
         citationKey,
-        foundCitation?.verificationImageBase64,
+        verification?.verificationImageBase64,
         expandedImageSrc,
         isTooltipExpanded,
     ]);
-    const status = getCitationStatus(foundCitation ?? null);
+    const status = getCitationStatus(verification ?? null);
     // const { isVerified, isPending } = status;
     const { isMiss, isPartialMatch, isVerified, isPending } = status;
     const displayText = useMemo(() => {
@@ -271,7 +274,10 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         }
         // For text/minimal/brackets, show the value or fullPhrase
         return getCitationDisplayText(citation, {
-            displayCitationValue: variant === "text" || variant === "minimal" || variant === "brackets" || displayCitationValue,
+            displayCitationValue: variant === "text" ||
+                variant === "minimal" ||
+                variant === "brackets" ||
+                displayCitationValue,
             fallbackDisplay,
         });
     }, [citation, variant, displayCitationValue, fallbackDisplay]);
@@ -292,8 +298,11 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         }
     }, [eventHandlers, citation, citationKey, isMobile]);
     // Early return for miss with fallback display
-    if (fallbackDisplay !== null && fallbackDisplay !== undefined && displayCitationValue && isMiss) {
-        return _jsx("span", { className: classNames("dc-citation-fallback", className), children: fallbackDisplay });
+    if (fallbackDisplay !== null &&
+        fallbackDisplay !== undefined &&
+        displayCitationValue &&
+        isMiss) {
+        return (_jsx("span", { className: classNames("dc-citation-fallback", className), children: fallbackDisplay }));
     }
     // Render the appropriate indicator based on match quality
     const renderStatusIndicator = () => {
@@ -323,12 +332,14 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
                 status,
                 citationKey,
                 displayText,
-                isMergedDisplay: variant === "text" || variant === "brackets" || displayCitationValue,
+                isMergedDisplay: variant === "text" ||
+                    variant === "brackets" ||
+                    displayCitationValue,
             });
         }
         // Indicator-only variant - just the checkmark/warning
         if (variant === "indicator") {
-            return _jsx("span", { className: "dc-citation-text", children: renderStatusIndicator() });
+            return (_jsx("span", { className: "dc-citation-text", children: renderStatusIndicator() }));
         }
         // Text variant - no special styling, shows value with indicator
         if (variant === "text") {
@@ -347,23 +358,30 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
     };
     // Determine if popover should be shown
     const isPopoverHidden = popoverPosition === "hidden";
-    const shouldShowPopover = !isPopoverHidden && foundCitation && (foundCitation.verificationImageBase64 || foundCitation.matchSnippet);
+    const shouldShowPopover = !isPopoverHidden &&
+        verification &&
+        (verification.verificationImageBase64 || verification.matchSnippet);
     // Determine if status tooltip should be shown (miss/partial without full verification)
     const shouldShowStatusTooltip = !isPopoverHidden && (isMiss || isPartialMatch) && !shouldShowPopover;
     // Popover content - determine position class (only "top" or "bottom" add classes)
     const popoverPositionClass = popoverPosition === "bottom" ? "dc-popover--bottom" : "";
-    const popoverContent = shouldShowPopover ? (_jsx("span", { className: classNames("dc-popover", popoverPositionClass), children: renderPopoverContent ? (renderPopoverContent({ citation, foundCitation: foundCitation ?? null, status })) : (_jsx(DefaultPopoverContent, { citation: citation, foundCitation: foundCitation ?? null, status: status, onImageClick: handleImageClick })) })) : null;
+    const popoverContent = shouldShowPopover ? (_jsx("span", { className: classNames("dc-popover", popoverPositionClass), children: renderPopoverContent ? (renderPopoverContent({
+            citation,
+            verification: verification ?? null,
+            status,
+        })) : (_jsx(DefaultPopoverContent, { citation: citation, verification: verification ?? null, status: status, onImageClick: handleImageClick })) })) : null;
     // Status tooltip for miss/partial explanations
-    const statusTooltipContent = shouldShowStatusTooltip ? (_jsx(StatusTooltipContent, { citation: citation, status: status, foundCitation: foundCitation ?? null, isExpanded: isPhrasesExpanded, onToggleExpand: handleTogglePhrases })) : null;
-    const citationTrigger = (_jsx("span", { ref: node => {
-            containerRef.current = node;
+    const statusTooltipContent = shouldShowStatusTooltip ? (_jsx(StatusTooltipContent, { citation: citation, status: status, verification: verification ?? null, isExpanded: isPhrasesExpanded, onToggleExpand: handleTogglePhrases })) : null;
+    const citationTrigger = (_jsx("span", { ref: (node) => {
+            containerRef.current =
+                node;
             if (typeof ref === "function") {
                 ref(node);
             }
             else if (ref) {
                 ref.current = node;
             }
-        }, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-tooltip-expanded": isTooltipExpanded, "data-has-image": !!foundCitation?.verificationImageBase64, className: classNames("dc-citation", `dc-citation--${variant}`, foundStatusClass, className), onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onClick: handleToggleTooltip, onTouchEndCapture: isMobile ? handleTouchEnd : undefined, "aria-label": displayText ? `[${displayText}]` : undefined, "aria-expanded": isTooltipExpanded, children: renderCitationContent() }));
+        }, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-tooltip-expanded": isTooltipExpanded, "data-has-image": !!verification?.verificationImageBase64, className: classNames("dc-citation", `dc-citation--${variant}`, foundStatusClass, className), onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onClick: handleToggleTooltip, onTouchEndCapture: isMobile ? handleTouchEnd : undefined, "aria-label": displayText ? `[${displayText}]` : undefined, "aria-expanded": isTooltipExpanded, children: renderCitationContent() }));
     // Image overlay for full-size view
     const imageOverlay = expandedImageSrc ? (_jsx(ImageOverlay, { src: expandedImageSrc, alt: "Citation verification - full size", onClose: handleCloseOverlay })) : null;
     // Wrap with popover or status tooltip if needed

package/lib/react/CitationVariants.d.ts

@@ -1,6 +1,6 @@
 import React, { type ReactNode } from "react";
 import type { CitationStatus } from "../types/citation.js";
-import type { FoundHighlightLocation } from "../types/foundHighlight.js";
+import type { Verification } from "../types/verification.js";
 import type { SearchState } from "../types/search.js";
 import type { BaseCitationProps, CitationVariant as CitationVariantType, CitationEventHandlers } from "./types.js";
 /**
@@ -8,7 +8,7 @@ import type { BaseCitationProps, CitationVariant as CitationVariantType, Citatio
  */
 export interface CitationVariantProps extends BaseCitationProps {
     /** Found citation highlight location data */
-    foundCitation?: FoundHighlightLocation | null;
+    verification?: Verification | null;
     /** Current search state for the citation */
     searchState?: SearchState | null;
     /** Event handlers */
@@ -38,7 +38,7 @@ export interface ChipCitationProps extends CitationVariantProps {
  *
  * @example
  * ```tsx
- * <ChipCitation citation={citation} foundCitation={found} size="md" />
+ * <ChipCitation citation={citation} verification={found} size="md" />
  * ```
  */
 export declare const ChipCitation: React.ForwardRefExoticComponent<ChipCitationProps & React.RefAttributes<HTMLSpanElement>>;
@@ -52,7 +52,7 @@ export interface SuperscriptCitationProps extends CitationVariantProps {
  *
  * @example
  * ```tsx
- * <SuperscriptCitation citation={citation} foundCitation={found} />
+ * <SuperscriptCitation citation={citation} verification={found} />
  * // Renders: Text content¹
  * ```
  */

package/lib/react/CitationVariants.js

@@ -1,17 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { memo, useMemo, useCallback, forwardRef } from "react";
+import { memo, useMemo, useCallback, forwardRef, } from "react";
 import { getCitationStatus } from "../parsing/parseCitation.js";
 import { generateCitationKey, generateCitationInstanceId, getCitationDisplayText, getCitationValueText, classNames, } from "./utils.js";
 const TWO_DOTS_THINKING_CONTENT = "..";
 /**
  * Hook to get common citation data.
- * NOTE: Status is not memoized because foundCitation may be mutated in place.
+ * NOTE: Status is not memoized because verification may be mutated in place.
  */
-function useCitationData(citation, foundCitation) {
+function useCitationData(citation, verification) {
     const citationKey = useMemo(() => generateCitationKey(citation), [citation]);
     const citationInstanceId = useMemo(() => generateCitationInstanceId(citationKey), [citationKey]);
     // Don't memoize - object reference as dependency causes stale values on mutation
-    const status = getCitationStatus(foundCitation ?? null);
+    const status = getCitationStatus(verification ?? null);
     return { citationKey, citationInstanceId, status };
 }
 /**
@@ -28,11 +28,11 @@ const DefaultPartialIndicator = () => (_jsx("span", { className: "citation-parti
  *
  * @example
  * ```tsx
- * <ChipCitation citation={citation} foundCitation={found} size="md" />
+ * <ChipCitation citation={citation} verification={found} size="md" />
  * ```
  */
-export const ChipCitation = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, foundCitation, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), size = "md", showIcon = false, icon, }, ref) => {
-    const { citationKey, citationInstanceId, status } = useCitationData(citation, foundCitation);
+export const ChipCitation = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, verification, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), size = "md", showIcon = false, icon, }, ref) => {
+    const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
         displayCitationValue,
@@ -67,7 +67,8 @@ export const ChipCitation = forwardRef(({ citation, children, className, display
                 : isPending
                     ? "citation-chip--pending"
                     : "";
-    return (_jsxs(_Fragment, { children: [children, _jsxs("span", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "chip", className: classNames("citation-chip", sizeClasses[size], statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: e => e.stopPropagation(), "aria-label": displayText ? `Citation: ${displayText}` : undefined, children: [showIcon && (icon || _jsx("span", { className: "citation-chip__icon", children: "\uD83D\uDCC4" })), valueText && !displayCitationValue && _jsx("span", { className: "citation-chip__value", children: valueText }), _jsx("span", { className: "citation-chip__text", children: displayText }), isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && _jsx("span", { className: "citation-chip__pending", children: pendingContent })] })] }));
+    return (_jsxs(_Fragment, { children: [children, _jsxs("span", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "chip", className: classNames("citation-chip", sizeClasses[size], statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: (e) => e.stopPropagation(), "aria-label": displayText ? `Citation: ${displayText}` : undefined, children: [showIcon &&
+                        (icon || _jsx("span", { className: "citation-chip__icon", children: "\uD83D\uDCC4" })), valueText && !displayCitationValue && (_jsx("span", { className: "citation-chip__value", children: valueText })), _jsx("span", { className: "citation-chip__text", children: displayText }), isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && (_jsx("span", { className: "citation-chip__pending", children: pendingContent }))] })] }));
 });
 ChipCitation.displayName = "ChipCitation";
 /**
@@ -76,12 +77,12 @@ ChipCitation.displayName = "ChipCitation";
  *
  * @example
  * ```tsx
- * <SuperscriptCitation citation={citation} foundCitation={found} />
+ * <SuperscriptCitation citation={citation} verification={found} />
  * // Renders: Text content¹
  * ```
  */
-export const SuperscriptCitation = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, foundCitation, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), showBrackets = false, }, ref) => {
-    const { citationKey, citationInstanceId, status } = useCitationData(citation, foundCitation);
+export const SuperscriptCitation = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, verification, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), showBrackets = false, }, ref) => {
+    const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
         displayCitationValue,
@@ -108,7 +109,7 @@ export const SuperscriptCitation = forwardRef(({ citation, children, className,
                 : isPending
                     ? "citation-superscript--pending"
                     : "";
-    return (_jsxs(_Fragment, { children: [children, _jsxs("sup", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "superscript", className: classNames("citation-superscript", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: e => e.stopPropagation(), "aria-label": `Citation ${displayText}`, children: [showBrackets && "[", displayText, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent, showBrackets && "]"] })] }));
+    return (_jsxs(_Fragment, { children: [children, _jsxs("sup", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "superscript", className: classNames("citation-superscript", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: (e) => e.stopPropagation(), "aria-label": `Citation ${displayText}`, children: [showBrackets && "[", displayText, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent, showBrackets && "]"] })] }));
 });
 SuperscriptCitation.displayName = "SuperscriptCitation";
 const FOOTNOTE_SYMBOLS = ["*", "†", "‡", "§", "‖", "¶"];
@@ -122,8 +123,8 @@ const FOOTNOTE_SYMBOLS = ["*", "†", "‡", "§", "‖", "¶"];
  * // Renders: Text content*
  * ```
  */
-export const FootnoteCitation = forwardRef(({ citation, children, className, fallbackDisplay, foundCitation, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), symbolStyle = "number", customSymbol, }, ref) => {
-    const { citationKey, citationInstanceId, status } = useCitationData(citation, foundCitation);
+export const FootnoteCitation = forwardRef(({ citation, children, className, fallbackDisplay, verification, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), symbolStyle = "number", customSymbol, }, ref) => {
+    const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displaySymbol = useMemo(() => {
         if (symbolStyle === "custom" && customSymbol)
@@ -159,7 +160,7 @@ export const FootnoteCitation = forwardRef(({ citation, children, className, fal
                 : isPending
                     ? "citation-footnote--pending"
                     : "";
-    return (_jsxs(_Fragment, { children: [children, _jsxs("sup", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "footnote", className: classNames("citation-footnote", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: e => e.stopPropagation(), "aria-label": `Footnote ${displaySymbol}`, children: [displaySymbol, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent] })] }));
+    return (_jsxs(_Fragment, { children: [children, _jsxs("sup", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "footnote", className: classNames("citation-footnote", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: (e) => e.stopPropagation(), "aria-label": `Footnote ${displaySymbol}`, children: [displaySymbol, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent] })] }));
 });
 FootnoteCitation.displayName = "FootnoteCitation";
 /**
@@ -173,8 +174,8 @@ FootnoteCitation.displayName = "FootnoteCitation";
  * ```
  */
 export const InlineCitation = forwardRef(({ citation, children, className, displayCitationValue = true, // Default to merged for inline
-fallbackDisplay, foundCitation, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), underlineStyle = "dotted", }, ref) => {
-    const { citationKey, citationInstanceId, status } = useCitationData(citation, foundCitation);
+fallbackDisplay, verification, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), underlineStyle = "dotted", }, ref) => {
+    const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
         displayCitationValue,
@@ -202,7 +203,7 @@ fallbackDisplay, foundCitation, eventHandlers, preventTooltips = false, pendingC
                     ? "citation-inline--pending"
                     : "";
     const underlineClass = `citation-inline--underline-${underlineStyle}`;
-    return (_jsxs(_Fragment, { children: [children, _jsxs("span", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "inline", className: classNames("citation-inline", underlineClass, statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: e => e.stopPropagation(), "aria-label": `Citation: ${displayText}`, children: [displayText, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && _jsx("span", { className: "citation-inline__pending", children: pendingContent })] })] }));
+    return (_jsxs(_Fragment, { children: [children, _jsxs("span", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "inline", className: classNames("citation-inline", underlineClass, statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: (e) => e.stopPropagation(), "aria-label": `Citation: ${displayText}`, children: [displayText, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && (_jsx("span", { className: "citation-inline__pending", children: pendingContent }))] })] }));
 });
 InlineCitation.displayName = "InlineCitation";
 /**
@@ -215,8 +216,8 @@ InlineCitation.displayName = "InlineCitation";
  * // Renders: 1
  * ```
  */
-export const MinimalCitation = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, foundCitation, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), showStatusIndicator = true, }, ref) => {
-    const { citationKey, citationInstanceId, status } = useCitationData(citation, foundCitation);
+export const MinimalCitation = forwardRef(({ citation, children, className, displayCitationValue = false, fallbackDisplay, verification, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), showStatusIndicator = true, }, ref) => {
+    const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
         displayCitationValue,
@@ -243,7 +244,7 @@ export const MinimalCitation = forwardRef(({ citation, children, className, disp
                 : isPending
                     ? "citation-minimal--pending"
                     : "";
-    return (_jsxs(_Fragment, { children: [children, _jsxs("span", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "minimal", className: classNames("citation-minimal", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: e => e.stopPropagation(), "aria-label": `Citation ${displayText}`, children: [displayText, showStatusIndicator && (_jsxs(_Fragment, { children: [isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent] }))] })] }));
+    return (_jsxs(_Fragment, { children: [children, _jsxs("span", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "minimal", className: classNames("citation-minimal", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: (e) => e.stopPropagation(), "aria-label": `Citation ${displayText}`, children: [displayText, showStatusIndicator && (_jsxs(_Fragment, { children: [isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent] }))] })] }));
 });
 MinimalCitation.displayName = "MinimalCitation";
 /**
@@ -259,7 +260,7 @@ export const CitationVariantFactory = forwardRef(({ variant = "bracket", chipPro
         case "chip":
             return _jsx(ChipCitation, { ref: ref, ...props, ...chipProps });
         case "superscript":
-            return _jsx(SuperscriptCitation, { ref: ref, ...props, ...superscriptProps });
+            return (_jsx(SuperscriptCitation, { ref: ref, ...props, ...superscriptProps }));
         case "footnote":
             return _jsx(FootnoteCitation, { ref: ref, ...props, ...footnoteProps });
         case "inline":

package/lib/react/primitives.d.ts

@@ -4,14 +4,14 @@
  */
 import React, { type ReactNode, type HTMLAttributes, type MouseEvent, type TouchEvent } from "react";
 import type { Citation as CitationType, CitationStatus } from "../types/citation.js";
-import type { FoundHighlightLocation } from "../types/foundHighlight.js";
+import type { Verification } from "../types/verification.js";
 import type { SearchState } from "../types/search.js";
 interface CitationContextValue {
     citation: CitationType;
     citationKey: string;
     citationInstanceId: string;
     status: CitationStatus;
-    foundCitation: FoundHighlightLocation | null;
+    verification: Verification | null;
     searchState: SearchState | null;
     config: {
         displayCitationValue: boolean;
@@ -25,7 +25,7 @@ export declare function useCitationContext(): CitationContextValue;
 export declare function useCitationContextSafe(): CitationContextValue | null;
 export interface CitationRootProps {
     citation: CitationType;
-    foundCitation?: FoundHighlightLocation | null;
+    verification?: Verification | null;
     searchState?: SearchState | null;
     children: ReactNode;
     displayCitationValue?: boolean;

package/lib/react/primitives.js

@@ -5,7 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  */
 import { createContext, useContext, useMemo, useCallback, forwardRef, } from "react";
 import { getCitationStatus } from "../parsing/parseCitation.js";
-import { generateCitationKey, generateCitationInstanceId, classNames } from "./utils.js";
+import { generateCitationKey, generateCitationInstanceId, classNames, } from "./utils.js";
 const CitationContext = createContext(null);
 /** Access citation context. Must be used within Citation.Root. */
 export function useCitationContext() {
@@ -20,16 +20,16 @@ export function useCitationContextSafe() {
     return useContext(CitationContext);
 }
 /** Root component that provides citation context to all child primitives. */
-export const CitationRoot = forwardRef(({ citation, foundCitation = null, searchState = null, children, displayCitationValue = false, fallbackDisplay = null, pendingContent = "..", className, ...props }, ref) => {
+export const CitationRoot = forwardRef(({ citation, verification = null, searchState = null, children, displayCitationValue = false, fallbackDisplay = null, pendingContent = "..", className, ...props }, ref) => {
     const citationKey = useMemo(() => generateCitationKey(citation), [citation]);
     const citationInstanceId = useMemo(() => generateCitationInstanceId(citationKey), [citationKey]);
-    const status = getCitationStatus(foundCitation);
+    const status = getCitationStatus(verification);
     const contextValue = useMemo(() => ({
         citation,
         citationKey,
         citationInstanceId,
         status,
-        foundCitation,
+        verification,
         searchState,
         config: {
             displayCitationValue,
@@ -41,7 +41,7 @@ export const CitationRoot = forwardRef(({ citation, foundCitation = null, search
         citationKey,
         citationInstanceId,
         status,
-        foundCitation,
+        verification,
         searchState,
         displayCitationValue,
         fallbackDisplay,
@@ -83,7 +83,9 @@ export const CitationTrigger = forwardRef(({ children, className, onCitationClic
             onCitationTouchEnd?.(citation, citationKey, e);
         }
     }, [onTouchEnd, isMobile, onCitationTouchEnd, citation, citationKey]);
-    const statusClasses = classNames(status.isVerified && !status.isPartialMatch && "citation-trigger--verified", status.isPartialMatch && "citation-trigger--partial", status.isMiss && "citation-trigger--miss", status.isPending && "citation-trigger--pending");
+    const statusClasses = classNames(status.isVerified &&
+        !status.isPartialMatch &&
+        "citation-trigger--verified", status.isPartialMatch && "citation-trigger--partial", status.isMiss && "citation-trigger--miss", status.isPending && "citation-trigger--pending");
     return (_jsx("span", { ref: ref, role: "button", tabIndex: 0, className: classNames("citation-trigger", statusClasses, className), onClick: handleClick, onMouseDown: handleMouseDown, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onTouchEndCapture: isMobile ? handleTouchEnd : undefined, ...props, children: children }));
 });
 CitationTrigger.displayName = "Citation.Trigger";
@@ -99,7 +101,10 @@ export const CitationNumber = forwardRef(({ className, number, ...props }, ref)
         if (number !== undefined)
             return String(number);
         if (config.displayCitationValue) {
-            return citation.value || citation.citationNumber?.toString() || config.fallbackDisplay || "";
+            return (citation.value ||
+                citation.citationNumber?.toString() ||
+                config.fallbackDisplay ||
+                "");
         }
         return citation.citationNumber?.toString() || "";
     }, [number, citation, config]);

package/lib/react/types.d.ts

@@ -1,5 +1,5 @@
 import type { Citation, CitationStatus } from "../types/citation.js";
-import type { FoundHighlightLocation } from "../types/foundHighlight.js";
+import type { Verification } from "../types/verification.js";
 import type { SearchState } from "../types/search.js";
 /**
  * Available citation display variants.
@@ -130,7 +130,7 @@ export interface CitationContentProps extends BaseCitationProps {
     /** Unique instance ID for this citation render */
     citationInstanceId: string;
     /** Found citation highlight data */
-    foundCitation: FoundHighlightLocation | null | undefined;
+    verification: Verification | null | undefined;
     /** Current search state */
     searchState: SearchState | undefined | null;
     /** Actual page number where citation was found */
@@ -186,7 +186,7 @@ export interface CitationEventHandlers {
 export interface CitationTooltipProps {
     children: React.ReactNode;
     citation: Citation;
-    foundHighlight?: FoundHighlightLocation | null;
+    verification?: Verification | null;
     searchState?: SearchState | null;
     shouldShowTooltip: boolean;
 }

package/lib/types/citation.d.ts

@@ -1,10 +1,10 @@
 import { type ScreenBox } from "./boxes.js";
-import { type FoundHighlightLocation } from "./foundHighlight.js";
+import { type Verification } from "./verification.js";
 export type OutputImageFormat = "jpeg" | "png" | "avif" | undefined | null;
 export declare const DEFAULT_OUTPUT_IMAGE_FORMAT: "avif";
 export interface VerifyCitationResponse {
-    foundHighlights: {
-        [key: string]: FoundHighlightLocation;
+    verifications: {
+        [key: string]: Verification;
     };
 }
 export interface VerifyCitationRequest {
@@ -21,11 +21,11 @@ export interface Citation {
     keySpan?: string | null;
     value?: string | null;
     startPageKey?: string | null;
-    pageNumber?: number | null;
     lineIds?: number[] | null;
     reasoning?: string | null;
     selection?: ScreenBox | null;
     citationNumber?: number;
+    pageNumber?: number | null;
     timestamps?: {
         endTime?: string;
         startTime?: string;

package/lib/types/index.d.ts

@@ -5,7 +5,7 @@
  */
 export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./citation.js";
 export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
-export type { FoundHighlightLocation } from "./foundHighlight.js";
-export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./foundHighlight.js";
+export type { Verification } from "./verification.js";
+export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, deterministicIdFromVerification, } from "./verification.js";
 export type { SearchState, SearchStatus } from "./search.js";
 export type { ScreenBox, PdfSpaceItem, IVertex } from "./boxes.js";

package/lib/types/index.js

@@ -4,4 +4,4 @@
  * @packageDocumentation
  */
 export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
-export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./foundHighlight.js";
+export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, deterministicIdFromVerification, } from "./verification.js";

package/lib/types/{foundHighlight.d.ts → verification.d.ts}

@@ -1,11 +1,11 @@
 import { type Citation } from "./citation.js";
 import { type SearchState } from "./search.js";
 import { type PdfSpaceItem } from "./boxes.js";
-export declare const NOT_FOUND_HIGHLIGHT_INDEX = -1;
-export declare const PENDING_HIGHLIGHT_INDEX = -2;
-export declare const BLANK_HIGHLIGHT_LOCATION: FoundHighlightLocation;
-export declare function deterministicIdFromHighlightLocation(highlightLocation: FoundHighlightLocation): string;
-export interface FoundHighlightLocation {
+export declare const NOT_FOUND_VERIFICATION_INDEX = -1;
+export declare const PENDING_VERIFICATION_INDEX = -2;
+export declare const BLANK_VERIFICATION: Verification;
+export declare function deterministicIdFromVerification(verification: Verification): string;
+export interface Verification {
     regex?: RegExp | null;
     lowerCaseSearchTerm: string | null;
     label?: string | null;

package/lib/types/verification.js

@@ -0,0 +1,23 @@
+import { sha1Hash } from "../utils/sha.js";
+export const NOT_FOUND_VERIFICATION_INDEX = -1;
+export const PENDING_VERIFICATION_INDEX = -2;
+export const BLANK_VERIFICATION = {
+    pageNumber: NOT_FOUND_VERIFICATION_INDEX,
+    regex: null,
+    lowerCaseSearchTerm: null,
+    attachmentId: null,
+    matchSnippet: null,
+    source: null,
+    citation: {
+        fileId: undefined,
+        startPageKey: null,
+        fullPhrase: null,
+        keySpan: null,
+        lineIds: null,
+        reasoning: null,
+        pageNumber: NOT_FOUND_VERIFICATION_INDEX,
+    },
+};
+export function deterministicIdFromVerification(verification) {
+    return sha1Hash(`${verification.lowerCaseSearchTerm}-${verification.attachmentId}-${verification.pageNumber}-${verification.hitIndexWithinPage}-${verification.matchSnippet}-${verification?.hitIndexWithinPage}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@deepcitation/deepcitation-js",
-    "version": "1.0.9",
+    "version": "1.1.1",
     "description": "DeepCitation JavaScript SDK for deterministic AI citation verification",
     "type": "module",
     "private": false,

package/lib/types/foundHighlight.js

@@ -1,22 +0,0 @@
-import { sha1Hash } from "../utils/sha.js";
-export const NOT_FOUND_HIGHLIGHT_INDEX = -1;
-export const PENDING_HIGHLIGHT_INDEX = -2;
-export const BLANK_HIGHLIGHT_LOCATION = {
-    pageNumber: NOT_FOUND_HIGHLIGHT_INDEX,
-    regex: null,
-    lowerCaseSearchTerm: null,
-    attachmentId: null,
-    matchSnippet: null,
-    source: null,
-    citation: {
-        startPageKey: null,
-        lineIds: null,
-        pageNumber: NOT_FOUND_HIGHLIGHT_INDEX,
-        fileId: undefined,
-        fullPhrase: null,
-        value: null,
-    },
-};
-export function deterministicIdFromHighlightLocation(highlightLocation) {
-    return sha1Hash(`${highlightLocation.lowerCaseSearchTerm}-${highlightLocation.attachmentId}-${highlightLocation.pageNumber}-${highlightLocation.hitIndexWithinPage}-${highlightLocation.matchSnippet}-${highlightLocation?.hitIndexWithinPage}`);
-}