feat: human validation, recursive highlighting, data mentions rename

- Add human validation UI (✅/❌) for model-extracted data mentions
- Validation metadata stored inside dataset_name alongside judge_ fields
- Recursive highlighting works inside bold/italic/links
- Rename 'Datasets' to 'Data Mentions' throughout
- Switch input from _raw.json to _direct_judged.jsonl
- Document API reads local files in dev (highlights appear after save)
- Add /api/validate (PUT for validation, DELETE by index)
- Add /api/whoami for HF username auto-fetch
- Floating chevron panel toggle with badge count
- Rename annotation_tag to annotator

.env.example

@@ -0,0 +1,8 @@
+# Hugging Face token for accessing datasets
+HF_TOKEN=your_hf_token_here
+
+# Optional: Override the default HF dataset repo
+# HF_DATASET_REPO=rafmacalaba/wbg_annotation_data
+
+# Optional: Number of documents to scan on initial load (default: 5)
+# MAX_DOCS_TO_SCAN=5

Dockerfile

@@ -6,9 +6,9 @@ FROM base AS deps
 RUN apk add --no-cache libc6-compat
 WORKDIR /app
 
-# Copy package.json and install
-COPY package.json ./
-RUN npm install
+# Copy package files and install deterministically
+COPY package.json package-lock.json ./
+RUN npm ci
 
 # Rebuild the source code only when needed
 FROM base AS builder

app/api/annotate/route.js

