@deepcitation/deepcitation-js 1.0.2 → 1.0.3

package/lib/react/useSmartDiff.js

@@ -0,0 +1,64 @@
+import * as Diff from "diff";
+import { useMemo } from "react";
+export const useSmartDiff = (expected = "", actual = "") => {
+    return useMemo(() => {
+        // 1. Sanitize standard noise (CRLF, trailing spaces)
+        const cleanExpected = (expected || "").trim().replace(/\r\n/g, "\n");
+        const cleanActual = (actual || "").trim().replace(/\r\n/g, "\n");
+        // 2. First Pass: Diff by LINES.
+        // This isolates the "extra line" issue. The extra line becomes one "added" chunk,
+        // and it prevents the tokenizer from getting confused on the rest of the text.
+        const lineDiffs = Diff.diffLines(cleanExpected, cleanActual);
+        // 3. Second Pass: Process the line results to find "Modifications"
+        const processedDiffs = [];
+        let hasDiff = false;
+        let totalChange = 0;
+        for (let i = 0; i < lineDiffs.length; i++) {
+            const part = lineDiffs[i];
+            const nextPart = lineDiffs[i + 1];
+            // CHECK FOR MODIFICATION:
+            // If we see a "Removed" block immediately followed by an "Added" block,
+            // it means this specific line changed. We should DIFF WORDS inside this line.
+            if (part.removed && nextPart && nextPart.added) {
+                // Run word diff ONLY on this pair of lines
+                const wordDiffs = Diff.diffWordsWithSpace(part.value, nextPart.value);
+                processedDiffs.push({
+                    type: "modified",
+                    parts: wordDiffs,
+                });
+                hasDiff = true;
+                // Calculate raw change amount for variance score
+                totalChange += Math.abs(part.value.length - nextPart.value.length);
+                i++; // Skip the next part since we merged it into this block
+            }
+            // CHECK FOR PURE ADDITION/DELETION (The "Extra Line" Scenario)
+            else if (part.added || part.removed) {
+                processedDiffs.push({
+                    type: part.added ? "added" : "removed",
+                    parts: [{ value: part.value, added: part.added, removed: part.removed }],
+                });
+                hasDiff = true;
+                totalChange += part.value.length;
+            }
+            // UNCHANGED BLOCKS
+            else {
+                processedDiffs.push({
+                    type: "unchanged",
+                    parts: [{ value: part.value }],
+                });
+            }
+        }
+        // 4. Calculate a similarity score to decide UI defaults
+        // 1.0 = Perfect match, 0.0 = Totally different
+        const maxLength = Math.max(cleanExpected.length, cleanActual.length);
+        const similarity = maxLength === 0 ? 1 : 1 - totalChange / maxLength;
+        return {
+            diffResult: processedDiffs,
+            hasDiff,
+            similarity,
+            // If similarity is too low (< 60%), the Diff view is likely "Fruit Salad" (messy).
+            // We can use this boolean to default the UI to the "Source" tab.
+            isHighVariance: similarity < 0.6,
+        };
+    }, [expected, actual]);
+};

package/lib/react/utils.d.ts

@@ -0,0 +1,34 @@
+import type { Citation } from "../types/citation.js";
+/**
+ * Generates a unique, deterministic key for a citation based on its content.
+ * Uses a hash of the citation's identifying properties.
+ */
+export declare function generateCitationKey(citation: Citation): string;
+/**
+ * Generates a unique instance ID for a citation component render.
+ * Combines the citation key with a random suffix for uniqueness.
+ */
+export declare function generateCitationInstanceId(citationKey: string): string;
+/**
+ * Gets the display text for a citation based on configuration.
+ */
+export declare function getCitationDisplayText(citation: Citation, options?: {
+    displayCitationValue?: boolean;
+    fallbackDisplay?: string | null;
+}): string;
+/**
+ * Gets the value text to display before the citation bracket.
+ */
+export declare function getCitationValueText(citation: Citation, options?: {
+    displayCitationValue?: boolean;
+}): string;
+/**
+ * Joins class names, filtering out falsy values.
+ * This is a minimal implementation for the base component.
+ */
+export declare function classNames(...classes: (string | undefined | null | false)[]): string;
+/**
+ * Default padding values for citation styling.
+ */
+export declare const CITATION_X_PADDING = 4;
+export declare const CITATION_Y_PADDING = 1;

