@deepcitation/deepcitation-js 1.0.8 → 1.1.0

package/README.md

@@ -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

@@ -1,14 +1,58 @@
-import { sha1Hash } from "../utils/sha.js";
 import { normalizeCitations } from "./normalizeCitation.js";
 import { generateCitationKey } from "../react/utils.js";
+/**
+ * Parses a line_ids string that may contain individual numbers, ranges, or both.
+ * Examples: "1,2,3", "5-10", "1,5-7,10", "20-20"
+ *
+ * @param lineIdsString - The raw line_ids string (e.g., "1,5-7,10")
+ * @returns Sorted array of unique line IDs, or undefined if empty/invalid
+ */
+function parseLineIds(lineIdsString) {
+    if (!lineIdsString)
+        return undefined;
+    const lineIds = [];
+    const parts = lineIdsString.split(",");
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        // Check if this part is a range (e.g., "5-10")
+        if (trimmed.includes("-")) {
+            const [startStr, endStr] = trimmed.split("-");
+            const start = parseInt(startStr, 10);
+            const end = parseInt(endStr, 10);
+            if (!isNaN(start) && !isNaN(end) && start <= end) {
+                // Expand the range
+                for (let i = start; i <= end; i++) {
+                    lineIds.push(i);
+                }
+            }
+            else if (!isNaN(start)) {
+                // If only start is valid, just use it
+                lineIds.push(start);
+            }
+        }
+        else {
+            // Single number
+            const num = parseInt(trimmed, 10);
+            if (!isNaN(num)) {
+                lineIds.push(num);
+            }
+        }
+    }
+    if (lineIds.length === 0)
+        return undefined;
+    // Sort and deduplicate
+    return [...new Set(lineIds)].sort((a, b) => a - b);
+}
 /**
  * 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";
@@ -55,7 +99,6 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     const citationRegex = /<cite\s+file(?:_id|Id)='(\w{0,25})'\s+start_page[\_a-zA-Z]*='page[\_a-zA-Z]*(\d+)_index_(\d+)'\s+full_phrase='((?:[^'\\]|\\.)*)'\s+key_span='((?:[^'\\]|\\.)*)'\s+line(?:_ids|Ids)='([^']+)'(?:\s+(value|reasoning)='((?:[^'\\]|\\.)*)')?\s*\/>/g;
     const citationMatches = [...middleCite.matchAll(citationRegex)];
     const match = citationMatches?.[0];
-    const rawCitationMd = match?.[0];
     const pageNumber = match?.[2] ? parseInt(match?.[2]) : undefined;
     let fileId = match?.[1];
     let attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || match?.[1];
@@ -75,15 +118,9 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     }
     let lineIds;
     try {
-        // match[5] is line_ids
+        // match[6] is line_ids
         const lineIdsString = match?.[6]?.replace(/[A-Za-z_[\](){}:]/g, "");
-        lineIds = lineIdsString
-            ? lineIdsString
-                .split(",")
-                .map((id) => (isNaN(parseInt(id)) ? undefined : parseInt(id)))
-                .filter((id) => id !== undefined)
-                .sort((a, b) => a - b)
-            : undefined;
+        lineIds = lineIdsString ? parseLineIds(lineIdsString) : undefined;
     }
     catch (e) {
         if (isVerbose)
@@ -116,16 +153,13 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
         }
         timestamps = { startTime, endTime };
     }
-    const fragmentContext = sha1Hash(fragment).toString().slice(0, 8);
     const citation = {
-        fragmentContext,
         fileId: attachmentId,
         pageNumber,
         fullPhrase,
         keySpan,
         citationNumber,
         lineIds,
-        rawCitationMd,
         beforeCite,
         value,
         timestamps,

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";
@@ -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;
+    foundCitation?: 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;
+        foundCitation: 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 = "..";
@@ -80,7 +80,7 @@ const StatusTooltipContent = ({ citation, status, foundCitation, isExpanded, onT
         return null;
     // Get search attempts from foundCitation
     const searchAttempts = foundCitation?.searchState?.searchAttempts;
-    const failedAttempts = searchAttempts?.filter(a => !a.success) || [];
+    const failedAttempts = searchAttempts?.filter((a) => !a.success) || [];
     // Collect all unique phrases tried
     const allPhrases = [];
     const seenPhrases = new Set();
@@ -106,7 +106,9 @@ 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 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();
@@ -159,7 +161,7 @@ const DefaultPopoverContent = ({ foundCitation, status, onImageClick, }) => {
     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: ["\"", foundCitation.matchSnippet, "\""] })), pageNumber && pageNumber > 0 && (_jsxs("span", { className: "dc-popover-page", children: ["Page ", pageNumber] }))] }));
 };
 // =============================================================================
 // MAIN COMPONENT
@@ -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);
             }
         };
@@ -249,8 +252,8 @@ 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);
     }, [
@@ -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,16 +358,23 @@ 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 &&
+        foundCitation &&
+        (foundCitation.verificationImageBase64 || foundCitation.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,
+            foundCitation: foundCitation ?? null,
+            status,
+        })) : (_jsx(DefaultPopoverContent, { citation: citation, foundCitation: foundCitation ?? 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 citationTrigger = (_jsx("span", { ref: (node) => {
+            containerRef.current =
+                node;
             if (typeof ref === "function") {
                 ref(node);
             }

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;
+    foundCitation?: Verification | null;
     /** Current search state for the citation */
     searchState?: SearchState | null;
     /** Event handlers */

package/lib/react/CitationVariants.js

@@ -1,5 +1,5 @@
 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 = "..";
@@ -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";
 /**
@@ -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 = ["*", "†", "‡", "§", "‖", "¶"];
@@ -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";
 /**
@@ -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";
 /**
@@ -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;
+    foundCitation: 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;
+    foundCitation?: 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() {
@@ -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;
+    foundCitation: 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/react/utils.js

@@ -13,7 +13,6 @@ export function generateCitationKey(citation) {
         citation.lineIds?.join(",") || "",
         citation.timestamps?.startTime || "",
         citation.timestamps?.endTime || "",
-        citation.fragmentContext || "",
     ];
     return sha1Hash(keyParts.join("|")).slice(0, 16);
 }
@@ -31,7 +30,10 @@ export function generateCitationInstanceId(citationKey) {
 export function getCitationDisplayText(citation, options = {}) {
     const { displayCitationValue = false, fallbackDisplay } = options;
     if (displayCitationValue) {
-        return citation.value || citation.citationNumber?.toString() || fallbackDisplay || "";
+        return (citation.value ||
+            citation.citationNumber?.toString() ||
+            fallbackDisplay ||
+            "");
     }
     return citation.citationNumber?.toString() || "";
 }

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,17 +21,15 @@ 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;
     };
-    fragmentContext?: string | null;
-    rawCitationMd?: string;
     beforeCite?: string;
 }
 export interface CitationStatus {

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.8",
+    "version": "1.1.0",
     "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}`);
-}