@deepcitation/deepcitation-js 1.0.3 → 1.0.5

package/README.md

@@ -60,7 +60,7 @@ import { DeepCitation, wrapCitationPrompt } from "@deepcitation/deepcitation-js"
 const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
 
 // Upload source files
-const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
+const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
   { file: pdfBuffer, filename: "report.pdf" },
 ]);
 
@@ -68,7 +68,7 @@ const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
 const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
   systemPrompt: "You are a helpful assistant...",
   userPrompt: "Analyze this document",
-  fileDeepText: fileDeepTexts,
+  deepTextPromptPortion,
 });
 
 // Call your LLM

package/lib/client/DeepCitation.d.ts

@@ -91,7 +91,7 @@ export declare class DeepCitation {
      * });
      *
      * // Then prepare the file for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: result.fileId
      * });
      * ```
@@ -99,7 +99,7 @@ export declare class DeepCitation {
     convertToPdf(input: ConvertFileInput | string): Promise<ConvertFileResponse>;
     /**
      * Prepare a previously converted file for citation verification.
-     * Use this after calling convertToPdf() to extract text and get fileDeepText.
+     * Use this after calling convertToPdf() to extract text and get deepTextPromptPortion.
      *
      * @param options - Options with fileId from convertFile
      * @returns Upload response with fileId and extracted text
@@ -110,11 +110,11 @@ export declare class DeepCitation {
      * const converted = await dc.convertToPdf({ url: "https://example.com/article" });
      *
      * // Then prepare it for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: converted.fileId
      * });
      *
-     * // Use fileDeepText in your LLM prompt...
+     * // Use deepTextPromptPortion in your LLM prompt...
      * ```
      */
     prepareConvertedFile(options: PrepareConvertedFileOptions): Promise<UploadFileResponse>;
