@deepcitation/deepcitation-js 1.1.0 → 1.1.2

package/README.md

@@ -18,6 +18,12 @@
 
 LLMs hallucinate. Even when given source documents, they make up quotes, invent statistics, and cite pages that don't exist. DeepCitation solves this by **deterministically verifying every citation** against your source documents—and generating visual proof.
 
+<div align="center">
+<img src="./examples/assets/deepcitation-medical-demo.gif" alt="DeepCitation medical documentation demo showing verified inline citations" width="700" />
+<br />
+<em>Medical documentation with verified inline citations — certainty at a glance</em>
+</div>
+
 ```
 Before: "Revenue grew 45% [1]"  →  ❓ Did the LLM make this up?
 After:  "Revenue grew 45% [1]"  →  ✅ Verified on page 3, line 12 (with screenshot)
@@ -59,7 +65,7 @@ import { DeepCitation, wrapCitationPrompt } from "@deepcitation/deepcitation-js"
 
 const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
 
-// Upload source files
+// Upload source files, this can be done before the user types their prompt
 const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
   { file: pdfBuffer, filename: "report.pdf" },
 ]);
@@ -87,31 +93,49 @@ Verify citations against the source documents.
 ```typescript
 const result = await dc.verifyCitations({
   llmOutput: response.content,
-  fileDataParts,
+  fileDataParts, //optional 
 });
 
-// result.citations contains verification status + visual proof
+// result.verifications contains verification status + visual proof
+const { citations, verifications } = result;
+
 ```
 
 ### Step 3: Display
 
-Render verified citations with React components.
+Parse the LLM output and render verified citations inline with React components.
 
 ```tsx
 import { CitationComponent } from "@deepcitation/deepcitation-js/react";
+import {
+  parseCitation,
+  generateCitationKey,
+} from "@deepcitation/deepcitation-js";
 import "@deepcitation/deepcitation-js/react/styles.css";
 