package/lib/react/utils.js

@@ -0,0 +1,59 @@
+import { sha1Hash } from "../utils/sha.js";
+/**
+ * Generates a unique, deterministic key for a citation based on its content.
+ * Uses a hash of the citation's identifying properties.
+ */
+export function generateCitationKey(citation) {
+    const keyParts = [
+        citation.fileId || "",
+        citation.pageNumber?.toString() || "",
+        citation.fullPhrase || "",
+        citation.value || "",
+        citation.citationNumber?.toString() || "",
+        citation.lineIds?.join(",") || "",
+        citation.timestamps?.startTime || "",
+        citation.timestamps?.endTime || "",
+        citation.fragmentContext || "",
+    ];
+    return sha1Hash(keyParts.join("|")).slice(0, 16);
+}
+/**
+ * Generates a unique instance ID for a citation component render.
+ * Combines the citation key with a random suffix for uniqueness.
+ */
+export function generateCitationInstanceId(citationKey) {
+    const randomSuffix = Math.random().toString(36).substr(2, 9);
+    return `${citationKey}-${randomSuffix}`;
+}
+/**
+ * Gets the display text for a citation based on configuration.
+ */
+export function getCitationDisplayText(citation, options = {}) {
+    const { displayCitationValue = false, fallbackDisplay } = options;
+    if (displayCitationValue) {
+        return citation.value || citation.citationNumber?.toString() || fallbackDisplay || "";
+    }
+    return citation.citationNumber?.toString() || "";
+}
+/**
+ * Gets the value text to display before the citation bracket.
+ */
+export function getCitationValueText(citation, options = {}) {
+    const { displayCitationValue = false } = options;
+    if (displayCitationValue) {
+        return "";
+    }
+    return citation.value || "";
+}
+/**
+ * Joins class names, filtering out falsy values.
+ * This is a minimal implementation for the base component.
+ */
+export function classNames(...classes) {
+    return classes.filter(Boolean).join(" ");
+}
+/**
+ * Default padding values for citation styling.
+ */
+export const CITATION_X_PADDING = 4;
+export const CITATION_Y_PADDING = 1;

package/lib/types/boxes.d.ts

@@ -0,0 +1,11 @@
+export interface PdfSpaceItem extends ScreenBox {
+    text?: string;
+}
+export type IVertex = {
+    x: number;
+    y: number;
+};
+export interface ScreenBox extends IVertex {
+    width: number;
+    height: number;
+}

package/lib/types/boxes.js

@@ -0,0 +1 @@
+export {};

package/lib/types/citation.d.ts

@@ -0,0 +1,44 @@
+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 {
+    foundHighlights: {
+        [key: string]: FoundHighlightLocation;
+    };
+}
+export interface VerifyCitationRequest {
+    fileId: string;
+    citations: {
+        [key: string]: Citation;
+    };
+    outputImageFormat?: OutputImageFormat;
+    apiKey?: string;
+}
+export interface Citation {
+    fileId?: string;
+    fullPhrase?: string | null;
+    value?: string | null;
+    startPageKey?: string | null;
+    pageNumber?: number | null;
+    lineIds?: number[] | null;
+    reasoning?: string | null;
+    selection?: ScreenBox | null;
+    citationNumber?: number;
+    timestamps?: {
+        endTime?: string;
+        startTime?: string;
+    };
+    fragmentContext?: string | null;
+    rawCitationMd?: string;
+    beforeCite?: string;
+    formFieldName?: string | null;
+    formFieldValue?: string | null;
+}
+export interface CitationStatus {
+    isVerified: boolean;
+    isMiss: boolean;
+    isPartialMatch: boolean;
+    isPending: boolean;
+}

package/lib/types/citation.js

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

package/lib/types/foundHighlight.d.ts

