@deepcitation/deepcitation-js 1.1.49 → 1.1.51

package/lib/react/index.d.ts

@@ -1,6 +1,6 @@
-import { C as Citation, V as Verification, g as SearchStatus, a as CitationStatus, S as SourceType } from '../index-fvVBZYVK.js';
-export { C as CITATION_X_PADDING, c as CITATION_Y_PADDING, h as classNames, b as generateCitationInstanceId, g as generateCitationKey, d as getCitationDisplayText, f as getCitationKeySpanText, e as getCitationNumber, i as isUrlCitation } from '../utils-DuacFTtu.js';
+import { C as Citation, V as Verification, a as CitationStatus, g as SearchStatus, i as SourceType, e as SearchAttempt } from '../index-BHjI8Bh1.js';
 import React$1 from 'react';
+export { C as CITATION_X_PADDING, a as CITATION_Y_PADDING, d as classNames, g as generateCitationInstanceId, b as generateCitationKey, e as getCitationAnchorText, f as getCitationDisplayText, h as getCitationNumber, i as isUrlCitation } from '../utils-CoSP-i76.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -14,27 +14,29 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
  * | `superscript` | Small raised text like footnotes¹              |
  * | `minimal`     | Compact text with indicator, truncated         |
  * | `source`      | Source chip showing name + count (ChatGPT-style) |
+ * | `linter`      | Inline text with semantic underlines (solid/dashed/wavy) |
  */
-type CitationVariant = "chip" | "brackets" | "text" | "superscript" | "minimal" | "source";
+type CitationVariant = "chip" | "brackets" | "text" | "superscript" | "minimal" | "source" | "linter";
 /**
  * Content to display in the citation.
  *
  * | Content       | Description                                    |
  * |---------------|------------------------------------------------|
- * | `keySpan`     | Descriptive text (e.g., "Revenue Growth")      |
+ * | `anchorText`  | Descriptive text (e.g., "Revenue Growth")      |
  * | `number`      | Citation number (e.g., "1", "2", "3")          |
  * | `indicator`   | Only the status icon (✓/⚠), no text            |
  * | `source`      | Source name with count (e.g., "Wikipedia +2")  |
  *
  * Default content per variant:
- * - `chip` → `keySpan`
- * - `brackets` → `keySpan`
- * - `text` → `keySpan`
+ * - `chip` → `anchorText`
+ * - `brackets` → `anchorText`
+ * - `text` → `anchorText`
+ * - `linter` → `anchorText`
  * - `superscript` → `number`
  * - `minimal` → `number`
  * - `source` → `source`
  */
-type CitationContent = "keySpan" | "number" | "indicator" | "source";
+type CitationContent = "anchorText" | "number" | "indicator" | "source";
 /**
  * URL fetch/access status for URL citations.
  * Covers HTTP accessibility and redirect scenarios.
@@ -160,20 +162,27 @@ interface BaseCitationProps {
     /**
      * What content to display in the citation.
      * If not specified, defaults based on variant:
-     * - `chip` → `keySpan`
+     * - `chip` → `anchorText`
      * - `brackets` → `number`
-     * - `text` → `keySpan`
+     * - `text` → `anchorText`
      * - `superscript` → `number`
      * - `minimal` → `number`
      */
     content?: CitationContent;
-    /** Fallback display text when citation keySpan is empty */
+    /** Fallback display text when citation anchorText is empty */
     fallbackDisplay?: string | null;
 }
 /**
  * Visual style variants for URL citations.
+ *
+ * | Variant   | Description                                              |
+ * |-----------|----------------------------------------------------------|
+ * | `badge`   | Clean bordered badge with favicon (default)              |
+ * | `chip`    | Pill/badge style with background color                   |
+ * | `inline`  | Underlined inline link                                   |
+ * | `bracket` | [text✓] with square brackets                             |
  */
-type UrlCitationVariant = "chip" | "inline" | "bracket";
+type UrlCitationVariant = "badge" | "chip" | "inline" | "bracket";
 /**
  * Props for URL citation component
  */
