@deepcitation/deepcitation-js 1.1.10 → 1.1.12

package/lib/prompts/citationPrompts.d.ts

@@ -1,4 +1,4 @@
-export declare const CITATION_MARKDOWN_SYNTAX_PROMPT = "\nCitation syntax to use within Markdown:\n\u2022 To support any ideas or information that requires a citation from the provided content, use the following citation syntax:\n<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text />; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' key_span='the verbatim value or 1-3 words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />\n\n\u2022 Very important: for page numbers, only use the page number and page index info from the page_number_PAGE_index_INDEX format (e.g. <page_number_1_index_0>) and never from the contents inside the page.\n\u2022 start_page_key, full_phrase, and line_ids are required for each citation.\n\u2022 Infer line_ids, as we only provide the first, last, and every 5th line. When copying a previous <cite />, use the full info from the previous citation without changing the start_page_key, line_ids, or any other <cite /> attributes.\n\u2022 Use refer to line_ids inclusively, and use a range (or single) for each citation, split multiple sequential line_ids into multiple citations.\n\u2022 These citations will be replaced and displayed in-line as a numeric element (e.g. [1]), the markdown preceding <cite /> should read naturally with only one <cite /> per sentence with rare exceptions for two <cite /> in a sentence. <cite /> often present best at the end of the sentence, and are not grouped at the end of the document.\n\u2022 The full_phrase should be the exact verbatim text of the phrase or paragraph from the source document to support the insight or idea.\n\u2022 We do NOT put the full_phrase inside <cite ...></cite>; we only use full_phrase inside the full_phrase attribute.\n";
+export declare const CITATION_MARKDOWN_SYNTAX_PROMPT = "\nCitation syntax to use within Markdown:\n\u2022 To support any ideas or information that requires a citation from the provided content, use the following citation syntax:\n<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text />; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' key_span='the verbatim 1-3 words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />\n\n\u2022 Very important: for page numbers, only use the page number and page index info from the page_number_PAGE_index_INDEX format (e.g. <page_number_1_index_0>) and never from the contents inside the page.\n\u2022 start_page_key, full_phrase, and line_ids are required for each citation.\n\u2022 Infer line_ids, as we only provide the first, last, and every 5th line. When copying a previous <cite />, use the full info from the previous citation without changing the start_page_key, line_ids, or any other <cite /> attributes.\n\u2022 Use refer to line_ids inclusively, and use a range (or single) for each citation, split multiple sequential line_ids into multiple citations.\n\u2022 These citations will be replaced and displayed in-line as a numeric element (e.g. [1]), the markdown preceding <cite /> should read naturally with only one <cite /> per sentence with rare exceptions for two <cite /> in a sentence. <cite /> often present best at the end of the sentence, and are not grouped at the end of the document.\n\u2022 The full_phrase should be the exact verbatim text of the phrase or paragraph from the source document to support the insight or idea.\n\u2022 We do NOT put the full_phrase inside <cite ...></cite>; we only use full_phrase inside the full_phrase attribute.\n";
 export declare const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = "\n\u2022 To support any ideas or information that requires a citation from the provided content, use the following citation syntax:\n<cite file_id='file_id' full_phrase='the verbatim text of the phrase; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' reasoning='the logic connecting the form section requirements to the supporting source citation' />\n\u2022 These citations are displayed in-line or in the relevant list item, and are not grouped at the end of the document.\n";
 export interface WrapSystemPromptOptions {
     /** The original system prompt to wrap with citation instructions */

package/lib/prompts/citationPrompts.js

@@ -1,7 +1,7 @@
 export const CITATION_MARKDOWN_SYNTAX_PROMPT = `
 Citation syntax to use within Markdown:
 • To support any ideas or information that requires a citation from the provided content, use the following citation syntax:
-<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text />; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' key_span='the verbatim value or 1-3 words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />
+<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text />; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' key_span='the verbatim 1-3 words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />
 
 • Very important: for page numbers, only use the page number and page index info from the page_number_PAGE_index_INDEX format (e.g. <page_number_1_index_0>) and never from the contents inside the page.
 • start_page_key, full_phrase, and line_ids are required for each citation.
@@ -121,11 +121,11 @@ export const CITATION_JSON_OUTPUT_FORMAT = {
         },
         fullPhrase: {
             type: "string",
-            description: "The verbatim text of the terse phrase inside <file_text /> to support the value description (if there is a detected OCR correction, use the corrected text)",
+            description: "The verbatim text of the terse phrase inside <file_text /> to support the citation (if there is a detected OCR correction, use the corrected text)",
         },
         keySpan: {
             type: "string",
-            description: "the verbatim value or 1-3 words within fullPhrase that best support the citation",
+            description: "the verbatim 1-3 words within fullPhrase that best support the citation",
         },
         lineIds: {
             type: "array",
@@ -152,7 +152,7 @@ export const CITATION_AV_BASED_JSON_OUTPUT_FORMAT = {
         },
         fullPhrase: {
             type: "string",
-            description: "The exact verbatim text of the phrase or paragraph from the source document to support the value description (if there is a detected OCR correction, use the verbatim corrected text)",
+            description: "The exact verbatim text of the phrase or paragraph from the source document to support the citation (if there is a detected OCR correction, use the verbatim corrected text)",
         },
         timestamps: {
             type: "object",

package/lib/react/CitationComponent.d.ts

@@ -7,7 +7,7 @@ export type { CitationVariant } from "./types.js";
 /**
  * Props for the CitationComponent.
  *
- * @example Brackets variant (default) - shows value/number in brackets with blue styling
+ * @example Brackets variant (default) - shows keySpan/number in brackets with blue styling
  * ```tsx
  * <CitationComponent
  *   citation={{ citationNumber: 1, fullPhrase: "Revenue grew by 25%" }}
@@ -19,17 +19,17 @@ export type { CitationVariant } from "./types.js";
  * @example Numeric variant - shows just the citation number with indicator
  * ```tsx
  * <CitationComponent
- *   citation={{ citationNumber: 1, value: "25% growth" }}
+ *   citation={{ citationNumber: 1, keySpan: "25% growth" }}
  *   verification={verificationResult}
  *   variant="numeric"
  * />
  * // Renders: 1✓
  * ```
  *
- * @example Text variant - shows the value without styling
+ * @example Text variant - shows the keySpan without styling
  * ```tsx
  * <CitationComponent
- *   citation={{ citationNumber: 1, value: "25% growth" }}
+ *   citation={{ citationNumber: 1, keySpan: "25% growth" }}
  *   verification={verificationResult}
  *   variant="text"
  * />
@@ -73,9 +73,9 @@ export interface CitationComponentProps extends BaseCitationProps {
     verification?: Verification | null;
     /**
      * Display variant for the citation.
-     * - `brackets`: Shows value/number in brackets, blue text styling (default)
+     * - `brackets`: Shows keySpan/number in brackets, blue text styling (default)
      * - `numeric`: Shows citation number with indicator, no brackets
-     * - `text`: Shows the value, no text styling, no truncate, shows indicator
+     * - `text`: Shows the keySpan, no text styling, no truncate, shows indicator
      * - `minimal`: No brackets, just display text with indicator
      * - `indicator`: Only the status indicator (checkmark/warning), no text
      */

package/lib/react/CitationComponent.js

@@ -272,11 +272,11 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         if (variant === "numeric") {
             return citation.citationNumber?.toString() ?? "";
         }
-        // For text/minimal/brackets, show the value or fullPhrase
+        // For text/minimal variants, always show keySpan
+        // For brackets variant, show keySpan only if displayKeySpan prop is true
         return getCitationDisplayText(citation, {
             displayKeySpan: variant === "text" ||
                 variant === "minimal" ||
-                variant === "brackets" ||
                 displayKeySpan,
             fallbackDisplay,
         });
@@ -309,12 +309,13 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         if (renderIndicator) {
             return renderIndicator(status);
         }
-        if (isVerified) {
-            return _jsx(DefaultVerifiedIndicator, {});
-        }
-        else if (isPartialMatch) {
+        // Check partial match first since isVerified includes isPartialMatch
+        if (isPartialMatch) {
             return _jsx(DefaultPartialIndicator, {});
         }
+        else if (isVerified) {
+            return _jsx(DefaultVerifiedIndicator, {});
+        }
         else if (isPending) {
             return (_jsx("span", { className: "dc-indicator dc-indicator--pending", "aria-hidden": "true", children: TWO_DOTS_THINKING_CONTENT }));
         }
@@ -339,7 +340,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         if (variant === "indicator") {
             return (_jsx("span", { className: "dc-citation-text", children: renderStatusIndicator() }));
         }
-        // Text variant - no special styling, shows value with indicator
+        // Text variant - no special styling, shows keySpan with indicator
         if (variant === "text") {
             return (_jsxs("span", { className: "dc-citation-text dc-citation-text--plain", children: [displayText, renderStatusIndicator()] }));
         }
@@ -351,7 +352,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         if (variant === "numeric") {
             return (_jsxs("span", { className: "dc-citation-text", children: [displayText, renderStatusIndicator()] }));
         }
-        // Brackets variant (default) - value/number in brackets with styling
+        // Brackets variant (default) - keySpan/number in brackets with styling
         return (_jsxs("span", { className: "dc-citation-bracket", "aria-hidden": "true", role: "presentation", children: ["[", _jsxs("span", { className: "dc-citation-text", children: [displayText, renderStatusIndicator()] }), "]"] }));
     };
     // Determine if popover should be shown

package/lib/react/primitives.d.ts

@@ -55,12 +55,12 @@ export interface CitationNumberProps extends HTMLAttributes<HTMLSpanElement> {
 }
 /** Displays the citation number. */
 export declare const CitationNumber: React.ForwardRefExoticComponent<CitationNumberProps & React.RefAttributes<HTMLSpanElement>>;
-export interface CitationValueProps extends HTMLAttributes<HTMLSpanElement> {
-    value?: string;
+export interface CitationKeySpanProps extends HTMLAttributes<HTMLSpanElement> {
+    keySpan?: string;
     separator?: string;
 }
-/** Displays the citation value (summary text). */
-export declare const CitationValue: React.ForwardRefExoticComponent<CitationValueProps & React.RefAttributes<HTMLSpanElement>>;
+/** Displays the citation keySpan (summary text). */
+export declare const CitationKeySpan: React.ForwardRefExoticComponent<CitationKeySpanProps & React.RefAttributes<HTMLSpanElement>>;
 export interface CitationIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
     verifiedIndicator?: ReactNode;
     partialIndicator?: ReactNode;
@@ -95,7 +95,7 @@ export declare const Citation: {
     readonly Trigger: React.ForwardRefExoticComponent<CitationTriggerProps & React.RefAttributes<HTMLSpanElement>>;
     readonly Bracket: React.ForwardRefExoticComponent<CitationBracketProps & React.RefAttributes<HTMLSpanElement>>;
     readonly Number: React.ForwardRefExoticComponent<CitationNumberProps & React.RefAttributes<HTMLSpanElement>>;
-    readonly Value: React.ForwardRefExoticComponent<CitationValueProps & React.RefAttributes<HTMLSpanElement>>;
+    readonly KeySpan: React.ForwardRefExoticComponent<CitationKeySpanProps & React.RefAttributes<HTMLSpanElement>>;
     readonly Indicator: React.ForwardRefExoticComponent<CitationIndicatorProps & React.RefAttributes<HTMLSpanElement>>;
     readonly Status: typeof CitationStatusComponent;
     readonly Phrase: React.ForwardRefExoticComponent<CitationPhraseProps & React.RefAttributes<HTMLSpanElement>>;

package/lib/react/primitives.js

@@ -114,21 +114,21 @@ export const CitationNumber = forwardRef(({ className, number, ...props }, ref)
     return (_jsx("span", { ref: ref, className: classNames("citation-number", className), ...props, children: displayNumber }));
 });
 CitationNumber.displayName = "Citation.Number";
-/** Displays the citation value (summary text). */
-export const CitationValue = forwardRef(({ className, value, separator = " ", ...props }, ref) => {
+/** Displays the citation keySpan (summary text). */
+export const CitationKeySpan = forwardRef(({ className, keySpan, separator = " ", ...props }, ref) => {
     const { citation, config } = useCitationContext();
-    const displayValue = useMemo(() => {
-        if (value !== undefined)
-            return value;
+    const displayKeySpan = useMemo(() => {
+        if (keySpan !== undefined)
+            return keySpan;
         if (!config.displayKeySpan)
             return "";
         return citation.keySpan?.toString() || "";
-    }, [value, citation, config]);
-    if (!displayValue)
+    }, [keySpan, citation, config]);
+    if (!displayKeySpan)
         return null;
-    return (_jsxs("span", { ref: ref, className: classNames("citation-value", className), ...props, children: [displayValue, separator] }));
+    return (_jsxs("span", { ref: ref, className: classNames("citation-key-span", className), ...props, children: [displayKeySpan, separator] }));
 });
-CitationValue.displayName = "Citation.Value";
+CitationKeySpan.displayName = "Citation.KeySpan";
 /** Displays a status indicator based on citation verification state. */
 export const CitationIndicator = forwardRef(({ className, verifiedIndicator = "✓", partialIndicator = "*", missIndicator = null, pendingIndicator = null, showFor, ...props }, ref) => {
     const { status } = useCitationContext();
@@ -187,7 +187,7 @@ export const Citation = {
     Trigger: CitationTrigger,
     Bracket: CitationBracket,
     Number: CitationNumber,
-    Value: CitationValue,
+    KeySpan: CitationKeySpan,
     Indicator: CitationIndicator,
     Status: CitationStatusComponent,
     Phrase: CitationPhrase,

package/lib/react/types.d.ts

@@ -4,9 +4,9 @@ import type { SearchState } from "../types/search.js";
 /**
  * Available citation display variants.
  *
- * - `brackets`: Shows value/number in brackets with blue text styling (default)
+ * - `brackets`: Shows keySpan/number in brackets with blue text styling (default)
  * - `numeric`: Shows citation number with indicator, no brackets
- * - `text`: Shows the value, no text styling, no truncate, shows indicator
+ * - `text`: Shows the keySpan, no text styling, no truncate, shows indicator
  * - `minimal`: No brackets, just display text with indicator
  * - `indicator`: Only the status indicator (checkmark/warning), no text
  */
@@ -89,9 +89,9 @@ export interface BaseCitationProps {
     className?: string;
     /** Class name for controlling inner content width */
     innerWidthClassName?: string;
-    /** When true, displays value/citationNumber merged in the bracket */
+    /** When true, displays keySpan/citationNumber merged in the bracket */
     displayKeySpan?: boolean;
-    /** Fallback display text when citation value is empty */
+    /** Fallback display text when citation keySpan is empty */
     fallbackDisplay?: string | null;
     /** Display variant for the citation */
     variant?: CitationVariant;
@@ -164,7 +164,7 @@ export interface CitationRenderProps {
     citationKey: string;
     /** Display text for the citation */
     displayText: string;
-    /** Whether this is a merged value display */
+    /** Whether this is a merged keySpan display */
     isMergedDisplay: boolean;
 }
 /**

package/lib/react/utils.js

@@ -1,5 +1,5 @@
 import { sha1Hash } from "../utils/sha.js";
-import { getCitationPageNumber } from "@/parsing/normalizeCitation.js";
+import { getCitationPageNumber } from "../parsing/normalizeCitation.js";
 /**
  * Generates a unique, deterministic key for a citation based on its content.
  * Uses a hash of the citation's identifying properties.

package/package.json

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