@@ -0,0 +1,23 @@
+import { VERIFICATION_VERSION_NUMBER, type Citation } from "./citation";
+import { type SearchState } from "./search";
+import { type PdfSpaceItem } from "./boxes";
+export declare const NOT_FOUND_HIGHLIGHT_INDEX = -1;
+export declare const PENDING_HIGHLIGHT_INDEX = -2;
+export declare const BLANK_HIGHLIGHT_LOCATION: FoundHighlightLocation;
+export declare function deterministicIdFromHighlightLocation(highlightLocation: FoundHighlightLocation): string;
+export interface FoundHighlightLocation {
+    regex?: RegExp | null;
+    lowerCaseSearchTerm: string | null;
+    label?: string | null;
+    attachmentId?: string | null;
+    pageNumber?: number | null;
+    timestamp?: number | null;
+    citation?: Citation;
+    searchState?: SearchState | null;
+    hitIndexWithinPage?: number | null;
+    matchSnippet?: string | null;
+    pdfSpaceItem?: PdfSpaceItem;
+    verificationImageBase64?: string | null;
+    source?: typeof VERIFICATION_VERSION_NUMBER | string | null;
+    verifiedAt?: Date;
+}

package/lib/types/foundHighlight.js

@@ -0,0 +1,22 @@
+import { sha1Hash } from "../utils/sha.js";
+export const NOT_FOUND_HIGHLIGHT_INDEX = -1;
+export const PENDING_HIGHLIGHT_INDEX = -2;
+export const BLANK_HIGHLIGHT_LOCATION = {
+    pageNumber: NOT_FOUND_HIGHLIGHT_INDEX,
+    regex: null,
+    lowerCaseSearchTerm: null,
+    attachmentId: null,
+    matchSnippet: null,
+    source: null,
+    citation: {
+        startPageKey: null,
+        lineIds: null,
+        pageNumber: NOT_FOUND_HIGHLIGHT_INDEX,
+        fileId: undefined,
+        fullPhrase: null,
+        value: null,
+    },
+};
+export function deterministicIdFromHighlightLocation(highlightLocation) {
+    return sha1Hash(`${highlightLocation.lowerCaseSearchTerm}-${highlightLocation.attachmentId}-${highlightLocation.pageNumber}-${highlightLocation.hitIndexWithinPage}-${highlightLocation.matchSnippet}-${highlightLocation?.hitIndexWithinPage}`);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Type definitions for DeepCitation
+ *
+ * @packageDocumentation
+ */
+export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./citation.js";
+export { VERIFICATION_VERSION_NUMBER, 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";
+export type { ScreenBox, PdfSpaceItem, IVertex } from "./boxes.js";

package/lib/types/index.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for DeepCitation
+ *
+ * @packageDocumentation
+ */
+export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
+export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./foundHighlight.js";

package/lib/types/search.d.ts

@@ -0,0 +1,30 @@
+export type SearchStatus = "loading" | "pending" | "not_found" | "partial_text_found" | "found" | "found_value_only" | "found_phrase_missed_value" | "found_on_other_page" | "found_on_other_line" | "first_word_found" | "timestamp_wip";
+export type SearchMethod = "exact_line_match" | "line_with_buffer" | "current_page" | "adjacent_pages" | "expanded_window" | "regex_search" | "bm25_search" | "fuzzy_regex" | "first_word_fallback";
+export interface SearchAttempt {
+    method: SearchMethod;
+    success: boolean;
+    searchPhrases: string[];
+    pageSearched?: number;
+    matchScore?: number;
+    matchSnippet?: string;
+    notes?: string;
+    durationMs?: number;
+    startTime?: number;
+    endTime?: number;
+}
+export interface SearchState {
+    status: SearchStatus;
+    expectedPage?: number | null;
+    actualPage?: number | null;
+    expectedLineIds?: number[] | null;
+    actualLineIds?: number[] | null;
+    actualTimestamps?: {
+        startTime?: string;
+        endTime?: string;
+    };
+    expectedTimestamps?: {
+        startTime?: string;
+        endTime?: string;
+    };
+    searchAttempts?: SearchAttempt[];
+}

package/lib/types/search.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/sha.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pure JavaScript SHA-1 implementation.
+ * Based on the FIPS 180-4 specification.
+ * No external dependencies.
+ */
+/**
+ * Computes a SHA-1 hash of the provided data.
+ * Used internally by generateCitationKey in react/utils.ts
+ */
+export declare function sha1Hash(data: string | any): string;

package/lib/utils/sha.js

@@ -0,0 +1,108 @@
+/**
+ * Pure JavaScript SHA-1 implementation.
+ * Based on the FIPS 180-4 specification.
+ * No external dependencies.
+ */
+function utf8Encode(str) {
+    const encoder = new TextEncoder();
+    return encoder.encode(str);
+}
+function sha1(message) {
+    // Initial hash values
+    let h0 = 0x67452301;
+    let h1 = 0xefcdab89;
+    let h2 = 0x98badcfe;
+    let h3 = 0x10325476;
+    let h4 = 0xc3d2e1f0;
+    // Pre-processing: adding padding bits
+    const msgLen = message.length;
+    const bitLen = msgLen * 8;
+    // Calculate padded length: message + 1 (0x80) + padding + 8 (length)
+    // Total must be multiple of 64 bytes (512 bits)
+    const totalLen = msgLen + 1 + 8; // minimum: msg + 0x80 + 64-bit length
+    const paddedLen = Math.ceil(totalLen / 64) * 64;
+    // Create padded buffer
+    const padded = new ArrayBuffer(paddedLen);
+    const paddedView = new Uint8Array(padded);
+    const dataView = new DataView(padded);
+    // Copy message
+    paddedView.set(message);
+    // Append bit '1' (0x80)
+    paddedView[msgLen] = 0x80;
+    // Append length as 64-bit big-endian (in bits)
+    // High 32 bits (for messages > 512MB, which we don't support)
+    dataView.setUint32(paddedLen - 8, Math.floor(bitLen / 0x100000000), false);
+    // Low 32 bits
+    dataView.setUint32(paddedLen - 4, bitLen >>> 0, false);
+    // Process each 512-bit (64-byte) chunk
+    const w = new Uint32Array(80);
+    for (let offset = 0; offset < paddedLen; offset += 64) {
+        // Break chunk into sixteen 32-bit big-endian words
+        for (let i = 0; i < 16; i++) {
+            w[i] = dataView.getUint32(offset + i * 4, false);
+        }
+        // Extend the sixteen 32-bit words into eighty 32-bit words
+        for (let i = 16; i < 80; i++) {
+            const val = w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16];
+            w[i] = (val << 1) | (val >>> 31);
+        }
+        // Initialize working variables
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        // Main loop
+        for (let i = 0; i < 80; i++) {
+            let f;
+            let k;
+            if (i < 20) {
+                f = (b & c) | (~b & d);
+                k = 0x5a827999;
+            }
+            else if (i < 40) {
+                f = b ^ c ^ d;
+                k = 0x6ed9eba1;
+            }
+            else if (i < 60) {
+                f = (b & c) | (b & d) | (c & d);
+                k = 0x8f1bbcdc;
+            }
+            else {
+                f = b ^ c ^ d;
+                k = 0xca62c1d6;
+            }
+            const temp = (((a << 5) | (a >>> 27)) + f + e + k + w[i]) >>> 0;
+            e = d;
+            d = c;
+            c = ((b << 30) | (b >>> 2)) >>> 0;
+            b = a;
+            a = temp;
+        }
+        // Add this chunk's hash to result
+        h0 = (h0 + a) >>> 0;
+        h1 = (h1 + b) >>> 0;
+        h2 = (h2 + c) >>> 0;
+        h3 = (h3 + d) >>> 0;
+        h4 = (h4 + e) >>> 0;
+    }
+    // Produce the final hash value (160-bit) as hex string
+    const hex = (n) => n.toString(16).padStart(8, "0");
+    return hex(h0) + hex(h1) + hex(h2) + hex(h3) + hex(h4);
+}
+/**
+ * Computes a SHA-1 hash of the provided data.
+ * Used internally by generateCitationKey in react/utils.ts
+ */
+export function sha1Hash(data) {
+    try {
+        if (!data)
+            return "";
+        const str = typeof data === "string" ? data : JSON.stringify(data);
+        return sha1(utf8Encode(str));
+    }
+    catch (error) {
+        console.error("Error in making the hash:", error);
+    }
+    return "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@deepcitation/deepcitation-js",
-    "version": "1.0.2",
+    "version": "1.0.3",
     "description": "DeepCitation JavaScript SDK for deterministic AI citation verification",
     "type": "module",
     "private": false,
@@ -13,10 +13,13 @@
     },
     "main": "./lib/index.js",
     "types": "./lib/index.d.ts",
+    "sideEffects": [
+        "*.css",
+        "src/react/styles.css"
+    ],
     "files": [
         "lib",
         "src/react/styles.css",
-        "README.md",
         "LICENSE"
     ],
     "scripts": {