-function Response({ citations, verifications }) {
-  return (
-    <p>
-      Revenue grew by
-      <CitationComponent
-        citation={citations["1"]}
-        foundCitation={verifications["1"]}
-      />
-      this quarter.
-    </p>
-  );
+function Response({ llmOutput, verifications }) {
+  // Split LLM output by citation tags and render inline
+  const renderWithCitations = (text: string) => {
+    const parts = text.split(/(<cite\s+[^>]*\/>)/g);
+
+    return parts.map((part, index) => {
+      if (part.startsWith("<cite")) {
+        const { citation } = parseCitation(part);
+        const citationKey = generateCitationKey(citation);
+
+        return (
+          <CitationComponent
+            key={index}
+            citation={citation}
+            verification={verifications[citationKey]}
+          />
+        );
+      }
+      return <span key={index}>{part}</span>;
+    });
+  };
+
+  return <div>{renderWithCitations(llmOutput)}</div>;
 }
 ```
 
@@ -123,8 +147,7 @@ function Response({ citations, verifications }) {
 
 ```typescript
 const dc = new DeepCitation({
-  apiKey: string,      // Your API key (sk-dc-*)
-  apiUrl?: string,     // Optional: Custom API URL
+  apiKey: string      // Your API key (sk-dc-*)
 });
 
 // Upload and prepare source files

package/lib/parsing/parseCitation.js

@@ -100,8 +100,9 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     const citationMatches = [...middleCite.matchAll(citationRegex)];
     const match = citationMatches?.[0];
     const pageNumber = match?.[2] ? parseInt(match?.[2]) : undefined;
+    const pageIndex = match?.[3] ? parseInt(match?.[3]) : undefined;
     let fileId = match?.[1];
-    let attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || match?.[1];
+    let attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || fileId;
     // Use helper to handle escaped quotes inside the phrase
     let fullPhrase = cleanAndUnescape(match?.[4]);
     let keySpan = cleanAndUnescape(match?.[5]);
@@ -138,8 +139,7 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     let timestamps;
     if (avMatch) {
         fileId = avMatch?.[1];
-        attachmentId =
-            fileId?.length === 20 ? fileId : mdAttachmentId || avMatch?.[1];
+        attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || fileId;
         fullPhrase = cleanAndUnescape(avMatch?.[2]);
         const timestampsString = avMatch?.[3]?.replace(/timestamps=['"]|['"]/g, "");
         const [startTime, endTime] = timestampsString?.split("-") || [];
@@ -156,6 +156,7 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     const citation = {
         fileId: attachmentId,
         pageNumber,
+        startPageKey: `page_number_${pageNumber || 1}_index_${pageIndex || 0}`,
         fullPhrase,
         keySpan,
         citationNumber,
@@ -194,13 +195,21 @@ const parseJsonCitation = (jsonCitation, citationNumber) => {
     if (!fullPhrase) {
         return null;
     }
-    // Parse startPageKey format: "page_number_PAGE_index_INDEX"
+    // Parse startPageKey format: "page_number_PAGE_index_INDEX" or simple "PAGE_INDEX"
     let pageNumber;
     if (startPageKey) {
+        // Try full format first: page_number_5_index_2 or pageKey_5_index_2
         const pageMatch = startPageKey.match(/page[_a-zA-Z]*(\d+)_index_(\d+)/i);
         if (pageMatch) {
             pageNumber = parseInt(pageMatch[1], 10);
         }
+        else {
+            // Try simple n_m format: 5_4 (page 5, index 4)
+            const simpleMatch = startPageKey.match(/^(\d+)_(\d+)$/);
+            if (simpleMatch) {
+                pageNumber = parseInt(simpleMatch[1], 10);
+            }
+        }
     }
     // Sort lineIds if present
     const lineIds = rawLineIds?.length

package/lib/react/CitationComponent.d.ts

@@ -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?: Verification | 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: Verification | null;
+        verification: Verification | null;
         status: CitationStatus;
     }) => ReactNode;
 }

package/lib/react/CitationComponent.js

@@ -74,12 +74,12 @@ 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;
+    // Get search attempts from verification
+    const searchAttempts = verification?.searchState?.searchAttempts;
     const failedAttempts = searchAttempts?.filter((a) => !a.success) || [];
     // Collect all unique phrases tried
     const allPhrases = [];
@@ -105,7 +105,7 @@ const StatusTooltipContent = ({ citation, status, foundCitation, isExpanded, onT
     }
     if (isPartialMatch) {
         const expectedText = citation.fullPhrase || citation.value || "";
-        const actualText = foundCitation?.matchSnippet || "";
+        const actualText = verification?.matchSnippet || "";
         const truncatedExpected = expectedText.length > 100
             ? expectedText.slice(0, 100) + "…"
             : expectedText;
@@ -140,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
@@ -182,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);
@@ -235,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);
@@ -243,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
@@ -260,11 +260,11 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         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(() => {
@@ -359,19 +359,19 @@ 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);
+        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,
+            verification: verification ?? null,
             status,
-        })) : (_jsx(DefaultPopoverContent, { citation: citation, foundCitation: foundCitation ?? null, status: status, onImageClick: handleImageClick })) })) : null;
+        })) : (_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 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;
@@ -381,7 +381,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
             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

@@ -8,7 +8,7 @@ import type { BaseCitationProps, CitationVariant as CitationVariantType, Citatio
  */
 export interface CitationVariantProps extends BaseCitationProps {
     /** Found citation highlight location data */
-    foundCitation?: Verification | 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

@@ -5,13 +5,13 @@ import { generateCitationKey, generateCitationInstanceId, getCitationDisplayText
 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,
@@ -77,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,
@@ -123,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)
@@ -174,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,
@@ -216,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,

package/lib/react/primitives.d.ts

@@ -11,7 +11,7 @@ interface CitationContextValue {
     citationKey: string;
     citationInstanceId: string;
     status: CitationStatus;
-    foundCitation: Verification | 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?: Verification | null;
+    verification?: Verification | null;
     searchState?: SearchState | null;
     children: ReactNode;
     displayCitationValue?: boolean;

package/lib/react/primitives.js

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

package/lib/react/types.d.ts

@@ -130,7 +130,7 @@ export interface CitationContentProps extends BaseCitationProps {
     /** Unique instance ID for this citation render */
     citationInstanceId: string;
     /** Found citation highlight data */
-    foundCitation: Verification | null | undefined;
+    verification: Verification | null | undefined;
     /** Current search state */
     searchState: SearchState | undefined | null;
     /** Actual page number where citation was found */

package/lib/react/utils.js

@@ -8,8 +8,8 @@ export function generateCitationKey(citation) {
         citation.fileId || "",
         citation.pageNumber?.toString() || "",
         citation.fullPhrase || "",
+        citation.keySpan?.toString() || "",
         citation.value || "",
-        citation.citationNumber?.toString() || "",
         citation.lineIds?.join(",") || "",
         citation.timestamps?.startTime || "",
         citation.timestamps?.endTime || "",

package/package.json

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