@@ -244,7 +253,7 @@ interface CitationRenderProps {
     citationKey: string;
     /** Display text for the citation */
     displayText: string;
-    /** Whether this is a merged keySpan display */
+    /** Whether this is a merged anchorText display */
     isMergedDisplay: boolean;
 }
 /**
@@ -569,6 +578,22 @@ type GroupCitationsBySource = (citations: CitationDrawerItem[]) => SourceCitatio
  * Extracts domain from URL for compact display.
  */
 declare function extractDomain(url: string): string;
+/**
+ * Truncates a string to max length with ellipsis.
+ */
+declare function truncateString(str: string, maxLength: number): string;
+/**
+ * Get path from URL for display.
+ */
+declare function getUrlPath(url: string): string;
+/**
+ * Status indicator icons for URL fetch states.
+ */
+declare const STATUS_ICONS: Record<UrlFetchStatus, {
+    icon: string;
+    label: string;
+    className: string;
+}>;
 /**
  * Checks if status is a blocked status.
  */
@@ -589,6 +614,51 @@ declare function isRedirectedStatus(status: UrlFetchStatus): boolean;
  * Checks if URL was successfully verified.
  */
 declare function isVerifiedStatus(status: UrlFetchStatus): boolean;
+/**
+ * URL Citation Component
+ *
+ * Displays a URL citation with compact domain display,
+ * verification status, and blocked/error indicators.
+ *
+ * @example
+ * ```tsx
+ * <UrlCitationComponent
+ *   urlMeta={{
+ *     url: "https://example.com/article",
+ *     fetchStatus: "verified",
+ *   }}
+ * />
+ * // Renders: [example.com ✓]
+ *
+ * <UrlCitationComponent
+ *   urlMeta={{
+ *     url: "https://protected-site.com/page",
+ *     fetchStatus: "blocked_login",
+ *   }}
+ * />
+ * // Renders: [protected-site.com 🔒]
+ * ```
+ */
+declare const UrlCitationComponent: React$1.ForwardRefExoticComponent<UrlCitationProps & React$1.RefAttributes<HTMLSpanElement>>;
+/**
+ * Memoized version for performance.
+ */
+declare const MemoizedUrlCitationComponent: React$1.NamedExoticComponent<UrlCitationProps & React$1.RefAttributes<HTMLSpanElement>>;
+/**
+ * Hook to parse URL and create UrlCitationMeta.
+ */
+declare function useUrlMeta(url: string, fetchStatus?: UrlFetchStatus, additionalMeta?: Partial<UrlCitationMeta>): UrlCitationMeta;
+/**
+ * Compact URL display utilities.
+ */
+declare const urlDisplayUtils: {
+    extractDomain: typeof extractDomain;
+    truncateString: typeof truncateString;
+    getUrlPath: typeof getUrlPath;
+    isBlockedStatus: typeof isBlockedStatus;
+    isErrorStatus: typeof isErrorStatus;
+    isVerifiedStatus: typeof isVerifiedStatus;
+};
 
 /**
  * Props for the CitationComponent.
@@ -643,19 +713,21 @@ interface CitationComponentProps extends BaseCitationProps {
      * - `superscript`: Small raised text like footnotes¹
      * - `minimal`: Compact text with indicator, truncated
      * - `source`: ChatGPT-style source chip with name + count
+     * - `linter`: Inline text with semantic underlines (solid/dashed/wavy)
      */
     variant?: CitationVariant;
     /**
      * What content to display in the citation.
-     * - `keySpan`: Descriptive text (e.g., "Revenue Growth")
+     * - `anchorText`: Descriptive text (e.g., "Revenue Growth")
      * - `number`: Citation number (e.g., "1", "2", "3")
      * - `indicator`: Only the status icon, no text
      * - `source`: Source name (e.g., "Wikipedia")
      *
      * Defaults based on variant:
-     * - `chip` → `keySpan`
-     * - `brackets` → `keySpan`
-     * - `text` → `keySpan`
+     * - `chip` → `anchorText`
+     * - `brackets` → `anchorText`
+     * - `text` → `anchorText`
+     * - `linter` → `anchorText`
      * - `superscript` → `number`
      * - `minimal` → `number`
      * - `source` → `source`
@@ -692,6 +764,11 @@ interface CitationComponentProps extends BaseCitationProps {
      * Falls back to citation.faviconUrl if not provided.
      */
     faviconUrl?: string;
