@vertesia/ui 1.5.0-dev.20260717.131047Z → 1.5.0-dev.20260722.120446Z

package/src/features/magic-pdf/GroundedExtractionView.tsx

@@ -0,0 +1,1055 @@
+import {
+    Badge,
+    Button,
+    cn,
+    ErrorBox,
+    errorMessage,
+    ResizableHandle,
+    ResizablePanel,
+    ResizablePanelGroup,
+    Spinner,
+    useFetch,
+    VTooltip,
+} from '@vertesia/ui/core';
+import { useUITranslation } from '@vertesia/ui/i18n';
+import { useUserSession } from '@vertesia/ui/session';
+import {
+    CheckCircle2,
+    ChevronLeft,
+    ChevronRight,
+    Eye,
+    FileDown,
+    FileJson2,
+    FileText,
+    Grid3X3,
+    Image as ImageIcon,
+    Sparkles,
+    X,
+} from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+import { GroundedExtractionAssistantPanel } from './GroundedExtractionAssistantPanel';
+
+const ADVANCED_PROCESSING_PREFIX = 'magic-pdf';
+
+interface GroundedBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+/**
+ * Citation paths sometimes carry a leading "data." or "$." (the extraction
+ * schema nests the object under "data", and some models echo it). The server
+ * strips it for value resolution; the UI must match on the same normalized form
+ * so per-field scores, checkmarks and click-to-locate work for both variants.
+ */
+function normalizeCitationPath(path: string): string {
+    return path.replace(/^\$\.?/, '').replace(/^data\./, '');
+}
+
+interface GroundedCitation {
+    path: string;
+    page: number;
+    block_ids: number[];
+    cells?: { start: string; end: string };
+    verified: boolean;
+    source_text?: string;
+    value?: string;
+    boxes: GroundedBox[];
+    misaligned?: boolean;
+    snapped?: boolean;
+    reviewed?: boolean;
+    confidence?: number;
+}
+
+interface GroundedExtractionFile {
+    version: number;
+    object_id: string;
+    run_id: string;
+    model?: string;
+    generated_at: string;
+    pages: Record<string, { width: number; height: number; rotation?: number }>;
+    data: Record<string, unknown>;
+    citations: GroundedCitation[];
+    /** Mean provenance confidence in [0,1]; 1.0 = verified against a digital text layer */
+    confidence?: number;
+    /** Content hardness: 0 = clean digital text, 1 = unreadable */
+    hardness?: { score: number; escalated?: boolean };
+    conflicts?: { path: string; kept: unknown; dropped: unknown }[];
+    /** Doc-level trust verdict: whether the content can be used without a human check */
+    verdict?: 'good_to_go' | 'needs_review';
+    /** One-sentence rationale for `verdict` */
+    verdict_reason?: string;
+    /** Post-extraction review result, when a review ran */
+    review?: {
+        assessment: 'complete' | 'issues_found';
+        summary?: string;
+        corrections_applied?: number;
+        verdict?: 'good_to_go' | 'needs_review';
+        verdict_reason?: string;
+    };
+}
+
+interface GroundedExtractionViewProps {
+    objectId: string;
+    onClose?: () => void;
+}
+
+type PageImageMode = 'original' | 'grid';
+
+/** True when a grounded extraction result exists for the object */
+export function useGroundedExtractionAvailable(objectId: string): boolean {
+    const { client } = useUserSession();
+    const [available, setAvailable] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        setAvailable(false);
+        client.files
+            .getDownloadUrl(`${ADVANCED_PROCESSING_PREFIX}/${objectId}/grounded-extraction.json`)
+            .then((r) => fetch(r.url, { method: 'HEAD' }))
+            .then((res) => {
+                if (!cancelled) setAvailable(res.ok);
+            })
+            .catch(() => {
+                // no grounded extraction for this object
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, objectId]);
+    return available;
+}
+
+export interface GroundedSummary {
+    confidence?: number;
+    verified: number;
+    total: number;
+    verdict?: 'good_to_go' | 'needs_review';
+    verdict_reason?: string;
+}
+
+/** Lightweight summary of the object's grounded extraction, or null when none exists */
+export function useGroundedSummary(objectId: string): GroundedSummary | null {
+    const { client } = useUserSession();
+    const [summary, setSummary] = useState<GroundedSummary | null>(null);
+    useEffect(() => {
+        let cancelled = false;
+        setSummary(null);
+        client.files
+            .getDownloadUrl(`${ADVANCED_PROCESSING_PREFIX}/${objectId}/grounded-extraction.json`)
+            .then((r) => fetch(r.url))
+            .then((res) => (res.ok ? res.json() : null))
+            .then((file: GroundedExtractionFile | null) => {
+                if (cancelled || !file?.citations) return;
+                setSummary({
+                    confidence: file.confidence,
+                    verified: file.citations.filter((c) => c.verified).length,
+                    total: file.citations.length,
+                    verdict: file.verdict,
+                    verdict_reason: file.verdict_reason,
+                });
+            })
+            .catch(() => {
+                // no grounded extraction for this object
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, objectId]);
+    return summary;
+}
+
+/**
+ * Embeddable grounded-extraction review panel (fills its container): extracted
+ * properties on one side, source pages with citation boxes on the other.
+ * Clicking a property highlights where in the document it was read.
+ */
+export function GroundedExtractionPanel({ objectId, onClose }: GroundedExtractionViewProps) {
+    const { t } = useUITranslation();
+    const { client } = useUserSession();
+
+    const {
+        data: extraction,
+        error,
+        isLoading,
+        refetch,
+    } = useFetch<GroundedExtractionFile>(async () => {
+        const response = await client.files.getDownloadUrl(
+            `${ADVANCED_PROCESSING_PREFIX}/${objectId}/grounded-extraction.json`,
+        );
+        const result = await fetch(response.url);
+        if (!result.ok) {
+            throw new Error(t('grounded.notFound'));
+        }
+        return result.json();
+    }, [objectId]);
+
+    if (error) {
+        return (
+            <div className="flex h-full items-center justify-center">
+                <div className="flex flex-col items-center gap-4 p-8 max-w-md">
+                    <ErrorBox title={t('grounded.failedToLoad')}>{errorMessage(error)}</ErrorBox>
+                    {onClose && (
+                        <Button variant="outline" onClick={onClose}>
+                            {t('pdf.close')}
+                        </Button>
+                    )}
+                </div>
+            </div>
+        );
+    }
+
+    if (isLoading || !extraction) {
+        return (
+            <div className="flex h-full items-center justify-center">
+                <Spinner size="lg" />
+            </div>
+        );
+    }
+
+    return (
+        <div className="relative h-full">
+            <GroundedExtractionViewImpl
+                extraction={extraction}
+                objectId={objectId}
+                onClose={onClose}
+                onExtractionChanged={refetch}
+            />
+        </div>
+    );
+}
+
+/**
+ * Full-screen route wrapper around GroundedExtractionPanel.
+ */
+export function GroundedExtractionView({ objectId, onClose }: GroundedExtractionViewProps) {
+    return (
+        <div className="fixed inset-0 bg-background z-50">
+            <GroundedExtractionPanel objectId={objectId} onClose={onClose} />
+        </div>
+    );
+}
+
+function GroundedExtractionViewImpl({
+    extraction,
+    objectId,
+    onClose,
+    onExtractionChanged,
+}: {
+    extraction: GroundedExtractionFile;
+    objectId: string;
+    onClose?: () => void;
+    onExtractionChanged?: () => void;
+}) {
+    const { t } = useUITranslation();
+    const { client } = useUserSession();
+    const pageNumbers = useMemo(
+        () =>
+            Object.keys(extraction.pages)
+                .map((p) => parseInt(p, 10))
+                .sort((a, b) => a - b),
+        [extraction.pages],
+    );
+
+    const downloadArtifact = (path: string) => {
+        client.files
+            .getDownloadUrl(`${ADVANCED_PROCESSING_PREFIX}/${objectId}/${path}`)
+            .then((r) => window.open(r.url, '_blank'))
+            .catch(() => {
+                // artifact absent for this document
+            });
+    };
+    const [page, setPage] = useState(pageNumbers[0] ?? 1);
+    const [selectedPath, setSelectedPath] = useState<string | undefined>(undefined);
+    const [showBreakdown, setShowBreakdown] = useState(false);
+    const [showVerdict, setShowVerdict] = useState(false);
+    const [pageImageMode, setPageImageMode] = useState<PageImageMode>('original');
+    const [assistantOpen, setAssistantOpen] = useState(false);
+
+    const breakdown = useMemo(() => {
+        const groups = { digital: 0, ocr: 0, reviewerConfirmed: 0, snapped: 0, imageRead: 0 };
+        const unverified: GroundedCitation[] = [];
+        for (const c of extraction.citations) {
+            if (c.verified) {
+                // Programmatic verification: the value matched the extracted text
+                // (digital text layer verbatim, or the OCR text).
+                if (c.snapped) groups.snapped++;
+                else if ((c.confidence ?? 0) >= 1) groups.digital++;
+                else groups.ocr++;
+            } else if (c.reviewed) {
+                // Model verification: the reviewer read the page image and confirmed
+                // the value. This is a strong signal — and the ONLY one available for
+                // scanned/handwritten content, where there is no text layer to match.
+                groups.reviewerConfirmed++;
+            } else {
+                // Read from the image but neither text-matched nor reviewer-confirmed.
+                groups.imageRead++;
+                unverified.push(c);
+            }
+        }
+        // Two kinds of verification, both trustworthy:
+        //  - digitally verified: matched the document's text (digital layer or OCR)
+        //  - model verified: the reviewer confirmed it against the page image
+        const digitallyVerified = groups.digital + groups.ocr + groups.snapped;
+        const modelVerified = groups.reviewerConfirmed;
+        return {
+            groups,
+            unverified,
+            digitallyVerified,
+            modelVerified,
+            totalVerified: digitallyVerified + modelVerified,
+        };
+    }, [extraction.citations]);
+
+    const citationsByPath = useMemo(() => {
+        const map = new Map<string, GroundedCitation[]>();
+        for (const citation of extraction.citations) {
+            const key = normalizeCitationPath(citation.path);
+            const list = map.get(key) ?? [];
+            list.push(citation);
+            map.set(key, list);
+        }
+        return map;
+    }, [extraction.citations]);
+
+    const totalCitations = extraction.citations.length;
+
+    const selectPath = (path: string) => {
+        setSelectedPath(path);
+        const citation = citationsByPath.get(normalizeCitationPath(path))?.[0];
+        if (citation) {
+            setPage(citation.page);
+        }
+    };
+
+    const pageIndex = pageNumbers.indexOf(page);
+    const selectedCitation = selectedPath
+        ? citationsByPath.get(normalizeCitationPath(selectedPath))?.find((citation) => citation.page === page)
+        : undefined;
+    const selectedCellRange = selectedCitation?.cells
+        ? selectedCitation.cells.start === selectedCitation.cells.end
+            ? selectedCitation.cells.start
+            : `${selectedCitation.cells.start}:${selectedCitation.cells.end}`
+        : undefined;
+
+    return (
+        <ResizablePanelGroup direction="horizontal" className="absolute inset-0">
+            <ResizablePanel defaultSize={55} minSize={25} className="flex flex-col bg-muted">
+                {/* Page navigation */}
+                <div className="relative flex h-9 shrink-0 items-center justify-center bg-sidebar px-2 border-b border-sidebar-border">
+                    {selectedCellRange && (
+                        <Badge
+                            variant="secondary"
+                            className="absolute start-2 max-w-32 truncate font-mono text-[11px]"
+                            title={selectedCellRange}
+                        >
+                            {selectedCellRange}
+                        </Badge>
+                    )}
+                    <div className="flex items-center gap-2">
+                        <Button
+                            variant="ghost"
+                            size="xs"
+                            aria-label={t('grounded.previousPage')}
+                            disabled={pageIndex <= 0}
+                            onClick={() => setPage(pageNumbers[pageIndex - 1])}
+                        >
+                            <ChevronLeft className="size-4" />
+                        </Button>
+                        <span className="text-xs text-muted-foreground">
+                            {t('pdf.pageOf', { pageNumber: page, totalPages: pageNumbers.length })}
+                        </span>
+                        <Button
+                            variant="ghost"
+                            size="xs"
+                            aria-label={t('grounded.nextPage')}
+                            disabled={pageIndex >= pageNumbers.length - 1}
+                            onClick={() => setPage(pageNumbers[pageIndex + 1])}
+                        >
+                            <ChevronRight className="size-4" />
+                        </Button>
+                    </div>
+                    <fieldset className="absolute end-2 flex items-center gap-0.5 rounded border-0 bg-muted p-0.5">
+                        <legend className="sr-only">{t('grounded.checkerboard')}</legend>
+                        <VTooltip description={t('pdf.originalImages')} placement="bottom" size="xs" asChild>
+                            <Button
+                                variant={pageImageMode === 'original' ? 'outline' : 'ghost'}
+                                size="xs"
+                                aria-label={t('pdf.originalImages')}
+                                aria-pressed={pageImageMode === 'original'}
+                                className="h-6 gap-1 px-1.5"
+                                onClick={() => setPageImageMode('original')}
+                            >
+                                <ImageIcon className="size-3.5" />
+                                <span className="hidden sm:inline">{t('pdf.page')}</span>
+                            </Button>
+                        </VTooltip>
+                        <VTooltip description={t('grounded.checkerboard')} placement="bottom" size="xs" asChild>
+                            <Button
+                                variant={pageImageMode === 'grid' ? 'outline' : 'ghost'}
+                                size="xs"
+                                aria-label={t('grounded.checkerboard')}
+                                aria-pressed={pageImageMode === 'grid'}
+                                className="h-6 gap-1 px-1.5"
+                                onClick={() => setPageImageMode('grid')}
+                            >
+                                <Grid3X3 className="size-3.5" />
+                                <span className="hidden sm:inline">{t('grounded.checkerboard')}</span>
+                            </Button>
+                        </VTooltip>
+                    </fieldset>
+                </div>
+                <div className="flex-1 overflow-auto p-2">
+                    <PageWithOverlay
+                        objectId={objectId}
+                        page={page}
+                        dims={extraction.pages[String(page)]}
+                        citations={extraction.citations.filter((c) => c.page === page)}
+                        selectedPath={selectedPath}
+                        onSelectPath={setSelectedPath}
+                        imageMode={pageImageMode}
+                    />
+                </div>
+            </ResizablePanel>
+            <ResizableHandle className="w-[4px] bg-border cursor-ew-resize" />
+            <ResizablePanel defaultSize={45} minSize={20} className="flex flex-col">
+                {/* Header */}
+                <div className="flex h-9 items-center justify-between shrink-0 bg-sidebar px-2 border-b border-sidebar-border">
+                    <span className="text-sm font-medium">{t('grounded.title')}</span>
+                    <div className="flex items-center gap-2">
+                        <VTooltip description={t('grounded.assistantTooltip')} placement="bottom" size="xs" asChild>
+                            <Button
+                                variant={assistantOpen ? 'primary' : 'ghost'}
+                                size="xs"
+                                aria-label={t('grounded.assistant')}
+                                onClick={() => setAssistantOpen((v) => !v)}
+                            >
+                                <Sparkles className="size-4" />
+                            </Button>
+                        </VTooltip>
+                        {extraction.verdict && (
+                            <button
+                                type="button"
+                                className="cursor-pointer"
+                                onClick={() => setShowVerdict((v) => !v)}
+                                aria-expanded={showVerdict}
+                                aria-label={t('grounded.verdictDetails')}
+                            >
+                                <Badge variant={extraction.verdict === 'good_to_go' ? 'success' : 'attention'}>
+                                    {extraction.verdict === 'good_to_go'
+                                        ? t('grounded.verdictGoodToGo')
+                                        : t('grounded.verdictNeedsReview')}
+                                </Badge>
+                            </button>
+                        )}
+                        {typeof extraction.hardness?.score === 'number' && (
+                            <Badge
+                                variant={
+                                    extraction.hardness.score >= 0.5
+                                        ? 'attention'
+                                        : extraction.hardness.score >= 0.2
+                                          ? 'info'
+                                          : 'secondary'
+                                }
+                                title={t('grounded.hardnessHint')}
+                            >
+                                {t('grounded.hardness', {
+                                    percent: Math.round(extraction.hardness.score * 100),
+                                })}
+                                {extraction.hardness.escalated ? ' ↑' : ''}
+                            </Badge>
+                        )}
+                        {extraction.citations.length > 0 &&
+                            (() => {
+                                // Real verification: fraction of values actually confirmed —
+                                // digitally (verbatim/OCR match) OR by the reviewer against the
+                                // image. NOT mean confidence, which scores image-read values high
+                                // even when nothing was verified (e.g. 98% "confidence" on 2/64).
+                                const verifiedPct = Math.round(
+                                    (100 * breakdown.totalVerified) / extraction.citations.length,
+                                );
+                                return (
+                                    <Badge
+                                        variant={
+                                            verifiedPct >= 95
+                                                ? 'success'
+                                                : verifiedPct >= 50
+                                                  ? 'attention'
+                                                  : 'destructive'
+                                        }
+                                        title={t('grounded.confidenceHint')}
+                                    >
+                                        {t('grounded.confidence', { percent: verifiedPct })}
+                                    </Badge>
+                                );
+                            })()}
+                        <button
+                            type="button"
+                            className="flex cursor-pointer items-center gap-1"
+                            onClick={() => setShowBreakdown((v) => !v)}
+                            aria-expanded={showBreakdown}
+                            aria-label={t('grounded.breakdownTitle')}
+                        >
+                            {breakdown.digitallyVerified > 0 && (
+                                <Badge variant="success" title={t('grounded.digitalVerifiedHint')}>
+                                    {t('grounded.digitalVerifiedOf', {
+                                        count: breakdown.digitallyVerified,
+                                        total: totalCitations,
+                                    })}
+                                </Badge>
+                            )}
+                            {breakdown.modelVerified > 0 && (
+                                <Badge variant="success" title={t('grounded.modelVerifiedHint')}>
+                                    {t('grounded.modelVerifiedOf', {
+                                        count: breakdown.modelVerified,
+                                        total: totalCitations,
+                                    })}
+                                </Badge>
+                            )}
+                            {breakdown.groups.imageRead > 0 && (
+                                <Badge variant="attention" title={t('grounded.unverifiedHint')}>
+                                    {t('grounded.unverifiedCount', { count: breakdown.groups.imageRead })}
+                                </Badge>
+                            )}
+                        </button>
+                        <Button
+                            variant="ghost"
+                            size="xs"
+                            aria-label={t('grounded.downloadCitations')}
+                            title={t('grounded.downloadCitations')}
+                            onClick={() => downloadArtifact('grounded-extraction.json')}
+                        >
+                            <FileJson2 className="size-4" />
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="xs"
+                            aria-label={t('grounded.downloadBlocks')}
+                            title={t('grounded.downloadBlocks')}
+                            onClick={() => downloadArtifact(`pages/page-${page}.json`)}
+                        >
+                            <FileText className="size-4" />
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="xs"
+                            aria-label={t('grounded.downloadAnnotated')}
+                            title={t('grounded.downloadAnnotated')}
+                            onClick={() => downloadArtifact('grounded-annotated.pdf')}
+                        >
+                            <FileDown className="size-4" />
+                        </Button>
+                        {!!onClose && (
+                            <Button variant="ghost" size="xs" onClick={onClose} aria-label={t('pdf.close')}>
+                                <X className="size-4" />
+                            </Button>
+                        )}
+                    </div>
+                </div>
+                {showVerdict && extraction.verdict && (
+                    <div className="shrink-0 border-b border-border bg-background px-3 py-2 text-sm">
+                        <div className="flex items-center gap-2">
+                            <span
+                                className={cn(
+                                    'font-medium',
+                                    extraction.verdict === 'good_to_go' ? 'text-success' : 'text-attention',
+                                )}
+                            >
+                                {extraction.verdict === 'good_to_go'
+                                    ? t('grounded.verdictGoodToGo')
+                                    : t('grounded.verdictNeedsReview')}
+                            </span>
+                            <span className="text-xs text-muted-foreground">
+                                {extraction.review
+                                    ? t('grounded.verdictByReviewer')
+                                    : t('grounded.verdictByConfidence')}
+                            </span>
+                        </div>
+                        {(extraction.verdict_reason ?? extraction.review?.verdict_reason) && (
+                            <p className="mt-1 text-xs">
+                                {extraction.verdict_reason ?? extraction.review?.verdict_reason}
+                            </p>
+                        )}
+                        {extraction.review?.summary && (
+                            <p className="mt-2 text-xs text-muted-foreground">
+                                <span className="font-medium text-foreground">{t('grounded.reviewSummary')}: </span>
+                                {extraction.review.summary}
+                            </p>
+                        )}
+                        {typeof extraction.review?.corrections_applied === 'number' &&
+                            extraction.review.corrections_applied > 0 && (
+                                <p className="mt-1 text-xs text-info">
+                                    {t('grounded.reviewCorrections', {
+                                        count: extraction.review.corrections_applied,
+                                    })}
+                                </p>
+                            )}
+                    </div>
+                )}
+                {showBreakdown && (
+                    <div className="shrink-0 border-b border-border bg-background px-3 py-2 text-sm max-h-72 overflow-auto">
+                        <div className="font-medium mb-1">{t('grounded.breakdownTitle')}</div>
+                        <div className="grid grid-cols-2 gap-x-4 text-xs">
+                            <span className="col-span-2 mt-1 font-medium text-success">
+                                {t('grounded.digitalVerifiedOf', {
+                                    count: breakdown.digitallyVerified,
+                                    total: totalCitations,
+                                })}
+                            </span>
+                            <span className="ps-2 text-muted-foreground">{t('grounded.breakdownDigital')}</span>
+                            <span className="text-end text-success">{breakdown.groups.digital}</span>
+                            <span className="ps-2 text-muted-foreground">{t('grounded.breakdownOcr')}</span>
+                            <span className="text-end text-success">{breakdown.groups.ocr}</span>
+                            <span className="ps-2 text-muted-foreground">{t('grounded.breakdownSnapped')}</span>
+                            <span className="text-end text-success">{breakdown.groups.snapped}</span>
+                            <span className="col-span-2 mt-2 font-medium text-success">
+                                {t('grounded.modelVerifiedOf', {
+                                    count: breakdown.modelVerified,
+                                    total: totalCitations,
+                                })}
+                            </span>
+                            <span className="ps-2 text-muted-foreground">{t('grounded.breakdownReviewer')}</span>
+                            <span className="text-end text-success">{breakdown.groups.reviewerConfirmed}</span>
+                            {breakdown.groups.imageRead > 0 && (
+                                <>
+                                    <span className="col-span-2 mt-2 font-medium text-attention">
+                                        {t('grounded.unverifiedCount', { count: breakdown.groups.imageRead })}
+                                    </span>
+                                    <span className="ps-2 text-muted-foreground">
+                                        {t('grounded.breakdownImageRead')}
+                                    </span>
+                                    <span className="text-end text-attention">{breakdown.groups.imageRead}</span>
+                                </>
+                            )}
+                        </div>
+                        <p className="mt-2 text-xs text-muted-foreground">{t('grounded.breakdownVerificationHelp')}</p>
+                        {breakdown.unverified.length > 0 && (
+                            <div className="mt-2">
+                                <div className="text-xs font-medium text-muted-foreground mb-1">
+                                    {t('grounded.breakdownUnverifiedList')}
+                                </div>
+                                <ul className="space-y-0.5">
+                                    {breakdown.unverified.map((c) => (
+                                        <li key={c.path}>
+                                            <button
+                                                type="button"
+                                                className="w-full text-start text-xs rounded px-1 py-0.5 hover:bg-muted cursor-pointer"
+                                                onClick={() => {
+                                                    selectPath(c.path);
+                                                    setShowBreakdown(false);
+                                                }}
+                                            >
+                                                <span className="text-muted-foreground">{c.path}</span>{' '}
+                                                <span>{String(c.value ?? '')}</span>
+                                            </button>
+                                        </li>
+                                    ))}
+                                </ul>
+                            </div>
+                        )}
+                    </div>
+                )}
+                {/* Extracted data */}
+                <div className="flex-1 overflow-auto p-3">
+                    <DataNode
+                        value={extraction.data}
+                        path=""
+                        citationsByPath={citationsByPath}
+                        selectedPath={selectedPath}
+                        onSelect={selectPath}
+                    />
+                    {extraction.conflicts && extraction.conflicts.length > 0 && (
+                        <div className="mt-4 text-xs text-attention">
+                            {t('grounded.conflicts', { count: extraction.conflicts.length })}
+                        </div>
+                    )}
+                </div>
+            </ResizablePanel>
+            {assistantOpen && (
+                <>
+                    <ResizableHandle className="w-[4px] bg-border cursor-ew-resize" />
+                    <ResizablePanel defaultSize={30} minSize={20} className="flex flex-col border-s border-border">
+                        <GroundedExtractionAssistantPanel
+                            objectId={objectId}
+                            onExtractionChanged={onExtractionChanged}
+                            selectedField={selectedPath}
+                            onClose={() => setAssistantOpen(false)}
+                        />
+                    </ResizablePanel>
+                </>
+            )}
+        </ResizablePanelGroup>
+    );
+}
+
+function PageWithOverlay({
+    objectId,
+    page,
+    dims,
+    citations,
+    selectedPath,
+    onSelectPath,
+    imageMode,
+}: {
+    objectId: string;
+    page: number;
+    dims?: { width: number; height: number; rotation?: number };
+    citations: GroundedCitation[];
+    selectedPath?: string;
+    onSelectPath: (path: string) => void;
+    imageMode: PageImageMode;
+}) {
+    const { t } = useUITranslation();
+    const { client } = useUserSession();
+    const [imageUrl, setImageUrl] = useState<string | undefined>(undefined);
+
+    useEffect(() => {
+        let cancelled = false;
+        setImageUrl(undefined);
+        client.files
+            .getDownloadUrl(`${ADVANCED_PROCESSING_PREFIX}/${objectId}/pages/page-${page}.${imageMode}.jpg`)
+            .then((r) => {
+                if (!cancelled) setImageUrl(r.url);
+            })
+            .catch((err: unknown) => console.warn('Failed to load page image', err));
+        return () => {
+            cancelled = true;
+        };
+    }, [client, imageMode, objectId, page]);
+
+    if (!imageUrl || !dims) {
+        return (
+            <div className="flex items-center justify-center h-64">
+                <Spinner />
+            </div>
+        );
+    }
+
+    // Citation boxes live in the page's (possibly OCR-rotated) coordinate space,
+    // which `dims` describes. They overlay directly on a container that is that
+    // same space — so when the page is rotated we rotate the image to fill that
+    // space rather than transforming every box.
+    const boxOverlays = citations.flatMap((citation) =>
+        citation.boxes.map((box, i) => {
+            const isSelected =
+                selectedPath !== undefined &&
+                normalizeCitationPath(selectedPath) === normalizeCitationPath(citation.path);
+            const cellRange = citation.cells
+                ? citation.cells.start === citation.cells.end
+                    ? citation.cells.start
+                    : `${citation.cells.start}:${citation.cells.end}`
+                : undefined;
+            return (
+                <button
+                    key={`${citation.path}-${i}`}
+                    type="button"
+                    aria-label={citation.path}
+                    title={`${citation.path}${cellRange ? `\n${cellRange}` : ''}${citation.source_text ? `\n${citation.source_text}` : ''}`}
+                    onClick={() => onSelectPath(normalizeCitationPath(citation.path))}
+                    className={cn(
+                        'absolute cursor-pointer border rounded-[1px] transition-colors',
+                        citation.misaligned && 'border-dashed',
+                        isSelected
+                            ? 'border-2 border-destructive bg-destructive/20 z-10'
+                            : selectedPath
+                              ? 'border-info/30 hover:border-info'
+                              : citation.verified
+                                ? 'border-success/70 hover:bg-success/20'
+                                : citation.reviewed
+                                  ? 'border-info/70 hover:bg-info/20'
+                                  : 'border-attention/80 hover:bg-attention/20',
+                    )}
+                    style={{
+                        // inline position: the app's button base styles override the
+                        // `absolute` utility class with position: relative
+                        position: 'absolute',
+                        left: `${(box.x / dims.width) * 100}%`,
+                        top: `${(box.y / dims.height) * 100}%`,
+                        width: `${(box.w / dims.width) * 100}%`,
+                        height: `${(box.h / dims.height) * 100}%`,
+                    }}
+                />
+            );
+        }),
+    );
+
+    // The stored page image is in the source orientation; the OCR pass may have
+    // rotated the page to upright to read it, so `rotation` (CW degrees) is how
+    // much the image must turn to match the citation coordinates. A 90/270 turn
+    // also transposes the image box, so it is sized to the container's transpose.
+    const rot = (((dims.rotation ?? 0) % 360) + 360) % 360;
+    if (rot !== 0) {
+        const transpose = rot === 90 || rot === 270;
+        return (
+            <div className="relative w-full" style={{ aspectRatio: `${dims.width} / ${dims.height}` }}>
+                <img
+                    src={imageUrl}
+                    alt={t('grounded.pageAlt', { page })}
+                    className="absolute select-none"
+                    style={{
+                        left: '50%',
+                        top: '50%',
+                        width: `${(transpose ? dims.height / dims.width : 1) * 100}%`,
+                        height: `${(transpose ? dims.width / dims.height : 1) * 100}%`,
+                        maxWidth: 'none',
+                        transform: `translate(-50%, -50%) rotate(${rot}deg)`,
+                        transformOrigin: 'center center',
+                    }}
+                />
+                {boxOverlays}
+            </div>
+        );
+    }
+
+    return (
+        <div className="relative w-full">
+            <img src={imageUrl} alt={t('grounded.pageAlt', { page })} className="w-full select-none" />
+            {boxOverlays}
+        </div>
+    );
+}
+
+function DataNode({
+    value,
+    path,
+    citationsByPath,
+    selectedPath,
+    onSelect,
+}: {
+    value: unknown;
+    path: string;
+    citationsByPath: Map<string, GroundedCitation[]>;
+    selectedPath?: string;
+    onSelect: (path: string) => void;
+}) {
+    if (Array.isArray(value)) {
+        if (value.length > 0 && value.every((item) => item !== null && typeof item === 'object')) {
+            return (
+                <ArrayTable
+                    items={value as Record<string, unknown>[]}
+                    path={path}
+                    citationsByPath={citationsByPath}
+                    selectedPath={selectedPath}
+                    onSelect={onSelect}
+                />
+            );
+        }
+        return (
+            <div className="space-y-1">
+                {value.map((item, i) => (
+                    <DataNode
+                        key={`${path}[${i}]`}
+                        value={item}
+                        path={`${path}[${i}]`}
+                        citationsByPath={citationsByPath}
+                        selectedPath={selectedPath}
+                        onSelect={onSelect}
+                    />
+                ))}
+            </div>
+        );
+    }
+    if (value !== null && typeof value === 'object') {
+        return (
+            <div className={path ? 'ps-3 border-s border-border space-y-0.5' : 'space-y-0.5'}>
+                {Object.entries(value as Record<string, unknown>).map(([key, child]) => {
+                    const childPath = path ? `${path}.${key}` : key;
+                    const isLeaf = child === null || typeof child !== 'object';
+                    if (isLeaf) {
+                        return (
+                            <LeafRow
+                                key={childPath}
+                                label={key}
+                                value={child}
+                                path={childPath}
+                                citationsByPath={citationsByPath}
+                                selectedPath={selectedPath}
+                                onSelect={onSelect}
+                            />
+                        );
+                    }
+                    // Arrays of objects render as a table with its own labeled header
+                    const rendersOwnLabel =
+                        Array.isArray(child) &&
+                        child.length > 0 &&
+                        child.every((item) => item !== null && typeof item === 'object');
+                    return (
+                        <div key={childPath} className="pt-1">
+                            {!rendersOwnLabel && (
+                                <div className="text-xs font-semibold text-muted-foreground uppercase tracking-wide">
+                                    {key}
+                                </div>
+                            )}
+                            <DataNode
+                                value={child}
+                                path={childPath}
+                                citationsByPath={citationsByPath}
+                                selectedPath={selectedPath}
+                                onSelect={onSelect}
+                            />
+                        </div>
+                    );
+                })}
+            </div>
+        );
+    }
+    return null;
+}
+
+function ArrayTable({
+    items,
+    path,
+    citationsByPath,
+    selectedPath,
+    onSelect,
+}: {
+    items: Record<string, unknown>[];
+    path: string;
+    citationsByPath: Map<string, GroundedCitation[]>;
+    selectedPath?: string;
+    onSelect: (path: string) => void;
+}) {
+    const { t } = useUITranslation();
+    const columns = useMemo(() => {
+        const keys = new Set<string>();
+        for (const item of items) {
+            for (const key of Object.keys(item)) keys.add(key);
+        }
+        return Array.from(keys);
+    }, [items]);
+
+    return (
+        <div className="pt-1">
+            <div className="text-xs font-semibold text-muted-foreground uppercase tracking-wide">
+                {path.split('.').pop()} ({items.length})
+            </div>
+            <div className="overflow-x-auto">
+                <table className="w-full text-xs">
+                    <thead>
+                        <tr className="text-start text-muted-foreground">
+                            {columns.map((col) => (
+                                <th key={col} scope="col" className="py-1 pe-2 font-medium">
+                                    {col}
+                                </th>
+                            ))}
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {items.map((item, i) => (
+                            <tr key={`${path}[${i}]`} className="border-t border-border/50">
+                                {columns.map((col) => {
+                                    const cellPath = `${path}[${i}].${col}`;
+                                    const citation = citationsByPath.get(cellPath)?.[0];
+                                    const isSelected = selectedPath === cellPath;
+                                    return (
+                                        <td key={col} className="py-0.5 pe-2">
+                                            <button
+                                                type="button"
+                                                onClick={() => onSelect(cellPath)}
+                                                className={cn(
+                                                    'text-start rounded px-1 w-full',
+                                                    isSelected
+                                                        ? 'bg-destructive/15 ring-1 ring-destructive'
+                                                        : citation
+                                                          ? 'hover:bg-muted cursor-pointer'
+                                                          : 'text-muted-foreground cursor-default',
+                                                )}
+                                            >
+                                                {formatValue(item[col])}
+                                                {citation && typeof citation.confidence === 'number' && (
+                                                    <span
+                                                        className={cn(
+                                                            'ms-1 text-[10px]',
+                                                            scoreColor(citation.confidence),
+                                                        )}
+                                                        title={t('grounded.confidenceHint')}
+                                                    >
+                                                        {formatScore(citation.confidence)}
+                                                    </span>
+                                                )}
+                                            </button>
+                                        </td>
+                                    );
+                                })}
+                            </tr>
+                        ))}
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    );
+}
+
+function LeafRow({
+    label,
+    value,
+    path,
+    citationsByPath,
+    selectedPath,
+    onSelect,
+}: {
+    label: string;
+    value: unknown;
+    path: string;
+    citationsByPath: Map<string, GroundedCitation[]>;
+    selectedPath?: string;
+    onSelect: (path: string) => void;
+}) {
+    const { t } = useUITranslation();
+    const citation = citationsByPath.get(path)?.[0];
+    const isSelected = selectedPath === path;
+
+    return (
+        <button
+            type="button"
+            onClick={() => citation && onSelect(path)}
+            className={cn(
+                'flex items-center gap-2 w-full text-start text-sm rounded px-1.5 py-0.5',
+                isSelected ? 'bg-destructive/15 ring-1 ring-destructive' : citation ? 'hover:bg-muted' : '',
+                !citation && 'cursor-default',
+            )}
+        >
+            <span className="text-muted-foreground min-w-28 shrink-0">{label}</span>
+            <span className="flex-1 wrap-break-word">{formatValue(value)}</span>
+            {citation && typeof citation.confidence === 'number' && (
+                <span
+                    className={cn('text-xs shrink-0', scoreColor(citation.confidence))}
+                    title={t('grounded.confidenceHint')}
+                >
+                    {formatScore(citation.confidence)}
+                </span>
+            )}
+            {citation &&
+                (citation.verified ? (
+                    <CheckCircle2 aria-label={t('grounded.verified')} className="size-3.5 shrink-0 text-success" />
+                ) : citation.reviewed ? (
+                    <Sparkles aria-label={t('grounded.aiVerified')} className="size-3.5 shrink-0 text-info" />
+                ) : (
+                    <Eye aria-label={t('grounded.readFromImage')} className="size-3.5 shrink-0 text-attention" />
+                ))}
+        </button>
+    );
+}
+
+/**
+ * Tier scores (1.0, 0.99, 0.5...) are policy values and display as integers;
+ * OCR-measured scores carry real decimals from tesseract and keep two.
+ */
+function formatScore(confidence: number): string {
+    const pct = confidence * 100;
+    return Number.isInteger(pct) ? `${pct}%` : `${(Math.floor(pct * 100) / 100).toFixed(2)}%`;
+}
+
+function scoreColor(confidence: number): string {
+    if (confidence >= 0.95) return 'text-success';
+    if (confidence >= 0.7) return 'text-attention';
+    return 'text-destructive';
+}
+
+function formatValue(value: unknown): string {
+    if (value === null || value === undefined || value === '') return '—';
+    if (typeof value === 'boolean') return value ? 'true' : 'false';
+    if (typeof value === 'object') return JSON.stringify(value);
+    return String(value);
+}