@@ -1,28 +1,80 @@
-import { saveAnnotation } from '../../../utils/storage.js';
+import { saveAnnotation, deleteAnnotation, updateAnnotation } from '../../../utils/storage.js';
+import { NextResponse } from 'next/server';
 
 export async function POST(request) {
     try {
         const body = await request.json();
-        const { document_index, page_number, selected_text, annotation_note } = body;
+        const {
+            dataset_name,
+            dataset_tag,
+            document_index,
+            page_number,
+        } = body;
 
-        if (!document_index || page_number === undefined || !selected_text) {
-            return new Response(JSON.stringify({ error: "Missing required fields" }), { status: 400 });
+        if (
+            document_index === undefined || document_index === null ||
+            page_number === undefined ||
+            !dataset_name?.text ||
+            !dataset_tag
+        ) {
+            return NextResponse.json(
+                { error: 'Missing required fields: dataset_name.text, dataset_tag, document_index, page_number' },
+                { status: 400 }
+            );
         }
 
-        const annotation = {
-            document_index,
-            page_number,
-            selected_text,
-            annotation_note: annotation_note || "",
-            timestamp: new Date().toISOString()
-        };
+        await saveAnnotation(body);
+        return NextResponse.json({ success: true });
+    } catch (error) {
+        console.error('Annotation error:', error);
+        return NextResponse.json({ error: 'Failed to save annotation: ' + error.message }, { status: 500 });
+    }
+}
+
+export async function DELETE(request) {
+    try {
+        const { searchParams } = new URL(request.url);
+        const timestamp = searchParams.get('timestamp');
+        const docIndex = parseInt(searchParams.get('doc'), 10);
+        const pageNumber = parseInt(searchParams.get('page'), 10);
+
+        if (!timestamp || isNaN(docIndex) || isNaN(pageNumber)) {
+            return NextResponse.json(
+                { error: 'Missing timestamp, doc, or page parameter' },
+                { status: 400 }
+            );
+        }
+
+        const deleted = await deleteAnnotation(timestamp, docIndex, pageNumber);
+        if (deleted) {
+            return NextResponse.json({ success: true });
+        }
+        return NextResponse.json({ error: 'Annotation not found' }, { status: 404 });
+    } catch (error) {
+        console.error('Delete annotation error:', error);
+        return NextResponse.json({ error: 'Failed to delete annotation: ' + error.message }, { status: 500 });
+    }
+}
 
-        await saveAnnotation(annotation);
+export async function PUT(request) {
+    try {
+        const body = await request.json();
+        const { timestamp, document_index, page_number, updates } = body;
 
-        return new Response(JSON.stringify({ success: true, annotation }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+        if (!timestamp || document_index === undefined || page_number === undefined || !updates) {
+            return NextResponse.json(
+                { error: 'Missing timestamp, document_index, page_number, or updates' },
+                { status: 400 }
+            );
+        }
 
+        const updated = await updateAnnotation(timestamp, document_index, page_number, updates);
+        if (updated) {
+            return NextResponse.json({ success: true, annotation: updated });
+        }
+        return NextResponse.json({ error: 'Annotation not found' }, { status: 404 });
     } catch (error) {
-        console.error("Annotation save error:", error);
-        return new Response(JSON.stringify({ error: "Failed to save annotation" }), { status: 500 });
+        console.error('Update annotation error:', error);
+        return NextResponse.json({ error: 'Failed to update annotation: ' + error.message }, { status: 500 });
     }
 }

app/api/annotations/route.js

@@ -0,0 +1,22 @@
+import { getAnnotations } from '../../../utils/storage.js';
+
+export async function GET(request) {
+    try {
+        const { searchParams } = new URL(request.url);
+        const docIndex = searchParams.get('document_index');
+
+        const filter = docIndex !== null ? parseInt(docIndex, 10) : null;
+        const annotations = await getAnnotations(filter);
+
+        return new Response(JSON.stringify(annotations), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' }
+        });
+    } catch (error) {
+        console.error("Error fetching annotations:", error);
+        return new Response(
+            JSON.stringify({ error: "Failed to fetch annotations" }),
+            { status: 500, headers: { 'Content-Type': 'application/json' } }
+        );
+    }
+}

app/api/document/route.js

@@ -1,37 +1,88 @@
+import { HF_DATASET_BASE_URL } from '../../../utils/config.js';
+import fs from 'fs';
+import path from 'path';
+
+const isHFSpace = () => {
+    return process.env.HF_TOKEN && process.env.NODE_ENV !== 'development';
+};
+
 export async function GET(request) {
     const { searchParams } = new URL(request.url);
     const index = searchParams.get('index');
     const page = searchParams.get('page');
 
-    if (!index || !page) {
-        return new Response(JSON.stringify({ error: "Missing index or page parameter" }), { status: 400 });
+    // Validate required params
+    if (index === null || page === null) {
+        return new Response(
+            JSON.stringify({ error: "Missing index or page parameter" }),
+            { status: 400, headers: { 'Content-Type': 'application/json' } }
+        );
+    }
+
+    // Validate numeric values
+    const indexNum = parseInt(index, 10);
+    const pageNum = parseInt(page, 10);
+
+    if (isNaN(indexNum) || isNaN(pageNum) || indexNum < 0 || pageNum < 0) {
+        return new Response(
+            JSON.stringify({ error: "index and page must be non-negative integers" }),
+            { status: 400, headers: { 'Content-Type': 'application/json' } }
+        );
     }
 
     try {
-        const HF_DATASET_ID = "rafmacalaba/wbg_annotation_data";
-        const docUrl = `https://huggingface.co/datasets/${HF_DATASET_ID}/raw/main/annotation_data/wbg_extractions/doc_${index}/raw/doc_${index}_raw.json`;
+        let pagesData;
 
-        const res = await fetch(docUrl, {
-            headers: { 'Authorization': `Bearer ${process.env.HF_TOKEN}` }
-        });
+        if (isHFSpace()) {
+            // Production: fetch from HuggingFace
+            const docUrl = `${HF_DATASET_BASE_URL}/raw/main/annotation_data/wbg_extractions/doc_${indexNum}/raw/doc_${indexNum}_direct_judged.jsonl`;
+            const res = await fetch(docUrl, {
+                headers: { 'Authorization': `Bearer ${process.env.HF_TOKEN}` }
+            });
 
-        if (!res.ok) {
-            return new Response(JSON.stringify({ error: `doc_${index}_raw.json not found on HF Datasets` }), { status: res.status });
-        }
+            if (!res.ok) {
+                return new Response(
+                    JSON.stringify({ error: `doc_${indexNum}_direct_judged.jsonl not found on HF Datasets` }),
+                    { status: res.status, headers: { 'Content-Type': 'application/json' } }
+                );
+            }
+            pagesData = await res.json();
+        } else {
+            // Local dev: read from local file (reflects saved annotations immediately)
+            const filePath = path.join(
+                process.cwd(),
+                'annotation_data', 'wbg_extractions',
+                `doc_${indexNum}`, 'raw', `doc_${indexNum}_direct_judged.jsonl`
+            );
 
-        const pagesData = await res.json();
+            if (!fs.existsSync(filePath)) {
+                return new Response(
+                    JSON.stringify({ error: `doc_${indexNum}_direct_judged.jsonl not found locally` }),
+                    { status: 404, headers: { 'Content-Type': 'application/json' } }
+                );
+            }
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            pagesData = JSON.parse(raw);
+        }
 
-        // Find the specific page
-        const pageData = pagesData.find(p => p.document.pages[0] === parseInt(page));
+        const pageData = pagesData.find(p => p.document?.pages?.[0] === pageNum);
 
         if (!pageData) {
-            return new Response(JSON.stringify({ error: `Page ${page} not found in doc ${index}` }), { status: 404 });
+            return new Response(
+                JSON.stringify({ error: `Page ${pageNum} not found in doc ${indexNum}` }),
+                { status: 404, headers: { 'Content-Type': 'application/json' } }
+            );
         }
 
-        return new Response(JSON.stringify(pageData), { status: 200, headers: { 'Content-Type': 'application/json' } });
-
+        return new Response(JSON.stringify(pageData), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' }
+        });
     } catch (error) {
         console.error(error);
-        return new Response(JSON.stringify({ error: "Failed to fetch document page from HF" }), { status: 500 });
+        return new Response(
+            JSON.stringify({ error: "Failed to fetch document page" }),
+            { status: 500, headers: { 'Content-Type': 'application/json' } }
+        );
     }
 }

app/api/documents/route.js

@@ -1,67 +1,58 @@
+import { HF_DATASET_BASE_URL, MAX_DOCS_TO_SCAN } from '../../../utils/config.js';
+
 export async function GET() {
     try {
-        const HF_DATASET_ID = "rafmacalaba/wbg_annotation_data";
-
-        // Fetch the index file from HF Datasets raw URL
-        const linksUrl = `https://huggingface.co/datasets/${HF_DATASET_ID}/raw/main/annotation_data/wbg_data/wbg_pdf_links.json`;
+        // Fetch the index file from HF Datasets
+        const linksUrl = `${HF_DATASET_BASE_URL}/raw/main/annotation_data/wbg_data/wbg_pdf_links.json`;
         const linksRes = await fetch(linksUrl, {
             headers: {
                 'Authorization': `Bearer ${process.env.HF_TOKEN}`
             },
-            next: { revalidate: 3600 } // Cache for an hour to not spam HF
+            next: { revalidate: 3600 }
         });
 
         if (!linksRes.ok) {
             console.error("Failed to fetch links JSON", await linksRes.text());
-            return new Response(JSON.stringify({ error: "Missing wbg_pdf_links.json on HF Datasets" }), { status: 404 });
+            return new Response(
+                JSON.stringify({ error: "Missing wbg_pdf_links.json on HF Datasets" }),
+                { status: 404, headers: { 'Content-Type': 'application/json' } }
+            );
         }
 
         const links = await linksRes.json();
-        const documents = [];
-
-        // Because scanning 1220 external HTTP JSON files concurrently on every page load would be extremely slow 
-        // and easily hit rate limits, we will implement a simplified approach.
-        // For a production app, we would pre-compute this list and upload it as a manifest. 
-        // For this MVP, we will only scan the first 5 "success" links to populate the dropdown quickly,
-        // assuming those are the priority documents to annotate.
 
-        const maxDocsToScan = 5;
-        let scanCount = 0;
+        // Filter to successful links and take the first N
+        const successLinks = links.filter(l => l.status === 'success').slice(0, MAX_DOCS_TO_SCAN);
 
-        for (const link of links) {
-            if (link.status === 'success') {
-                scanCount++;
+        // Parallel fetch — much faster than sequential scanning
+        const results = await Promise.allSettled(
+            successLinks.map(async (link) => {
+                const docUrl = `${HF_DATASET_BASE_URL}/raw/main/annotation_data/wbg_extractions/doc_${link.index}/raw/doc_${link.index}_direct_judged.jsonl`;
+                const docRes = await fetch(docUrl, {
+                    headers: { 'Authorization': `Bearer ${process.env.HF_TOKEN}` }
+                });
 
-                try {
-                    const docUrl = `https://huggingface.co/datasets/${HF_DATASET_ID}/raw/main/annotation_data/wbg_extractions/doc_${link.index}/raw/doc_${link.index}_raw.json`;
-                    const docRes = await fetch(docUrl, {
-                        headers: { 'Authorization': `Bearer ${process.env.HF_TOKEN}` }
-                    });
+                if (!docRes.ok) return null;
 
-                    if (docRes.ok) {
-                        const pagesData = await docRes.json();
+                const pagesData = await docRes.json();
+                const annotatablePages = pagesData
+                    .filter(page => page.datasets && page.datasets.length > 0)
+                    .map(page => page.document.pages[0]);
 
-                        // Find pages with non-empty datasets
-                        const annotatablePages = pagesData
-                            .filter(page => page.datasets && page.datasets.length > 0)
-                            .map(page => page.document.pages[0]);
+                if (annotatablePages.length === 0) return null;
 
-                        if (annotatablePages.length > 0) {
-                            documents.push({
-                                index: link.index,
-                                pdf_url: link.direct_pdf_url,
-                                landing_page: link.landing_page_url,
-                                annotatable_pages: annotatablePages
-                            });
-                        }
-                    }
-                } catch (e) {
-                    console.error(`Failed to scan doc ${link.index} from HF`, e);
-                }
+                return {
+                    index: link.index,
+                    pdf_url: link.direct_pdf_url,
+                    landing_page: link.landing_page_url,
+                    annotatable_pages: annotatablePages
+                };
+            })
+        );
 
-                if (scanCount >= maxDocsToScan) break;
-            }
-        }
+        const documents = results
+            .filter(r => r.status === 'fulfilled' && r.value !== null)
+            .map(r => r.value);
 
         return new Response(JSON.stringify(documents), {
             status: 200,
@@ -72,6 +63,9 @@ export async function GET() {
         });
     } catch (error) {
         console.error(error);
-        return new Response(JSON.stringify({ error: "Failed to fetch documents from HF" }), { status: 500 });
+        return new Response(
+            JSON.stringify({ error: "Failed to fetch documents from HF" }),
+            { status: 500, headers: { 'Content-Type': 'application/json' } }
+        );
     }
 }

app/api/health/route.js

@@ -0,0 +1,10 @@
+export async function GET() {
+    return new Response(
+        JSON.stringify({
+            status: 'ok',
+            timestamp: new Date().toISOString(),
+            environment: process.env.NODE_ENV || 'unknown'
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } }
+    );
+}

app/api/validate/route.js

@@ -0,0 +1,182 @@
+import { NextResponse } from 'next/server';
+import fs from 'fs';
+import path from 'path';
+import { commit } from '@huggingface/hub';
+import { HF_DATASET_ID, HF_DATASET_BASE_URL } from '../../../utils/config.js';
+
+const isHFSpace = () => process.env.HF_TOKEN && process.env.NODE_ENV !== 'development';
+
+function getDocFilePath(docIndex) {
+    return path.join(
+        process.cwd(),
+        'annotation_data', 'wbg_extractions',
+        `doc_${docIndex}`, 'raw', `doc_${docIndex}_direct_judged.jsonl`
+    );
+}
+
+function getDocRepoPath(docIndex) {
+    return `annotation_data/wbg_extractions/doc_${docIndex}/raw/doc_${docIndex}_direct_judged.jsonl`;
+}
+
+/**
+ * PUT /api/validate
+ * Updates a specific dataset entry within a page by its array index.
+ * Body: { document_index, page_number, dataset_index, updates }
+ */
+export async function PUT(request) {
+    try {
+        const { document_index, page_number, dataset_index, updates } = await request.json();
+
+        if (document_index == null || page_number == null || dataset_index == null || !updates) {
+            return NextResponse.json(
+                { error: 'Missing document_index, page_number, dataset_index, or updates' },
+                { status: 400 }
+            );
+        }
+
+        let pagesData;
+
+        if (isHFSpace()) {
+            const url = `${HF_DATASET_BASE_URL}/raw/main/${getDocRepoPath(document_index)}`;
+            const res = await fetch(url, {
+                headers: { 'Authorization': `Bearer ${process.env.HF_TOKEN}` }
+            });
+            if (!res.ok) {
+                return NextResponse.json({ error: 'Document not found on HF' }, { status: 404 });
+            }
+            pagesData = await res.json();
+        } else {
+            const filePath = getDocFilePath(document_index);
+            if (!fs.existsSync(filePath)) {
+                return NextResponse.json({ error: 'Document not found locally' }, { status: 404 });
+            }
+            pagesData = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+
+        // Find the page
+        const pageIdx = pagesData.findIndex(p => p.document?.pages?.[0] === page_number);
+        if (pageIdx === -1) {
+            return NextResponse.json({ error: `Page ${page_number} not found` }, { status: 404 });
+        }
+
+        const datasets = pagesData[pageIdx].datasets || [];
+        if (dataset_index < 0 || dataset_index >= datasets.length) {
+            return NextResponse.json({ error: `Dataset index ${dataset_index} out of range` }, { status: 400 });
+        }
+
+        // Merge updates into dataset_name (same level as judge_ fields)
+        const currentEntry = pagesData[pageIdx].datasets[dataset_index];
+        pagesData[pageIdx].datasets[dataset_index] = {
+            ...currentEntry,
+            dataset_name: {
+                ...currentEntry.dataset_name,
+                ...updates,
+            },
+        };
+
+        // Save back
+        if (isHFSpace()) {
+            const token = process.env.HF_TOKEN;
+            const repoPath = getDocRepoPath(document_index);
+            const content = JSON.stringify(pagesData, null, 2);
+            await commit({
+                repo: { type: 'dataset', name: HF_DATASET_ID },
+                credentials: { accessToken: token },
+                title: `Validate dataset in doc_${document_index} page ${page_number}`,
+                operations: [{
+                    operation: 'addOrUpdate',
+                    path: repoPath,
+                    content: new Blob([content], { type: 'application/json' }),
+                }],
+            });
+        } else {
+            const filePath = getDocFilePath(document_index);
+            fs.writeFileSync(filePath, JSON.stringify(pagesData, null, 2));
+        }
+
+        return NextResponse.json({
+            success: true,
+            dataset: pagesData[pageIdx].datasets[dataset_index],
+        });
+    } catch (error) {
+        console.error('Validate error:', error);
+        return NextResponse.json({ error: 'Failed to validate: ' + error.message }, { status: 500 });
+    }
+}
+
+/**
+ * DELETE /api/validate?doc=X&page=Y&idx=Z
+ * Removes a dataset entry by its array index.
+ */
+export async function DELETE(request) {
+    try {
+        const { searchParams } = new URL(request.url);
+        const document_index = parseInt(searchParams.get('doc'), 10);
+        const page_number = parseInt(searchParams.get('page'), 10);
+        const dataset_index = parseInt(searchParams.get('idx'), 10);
+
+        if (isNaN(document_index) || isNaN(page_number) || isNaN(dataset_index)) {
+            return NextResponse.json(
+                { error: 'Missing doc, page, or idx parameter' },
+                { status: 400 }
+            );
+        }
+
+        let pagesData;
+
+        if (isHFSpace()) {
+            const url = `${HF_DATASET_BASE_URL}/raw/main/${getDocRepoPath(document_index)}`;
+            const res = await fetch(url, {
+                headers: { 'Authorization': `Bearer ${process.env.HF_TOKEN}` }
+            });
+            if (!res.ok) {
+                return NextResponse.json({ error: 'Document not found on HF' }, { status: 404 });
+            }
+            pagesData = await res.json();
+        } else {
+            const filePath = getDocFilePath(document_index);
+            if (!fs.existsSync(filePath)) {
+                return NextResponse.json({ error: 'Document not found locally' }, { status: 404 });
+            }
+            pagesData = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+
+        const pageIdx = pagesData.findIndex(p => p.document?.pages?.[0] === page_number);
+        if (pageIdx === -1) {
+            return NextResponse.json({ error: `Page ${page_number} not found` }, { status: 404 });
+        }
+
+        const datasets = pagesData[pageIdx].datasets || [];
+        if (dataset_index < 0 || dataset_index >= datasets.length) {
+            return NextResponse.json({ error: `Dataset index ${dataset_index} out of range` }, { status: 400 });
+        }
+
+        // Remove the entry
+        pagesData[pageIdx].datasets.splice(dataset_index, 1);
+
+        // Save back
+        if (isHFSpace()) {
+            const token = process.env.HF_TOKEN;
+            const repoPath = getDocRepoPath(document_index);
+            const content = JSON.stringify(pagesData, null, 2);
+            await commit({
+                repo: { type: 'dataset', name: HF_DATASET_ID },
+                credentials: { accessToken: token },
+                title: `Delete dataset from doc_${document_index} page ${page_number}`,
+                operations: [{
+                    operation: 'addOrUpdate',
+                    path: repoPath,
+                    content: new Blob([content], { type: 'application/json' }),
+                }],
+            });
+        } else {
+            const filePath = getDocFilePath(document_index);
+            fs.writeFileSync(filePath, JSON.stringify(pagesData, null, 2));
+        }
+
+        return NextResponse.json({ success: true });
+    } catch (error) {
+        console.error('Delete error:', error);
+        return NextResponse.json({ error: 'Failed to delete: ' + error.message }, { status: 500 });
+    }
+}

app/api/whoami/route.js

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+
+/**
+ * Returns the HF username for the current token.
+ * Used to auto-fill the annotator name in production.
+ */
+export async function GET() {
+    const token = process.env.HF_TOKEN;
+    if (!token) {
+        return NextResponse.json({ username: null }, { status: 200 });
+    }
+
+    try {
+        const res = await fetch('https://huggingface.co/api/whoami-v2', {
+            headers: { 'Authorization': `Bearer ${token}` },
+        });
+
+        if (!res.ok) {
+            return NextResponse.json({ username: null }, { status: 200 });
+        }
+
+        const data = await res.json();
+        return NextResponse.json({ username: data.name || null });
+    } catch (error) {
+        console.error('HF whoami error:', error);
+        return NextResponse.json({ username: null }, { status: 200 });
+    }
+}

app/components/AnnotationModal.js

@@ -0,0 +1,104 @@
+"use client";
+
+import { useState, useEffect, useRef } from 'react';
+
+const DATASET_TAGS = [
+    { value: 'named', label: 'Named Dataset', description: 'A specific, named dataset (e.g. "2022 national census")' },
+    { value: 'descriptive', label: 'Descriptive', description: 'A described but not formally named dataset' },
+    { value: 'vague', label: 'Vague', description: 'An unclear or ambiguous data reference' },
+];
+
+export default function AnnotationModal({
+    isOpen,
+    selectedText,
+    annotatorName,
+    onAnnotatorChange,
+    onSubmit,
+    onClose,
+}) {
+    const [datasetTag, setDatasetTag] = useState('named');
+    const [saving, setSaving] = useState(false);
+    const noteRef = useRef(null);
+
+    useEffect(() => {
+        if (isOpen && noteRef.current) {
+            noteRef.current.focus();
+        }
+    }, [isOpen]);
+
+    useEffect(() => {
+        const handleEsc = (e) => { if (e.key === 'Escape') onClose(); };
+        if (isOpen) window.addEventListener('keydown', handleEsc);
+        return () => window.removeEventListener('keydown', handleEsc);
+    }, [isOpen, onClose]);
+
+    if (!isOpen) return null;
+
+    const handleSubmit = async () => {
+        setSaving(true);
+        await onSubmit({ dataset_tag: datasetTag });
+        setSaving(false);
+        setDatasetTag('named');
+    };
+
+    return (
+        <div className="modal-overlay" onClick={(e) => { if (e.target === e.currentTarget) onClose(); }}>
+            <div className="modal-content">
+                <div className="modal-header">
+                    <h3>Add Annotation</h3>
+                    <button className="modal-close" onClick={onClose}>&times;</button>
+                </div>
+
+                <div className="modal-body">
+                    {/* Selected text preview */}
+                    <div className="form-group">
+                        <label>Selected Text</label>
+                        <div className="selected-text-preview">"{selectedText}"</div>
+                    </div>
+
+                    {/* Dataset tag dropdown */}
+                    <div className="form-group">
+                        <label htmlFor="dataset-tag">Dataset Tag</label>
+                        <select
+                            id="dataset-tag"
+                            className="form-select"
+                            value={datasetTag}
+                            onChange={(e) => setDatasetTag(e.target.value)}
+                        >
+                            {DATASET_TAGS.map(tag => (
+                                <option key={tag.value} value={tag.value}>
+                                    {tag.label}
+                                </option>
+                            ))}
+                        </select>
+                        <p className="form-help">
+                            {DATASET_TAGS.find(t => t.value === datasetTag)?.description}
+                        </p>
+                    </div>
+
+                    {/* Annotator name */}
+                    <div className="form-group">
+                        <label htmlFor="annotator-name">Your Name</label>
+                        <input
+                            id="annotator-name"
+                            type="text"
+                            className="form-input"
+                            placeholder="Enter your name"
+                            value={annotatorName}
+                            onChange={(e) => onAnnotatorChange(e.target.value)}
+                        />
+                    </div>
+                </div>
+
+                <div className="modal-footer">
+                    <button className="btn btn-secondary" onClick={onClose} disabled={saving}>
+                        Cancel
+                    </button>
+                    <button className="btn btn-primary" onClick={handleSubmit} disabled={saving}>
+                        {saving ? 'Saving...' : 'Save Annotation'}
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}

app/components/AnnotationPanel.js

@@ -0,0 +1,224 @@
+"use client";
+
+import { useState } from 'react';
+
+const TAG_STYLES = {
+    named: { color: '#10b981', bg: '#10b98120', label: 'Named' },
+    descriptive: { color: '#f59e0b', bg: '#f59e0b20', label: 'Descriptive' },
+    vague: { color: '#a78bfa', bg: '#a78bfa20', label: 'Vague' },
+    'non-dataset': { color: '#64748b', bg: '#64748b20', label: 'Non-Dataset' },
+};
+
+const TAG_OPTIONS = ['named', 'descriptive', 'vague', 'non-dataset'];
+
+export default function AnnotationPanel({
+    isOpen,
+    onClose,
+    datasets,          // ALL datasets on current page (model + human)
+    annotatorName,     // current user's name
+    onValidate,        // (datasetIdx, updates) => void
+    onDelete,
+}) {
+    const [validatingIdx, setValidatingIdx] = useState(null);
+    const [validationNotes, setValidationNotes] = useState('');
+    const [editingTagIdx, setEditingTagIdx] = useState(null);
+    const [editTag, setEditTag] = useState('');
+    const [confirmDelete, setConfirmDelete] = useState(null);
+
+    const startValidation = (idx, prefillNotes = '') => {
+        setValidatingIdx(idx);
+        setValidationNotes(prefillNotes);
+    };
+
+    const submitValidation = (ds, idx, verdict) => {
+        onValidate(idx, {
+            human_validated: true,
+            human_verdict: verdict,
+            human_notes: validationNotes.trim() || null,
+            annotator: annotatorName || 'user',
+            validated_at: new Date().toISOString(),
+        });
+        setValidatingIdx(null);
+        setValidationNotes('');
+    };
+
+    const startEditTag = (idx, currentTag) => {
+        setEditingTagIdx(idx);
+        setEditTag(currentTag);
+    };
+
+    const saveEditTag = (ds, idx) => {
+        onValidate(idx, { dataset_tag: editTag });
+        setEditingTagIdx(null);
+        setEditTag('');
+    };
+
+    const handleDelete = (ds, idx) => {
+        if (confirmDelete === idx) {
+            onDelete(ds, idx);
+            setConfirmDelete(null);
+        } else {
+            setConfirmDelete(idx);
+            setTimeout(() => setConfirmDelete(prev => prev === idx ? null : prev), 3000);
+        }
+    };
+
+    return (
+        <>
+            {isOpen && <div className="panel-backdrop" onClick={onClose} />}
+
+            <div className={`annotation-panel ${isOpen ? 'open' : ''}`}>
+                <div className="panel-header">
+                    <h3>Data Mentions</h3>
+                    <span className="panel-count">{datasets.length}</span>
+                    <button className="panel-close" onClick={onClose}>&times;</button>
+                </div>
+
+                <div className="panel-body">
+                    {datasets.length === 0 ? (
+                        <div className="panel-empty">
+                            <p>No datasets detected on this page.</p>
+                        </div>
+                    ) : (
+                        datasets.map((ds, i) => {
+                            const text = ds.dataset_name?.text || '';
+                            const tag = ds.dataset_tag || 'named';
+                            const style = TAG_STYLES[tag] || TAG_STYLES.named;
+                            const isHuman = !!ds.annotator;
+                            const isValidated = ds.dataset_name?.human_validated;
+                            const humanVerdict = ds.dataset_name?.human_verdict;
+                            const humanNotes = ds.dataset_name?.human_notes;
+                            const validatedBy = ds.dataset_name?.annotator;
+                            const judgeVerdict = ds.dataset_name?.judge_verdict;
+                            const judgeTag = ds.dataset_name?.judge_tag;
+                            const isValidating = validatingIdx === i;
+                            const isEditingTag = editingTagIdx === i;
+
+                            return (
+                                <div
+                                    key={`${text}-${ds.dataset_name?.start}-${i}`}
+                                    className={`panel-annotation-card ${isValidated ? (humanVerdict ? 'validated-correct' : 'validated-wrong') : ''}`}
+                                >
+                                    {/* Top row: tag + source */}
+                                    <div className="panel-card-top">
+                                        {isEditingTag ? (
+                                            <div className="inline-edit">
+                                                <select
+                                                    className="form-select-small"
+                                                    value={editTag}
+                                                    onChange={(e) => setEditTag(e.target.value)}
+                                                >
+                                                    {TAG_OPTIONS.map(t => (
+                                                        <option key={t} value={t}>
+                                                            {TAG_STYLES[t]?.label || t}
+                                                        </option>
+                                                    ))}
+                                                </select>
+                                                <button className="btn-panel save" onClick={() => saveEditTag(ds, i)}>✓</button>
+                                                <button className="btn-panel" onClick={() => setEditingTagIdx(null)}>✕</button>
+                                            </div>
+                                        ) : (
+                                            <span
+                                                className="annotation-tag-badge clickable"
+                                                style={{ color: style.color, backgroundColor: style.bg }}
+                                                onClick={() => startEditTag(i, tag)}
+                                                title="Click to change tag"
+                                            >
+                                                {style.label}
+                                            </span>
+                                        )}
+
+                                        <span className="panel-card-source">
+                                            {isHuman ? `👤 ${ds.annotator}` : '🤖 model'}
+                                        </span>
+                                    </div>
+
+                                    {/* Dataset text */}
+                                    <p className="panel-card-text">"{text}"</p>
+
+                                    {/* Judge info (for model extractions) */}
+                                    {judgeTag && (
+                                        <div className="panel-card-judge">
+                                            <span className={`judge-verdict ${judgeVerdict ? 'correct' : 'wrong'}`}>
+                                                Judge: {judgeVerdict ? '✓' : '✕'}
+                                            </span>
+                                            <span className="judge-tag">{judgeTag}</span>
+                                        </div>
+                                    )}
+
+                                    {/* Position info */}
+                                    {ds.dataset_name?.start != null && (
+                                        <span className="panel-card-position">
+                                            chars {ds.dataset_name.start}–{ds.dataset_name.end}
+                                        </span>
+                                    )}
+
+                                    {/* Existing validation status */}
+                                    {isValidated && (
+                                        <div className={`validation-status ${humanVerdict ? 'correct' : 'wrong'}`}>
+                                            {humanVerdict ? '✅ Validated correct' : '❌ Marked incorrect'}
+                                            <span className="validation-by"> by {validatedBy}</span>
+                                            {humanNotes && (
+                                                <p className="validation-notes">Note: {humanNotes}</p>
+                                            )}
+                                        </div>
+                                    )}
+
+                                    {/* Validation UI */}
+                                    {isValidating ? (
+                                        <div className="validation-form">
+                                            <textarea
+                                                className="validation-notes-input"
+                                                placeholder="Optional notes..."
+                                                value={validationNotes}
+                                                onChange={(e) => setValidationNotes(e.target.value)}
+                                                rows={2}
+                                            />
+                                            <div className="validation-buttons">
+                                                <button
+                                                    className="btn-panel correct"
+                                                    onClick={() => submitValidation(ds, i, true)}
+                                                >
+                                                    ✅ Correct
+                                                </button>
+                                                <button
+                                                    className="btn-panel wrong"
+                                                    onClick={() => submitValidation(ds, i, false)}
+                                                >
+                                                    ❌ Wrong
+                                                </button>
+                                                <button
+                                                    className="btn-panel"
+                                                    onClick={() => setValidatingIdx(null)}
+                                                >
+                                                    Cancel
+                                                </button>
+                                            </div>
+                                        </div>
+                                    ) : (
+                                        <div className="panel-card-actions">
+                                            <button
+                                                className="btn-panel validate"
+                                                onClick={() => startValidation(i, humanNotes || '')}
+                                            >
+                                                {isValidated ? '🔄 Re-validate' : '🏷️ Validate'}
+                                            </button>
+                                            {isHuman && (
+                                                <button
+                                                    className={`btn-panel delete ${confirmDelete === i ? 'confirming' : ''}`}
+                                                    onClick={() => handleDelete(ds, i)}
+                                                >
+                                                    {confirmDelete === i ? '⚠ Confirm?' : '🗑 Delete'}
+                                                </button>
+                                            )}
+                                        </div>
+                                    )}
+                                </div>
+                            );
+                        })
+                    )}
+                </div>
+            </div>
+        </>
+    );
+}

app/components/AnnotationsList.js

@@ -0,0 +1,48 @@
+"use client";
+
+const TAG_STYLES = {
+    named: { color: '#10b981', bg: '#10b98120' },
+    descriptive: { color: '#f59e0b', bg: '#f59e0b20' },
+    vague: { color: '#a78bfa', bg: '#a78bfa20' },
+    'non-dataset': { color: '#64748b', bg: '#64748b20' },
+};
+
+export default function AnnotationsList({ annotations }) {
+    if (!annotations || annotations.length === 0) return null;
+
+    return (
+        <div className="annotations-list">
+            <h3>Annotations ({annotations.length})</h3>
+            <ul>
+                {annotations.map((a, i) => {
+                    const text = a.dataset_name?.text || a.selected_text || '';
+                    const tag = a.dataset_tag || 'named';
+                    const author = a.annotation_tag || a.annotator_name || 'user';
+                    const style = TAG_STYLES[tag] || TAG_STYLES.named;
+
+                    return (
+                        <li key={`${text}-${i}`}>
+                            <div className="annotation-meta">
+                                <span className="annotation-location">
+                                    Doc {a.document_index} / Pg {a.page_number}
+                                </span>
+                                <span
+                                    className="annotation-tag-badge"
+                                    style={{ color: style.color, backgroundColor: style.bg }}
+                                >
+                                    {tag}
+                                </span>
+                            </div>
+                            <p className="annotation-text">
+                                <strong>Dataset:</strong> "{text}"
+                            </p>
+                            <small>
+                                by {author} · {a.timestamp ? new Date(a.timestamp).toLocaleString() : ''}
+                            </small>
+                        </li>
+                    );
+                })}
+            </ul>
+        </div>
+    );
+}

app/components/DocumentSelector.js

@@ -0,0 +1,29 @@
+"use client";
+
+export default function DocumentSelector({
+    documents,
+    selectedDocIndex,
+    onDocChange,
+}) {
+    return (
+        <div className="navigation-controls">
+            <div className="select-group">
+                <label htmlFor="doc-select">Document</label>
+                <select
+                    id="doc-select"
+                    value={selectedDocIndex ?? ''}
+                    onChange={(e) => {
+                        const docIdx = parseInt(e.target.value, 10);
+                        onDocChange(docIdx);
+                    }}
+                >
+                    {documents.map(doc => (
+                        <option key={doc.index} value={doc.index}>
+                            Document {doc.index} ({doc.annotatable_pages.length} pages)
+                        </option>
+                    ))}
+                </select>
+            </div>
+        </div>
+    );
+}

app/components/MarkdownAnnotator.js

@@ -0,0 +1,191 @@
+"use client";
+
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import React from 'react';
+
+// Color mapping for dataset tags
+const TAG_COLORS = {
+    named: { bg: '#10b98130', border: '#10b981', text: '#34d399', label: 'Named Dataset' },
+    descriptive: { bg: '#f59e0b30', border: '#f59e0b', text: '#fbbf24', label: 'Descriptive' },
+    vague: { bg: '#a78bfa30', border: '#a78bfa', text: '#c4b5fd', label: 'Vague' },
+    'non-dataset': { bg: '#64748b30', border: '#64748b', text: '#94a3b8', label: 'Non-Dataset' },
+};
+
+/**
+ * Highlights all dataset mentions within the markdown text.
+ * Returns the text with <mark> tags wrapping each dataset name occurrence.
+ */
+function highlightDatasets(text, datasets) {
+    if (!datasets || datasets.length === 0 || !text) return text;
+
+    // Build a list of {name, tag} sorted by name length descending (longest first to avoid partial overlaps)
+    const mentions = datasets
+        .filter(ds => ds.dataset_name?.text)
+        .map(ds => ({
+            name: ds.dataset_name.text,
+            tag: ds.dataset_tag || 'non-dataset',
+        }))
+        .sort((a, b) => b.name.length - a.name.length);
+
+    // Deduplicate by name
+    const seen = new Set();
+    const uniqueMentions = mentions.filter(m => {
+        if (seen.has(m.name)) return false;
+        seen.add(m.name);
+        return true;
+    });
+
+    if (uniqueMentions.length === 0) return text;
+
+    // Build regex that matches any of the dataset names
+    const escaped = uniqueMentions.map(m => m.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const pattern = new RegExp(`(${escaped.join('|')})`, 'gi');
+
+    // Create a lookup map for fast tag resolution
+    const nameToTag = {};
+    uniqueMentions.forEach(m => { nameToTag[m.name.toLowerCase()] = m.tag; });
+
+    // Split text by the pattern, preserving the matches
+    const parts = text.split(pattern);
+
+    return parts.map((part, i) => {
+        const tag = nameToTag[part.toLowerCase()];
+        if (tag) {
+            const colors = TAG_COLORS[tag] || TAG_COLORS['non-dataset'];
+            return `<mark data-tag="${tag}" style="background-color:${colors.bg};border-bottom:2px solid ${colors.border};color:${colors.text};padding:1px 3px;border-radius:3px;cursor:pointer;" title="[${colors.label}] ${part}">${part}</mark>`;
+        }
+        return part;
+    }).join('');
+}
+
+export default function MarkdownAnnotator({ selectedDocIndex, selectedPage, currentPageData, loadingPage, onAnnotate, onTogglePanel, annotationCount }) {
+    const handleAnnotateClick = () => {
+        const selection = window.getSelection();
+        if (selection && selection.toString().trim() !== "" && selection.rangeCount > 0) {
+            const text = selection.toString().trim();
+
+            // Compute the character offset of the selection start within the
+            // .markdown-preview container. This lets us disambiguate when the
+            // same text appears multiple times on the page.
+            let selectionOffset = 0;
+            const container = document.querySelector('.markdown-preview');
+            if (container) {
+                try {
+                    const range = selection.getRangeAt(0);
+                    const preCaretRange = document.createRange();
+                    preCaretRange.setStart(container, 0);
+                    preCaretRange.setEnd(range.startContainer, range.startOffset);
+                    selectionOffset = preCaretRange.toString().length;
+                } catch (e) {
+                    // Fallback: offset 0 (will just use first occurrence)
+                    selectionOffset = 0;
+                }
+            }
+
+            onAnnotate(text, selectionOffset);
+        } else {
+            const btn = document.getElementById('annotate-btn');
+            if (btn) {
+                btn.classList.add('shake');
+                setTimeout(() => btn.classList.remove('shake'), 500);
+            }
+        }
+    };
+
+    // Pre-process the markdown text to inject highlight markers
+    const datasets = currentPageData?.datasets || [];
+    const rawText = currentPageData?.input_text || "";
+    const highlightedText = highlightDatasets(rawText, datasets);
+
+    // Recursive helper: processes children at any depth so text inside
+    // <strong>, <em>, <a>, etc. also gets highlighted.
+    const processChildren = (children) =>
+        React.Children.map(children, child => {
+            if (typeof child === 'string') {
+                const highlighted = highlightDatasets(child, datasets);
+                if (highlighted !== child) {
+                    return <span dangerouslySetInnerHTML={{ __html: highlighted }} />;
+                }
+                return child;
+            }
+            // If it's a React element with children, recurse into it
+            if (React.isValidElement(child) && child.props?.children) {
+                return React.cloneElement(child, {}, processChildren(child.props.children));
+            }
+            return child;
+        });
+
+    // Build component overrides for all block-level and inline elements
+    const highlightWrapper = (Tag) => ({ children, ...props }) => (
+        <Tag {...props}>{processChildren(children)}</Tag>
+    );
+
+    const highlightComponents = {
+        p: highlightWrapper('p'),
+        li: highlightWrapper('li'),
+        td: highlightWrapper('td'),
+        th: highlightWrapper('th'),
+    };
+
+    return (
+        <div className="annotator-container">
+            <div className="annotator-header">
+                <h2>Markdown Annotation</h2>
+                <button
+                    id="annotate-btn"
+                    onClick={handleAnnotateClick}
+                    className="btn btn-primary"
+                    title="Select text below, then click to annotate"
+                >
+                    ✍️ Annotate Selection
+                </button>
+            </div>
+
+            {/* Dataset legend */}
+            {datasets.length > 0 && (
+                <div className="dataset-legend">
+                    {Object.entries(TAG_COLORS).map(([tag, colors]) => {
+                        const count = datasets.filter(ds => ds.dataset_tag === tag).length;
+                        if (count === 0) return null;
+                        return (
+                            <span key={tag} className="legend-item" style={{ borderColor: colors.border }}>
+                                <span className="legend-dot" style={{ backgroundColor: colors.border }} />
+                                {colors.label} ({count})
+                            </span>
+                        );
+                    })}
+                </div>
+            )}
+
+            <div className="markdown-content">
+                <div className="markdown-content-header">
+                    <h3>Doc {selectedDocIndex}, Page {selectedPage}</h3>
+                    {datasets.length > 0 && (
+                        <span className="dataset-count">
+                            {datasets.length} data mention{datasets.length !== 1 ? 's' : ''} detected
+                        </span>
+                    )}
+                </div>
+
+                {loadingPage ? (
+                    <div className="loading-spinner-container">
+                        <div className="loading-spinner" />
+                        <p>Loading page data...</p>
+                    </div>
+                ) : currentPageData ? (
+                    <div className="markdown-preview">
+                        <ReactMarkdown
+                            remarkPlugins={[remarkGfm]}
+                            components={highlightComponents}
+                        >
+                            {rawText || "No text available."}
+                        </ReactMarkdown>
+                    </div>
+                ) : (
+                    <p className="text-muted">Select a document and page to view extracted text.</p>
+                )}
+            </div>
+        </div>
+    );
+}

app/components/PageNavigator.js

@@ -0,0 +1,36 @@
+"use client";
+
+export default function PageNavigator({
+    currentIndex,
+    totalPages,
+    currentPageNumber,
+    onPrevious,
+    onNext,
+}) {
+    return (
+        <div className="page-navigator">
+            <button
+                className="btn btn-nav"
+                onClick={onPrevious}
+                disabled={currentIndex <= 0}
+                aria-label="Previous page"
+            >
+                ← Prev
+            </button>
+
+            <span className="page-indicator">
+                Page <strong>{currentPageNumber}</strong>
+                <span className="page-count">{currentIndex + 1} / {totalPages}</span>
+            </span>
+
+            <button
+                className="btn btn-nav"
+                onClick={onNext}
+                disabled={currentIndex >= totalPages - 1}
+                aria-label="Next page"
+            >
+                Next →
+            </button>
+        </div>
+    );
+}

app/components/PdfViewer.js

@@ -0,0 +1,28 @@
+"use client";
+
+export default function PdfViewer({ pdfUrl, pageNumber }) {
+    if (!pdfUrl) {
+        return (
+            <div className="pdf-placeholder">
+                <p>No PDF available for this document.</p>
+            </div>
+        );
+    }
+
+    // PDF pages in our data are 0-indexed; PDF.js viewer expects 1-indexed pages
+    const viewerPage = (pageNumber ?? 0) + 1;
+
+    // Use Mozilla's hosted PDF.js viewer — supports #page=N for direct page navigation.
+    // This avoids X-Frame-Options restrictions from the source server.
+    const pdfJsViewerUrl = `https://mozilla.github.io/pdf.js/web/viewer.html?file=${encodeURIComponent(pdfUrl)}#page=${viewerPage}`;
+
+    return (
+        <iframe
+            key={`pdf-${pdfUrl}-page-${viewerPage}`}
+            src={pdfJsViewerUrl}
+            className="pdf-frame"
+            title={`PDF Page ${viewerPage}`}
+            allow="fullscreen"
+        />
+    );
+}

app/globals.css

@@ -5,12 +5,20 @@
   --accent: #3b82f6;
   --accent-hover: #2563eb;
   --border-color: #334155;
+  --success: #10b981;
+  --error: #ef4444;
+  --surface: #334155;
+  --nav-height: 56px;
+}
+
+* {
+  box-sizing: border-box;
 }
 
 body {
   margin: 0;
   padding: 0;
-  font-family: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+  font-family: 'Inter', ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
   background-color: var(--bg-color);
   color: var(--text-color);
   display: flex;
@@ -25,17 +33,23 @@ h4 {
   color: #f8fafc;
 }
 
+/* ── Layout ─────────────────────────────────────── */
+
 .container {
   display: flex;
   width: 100%;
   height: 100%;
+  flex-wrap: wrap;
 }
 
 .pane {
   flex: 1;
-  padding: 24px;
+  padding: 20px 24px;
   display: flex;
   flex-direction: column;
+  /* Both panes are non-scrollable — content must fit */
+  height: calc(100vh - var(--nav-height));
+  overflow: hidden;
 }
 
 .left-pane {
@@ -43,32 +57,250 @@ h4 {
   background-color: #020617;
 }
 
+.right-pane {
+  background-color: var(--pane-bg);
+  overflow-y: auto;
+}
+
+.pane-header {
+  flex-shrink: 0;
+  margin-bottom: 12px;
+}
+
+.pane-header h2 {
+  margin-bottom: 8px;
+}
+
+/* ── Document Selector ──────────────────────────── */
+
+.navigation-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.select-group {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.select-group label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: #94a3b8;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.select-group select {
+  background-color: var(--surface);
+  color: var(--text-color);
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 0.9rem;
+  cursor: pointer;
+  transition: border-color 0.2s;
+}
+
+.select-group select:hover,
+.select-group select:focus {
+  border-color: var(--accent);
+  outline: none;
+}
+
+/* ── PDF Viewer ─────────────────────────────────── */
+
 .pdf-frame {
-  flex-grow: 1;
+  flex: 1;
   width: 100%;
+  min-height: 0;
   border: none;
   background: white;
   border-radius: 12px;
   box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
 }
 
-.right-pane {
-  background-color: var(--pane-bg);
-  overflow-y: auto;
+.pdf-placeholder {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--surface);
+  border-radius: 12px;
+  color: #94a3b8;
+}
+
+/* ── Bottom Navigation ──────────────────────────── */
+
+.bottom-nav {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: var(--nav-height);
+  background-color: #020617;
+  border-top: 1px solid var(--border-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 100;
 }
 
+.page-navigator {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+}
+
+.page-indicator {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+  min-width: 100px;
+  text-align: center;
+}
+
+.page-indicator strong {
+  font-size: 1.1rem;
+  color: #f8fafc;
+}
+
+.page-count {
+  font-size: 0.75rem;
+  color: #64748b;
+}
+
+.btn-nav {
+  background-color: var(--surface);
+  color: var(--text-color);
+  padding: 10px 20px;
+  font-weight: 600;
+  font-size: 0.9rem;
+  border-radius: 8px;
+  border: 1px solid var(--border-color);
+  transition: all 0.2s;
+}
+
+.btn-nav:hover:not(:disabled) {
+  background-color: var(--accent);
+  border-color: var(--accent);
+  transform: translateY(-1px);
+}
+
+.btn-nav:disabled {
+  opacity: 0.3;
+  cursor: not-allowed;
+}
+
+/* ── Annotator Header ───────────────────────────── */
+
+.annotator-container {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+}
+
+.annotator-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  flex-shrink: 0;
+  margin-bottom: 12px;
+}
+
+.annotator-header h2 {
+  margin: 0;
+}
+
+.annotator-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+/* ── Markdown Content ───────────────────────────── */
+
 .markdown-content {
   background-color: #2dd4bf10;
-  padding: 24px;
+  padding: 20px;
   border-radius: 12px;
-  margin-bottom: 24px;
   line-height: 1.6;
   border: 1px solid #2dd4bf30;
-  font-size: 1.05rem;
+  font-size: 0.95rem;
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.markdown-content-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 12px;
+  flex-shrink: 0;
+}
+
+.markdown-content-header h3 {
+  margin: 0;
+  font-size: 0.9rem;
+}
+
+.dataset-count {
+  background-color: #2dd4bf20;
+  color: #2dd4bf;
+  padding: 4px 10px;
+  border-radius: 20px;
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+
+/* ── Dataset Legend ─────────────────────────────── */
+
+.dataset-legend {
+  display: flex;
+  gap: 12px;
+  flex-wrap: wrap;
+  flex-shrink: 0;
+  margin-bottom: 8px;
+}
+
+.legend-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 0.75rem;
+  color: #94a3b8;
+  padding: 4px 10px;
+  border-radius: 6px;
+  background-color: #1e293b;
+  border: 1px solid;
+}
+
+.legend-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+/* ── Highlight marks ────────────────────────────── */
+
+.markdown-preview mark {
+  transition: all 0.15s ease;
+}
+
+.markdown-preview mark:hover {
+  filter: brightness(1.3);
+  transform: scale(1.02);
+  display: inline-block;
 }
 
 .markdown-preview {
-  margin-top: 16px;
   color: #f1f5f9;
 }
 
@@ -77,22 +309,22 @@ h4 {
 .markdown-preview h3,
 .markdown-preview h4 {
   color: #38bdf8;
-  margin-top: 1.5em;
-  margin-bottom: 0.5em;
+  margin-top: 1.2em;
+  margin-bottom: 0.4em;
 }
 
 .markdown-preview p {
-  margin-bottom: 1em;
+  margin-bottom: 0.8em;
 }
 
 .markdown-preview ul,
 .markdown-preview ol {
-  margin-bottom: 1em;
+  margin-bottom: 0.8em;
   padding-left: 20px;
 }
 
 .markdown-preview li {
-  margin-bottom: 0.25em;
+  margin-bottom: 0.2em;
 }
 
 .markdown-preview strong,
@@ -138,53 +370,701 @@ h4 {
   border: 0;
   height: 1px;
   background: var(--border-color);
-  margin: 20px 0;
+  margin: 16px 0;
+}
+
+.text-muted {
+  color: #94a3b8;
 }
 
+/* ── Buttons ────────────────────────────────────── */
+
 .btn {
-  background-color: var(--accent);
-  color: #ffffff;
   border: none;
-  padding: 12px 20px;
-  font-size: 16px;
+  padding: 10px 18px;
+  font-size: 14px;
   border-radius: 8px;
   cursor: pointer;
   font-weight: 600;
   transition: all 0.2s ease;
+}
+
+.btn-primary {
+  background-color: var(--accent);
+  color: #ffffff;
   box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
 }
 
-.btn:hover {
+.btn-primary:hover {
   background-color: var(--accent-hover);
   transform: translateY(-1px);
 }
 
-.btn:active {
+.btn-primary:active {
   transform: translateY(0);
 }
 
-.annotations-list {
-  margin-top: 32px;
+.btn-secondary {
+  background-color: var(--surface);
+  color: var(--text-color);
 }
 
-.annotations-list ul {
-  list-style: none;
-  padding: 0;
+.btn-secondary:hover {
+  background-color: #475569;
+}
+
+/* ── Annotations Side Panel ─────────────────────── */
+
+.panel-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.3);
+  z-index: 200;
+}
+
+.annotation-panel {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: var(--nav-height);
+  width: 380px;
+  background-color: var(--pane-bg);
+  border-left: 1px solid var(--border-color);
+  z-index: 300;
+  transform: translateX(100%);
+  transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  display: flex;
+  flex-direction: column;
+  box-shadow: -8px 0 30px rgb(0 0 0 / 0.3);
+}
+
+.annotation-panel.open {
+  transform: translateX(0);
+}
+
+.panel-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--border-color);
+  flex-shrink: 0;
+}
+
+.panel-header h3 {
   margin: 0;
+  flex: 1;
 }
 
-.annotations-list li {
-  background-color: #33415550;
+.panel-count {
+  background-color: var(--accent);
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: 700;
+  padding: 2px 8px;
+  border-radius: 10px;
+  min-width: 24px;
+  text-align: center;
+}
+
+.panel-close {
+  background: none;
+  border: none;
+  color: #94a3b8;
+  font-size: 22px;
+  cursor: pointer;
+  padding: 4px 8px;
+  border-radius: 6px;
+  transition: all 0.15s;
+}
+
+.panel-close:hover {
+  background-color: var(--surface);
+  color: var(--text-color);
+}
+
+.panel-body {
+  flex: 1;
+  overflow-y: auto;
   padding: 16px;
+}
+
+.panel-empty {
+  text-align: center;
+  padding: 40px 20px;
+  color: #64748b;
+}
+
+.panel-empty p:first-child {
+  font-size: 1rem;
+}
+
+/* ── Panel Cards ────────────────────────────────── */
+
+.panel-annotation-card {
+  background-color: #0f172a;
+  border: 1px solid var(--border-color);
+  border-radius: 10px;
+  padding: 14px;
   margin-bottom: 12px;
-  border-radius: 8px;
-  border-left: 4px solid #2dd4bf;
+  transition: border-color 0.2s;
+}
+
+.panel-annotation-card:hover {
+  border-color: var(--accent);
+}
+
+.panel-card-top {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 8px;
+}
+
+.panel-card-author {
+  font-size: 0.75rem;
+  color: #64748b;
+  font-style: italic;
+}
+
+.panel-card-text {
+  margin: 0 0 6px;
+  font-size: 0.9rem;
+  color: #e2e8f0;
+  line-height: 1.4;
+}
+
+.panel-card-position {
+  display: inline-block;
+  font-size: 0.7rem;
+  color: #475569;
+  font-family: monospace;
+  margin-bottom: 8px;
+}
+
+.panel-card-actions {
+  display: flex;
+  gap: 8px;
+}
+
+.btn-panel {
+  background: none;
+  border: 1px solid var(--border-color);
+  color: #94a3b8;
+  font-size: 0.75rem;
+  padding: 4px 10px;
+  border-radius: 5px;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.btn-panel:hover {
+  border-color: #94a3b8;
+  color: var(--text-color);
+}
+
+.btn-panel.save {
+  border-color: #10b981;
+  color: #10b981;
+}
+
+.btn-panel.save:hover {
+  background-color: #10b98120;
+}
+
+.btn-panel.delete.confirming {
+  border-color: var(--error);
+  color: var(--error);
+  animation: pulse 0.6s ease infinite alternate;
+}
+
+@keyframes pulse {
+  from {
+    opacity: 0.7;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+.panel-card-time {
+  font-size: 0.7rem;
+  color: #475569;
+  margin-top: 6px;
+}
+
+.form-select-small {
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 1px solid var(--accent);
+  border-radius: 5px;
+  padding: 3px 8px;
+  font-size: 0.75rem;
+  cursor: pointer;
+}
+
+.annotation-tag-badge {
+  font-size: 0.7rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 3px 8px;
+  border-radius: 4px;
+}
+
+.annotation-tag-badge.clickable {
+  cursor: pointer;
+  transition: opacity 0.15s;
+}
+
+.annotation-tag-badge.clickable:hover {
+  opacity: 0.8;
+}
+
+.panel-card-source {
+  font-size: 0.7rem;
+  color: #64748b;
+}
+
+.inline-edit {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+/* Judge info row */
+.panel-card-judge {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 0.7rem;
+  margin-top: 2px;
+}
+
+.judge-verdict {
+  font-weight: 600;
+}
+
+.judge-verdict.correct {
+  color: #10b981;
+}
+
+.judge-verdict.wrong {
+  color: #ef4444;
+}
+
+.judge-tag {
+  color: #64748b;
+  font-style: italic;
+}
+
+/* Validated card accents */
+.panel-annotation-card.validated-correct {
+  border-left: 3px solid #10b981;
+}
+
+.panel-annotation-card.validated-wrong {
+  border-left: 3px solid #ef4444;
+}
+
+/* Validation status */
+.validation-status {
+  font-size: 0.75rem;
+  margin-top: 6px;
+  padding: 6px 8px;
+  border-radius: 6px;
+}
+
+.validation-status.correct {
+  background-color: #10b98115;
+  color: #10b981;
+}
+
+.validation-status.wrong {
+  background-color: #ef444415;
+  color: #ef4444;
+}
+
+.validation-by {
+  color: #64748b;
+  font-style: italic;
+}
+
+.validation-notes {
+  margin: 4px 0 0;
+  color: var(--text-muted);
+  font-style: italic;
+}
+
+/* Validation form */
+.validation-form {
+  margin-top: 8px;
+}
+
+.validation-notes-input {
+  width: 100%;
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 1px solid var(--border-color);
+  border-radius: 6px;
+  padding: 6px 8px;
+  font-size: 0.75rem;
+  resize: vertical;
+  margin-bottom: 6px;
+  font-family: inherit;
+}
+
+.validation-notes-input:focus {
+  outline: none;
+  border-color: var(--accent);
+}
+
+.validation-buttons {
+  display: flex;
+  gap: 4px;
+}
+
+.btn-panel.correct {
+  border-color: #10b981;
+  color: #10b981;
+}
+
+.btn-panel.correct:hover {
+  background-color: #10b98120;
+}
+
+.btn-panel.wrong {
+  border-color: #ef4444;
+  color: #ef4444;
+}
+
+.btn-panel.wrong:hover {
+  background-color: #ef444420;
+}
+
+.btn-panel.validate {
+  border-color: #6366f1;
+  color: #6366f1;
+}
+
+.btn-panel.validate:hover {
+  background-color: #6366f120;
+}
+
+/* ── Floating Panel Chevron ────────────────────── */
+
+.panel-chevron {
+  position: fixed;
+  right: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  z-index: 150;
+  background-color: var(--surface);
+  border: 1px solid var(--border-color);
+  border-right: none;
+  color: var(--text-color);
+  font-size: 1.4rem;
+  font-weight: 700;
+  padding: 12px 6px;
+  border-radius: 8px 0 0 8px;
+  cursor: pointer;
+  transition: all 0.2s;
+  line-height: 1;
+}
+
+.panel-chevron:hover {
+  background-color: var(--accent);
+  border-color: var(--accent);
+}
+
+.chevron-badge {
+  position: absolute;
+  top: -6px;
+  left: -6px;
+  background-color: var(--accent);
+  color: #fff;
+  font-size: 0.6rem;
+  font-weight: 700;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+
+
+/* ── Modal ──────────────────────────────────────── */
+
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background-color: rgba(0, 0, 0, 0.6);
   backdrop-filter: blur(4px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+  animation: fadeIn 0.15s ease;
+}
+
+.modal-content {
+  background-color: var(--pane-bg);
+  border: 1px solid var(--border-color);
+  border-radius: 16px;
+  width: 90%;
+  max-width: 520px;
+  box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.5);
+  animation: slideUp 0.2s ease;
 }
 
-.annotations-list small {
+.modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 20px 24px 0;
+}
+
+.modal-header h3 {
+  margin: 0;
+}
+
+.modal-close {
+  background: none;
+  border: none;
   color: #94a3b8;
+  font-size: 24px;
+  cursor: pointer;
+  padding: 4px 8px;
+  border-radius: 6px;
+  transition: all 0.15s;
+}
+
+.modal-close:hover {
+  background-color: var(--surface);
+  color: var(--text-color);
+}
+
+.modal-body {
+  padding: 20px 24px;
+}
+
+.modal-footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: 12px;
+  padding: 0 24px 20px;
+}
+
+/* ── Form Elements ──────────────────────────────── */
+
+.form-group {
+  margin-bottom: 16px;
+}
+
+.form-group label {
   display: block;
-  margin-top: 8px;
   font-size: 0.8rem;
+  font-weight: 600;
+  color: #94a3b8;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: 6px;
+}
+
+.selected-text-preview {
+  background-color: #2dd4bf15;
+  border: 1px solid #2dd4bf30;
+  padding: 12px;
+  border-radius: 8px;
+  font-style: italic;
+  color: #2dd4bf;
+  max-height: 100px;
+  overflow-y: auto;
+  font-size: 0.95rem;
+}
+
+.form-select {
+  width: 100%;
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
+  padding: 10px 12px;
+  font-size: 0.95rem;
+  font-family: inherit;
+  cursor: pointer;
+  transition: border-color 0.2s;
+}
+
+.form-select:focus {
+  border-color: var(--accent);
+  outline: none;
+}
+
+.form-help {
+  margin-top: 6px;
+  margin-bottom: 0;
+  font-size: 0.8rem;
+  color: #64748b;
+  font-style: italic;
+}
+
+.form-input,
+.form-textarea {
+  width: 100%;
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
+  padding: 10px 12px;
+  font-size: 0.95rem;
+  font-family: inherit;
+  transition: border-color 0.2s;
+}
+
+.form-input:focus,
+.form-textarea:focus {
+  border-color: var(--accent);
+  outline: none;
+}
+
+.form-textarea {
+  resize: vertical;
+  min-height: 80px;
+}
+
+/* ── Toast Notifications ────────────────────────── */
+
+.toast {
+  position: fixed;
+  bottom: calc(var(--nav-height) + 16px);
+  right: 24px;
+  padding: 14px 24px;
+  border-radius: 10px;
+  font-weight: 600;
+  font-size: 0.9rem;
+  z-index: 2000;
+  animation: slideInRight 0.3s ease, fadeOut 0.3s ease 2.7s forwards;
+  box-shadow: 0 10px 25px -5px rgb(0 0 0 / 0.3);
+}
+
+.toast-success {
+  background-color: var(--success);
+  color: #fff;
+}
+
+.toast-error {
+  background-color: var(--error);
+  color: #fff;
+}
+
+/* ── Loading ────────────────────────────────────── */
+
+.loading-container {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100vh;
+  width: 100%;
+  gap: 16px;
+  color: #94a3b8;
+}
+
+.loading-spinner-container {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 40px;
+  gap: 12px;
+  color: #94a3b8;
+}
+
+.loading-spinner {
+  width: 32px;
+  height: 32px;
+  border: 3px solid var(--border-color);
+  border-top-color: var(--accent);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+/* ── Animations ─────────────────────────────────── */
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes slideUp {
+  from {
+    transform: translateY(20px);
+    opacity: 0;
+  }
+
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}
+
+@keyframes slideInRight {
+  from {
+    transform: translateX(100%);
+    opacity: 0;
+  }
+
+  to {
+    transform: translateX(0);
+    opacity: 1;
+  }
+}
+
+@keyframes fadeOut {
+  from {
+    opacity: 1;
+  }
+
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes shake {
+
+  0%,
+  100% {
+    transform: translateX(0);
+  }
+
+  25% {
+    transform: translateX(-5px);
+  }
+
+  50% {
+    transform: translateX(5px);
+  }
+
+  75% {
+    transform: translateX(-5px);
+  }
+}
+
+.shake {
+  animation: shake 0.4s ease;
 }

app/page.js

@@ -1,21 +1,49 @@
 "use client";
 
-import { useState, useEffect } from 'react';
-import ReactMarkdown from 'react-markdown';
-import remarkGfm from 'remark-gfm';
+import { useState, useEffect, useCallback } from 'react';
+import DocumentSelector from './components/DocumentSelector';
+import PdfViewer from './components/PdfViewer';
+import MarkdownAnnotator from './components/MarkdownAnnotator';
+import AnnotationPanel from './components/AnnotationPanel';
+import AnnotationModal from './components/AnnotationModal';
+import PageNavigator from './components/PageNavigator';
 
 export default function Home() {
     const [documents, setDocuments] = useState([]);
     const [selectedDocIndex, setSelectedDocIndex] = useState(null);
-    const [selectedPage, setSelectedPage] = useState(null);
-
     const [currentDoc, setCurrentDoc] = useState(null);
+
+    // Page-by-page navigation: track the index into annotatable_pages array
+    const [pageIdx, setPageIdx] = useState(0);
     const [currentPageData, setCurrentPageData] = useState(null);
     const [loading, setLoading] = useState(true);
+    const [loadingPage, setLoadingPage] = useState(false);
+
+    // Annotations
+    const [annotations, setAnnotations] = useState([]);
+    const [annotatorName, setAnnotatorName] = useState('');
+
+    // Modal state
+    const [modalOpen, setModalOpen] = useState(false);
+    const [selectedText, setSelectedText] = useState('');
+    const [selectionOffset, setSelectionOffset] = useState(0);
+
+    // Side panel state
+    const [panelOpen, setPanelOpen] = useState(false);
 
-    // Array of local session annotations just for immediate UI feedback
-    const [sessionAnnotations, setSessionAnnotations] = useState([]);
+    // Toast state
+    const [toast, setToast] = useState(null);
 
+    const showToast = useCallback((message, type = 'success') => {
+        setToast({ message, type });
+        setTimeout(() => setToast(null), 3000);
+    }, []);
+
+    // Derived: current page number from the annotatable_pages array
+    const annotatablePages = currentDoc?.annotatable_pages ?? [];
+    const currentPageNumber = annotatablePages[pageIdx] ?? null;
+
+    // Load documents on mount
     useEffect(() => {
         fetch('/api/documents')
             .then(res => res.json())
@@ -23,7 +51,7 @@ export default function Home() {
                 setDocuments(data);
                 if (data.length > 0) {
                     setSelectedDocIndex(data[0].index);
-                    setSelectedPage(data[0].annotatable_pages[0]);
+                    setPageIdx(0);
                 }
                 setLoading(false);
             })
@@ -33,139 +61,318 @@ export default function Home() {
             });
     }, []);
 
+    // Update currentDoc when selection changes
     useEffect(() => {
-        if (selectedDocIndex !== null && selectedPage !== null) {
+        if (selectedDocIndex !== null) {
             const doc = documents.find(d => d.index === selectedDocIndex);
             setCurrentDoc(doc);
+        }
+    }, [selectedDocIndex, documents]);
 
-            fetch(`/api/document?index=${selectedDocIndex}&page=${selectedPage}`)
+    // Fetch page data (reusable — called on page change and after saving)
+    const refreshPageData = useCallback(() => {
+        if (selectedDocIndex !== null && currentPageNumber !== null) {
+            setLoadingPage(true);
+            fetch(`/api/document?index=${selectedDocIndex}&page=${currentPageNumber}`)
                 .then(res => res.json())
                 .then(data => {
                     setCurrentPageData(data);
+                    setLoadingPage(false);
                 })
-                .catch(err => console.error("Failed to load page data", err));
-        }
-    }, [selectedDocIndex, selectedPage, documents]);
-
-    const handleAnnotate = async () => {
-        const selection = window.getSelection();
-        if (selection && selection.toString().trim() !== "") {
-            const selectedText = selection.toString().trim();
-            const note = window.prompt("Enter annotation note for: " + selectedText);
-
-            const payload = {
-                document_index: selectedDocIndex,
-                page_number: selectedPage,
-                selected_text: selectedText,
-                annotation_note: note || "No note provided",
-                timestamp: new Date().toISOString()
-            };
-
-            try {
-                const res = await fetch('/api/annotate', {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify(payload)
+                .catch(err => {
+                    console.error("Failed to load page data", err);
+                    setLoadingPage(false);
                 });
+        }
+    }, [selectedDocIndex, currentPageNumber]);
+
+    // Load page data when page changes
+    useEffect(() => {
+        refreshPageData();
+    }, [refreshPageData]);
+
+    // Load persisted annotations on mount
+    useEffect(() => {
+        fetch('/api/annotations')
+            .then(res => res.json())
+            .then(data => {
+                if (Array.isArray(data)) setAnnotations(data);
+            })
+            .catch(err => console.error("Failed to load annotations", err));
+    }, [])
 
-                if (res.ok) {
-                    setSessionAnnotations(prev => [...prev, payload]);
-                    window.alert("Annotation saved locally to human_annotations.json!");
-                } else {
-                    window.alert("Failed to save annotation.");
+    // Auto-fetch HF username in production
+    useEffect(() => {
+        fetch('/api/whoami')
+            .then(res => res.ok ? res.json() : null)
+            .then(data => {
+                if (data?.username) {
+                    setAnnotatorName(data.username);
+                    localStorage.setItem('annotator_name', data.username);
                 }
-            } catch (err) {
-                console.error(err);
-                window.alert("Network error saving annotation.");
+            })
+            .catch(() => { }); // Silently ignore — falls back to localStorage name
+    }, []);
+
+    // Load annotator name from localStorage
+    useEffect(() => {
+        const saved = localStorage.getItem('annotator_name');
+        if (saved) setAnnotatorName(saved);
+    }, []);
+
+    const handleAnnotatorChange = (name) => {
+        setAnnotatorName(name);
+        localStorage.setItem('annotator_name', name);
+    };
+
+    const handleDocChange = (docIdx) => {
+        setSelectedDocIndex(docIdx);
+        setPageIdx(0);
+    };
+
+    const handlePrevPage = () => {
+        setPageIdx(prev => Math.max(0, prev - 1));
+    };
+
+    const handleNextPage = () => {
+        setPageIdx(prev => Math.min(annotatablePages.length - 1, prev + 1));
+    };
+
+    const handleAnnotate = (text, domOffset) => {
+        setSelectedText(text);
+        setSelectionOffset(domOffset || 0);
+        setModalOpen(true);
+    };
+
+    const handleAnnotationSubmit = async ({ dataset_tag }) => {
+        // Find ALL occurrences of the selected text in input_text
+        const inputText = currentPageData?.input_text || "";
+        const occurrences = [];
+        let searchFrom = 0;
+        while (searchFrom < inputText.length) {
+            const idx = inputText.indexOf(selectedText, searchFrom);
+            if (idx === -1) break;
+            occurrences.push(idx);
+            searchFrom = idx + 1;
+        }
+
+        let startIdx = null;
+        if (occurrences.length === 1) {
+            startIdx = occurrences[0];
+        } else if (occurrences.length > 1) {
+            const container = document.querySelector('.markdown-preview');
+            const visibleLen = container?.textContent?.length || inputText.length;
+            const ratio = inputText.length / visibleLen;
+            const estimatedSourcePos = selectionOffset * ratio;
+            startIdx = occurrences.reduce((best, idx) =>
+                Math.abs(idx - estimatedSourcePos) < Math.abs(best - estimatedSourcePos) ? idx : best
+            );
+        }
+
+        const endIdx = startIdx !== null ? startIdx + selectedText.length : null;
+
+        const payload = {
+            dataset_name: {
+                text: selectedText,
+                confidence: 1.0,
+                start: startIdx >= 0 ? startIdx : null,
+                end: endIdx,
+            },
+            dataset_tag: dataset_tag,
+            annotator: annotatorName || "user",
+            document_index: selectedDocIndex,
+            page_number: currentPageNumber,
+            timestamp: new Date().toISOString(),
+            description: null,
+            data_type: null,
+            acronym: null,
+            author: null,
+            producer: null,
+            geography: null,
+            publication_year: null,
+            reference_year: null,
+            reference_population: null,
+            is_used: null,
+            usage_context: null,
+        };
+
+        try {
+            const res = await fetch('/api/annotate', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload)
+            });
+
+            if (res.ok) {
+                setAnnotations(prev => [...prev, payload]);
+                setModalOpen(false);
+                showToast("Annotation saved!");
+                setPanelOpen(true);
+                refreshPageData(); // Refresh so new annotation appears highlighted
+            } else {
+                showToast("Failed to save annotation.", "error");
+            }
+        } catch (err) {
+            console.error(err);
+            showToast("Network error saving annotation.", "error");
+        }
+    };
+
+    // Delete dataset entry by index
+    const handleDeleteAnnotation = async (ds, idx) => {
+        try {
+            const res = await fetch(
+                `/api/validate?doc=${selectedDocIndex}&page=${currentPageNumber}&idx=${idx}`,
+                { method: 'DELETE' }
+            );
+            if (res.ok) {
+                refreshPageData();
+                showToast("Data mention deleted.");
+            } else {
+                showToast("Failed to delete.", "error");
+            }
+        } catch (err) {
+            console.error(err);
+            showToast("Network error deleting.", "error");
+        }
+    };
+
+    // Update annotation (e.g. change dataset_tag)
+    const handleUpdateAnnotation = async (annotation, idx, updates) => {
+        try {
+            const res = await fetch('/api/annotate', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    timestamp: annotation.timestamp,
+                    document_index: annotation.document_index ?? selectedDocIndex,
+                    page_number: annotation.page_number ?? currentPageNumber,
+                    updates,
+                })
+            });
+            if (res.ok) {
+                setAnnotations(prev => prev.map(a =>
+                    a.timestamp === annotation.timestamp ? { ...a, ...updates } : a
+                ));
+                showToast("Annotation updated.");
+            } else {
+                showToast("Failed to update annotation.", "error");
             }
-        } else {
-            window.alert("Please select some text to annotate.");
+        } catch (err) {
+            console.error(err);
+            showToast("Network error updating annotation.", "error");
         }
     };
 
-    if (loading) return <div className="p-4">Loading Data...</div>;
+    // All datasets on the current page (model + human)
+    const currentPageDatasets = currentPageData?.datasets || [];
+
+    // Validate a dataset entry (approve/reject with notes)
+    const handleValidateDataset = async (datasetIdx, updates) => {
+        try {
+            const res = await fetch('/api/validate', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    document_index: selectedDocIndex,
+                    page_number: currentPageNumber,
+                    dataset_index: datasetIdx,
+                    updates,
+                })
+            });
+            if (res.ok) {
+                refreshPageData();
+                showToast("Validation saved!");
+            } else {
+                showToast("Failed to save validation.", "error");
+            }
+        } catch (err) {
+            console.error(err);
+            showToast("Network error saving validation.", "error");
+        }
+    };
+
+    if (loading) {
+        return (
+            <div className="loading-container">
+                <div className="loading-spinner" />
+                <p>Loading documents...</p>
+            </div>
+        );
+    }
 
     return (
         <div className="container">
             <div className="pane left-pane">
-                <h2>PDF Viewer & Navigation</h2>
-
-                <div className="navigation-controls">
-                    <div>
-                        <label>Document: </label>
-                        <select
-                            value={selectedDocIndex || ''}
-                            onChange={(e) => {
-                                const docIdx = parseInt(e.target.value);
-                                setSelectedDocIndex(docIdx);
-                                const doc = documents.find(d => d.index === docIdx);
-                                if (doc && doc.annotatable_pages.length > 0) {
-                                    setSelectedPage(doc.annotatable_pages[0]);
-                                }
-                            }}
-                        >
-                            {documents.map(doc => (
-                                <option key={doc.index} value={doc.index}>
-                                    Document {doc.index} ({doc.annotatable_pages.length} pages available)
-                                </option>
-                            ))}
-                        </select>
-                    </div>
-
-                    <div style={{ marginTop: '12px' }}>
-                        <label>Annotatable Page: </label>
-                        <select
-                            value={selectedPage || ''}
-                            onChange={(e) => setSelectedPage(parseInt(e.target.value))}
-                        >
-                            {currentDoc?.annotatable_pages.map(p => (
-                                <option key={p} value={p}>Page {p}</option>
-                            ))}
-                        </select>
-                    </div>
+                <div className="pane-header">
+                    <h2>PDF Viewer</h2>
+                    <DocumentSelector
+                        documents={documents}
+                        selectedDocIndex={selectedDocIndex}
+                        onDocChange={handleDocChange}
+                    />
                 </div>
+                <PdfViewer
+                    pdfUrl={currentDoc?.pdf_url}
+                    pageNumber={currentPageNumber}
+                />
+            </div>
 
-                {currentDoc && currentDoc.pdf_url && (
-                    <iframe
-                        src={`https://docs.google.com/viewer?url=${encodeURIComponent(currentDoc.pdf_url)}&embedded=true`}
-                        className="pdf-frame"
-                        title={`Document ${currentDoc.index} PDF`}
-                        style={{ marginTop: '20px' }}
-                    />
+            <div className="pane right-pane">
+                <MarkdownAnnotator
+                    selectedDocIndex={selectedDocIndex}
+                    selectedPage={currentPageNumber}
+                    currentPageData={currentPageData}
+                    loadingPage={loadingPage}
+                    onAnnotate={handleAnnotate}
+                />
+            </div>
+
+            {/* Floating chevron to open annotations panel */}
+            <button
+                className="panel-chevron"
+                onClick={() => setPanelOpen(prev => !prev)}
+                title="Toggle annotations"
+            >
+                {panelOpen ? '›' : '‹'}
+                {!panelOpen && currentPageDatasets.length > 0 && (
+                    <span className="chevron-badge">{currentPageDatasets.length}</span>
                 )}
+            </button>
+            <AnnotationPanel
+                isOpen={panelOpen}
+                onClose={() => setPanelOpen(false)}
+                datasets={currentPageDatasets}
+                annotatorName={annotatorName}
+                onValidate={handleValidateDataset}
+                onDelete={handleDeleteAnnotation}
+            />
+
+            {/* Shared page navigator at the bottom */}
+            <div className="bottom-nav">
+                <PageNavigator
+                    currentIndex={pageIdx}
+                    totalPages={annotatablePages.length}
+                    currentPageNumber={currentPageNumber}
+                    onPrevious={handlePrevPage}
+                    onNext={handleNextPage}
+                />
             </div>
 
-            <div className="pane right-pane">
-                <h2>Markdown Annotation Mvp</h2>
-                <button onClick={handleAnnotate} className="btn" style={{ marginBottom: '20px' }}>
-                    Annotate Selection
-                </button>
-
-                <div className="markdown-content">
-                    <h3>Extracted Text (Doc {selectedDocIndex}, Page {selectedPage})</h3>
-                    {currentPageData ? (
-                        <div className="markdown-preview">
-                            <ReactMarkdown remarkPlugins={[remarkGfm]}>{currentPageData.input_text || "No text available."}</ReactMarkdown>
-                        </div>
-                    ) : (
-                        <p>Loading text...</p>
-                    )}
-                </div>
+            <AnnotationModal
+                isOpen={modalOpen}
+                selectedText={selectedText}
+                annotatorName={annotatorName}
+                onAnnotatorChange={handleAnnotatorChange}
+                onSubmit={handleAnnotationSubmit}
+                onClose={() => setModalOpen(false)}
+            />
 
-                <div className="annotations-list">
-                    {sessionAnnotations.length > 0 && <h3>Current Session Annotations</h3>}
-                    <ul>
-                        {sessionAnnotations.map((ann, idx) => (
-                            <li key={idx}>
-                                <strong>Doc {ann.document_index} / Pg {ann.page_number}</strong><br />
-                                <strong>Selected:</strong> "{ann.selected_text}" <br />
-                                <strong>Note:</strong> {ann.annotation_note} <br />
-                                <small>{new Date(ann.timestamp).toLocaleString()}</small>
-                            </li>
-                        ))}
-                    </ul>
+            {toast && (
+                <div className={`toast toast-${toast.type}`}>
+                    {toast.message}
                 </div>
-            </div>
+            )}
         </div>
     );
 }

utils/config.js

@@ -0,0 +1,4 @@
+// Centralized configuration for the annotation app
+export const HF_DATASET_ID = process.env.HF_DATASET_REPO || 'ai4data/annotation_data';
+export const HF_DATASET_BASE_URL = `https://huggingface.co/datasets/${HF_DATASET_ID}`;
+export const MAX_DOCS_TO_SCAN = parseInt(process.env.MAX_DOCS_TO_SCAN || '5', 10);

utils/storage.js

@@ -1,132 +1,258 @@
 import fs from 'fs';
 import path from 'path';
+import { commit } from '@huggingface/hub';
+import { HF_DATASET_ID, HF_DATASET_BASE_URL } from './config.js';
 
-// Get the root path of the project (handles Docker container `/app` or local)
 const getRootPath = () => process.cwd();
 
-// Determines if we are running in a Hugging Face Space
-// which we indicate by the presence of HF_TOKEN and not being explicitly in dev mode
 const isHFSpace = () => {
     return process.env.HF_TOKEN && process.env.NODE_ENV !== 'development';
 };
 
 /**
- * Saves the annotation payload to either the local system or HF Datasets
- * @param {Object} annotation { document_index, page_number, selected_text, annotation_note, timestamp }
+ * Returns the local file path for a document's raw JSON
+ */
+function getDocFilePath(docIndex) {
+    return path.join(
+        getRootPath(),
+        'annotation_data', 'wbg_extractions',
+        `doc_${docIndex}`, 'raw', `doc_${docIndex}_direct_judged.jsonl`
+    );
+}
+
+/**
+ * Returns the HF repo path for a document's raw JSON
+ */
+function getDocRepoPath(docIndex) {
+    return `annotation_data/wbg_extractions/doc_${docIndex}/raw/doc_${docIndex}_direct_judged.jsonl`;
+}
+
+/**
+ * Reads the full document JSON (all pages) from local file
+ */
+function readDocLocal(docIndex) {
+    const filePath = getDocFilePath(docIndex);
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+}
+
+/**
+ * Writes the full document JSON (all pages) to local file
+ */
+function writeDocLocal(docIndex, pagesData) {
+    const filePath = getDocFilePath(docIndex);
+    fs.writeFileSync(filePath, JSON.stringify(pagesData, null, 2));
+    console.log(`Saved doc_${docIndex}_direct_judged.jsonl locally`);
+}
+
+/**
+ * Finds the page index in the pages array by page_number
+ * Uses document.pages[0] to match, consistent with the document/route.js API
+ */
+function findPageIndex(pagesData, pageNumber) {
+    return pagesData.findIndex(p => p.document?.pages?.[0] === pageNumber);
+}
+
+/**
+ * Fetches the document JSON from HuggingFace
+ */
+async function fetchDocFromHF(docIndex) {
+    const token = process.env.HF_TOKEN;
+    const url = `${HF_DATASET_BASE_URL}/raw/main/${getDocRepoPath(docIndex)}`;
+    const res = await fetch(url, {
+        headers: { 'Authorization': `Bearer ${token}` }
+    });
+    if (!res.ok) throw new Error(`Failed to fetch doc_${docIndex} from HF: ${res.status}`);
+    return res.json();
+}
+
+/**
+ * Commits the updated document JSON back to HuggingFace
+ */
+async function commitDocToHF(docIndex, pagesData, commitMessage) {
+    const token = process.env.HF_TOKEN;
+    if (!token) throw new Error("Missing HF_TOKEN");
+
+    const repoPath = getDocRepoPath(docIndex);
+    const content = JSON.stringify(pagesData, null, 2);
+
+    await commit({
+        repo: { type: 'dataset', name: HF_DATASET_ID },
+        credentials: { accessToken: token },
+        title: commitMessage,
+        operations: [{
+            operation: 'addOrUpdate',
+            path: repoPath,
+            content: new Blob([content], { type: 'application/json' }),
+        }],
+    });
+    console.log(`Committed ${repoPath} to HF dataset ${HF_DATASET_ID}`);
+}
+
+// ─── Public API ────────────────────────────────────
+
+/**
+ * Saves an annotation by appending it to the page's datasets array
+ * in the per-document raw JSON file.
+ *
+ * @param {Object} annotation - Must include document_index, page_number, and dataset fields
  */
 export async function saveAnnotation(annotation) {
+    const { document_index: docIndex, page_number: pageNumber } = annotation;
+
+    // Build the dataset entry (strip routing fields — they stay at page/doc level)
+    const datasetEntry = {
+        dataset_name: annotation.dataset_name,
+        dataset_tag: annotation.dataset_tag,
+        annotator: annotation.annotator,
+        timestamp: annotation.timestamp,
+        description: annotation.description || null,
+        data_type: annotation.data_type || null,
+        acronym: annotation.acronym || null,
+        author: annotation.author || null,
+        producer: annotation.producer || null,
+        geography: annotation.geography || null,
+        publication_year: annotation.publication_year || null,
+        reference_year: annotation.reference_year || null,
+        reference_population: annotation.reference_population || null,
+        is_used: annotation.is_used || null,
+        usage_context: annotation.usage_context || null,
+    };
+
     if (isHFSpace()) {
-        await saveToHuggingFace(annotation);
+        // Production: fetch from HF, modify, commit back
+        const pagesData = await fetchDocFromHF(docIndex);
+        const pageIdx = findPageIndex(pagesData, pageNumber);
+        if (pageIdx === -1) throw new Error(`Page ${pageNumber} not found in doc_${docIndex}`);
+
+        pagesData[pageIdx].datasets.push(datasetEntry);
+        await commitDocToHF(docIndex, pagesData,
+            `Add human annotation to doc_${docIndex} page ${pageNumber}`);
     } else {
-        await saveToLocal(annotation);
+        // Local: read, modify, write
+        const pagesData = readDocLocal(docIndex);
+        if (!pagesData) throw new Error(`doc_${docIndex}_raw.json not found locally`);
+
+        const pageIdx = findPageIndex(pagesData, pageNumber);
+        if (pageIdx === -1) throw new Error(`Page ${pageNumber} not found in doc_${docIndex}`);
+
+        pagesData[pageIdx].datasets.push(datasetEntry);
+        writeDocLocal(docIndex, pagesData);
     }
 }
 
 /**
- * Saves annotation locally by creating or appending to human_annotations.json
+ * Deletes an annotation from the page's datasets array by timestamp
  */
-async function saveToLocal(annotation) {
-    const dataDir = path.join(getRootPath(), 'annotation_data');
-    const filePath = path.join(dataDir, 'human_annotations.json');
+export async function deleteAnnotation(timestamp, docIndex, pageNumber) {
+    if (isHFSpace()) {
+        const pagesData = await fetchDocFromHF(docIndex);
+        const pageIdx = findPageIndex(pagesData, pageNumber);
+        if (pageIdx === -1) return false;
 
-    // Ensure directory exists
-    if (!fs.existsSync(dataDir)) {
-        fs.mkdirSync(dataDir, { recursive: true });
-    }
+        const before = pagesData[pageIdx].datasets.length;
+        pagesData[pageIdx].datasets = pagesData[pageIdx].datasets.filter(
+            ds => ds.timestamp !== timestamp
+        );
+        if (pagesData[pageIdx].datasets.length === before) return false;
 
-    let annotations = [];
-    if (fs.existsSync(filePath)) {
-        try {
-            const raw = fs.readFileSync(filePath, 'utf-8');
-            annotations = JSON.parse(raw);
-        } catch (e) {
-            console.error("Error parsing existing annotations, creating new array.", e);
-        }
-    }
+        await commitDocToHF(docIndex, pagesData,
+            `Delete annotation from doc_${docIndex} page ${pageNumber}`);
+        return true;
+    } else {
+        const pagesData = readDocLocal(docIndex);
+        if (!pagesData) return false;
 
-    annotations.push(annotation);
-    fs.writeFileSync(filePath, JSON.stringify(annotations, null, 2));
-    console.log(`Saved annotation locally to ${filePath}`);
+        const pageIdx = findPageIndex(pagesData, pageNumber);
+        if (pageIdx === -1) return false;
+
+        const before = pagesData[pageIdx].datasets.length;
+        pagesData[pageIdx].datasets = pagesData[pageIdx].datasets.filter(
+            ds => ds.timestamp !== timestamp
+        );
+        if (pagesData[pageIdx].datasets.length === before) return false;
+
+        writeDocLocal(docIndex, pagesData);
+        return true;
+    }
 }
 
 /**
- * Commits the new annotation to a JSON Lines (JSONL) dataset on Hugging Face
+ * Updates an annotation in the page's datasets array by timestamp
  */
-async function saveToHuggingFace(annotation) {
-    const repoId = process.env.HF_DATASET_REPO || 'rafmacalaba/wbg_annotation_data';
-    const token = process.env.HF_TOKEN;
+export async function updateAnnotation(timestamp, docIndex, pageNumber, updates) {
+    if (isHFSpace()) {
+        const pagesData = await fetchDocFromHF(docIndex);
+        const pageIdx = findPageIndex(pagesData, pageNumber);
+        if (pageIdx === -1) return null;
 
-    if (!token) throw new Error("Missing HF_TOKEN for dataset commit.");
-
-    try {
-        const filename = `annotations/${annotation.document_index}_p${annotation.page_number}_${Date.now()}.json`;
-        const content = Buffer.from(JSON.stringify(annotation, null, 2)).toString('base64');
-
-        const payload = {
-            commit_message: `Add annotation for doc ${annotation.document_index} page ${annotation.page_number}`,
-            operations: [
-                {
-                    key: "path",
-                    value: filename
-                },
-                {
-                    key: "content",
-                    value: content
-                }
-            ]
+        const dsIdx = pagesData[pageIdx].datasets.findIndex(ds => ds.timestamp === timestamp);
+        if (dsIdx === -1) return null;
+
+        pagesData[pageIdx].datasets[dsIdx] = {
+            ...pagesData[pageIdx].datasets[dsIdx],
+            ...updates
         };
+        await commitDocToHF(docIndex, pagesData,
+            `Update annotation in doc_${docIndex} page ${pageNumber}`);
+        return pagesData[pageIdx].datasets[dsIdx];
+    } else {
+        const pagesData = readDocLocal(docIndex);
+        if (!pagesData) return null;
 
-        // Use the Hugging Face REST API directly
-        const res = await fetch(`https://huggingface.co/api/datasets/${repoId}/commit/main`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${token}`,
-                'Content-Type': 'application/json'
-            },
-            body: JSON.stringify({
-                summary: payload.commit_message,
-                operations: [
-                    {
-                        keyItem: "path",
-                        keyValue: filename,
-                        keyItem2: "content",
-                        keyValue2: content
-                    }
-                ]
-            }) // The API structure for operations is slightly complex, lets use a simple multipart form or the proper JSON
-        });
-
-        // Actually the HF Commit API expects a specific JSON structure. Let's send the correct one:
-        // { "operations": [{ "operation": "addOrUpdate", "path": "filename", "content": "base64encoded==" }], "commit_message": "..." }
-
-        const correctPayload = {
-            summary: payload.commit_message,
-            operations: [
-                {
-                    operation: "addOrUpdate",
-                    path: filename,
-                    content: content,
-                    encoding: "base64"
-                }
-            ]
+        const pageIdx = findPageIndex(pagesData, pageNumber);
+        if (pageIdx === -1) return null;
+
+        const dsIdx = pagesData[pageIdx].datasets.findIndex(ds => ds.timestamp === timestamp);
+        if (dsIdx === -1) return null;
+
+        pagesData[pageIdx].datasets[dsIdx] = {
+            ...pagesData[pageIdx].datasets[dsIdx],
+            ...updates
         };
+        writeDocLocal(docIndex, pagesData);
+        return pagesData[pageIdx].datasets[dsIdx];
+    }
+}
 
-        const executeRes = await fetch(`https://huggingface.co/api/datasets/${repoId}/commit/main`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${token}`,
-                'Content-Type': 'application/json'
-            },
-            body: JSON.stringify(correctPayload)
-        });
-
-        if (!executeRes.ok) {
-            throw new Error(`Failed to commit to HF: ${await executeRes.text()}`);
-        }
+/**
+ * Retrieves all human annotations (those with annotator field) from local files.
+ * Scans all doc files and returns entries that have a timestamp (human-added).
+ */
+export async function getAnnotations(docIndex = null) {
+    const extractionsDir = path.join(getRootPath(), 'annotation_data', 'wbg_extractions');
+    if (!fs.existsSync(extractionsDir)) return [];
+
+    const results = [];
+    const dirs = fs.readdirSync(extractionsDir).filter(d => d.startsWith('doc_'));
 
-        console.log(`Successfully committed annotation ${filename} to HF Space ${repoId}`);
-    } catch (e) {
-        console.error("Failed to commit to Hugging Face:", e);
-        throw e;
+    for (const dir of dirs) {
+        const idx = parseInt(dir.replace('doc_', ''), 10);
+        if (docIndex !== null && idx !== docIndex) continue;
+
+        const filePath = path.join(extractionsDir, dir, 'raw', `${dir}_direct_judged.jsonl`);
+        if (!fs.existsSync(filePath)) continue;
+
+        try {
+            const pagesData = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            for (const page of pagesData) {
+                const pageNum = page.document?.pages?.[0];
+                for (const ds of (page.datasets || [])) {
+                    // Only return human annotations (those with annotator field)
+                    if (ds.annotator) {
+                        results.push({
+                            ...ds,
+                            document_index: idx,
+                            page_number: pageNum,
+                        });
+                    }
+                }
+            }
+        } catch (e) {
+            console.error(`Error reading ${filePath}:`, e);
+        }
     }
+
+    return results;
 }