@@ -123,20 +123,20 @@ export declare class DeepCitation {
      * This is the recommended way to prepare files for LLM prompts.
      *
      * @param files - Array of files to upload with optional filenames and fileIds
-     * @returns Object containing fileDataParts for verification and fileDeepTexts for LLM
+     * @returns Object containing fileDataParts for verification and deepTextPromptPortion for LLM
      *
      * @example
      * ```typescript
-     * const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
+     * const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
      *   { file: pdfBuffer, filename: "report.pdf" },
      *   { file: invoiceBuffer, filename: "invoice.pdf" },
      * ]);
      *
-     * // Use fileDeepTexts in wrapCitationPrompt
+     * // Use deepTextPromptPortion in wrapCitationPrompt
      * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
      *   systemPrompt,
      *   userPrompt,
-     *   fileDeepText: fileDeepTexts
+     *   deepTextPromptPortion
      * });
      *
      * // Use fileDataParts later for verification

package/lib/client/DeepCitation.js

@@ -144,7 +144,7 @@ export class DeepCitation {
      * });
      *
      * // Then prepare the file for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: result.fileId
      * });
      * ```
@@ -208,7 +208,8 @@ export class DeepCitation {
         }
         if (!response.ok) {
             const error = await response.json().catch(() => ({}));
-            throw new Error(error?.error?.message || `Conversion failed with status ${response.status}`);
+            throw new Error(error?.error?.message ||
+                `Conversion failed with status ${response.status}`);
         }
         // Internal response includes attachmentId which we need for the two-step flow
         const apiResponse = (await response.json());
@@ -222,7 +223,7 @@ export class DeepCitation {
     }
     /**
      * Prepare a previously converted file for citation verification.
-     * Use this after calling convertToPdf() to extract text and get fileDeepText.
+     * Use this after calling convertToPdf() to extract text and get deepTextPromptPortion.
      *
      * @param options - Options with fileId from convertFile
      * @returns Upload response with fileId and extracted text
@@ -233,11 +234,11 @@ export class DeepCitation {
      * const converted = await dc.convertToPdf({ url: "https://example.com/article" });
      *
      * // Then prepare it for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: converted.fileId
      * });
      *
-     * // Use fileDeepText in your LLM prompt...
+     * // Use deepTextPromptPortion in your LLM prompt...
      * ```
      */
     async prepareConvertedFile(options) {
@@ -276,20 +277,20 @@ export class DeepCitation {
      * This is the recommended way to prepare files for LLM prompts.
      *
      * @param files - Array of files to upload with optional filenames and fileIds
-     * @returns Object containing fileDataParts for verification and fileDeepTexts for LLM
+     * @returns Object containing fileDataParts for verification and deepTextPromptPortion for LLM
      *
      * @example
      * ```typescript
-     * const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
+     * const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
      *   { file: pdfBuffer, filename: "report.pdf" },
      *   { file: invoiceBuffer, filename: "invoice.pdf" },
      * ]);
      *
-     * // Use fileDeepTexts in wrapCitationPrompt
+     * // Use deepTextPromptPortion in wrapCitationPrompt
      * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
      *   systemPrompt,
      *   userPrompt,
-     *   fileDeepText: fileDeepTexts
+     *   deepTextPromptPortion
      * });
      *
      * // Use fileDataParts later for verification
@@ -298,17 +299,17 @@ export class DeepCitation {
      */
     async prepareFiles(files) {
         if (files.length === 0) {
-            return { fileDataParts: [], fileDeepTexts: [] };
+            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 fileDataParts = results.map((result) => ({
             fileId: result.fileId,
         }));
-        const fileDeepTexts = results.map(result => result.fileDeepText);
-        return { fileDataParts, fileDeepTexts };
+        const deepTextPromptPortion = results.map((result) => result.deepTextPromptPortion);
+        return { fileDataParts, deepTextPromptPortion };
     }
     /**
      * Verify citations against a previously uploaded file.
@@ -377,7 +378,8 @@ export class DeepCitation {
         });
         if (!response.ok) {
             const error = await response.json().catch(() => ({}));
-            throw new Error(error?.error?.message || `Verification failed with status ${response.status}`);
+            throw new Error(error?.error?.message ||
+                `Verification failed with status ${response.status}`);
         }
         return (await response.json());
     }
@@ -446,7 +448,8 @@ export class DeepCitation {
             });
             if (!response.ok) {
                 const error = await response.json().catch(() => ({}));
-                throw new Error(error?.error?.message || `Verification failed with status ${response.status}`);
+                throw new Error(error?.error?.message ||
+                    `Verification failed with status ${response.status}`);
             }
             const result = (await response.json());
             Object.assign(allHighlights, result.foundHighlights);

package/lib/client/types.d.ts

@@ -15,7 +15,7 @@ export interface UploadFileResponse {
     /** The file ID assigned by DeepCitation (custom or auto-generated) */
     fileId: string;
     /** The full text content formatted for LLM prompts with page markers and line IDs. Use this in your user prompts. */
-    fileDeepText: string;
+    deepTextPromptPortion: string;
     /** Form fields extracted from PDF forms */
     formFields?: Array<{
         name: string;
@@ -89,7 +89,7 @@ export interface PrepareFilesResult {
     /** Array of file references for verification */
     fileDataParts: FileDataPart[];
     /** Array of formatted text content for LLM prompts (with page markers and line IDs) */
-    fileDeepTexts: string[];
+    deepTextPromptPortion: string[];
 }
 /**
  * Input for verifyCitationsFromLlmOutput

package/lib/index.d.ts

@@ -5,13 +5,13 @@
 export { DeepCitation } from "./client/index.js";
 export type { DeepCitationConfig, UploadFileResponse, UploadFileOptions, VerifyCitationsResponse, VerifyCitationsOptions, CitationInput, FileInput, FileDataPart, PrepareFilesResult, VerifyCitationsFromLlmOutputInput, } from "./client/index.js";
 export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByFileId, groupCitationsByFileIdObject, } from "./parsing/parseCitation.js";
-export { normalizeCitations, getCitationPageNumber } from "./parsing/normalizeCitation.js";
-export { isGeminiGarbage, cleanRepeatingLastSentence } from "./parsing/parseWorkAround.js";
+export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeCitation.js";
+export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
 export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./types/citation.js";
-export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } 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 { SearchState, SearchStatus, SearchMethod, SearchAttempt } from "./types/search.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";
 export { generateCitationKey } from "./react/utils.js";
@@ -19,7 +19,6 @@ export { generateCitationInstanceId } from "./react/utils.js";
 export { CITATION_X_PADDING, CITATION_Y_PADDING } from "./react/utils.js";
 export { CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, wrapSystemCitationPrompt, wrapCitationPrompt, } from "./prompts/citationPrompts.js";
 export type { WrapSystemPromptOptions, WrapCitationPromptOptions, WrapCitationPromptResult, } from "./prompts/citationPrompts.js";
-export { removeLineIdMetadata, removePageNumberMetadata, removeCitations } from "./parsing/normalizeCitation.js";
-export { compressPromptIds, decompressPromptIds } from "./prompts/promptCompression.js";
+export { removeLineIdMetadata, removePageNumberMetadata, removeCitations, } from "./parsing/normalizeCitation.js";
+export { compressPromptIds, decompressPromptIds, } from "./prompts/promptCompression.js";
 export type { CompressedResult } from "./prompts/types.js";
-export { CitationComponent } from "./react/CitationComponent.js";

package/lib/index.js

@@ -6,9 +6,9 @@
 export { DeepCitation } from "./client/index.js";
 // Parsing
 export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByFileId, groupCitationsByFileIdObject, } from "./parsing/parseCitation.js";
-export { normalizeCitations, getCitationPageNumber } from "./parsing/normalizeCitation.js";
-export { isGeminiGarbage, cleanRepeatingLastSentence } from "./parsing/parseWorkAround.js";
-export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
+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";
 // Utilities
 export { sha1Hash } from "./utils/sha.js";
@@ -17,6 +17,5 @@ export { generateCitationInstanceId } from "./react/utils.js";
 export { CITATION_X_PADDING, CITATION_Y_PADDING } from "./react/utils.js";
 // Prompts
 export { CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, wrapSystemCitationPrompt, wrapCitationPrompt, } from "./prompts/citationPrompts.js";
-export { removeLineIdMetadata, removePageNumberMetadata, removeCitations } from "./parsing/normalizeCitation.js";
-export { compressPromptIds, decompressPromptIds } from "./prompts/promptCompression.js";
-export { CitationComponent } from "./react/CitationComponent.js";
+export { removeLineIdMetadata, removePageNumberMetadata, removeCitations, } from "./parsing/normalizeCitation.js";
+export { compressPromptIds, decompressPromptIds, } from "./prompts/promptCompression.js";

package/lib/parsing/normalizeCitation.js

@@ -35,7 +35,7 @@ export const normalizeCitations = (response) => {
         return normalizeCitationContent(trimmedResponse);
     }
     trimmedResponse = citationParts
-        .map(part => (part.startsWith("<cite") ? normalizeCitationContent(part) : part))
+        .map((part) => part.startsWith("<cite") ? normalizeCitationContent(part) : part)
         .join("");
     return trimmedResponse;
 };
@@ -49,10 +49,14 @@ const normalizeCitationContent = (input) => {
             return "full_phrase";
         if (key === "lineIds" || key === "line_ids")
             return "line_ids";
-        if (key === "startPageKey" || key === "start_pageKey" || key === "start_page_key")
+        if (key === "startPageKey" ||
+            key === "start_pageKey" ||
+            key === "start_page_key")
             return "start_page_key";
         if (key === "fileID" || key === "fileId" || key === "file_id")
             return "file_id";
+        if (key === "keySpan" || key === "key_span")
+            return "key_span";
         return key;
     };
     // Helper to decode HTML entities (simple implementation, expand if needed)
@@ -67,7 +71,7 @@ const normalizeCitationContent = (input) => {
     // 2. ROBUST TEXT ATTRIBUTE PARSING (reasoning, value, full_phrase)
     // This regex matches: Key = Quote -> Content (lazy) -> Lookahead for (Next Attribute OR End of Tag)
     // It effectively ignores quotes inside the content during the initial capture.
-    const textAttributeRegex = /(fullPhrase|full_phrase|reasoning|value)\s*=\s*(['"])([\s\S]*?)(?=\s+(?:line_ids|lineIds|timestamps|fileId|file_id|start_page_key|start_pageKey|startPageKey|reasoning|value|full_phrase)|\s*\/?>)/gm;
+    const textAttributeRegex = /(fullPhrase|full_phrase|keySpan|key_span|reasoning|value)\s*=\s*(['"])([\s\S]*?)(?=\s+(?:line_ids|lineIds|timestamps|fileId|file_id|start_page_key|start_pageKey|startPageKey|keySpan|key_span|reasoning|value|full_phrase)|\s*\/?>)/gm;
     normalized = normalized.replace(textAttributeRegex, (_match, key, openQuote, rawContent) => {
         let content = rawContent;
         // The lazy match usually captures the closing quote because the lookahead
@@ -139,7 +143,7 @@ const normalizeCitationContent = (input) => {
         if (keys.length === 0)
             return tag;
         const hasTimestamps = typeof attrs.timestamps === "string" && attrs.timestamps.length > 0;
-        const startPageKeys = keys.filter(k => k.startsWith("start_page"));
+        const startPageKeys = keys.filter((k) => k.startsWith("start_page"));
         const ordered = [];
         // Shared first
         if (attrs.file_id)
@@ -151,15 +155,17 @@ const normalizeCitationContent = (input) => {
             ordered.push("timestamps");
         }
         else {
-            // Document citations: fileId, start_page*, full_phrase, line_ids, (optional reasoning/value), then any extras
+            // Document citations: fileId, start_page*, full_phrase, key_span, line_ids, (optional reasoning/value), then any extras
             if (startPageKeys.includes("start_page_key"))
                 ordered.push("start_page_key");
             startPageKeys
-                .filter(k => k !== "start_page_key")
+                .filter((k) => k !== "start_page_key")
                 .sort()
-                .forEach(k => ordered.push(k));
+                .forEach((k) => ordered.push(k));
             if (attrs.full_phrase)
                 ordered.push("full_phrase");
+            if (attrs.key_span)
+                ordered.push("key_span");
             if (attrs.line_ids)
                 ordered.push("line_ids");
         }
@@ -171,12 +177,12 @@ const normalizeCitationContent = (input) => {
         // Any remaining attributes, stable + deterministic (alpha)
         const used = new Set(ordered);
         keys
-            .filter(k => !used.has(k))
+            .filter((k) => !used.has(k))
             .sort()
-            .forEach(k => ordered.push(k));
-        const rebuiltAttrs = ordered.map(k => `${k}='${attrs[k]}'`).join(" ");
+            .forEach((k) => ordered.push(k));
+        const rebuiltAttrs = ordered.map((k) => `${k}='${attrs[k]}'`).join(" ");
         return `<cite ${rebuiltAttrs} />`;
     };
-    normalized = normalized.replace(/<cite\b[\s\S]*?\/>/gm, tag => reorderCiteTagAttributes(tag));
+    normalized = normalized.replace(/<cite\b[\s\S]*?\/>/gm, (tag) => reorderCiteTagAttributes(tag));
     return normalized;
 };

package/lib/parsing/parseCitation.js

@@ -16,8 +16,13 @@ export function getCitationStatus(foundHighlight) {
         searchState?.status === "found_on_other_page" ||
         searchState?.status === "found_on_other_line" ||
         searchState?.status === "first_word_found";
-    const isVerified = searchState?.status === "found" || isFoundValueMissedFullMatch || isPartialMatch || isFullMatchWithMissedValue;
-    const isPending = searchState?.status === "pending" || searchState?.status === "loading" || !searchState;
+    const isVerified = searchState?.status === "found" ||
+        isFoundValueMissedFullMatch ||
+        isPartialMatch ||
+        isFullMatchWithMissedValue;
+    const isPending = searchState?.status === "pending" ||
+        searchState?.status === "loading" ||
+        !searchState;
     return { isVerified, isMiss, isPartialMatch, isPending };
 }
 export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVerbose) => {
@@ -30,19 +35,24 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
         // Replace escaped single quotes with actual single quotes
         return trimmed.replace(/\\'/g, "'");
     };
-    const citationNumber = citationCounterRef?.current ? citationCounterRef.current++ : undefined;
+    const citationNumber = citationCounterRef?.current
+        ? citationCounterRef.current++
+        : undefined;
     const beforeCite = fragment.substring(0, fragment.indexOf("<cite"));
-    const afterCite = fragment.includes("/>") ? fragment.slice(fragment.indexOf("/>") + 2) : "";
+    const afterCite = fragment.includes("/>")
+        ? fragment.slice(fragment.indexOf("/>") + 2)
+        : "";
     const middleCite = fragment.substring(fragment.indexOf("<cite"), fragment.indexOf("/>") + 2);
     // GROUPS:
     // 1: fileId
     // 2: start_page number
     // 3: index number
     // 4: full_phrase content (escaped)
-    // 5: line_ids content
+    // 5: key_span content (escaped)
+    // 6: line_ids content
     // 6: Optional Key (value|reasoning)
     // 7: Optional Value content (escaped)
-    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+line(?:_ids|Ids)='([^']+)'(?:\s+(value|reasoning)='((?:[^'\\]|\\.)*)')?\s*\/>/g;
+    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];
@@ -51,11 +61,12 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     let attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || match?.[1];
     // Use helper to handle escaped quotes inside the phrase
     let fullPhrase = cleanAndUnescape(match?.[4]);
+    let keySpan = cleanAndUnescape(match?.[5]);
     // Handle the optional attribute (value or reasoning)
     let value;
     let reasoning;
-    const optionalKey = match?.[6]; // "value" or "reasoning"
-    const optionalContent = cleanAndUnescape(match?.[7]);
+    const optionalKey = match?.[7]; // "value" or "reasoning"
+    const optionalContent = cleanAndUnescape(match?.[8]);
     if (optionalKey === "value") {
         value = optionalContent;
     }
@@ -65,12 +76,12 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     let lineIds;
     try {
         // match[5] is line_ids
-        const lineIdsString = match?.[5]?.replace(/[A-Za-z_[\](){}:]/g, "");
+        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)
+                .map((id) => (isNaN(parseInt(id)) ? undefined : parseInt(id)))
+                .filter((id) => id !== undefined)
                 .sort((a, b) => a - b)
             : undefined;
     }
@@ -90,7 +101,8 @@ 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 || avMatch?.[1];
         fullPhrase = cleanAndUnescape(avMatch?.[2]);
         const timestampsString = avMatch?.[3]?.replace(/timestamps=['"]|['"]/g, "");
         const [startTime, endTime] = timestampsString?.split("-") || [];
@@ -110,6 +122,7 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
         fileId: attachmentId,
         pageNumber,
         fullPhrase,
+        keySpan,
         citationNumber,
         lineIds,
         rawCitationMd,
@@ -139,6 +152,7 @@ const parseJsonCitation = (jsonCitation, citationNumber) => {
     // Support both camelCase and snake_case property names
     const fullPhrase = jsonCitation.fullPhrase ?? jsonCitation.full_phrase;
     const startPageKey = jsonCitation.startPageKey ?? jsonCitation.start_page_key;
+    const keySpan = jsonCitation.keySpan ?? jsonCitation.key_span;
     const rawLineIds = jsonCitation.lineIds ?? jsonCitation.line_ids;
     const fileId = jsonCitation.fileId ?? jsonCitation.file_id;
     const reasoning = jsonCitation.reasoning;
@@ -155,13 +169,16 @@ const parseJsonCitation = (jsonCitation, citationNumber) => {
         }
     }
     // Sort lineIds if present
-    const lineIds = rawLineIds?.length ? [...rawLineIds].sort((a, b) => a - b) : undefined;
+    const lineIds = rawLineIds?.length
+        ? [...rawLineIds].sort((a, b) => a - b)
+        : undefined;
     const citation = {
         fileId,
         pageNumber,
         fullPhrase,
         citationNumber,
         lineIds,
+        keySpan,
         reasoning,
         value,
     };
@@ -176,6 +193,8 @@ const hasCitationProperties = (item) => typeof item === "object" &&
         "full_phrase" in item ||
         "startPageKey" in item ||
         "start_page_key" in item ||
+        "keySpan" in item ||
+        "key_span" in item ||
         "lineIds" in item ||
         "line_ids" in item);
 /**
@@ -220,7 +239,9 @@ const findJsonCitationsInObject = (obj, found) => {
         found.push(...items);
     }
     if (obj.citations && isJsonCitationFormat(obj.citations)) {
-        const items = Array.isArray(obj.citations) ? obj.citations : [obj.citations];
+        const items = Array.isArray(obj.citations)
+            ? obj.citations
+            : [obj.citations];
         found.push(...items);
     }
     // Recurse into object properties

package/lib/prompts/citationPrompts.d.ts

@@ -1,5 +1,5 @@
-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)' 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 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 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 */
     systemPrompt: string;
@@ -13,7 +13,7 @@ export interface WrapCitationPromptOptions {
     /** The original user prompt */
     userPrompt: string;
     /** The extracted file text with metadata (from uploadFile response). Can be a single string or array for multiple files. */
-    fileDeepText?: string | string[];
+    deepTextPromptPortion?: string | string[];
     /** Whether to use audio/video citation format (with timestamps) instead of text-based (with line IDs) */
     isAudioVideo?: boolean;
 }
@@ -54,14 +54,14 @@ export declare function wrapSystemCitationPrompt(options: WrapSystemPromptOption
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Analyze this document and summarize it.",
- *   fileDeepText, // from uploadFile response
+ *   deepTextPromptPortion, // from uploadFile response
  * });
  *
  * // Multiple files
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Compare these documents.",
- *   fileDeepText: [fileDeepText1, fileDeepText2], // array of file texts
+ *   deepTextPromptPortion: [deepTextPromptPortion1, deepTextPromptPortion2], // array of file texts
  * });
  *
  * // Use enhanced prompts with your LLM
@@ -92,6 +92,10 @@ export declare const CITATION_JSON_OUTPUT_FORMAT: {
             type: string;
             description: string;
         };
+        keySpan: {
+            type: string;
+            description: string;
+        };
         lineIds: {
             type: string;
             items: {

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)' 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 value or 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.
@@ -13,7 +13,7 @@ Citation syntax to use within Markdown:
 `;
 export const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = `
 • To support any ideas or information that requires a citation from the provided content, use the following citation syntax:
-<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' />
+<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' />
 • These citations are displayed in-line or in the relevant list item, and are not grouped at the end of the document.
 `;
 /**
@@ -35,8 +35,10 @@ export const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = `
  * ```
  */
 export function wrapSystemCitationPrompt(options) {
-    const { systemPrompt, isAudioVideo = false, prependCitationInstructions = false } = options;
-    const citationPrompt = isAudioVideo ? AV_CITATION_MARKDOWN_SYNTAX_PROMPT : CITATION_MARKDOWN_SYNTAX_PROMPT;
+    const { systemPrompt, isAudioVideo = false, prependCitationInstructions = false, } = options;
+    const citationPrompt = isAudioVideo
+        ? AV_CITATION_MARKDOWN_SYNTAX_PROMPT
+        : CITATION_MARKDOWN_SYNTAX_PROMPT;
     if (prependCitationInstructions) {
         return `${citationPrompt.trim()}
 
@@ -59,14 +61,14 @@ ${citationPrompt.trim()}`;
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Analyze this document and summarize it.",
- *   fileDeepText, // from uploadFile response
+ *   deepTextPromptPortion, // from uploadFile response
  * });
  *
  * // Multiple files
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Compare these documents.",
- *   fileDeepText: [fileDeepText1, fileDeepText2], // array of file texts
+ *   deepTextPromptPortion: [deepTextPromptPortion1, deepTextPromptPortion2], // array of file texts
  * });
  *
  * // Use enhanced prompts with your LLM
@@ -79,21 +81,23 @@ ${citationPrompt.trim()}`;
  * ```
  */
 export function wrapCitationPrompt(options) {
-    const { systemPrompt, userPrompt, fileDeepText, isAudioVideo = false } = options;
+    const { systemPrompt, userPrompt, deepTextPromptPortion, isAudioVideo = false, } = options;
     const enhancedSystemPrompt = wrapSystemCitationPrompt({
         systemPrompt,
         isAudioVideo,
     });
     // Build enhanced user prompt with file content if provided
     let enhancedUserPrompt = userPrompt;
-    if (fileDeepText) {
-        const fileTexts = Array.isArray(fileDeepText) ? fileDeepText : [fileDeepText];
+    if (deepTextPromptPortion) {
+        const fileTexts = Array.isArray(deepTextPromptPortion)
+            ? deepTextPromptPortion
+            : [deepTextPromptPortion];
         const fileContent = fileTexts
             .map((text, index) => {
             if (fileTexts.length === 1) {
-                return `<file_text>\n${text}\n</file_text>`;
+                return `\n${text}`;
             }
-            return `<file_text file_index="${index + 1}">\n${text}\n</file_text>`;
+            return `\n${text}`;
         })
             .join("\n\n");
         enhancedUserPrompt = `${fileContent}\n\n${userPrompt}`;
@@ -119,13 +123,24 @@ export const CITATION_JSON_OUTPUT_FORMAT = {
             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)",
         },
+        keySpan: {
+            type: "string",
+            description: "the verbatim value or words within fullPhrase that best support the citation",
+        },
         lineIds: {
             type: "array",
             items: { type: "number" },
             description: "Infer lineIds, as we only provide the first, last, and every 5th line. Provide inclusive lineIds for the fullPhrase.",
         },
     },
-    required: ["fileId", "startPageKey", "reasoning", "fullPhrase", "lineIds"],
+    required: [
+        "fileId",
+        "startPageKey",
+        "reasoning",
+        "fullPhrase",
+        "keySpan",
+        "lineIds",
+    ],
 };
 export const CITATION_AV_BASED_JSON_OUTPUT_FORMAT = {
     type: "object",

package/lib/types/citation.d.ts

@@ -1,6 +1,5 @@
 import { type ScreenBox } from "./boxes";
 import { type FoundHighlightLocation } from "./foundHighlight";
-export declare const VERIFICATION_VERSION_NUMBER = "0.4.37";
 export type OutputImageFormat = "jpeg" | "png" | "avif" | undefined | null;
 export declare const DEFAULT_OUTPUT_IMAGE_FORMAT: "avif";
 export interface VerifyCitationResponse {
@@ -19,6 +18,7 @@ export interface VerifyCitationRequest {
 export interface Citation {
     fileId?: string;
     fullPhrase?: string | null;
+    keySpan?: string | null;
     value?: string | null;
     startPageKey?: string | null;
     pageNumber?: number | null;
@@ -33,8 +33,6 @@ export interface Citation {
     fragmentContext?: string | null;
     rawCitationMd?: string;
     beforeCite?: string;
-    formFieldName?: string | null;
-    formFieldValue?: string | null;
 }
 export interface CitationStatus {
     isVerified: boolean;

package/lib/types/citation.js

@@ -1,2 +1 @@
-export const VERIFICATION_VERSION_NUMBER = "0.4.37";
 export const DEFAULT_OUTPUT_IMAGE_FORMAT = "avif";

package/lib/types/foundHighlight.d.ts

@@ -1,4 +1,4 @@
-import { VERIFICATION_VERSION_NUMBER, type Citation } from "./citation";
+import { type Citation } from "./citation";
 import { type SearchState } from "./search";
 import { type PdfSpaceItem } from "./boxes";
 export declare const NOT_FOUND_HIGHLIGHT_INDEX = -1;
@@ -18,6 +18,6 @@ export interface FoundHighlightLocation {
     matchSnippet?: string | null;
     pdfSpaceItem?: PdfSpaceItem;
     verificationImageBase64?: string | null;
-    source?: typeof VERIFICATION_VERSION_NUMBER | string | null;
+    source?: string | null;
     verifiedAt?: Date;
 }

package/lib/types/index.d.ts

@@ -4,7 +4,7 @@
  * @packageDocumentation
  */
 export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./citation.js";
-export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } 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 { SearchState, SearchStatus } from "./search.js";

package/lib/types/index.js

@@ -3,5 +3,5 @@
  *
  * @packageDocumentation
  */
-export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
+export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
 export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./foundHighlight.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@deepcitation/deepcitation-js",
-    "version": "1.0.3",
+    "version": "1.0.5",
     "description": "DeepCitation JavaScript SDK for deterministic AI citation verification",
     "type": "module",
     "private": false,
@@ -14,16 +14,14 @@
     "main": "./lib/index.js",
     "types": "./lib/index.d.ts",
     "sideEffects": [
-        "*.css",
-        "src/react/styles.css"
+        "*.css"
     ],
     "files": [
         "lib",
-        "src/react/styles.css",
         "LICENSE"
     ],
     "scripts": {
-        "build": "rimraf lib && tsc",
+        "build": "rimraf lib && tsc && cp src/react/styles.css lib/react/styles.css",
         "build:watch": "rimraf lib && tsc --watch",
         "test": "bun test ./src/__tests__/*.test.ts ./src/__tests__/*.test.tsx",
         "test:jest": "jest",
@@ -79,7 +77,7 @@
             "import": "./lib/react/index.js",
             "require": "./lib/react/index.js"
         },
-        "./react/styles.css": "./src/react/styles.css"
+        "./react/styles.css": "./lib/react/styles.css"
     },
     "keywords": [
         "citation",