+    /**
+     * Whether to show the status indicator (checkmark, warning, spinner).
+     * Defaults to true. Set to false to hide the indicator.
+     */
+    showIndicator?: boolean;
 }
 /**
  * CitationComponent displays a citation with verification status.
@@ -773,21 +850,21 @@ declare const DeepCitationIcon: ({ className }: {
 }) => react_jsx_runtime.JSX.Element;
 /**
  * Check icon SVG (no dependencies)
- * Size is controlled by parent container - use size-2 or similar on wrapper
+ * Size is controlled by parent container - use size-4 or similar on wrapper
  */
 declare const CheckIcon: ({ className }: {
     className?: string;
 }) => react_jsx_runtime.JSX.Element;
 /**
  * Warning icon SVG (no dependencies)
- * Size is controlled by parent container - use size-2 or similar on wrapper
+ * Size is controlled by parent container - use size-4 or similar on wrapper
  */
 declare const WarningIcon: ({ className }: {
     className?: string;
 }) => react_jsx_runtime.JSX.Element;
 /**
  * Spinner component for loading/pending state
- * Size is controlled by parent container - use size-2 or similar on wrapper
+ * Size is controlled by parent container - use size-4 or similar on wrapper
  * Animation (animate-spin) should be applied to the wrapper
  */
 declare const SpinnerIcon: ({ className }: {
@@ -814,6 +891,13 @@ declare const ExternalLinkIcon: ({ className }: {
 declare const CloseIcon: ({ className }: {
     className?: string;
 }) => react_jsx_runtime.JSX.Element;
+/**
+ * Lock icon for restricted/paywall content
+ * Size is controlled by parent container
+ */
+declare const LockIcon: ({ className }: {
+    className?: string;
+}) => react_jsx_runtime.JSX.Element;
 
 /**
  * Detects source type from URL domain.
@@ -963,4 +1047,247 @@ declare function useCitationDrawer(): {
     setCitations: (items: CitationDrawerItem[]) => void;
 };
 
-export { CheckIcon, type CitationBehaviorActions, type CitationBehaviorConfig, type CitationBehaviorContext, type CitationClickBehavior, CitationComponent, type CitationComponentProps, type CitationContent, type CitationContentProps, type CitationCursorClasses, CitationDrawer, type CitationDrawerItem, CitationDrawerItemComponent, type CitationDrawerItemProps, type CitationDrawerProps, type CitationEventHandlers, type CitationHoverBehavior, CitationOverlayProvider, type CitationRenderProps, type CitationStateClasses, type CitationStyles, type CitationTooltipProps, type CitationVariant, type CitationVariant as CitationVariantType, CloseIcon, type ContentMatchStatus, DeepCitationIcon, ExternalLinkIcon, type GroupCitationsBySource, LinkIcon, MemoizedCitationComponent, MemoizedSourcesListComponent, MemoizedSourcesListItem, MemoizedSourcesTrigger, type SourceChipProps, type SourceCitationGroup, SourcesListComponent, type SourcesListHeaderConfig, SourcesListItem, type SourcesListItemProps, type SourcesListProps, type SourcesListVariant, SourcesTrigger, type SourcesTriggerProps, SpinnerIcon, type UrlCitationMeta, type UrlCitationProps, type UrlCitationVariant, type UrlFetchStatus, type UrlVerificationMeta, WarningIcon, detectSourceType, extractDomain, getPlatformName, groupCitationsBySource, isAccessibleStatus, isBlockedStatus, isErrorStatus, isRedirectedStatus, isVerifiedStatus, sourceCitationsToListItems, useCitationDrawer, useCitationOverlay, useHasCitationOverlayProvider, useSourcesList };
+interface PrefetchedPopoverImageProps {
+    /** Whether the popover (and image) should be visible */
+    isVisible: boolean;
+    /** Base64 image source (data URI) */
+    src: string;
+    /** Alt text for accessibility */
+    alt: string;
+    /** Optional click handler for the image */
+    onClick?: () => void;
+    /** Optional className for the container */
+    className?: string;
+    /** Image style constraints */
+    imageStyle?: React$1.CSSProperties;
+}
+/**
+ * Renders an image that's pre-rendered in the background before being shown.
+ *
+ * Uses React 19.2's Activity component to keep the image rendered but hidden,
+ * so when the user hovers, the image appears instantly without a loading flash.
+ *
+ * @example
+ * ```tsx
+ * <PrefetchedPopoverImage
+ *   isVisible={isHovering}
+ *   src={verification.verificationImageBase64}
+ *   alt="Citation verification"
+ *   onClick={() => setExpandedImageSrc(src)}
+ * />
+ * ```
+ */
+declare function PrefetchedPopoverImage({ isVisible, src, alt, onClick, className, imageStyle, }: PrefetchedPopoverImageProps): react_jsx_runtime.JSX.Element;
+/**
+ * Memoized version of PrefetchedPopoverImage.
+ * Use this when the parent re-renders frequently.
+ */
+declare const MemoizedPrefetchedPopoverImage: React$1.MemoExoticComponent<typeof PrefetchedPopoverImage>;
+/**
+ * Hook to prefetch an image into browser cache.
+ * This is a simpler alternative when Activity isn't available or needed.
+ *
+ * @example
+ * ```tsx
+ * const prefetchImage = usePrefetchImage();
+ *
+ * // Prefetch when verification arrives
+ * useEffect(() => {
+ *   if (verification?.verificationImageBase64) {
+ *     prefetchImage(verification.verificationImageBase64);
+ *   }
+ * }, [verification?.verificationImageBase64]);
+ * ```
+ */
+declare function usePrefetchImage(): (src: string) => Promise<void>;
+/**
+ * Prefetches multiple images concurrently.
+ * Useful for batch prefetching all verification images.
+ *
+ * @example
+ * ```tsx
+ * // Prefetch all images when verifications load
+ * useEffect(() => {
+ *   const srcs = verifications
+ *     .filter(v => v.verificationImageBase64)
+ *     .map(v => v.verificationImageBase64!);
+ *   prefetchImages(srcs);
+ * }, [verifications]);
+ * ```
+ */
+declare function prefetchImages(srcs: string[]): Promise<void[]>;
+
+type DiffDisplayMode = "auto" | "inline" | "split";
+interface SplitDiffDisplayProps {
+    /** The expected/claimed text from the AI */
+    expected: string;
+    /** The actual text found in the source */
+    actual: string;
+    /** Optional label for the diff section */
+    label?: string;
+    /** Additional class name */
+    className?: string;
+    /** Sanitize function for text preprocessing */
+    sanitize?: (text: string) => string;
+    /** Display mode: auto (smart), inline (word diff), or split (two-row) */
+    mode?: DiffDisplayMode;
+    /** Show a match quality indicator bar */
+    showMatchQuality?: boolean;
+    /** Maximum characters before collapsing with "Show more" */
+    maxCollapsedLength?: number;
+    /** Expected anchorText to highlight within expected text */
+    anchorTextExpected?: string;
+    /** Found anchorText to highlight within actual text */
+    anchorTextFound?: string;
+    /** Verification status for contextual messages */
+    status?: SearchStatus | null;
+    /** Similarity score (0-1), calculated if not provided */
+    similarity?: number;
+}
+/**
+ * Get a human-readable status message for the verification status
+ */
+declare function getContextualStatusMessage(status: SearchStatus | null | undefined, expectedPage?: number | null, actualPage?: number | null): string;
+interface MatchQualityBarProps {
+    similarity: number;
+    className?: string;
+}
+declare const MatchQualityBar: React$1.FC<MatchQualityBarProps>;
+interface CollapsibleTextProps {
+    text: string;
+    maxLength: number;
+    className?: string;
+    anchorText?: string;
+    anchorTextClass?: string;
+}
+declare const CollapsibleText: React$1.FC<CollapsibleTextProps>;
+/**
+ * SplitDiffDisplay - Enhanced diff display with split view mode
+ *
+ * Features:
+ * - Auto mode: intelligently chooses inline or split based on similarity
+ * - Split view: clear two-row Expected/Found layout for high-variance diffs
+ * - KeySpan highlighting: underlines matching portions
+ * - Match quality bar: visual similarity indicator
+ * - Collapsible text: truncates long text with expand option
+ */
+declare const SplitDiffDisplay: React$1.FC<SplitDiffDisplayProps>;
+
+interface VerificationTabsProps {
+    expected: string;
+    actual: string;
+    label?: string;
+    renderCopyButton?: (text: string, position: "expected" | "found") => React$1.ReactNode;
+    emptyText?: string;
+    /** Verification status for contextual messages */
+    status?: SearchStatus | null;
+    /** Expected anchorText to highlight */
+    anchorText?: string;
+    /** Found anchorText to highlight */
+    verifiedKeySpan?: string;
+    /** Default display mode */
+    defaultMode?: DiffDisplayMode;
+    /** Expected page number (for status messages) */
+    expectedPage?: number | null;
+    /** Actual page number found (for status messages) */
+    actualPage?: number | null;
+    /** Show match quality indicator */
+    showMatchQuality?: boolean;
+    /** Maximum length before collapsing text */
+    maxCollapsedLength?: number;
+}
+declare const VerificationTabs: React$1.FC<VerificationTabsProps>;
+
+type DiffBlockType = "modified" | "added" | "removed" | "unchanged";
+interface DiffPart {
+    value: string;
+    added?: boolean;
+    removed?: boolean;
+}
+interface DiffBlock {
+    type: DiffBlockType;
+    parts: DiffPart[];
+}
+declare const useSmartDiff: (expected?: string, actual?: string) => {
+    diffResult: DiffBlock[];
+    hasDiff: boolean;
+    similarity: number;
+    isHighVariance: boolean;
+};
+
+interface VerificationLogProps {
+    /** Array of search attempts from verification */
+    searchAttempts: SearchAttempt[];
+    /** Overall verification status */
+    status?: SearchStatus | null;
+    /** Expected page number from citation */
+    expectedPage?: number;
+    /** Expected line number from citation */
+    expectedLine?: number;
+    /** Page where match was found */
+    foundPage?: number;
+    /** Line where match was found */
+    foundLine?: number;
+    /** Whether the log is expanded (controlled) */
+    isExpanded?: boolean;
+    /** Callback when expansion state changes */
+    onExpandChange?: (expanded: boolean) => void;
+    /** Full phrase from citation (for audit display) */
+    fullPhrase?: string;
+    /** Anchor text from citation (for audit display) */
+    anchorText?: string;
+}
+interface StatusHeaderProps {
+    /** Verification status */
+    status?: SearchStatus | null;
+    /** Page where match was found */
+    foundPage?: number;
+    /** Expected page from citation */
+    expectedPage?: number;
+    /** Whether this is a compact header (for success states) */
+    compact?: boolean;
+    /** Anchor text to display in the header (for combined layout) */
+    anchorText?: string;
+    /** Full phrase for quote box (when using combined layout) */
+    fullPhrase?: string;
+}
+interface QuoteBoxProps {
+    /** The phrase to display */
+    phrase: string;
+    /** Maximum length before truncation */
+    maxLength?: number;
+}
+/**
+ * Header bar showing verification status with icon and text.
+ *
+ * shadcn HoverCard style:
+ * - Clean white/dark background (no colored header backgrounds)
+ * - Colored icon only indicates status
+ * - Subtle ring border for elevation
+ * - Page badge uses arrow format for location differences (Pg 5 → 7)
+ */
+declare function StatusHeader({ status, foundPage, expectedPage, compact, anchorText, fullPhrase }: StatusHeaderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Styled quote box for displaying the phrase being verified.
+ * Issue #7: Removed serif/italic for modern UI consistency.
+ * Uses left border accent (which aligns with shadcn patterns).
+ */
+declare function QuoteBox({ phrase, maxLength }: QuoteBoxProps): react_jsx_runtime.JSX.Element;
+/**
+ * Collapsible verification log showing search attempt timeline.
+ * Displays a summary header that can be clicked to expand the full log.
+ */
+declare function VerificationLog({ searchAttempts, status, expectedPage, expectedLine, foundPage, foundLine, isExpanded: controlledIsExpanded, onExpandChange, fullPhrase, anchorText, }: VerificationLogProps): react_jsx_runtime.JSX.Element | null;
+interface AttemptingToVerifyProps {
+    /** The anchor text or key phrase being verified */
+    anchorText?: string;
+    /** The full phrase being searched */
+    fullPhrase?: string;
+}
+/**
+ * Section showing what citation is being verified.
+ * Displays the anchor text and quote box being searched.
+ */
+declare function AttemptingToVerify({ anchorText, fullPhrase }: AttemptingToVerifyProps): react_jsx_runtime.JSX.Element;
+
+export { AttemptingToVerify, type AttemptingToVerifyProps, CheckIcon, type CitationBehaviorActions, type CitationBehaviorConfig, type CitationBehaviorContext, type CitationClickBehavior, CitationComponent, type CitationComponentProps, type CitationContent, type CitationContentProps, type CitationCursorClasses, CitationDrawer, type CitationDrawerItem, CitationDrawerItemComponent, type CitationDrawerItemProps, type CitationDrawerProps, type CitationEventHandlers, type CitationHoverBehavior, CitationOverlayProvider, type CitationRenderProps, type CitationStateClasses, type CitationStyles, type CitationTooltipProps, type CitationVariant, type CitationVariant as CitationVariantType, CloseIcon, CollapsibleText, type ContentMatchStatus, DeepCitationIcon, type DiffBlock, type DiffBlockType, type DiffDisplayMode, type DiffPart, ExternalLinkIcon, type GroupCitationsBySource, LinkIcon, LockIcon, MatchQualityBar, MemoizedCitationComponent, MemoizedPrefetchedPopoverImage, MemoizedSourcesListComponent, MemoizedSourcesListItem, MemoizedSourcesTrigger, MemoizedUrlCitationComponent, PrefetchedPopoverImage, QuoteBox, type QuoteBoxProps, type SourceChipProps, type SourceCitationGroup, SourcesListComponent, type SourcesListHeaderConfig, SourcesListItem, type SourcesListItemProps, type SourcesListProps, type SourcesListVariant, SourcesTrigger, type SourcesTriggerProps, SpinnerIcon, SplitDiffDisplay, type SplitDiffDisplayProps, StatusHeader, type StatusHeaderProps, STATUS_ICONS as URL_STATUS_ICONS, UrlCitationComponent, type UrlCitationMeta, type UrlCitationProps, type UrlCitationVariant, type UrlFetchStatus, type UrlVerificationMeta, VerificationLog, type VerificationLogProps, VerificationTabs, WarningIcon, detectSourceType, extractDomain, getContextualStatusMessage, getPlatformName, groupCitationsBySource, isAccessibleStatus, isBlockedStatus, isErrorStatus, isRedirectedStatus, isVerifiedStatus, prefetchImages, sourceCitationsToListItems, urlDisplayUtils, useCitationDrawer, useCitationOverlay, useHasCitationOverlayProvider, usePrefetchImage, useSmartDiff, useSourcesList, useUrlMeta };