Add PDF extractor app and Dockerfile

Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.10-slim
+
+# System libraries PaddleOCR / OpenCV need at runtime.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libgl1 \
+        libglib2.0-0 \
+        libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Hugging Face Spaces runs the container as uid 1000. Create that user and a
+# writable home so model weights and caches have somewhere to live.
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /home/user/app
+
+# Install Python dependencies first so the layer caches across code changes.
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+# Pre-download the English PP-OCRv4 weights at build time so the first visitor
+# does not wait for the download. A network blip here is non-fatal: the app
+# downloads them on first use anyway.
+RUN python -c "from paddleocr import PaddleOCR; PaddleOCR(use_angle_cls=True, lang='en', show_log=False)" \
+    || echo "weight prewarm skipped; will download at runtime"
+
+# Application code.
+COPY --chown=user . .
+
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,10 +1,34 @@
 ---
 title: PDF Extractor
-emoji: 👀
-colorFrom: gray
-colorTo: green
+emoji: 📄
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
+short_description: Extract text from typed, scanned, and handwritten PDFs.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# PDF Extractor
+
+A live demo of a local-first PDF text extractor. Drop in a PDF and it returns a
+clean, searchable, exportable transcript. Pages that already have a text layer
+are read directly; scanned image pages are run through OCR.
+
+This Space runs on a free shared CPU, so OCR is slower than it would be on your
+own machine and there can be a short cold-start delay when the Space wakes up.
+The first request after a rebuild may also be slow while model weights load.
+
+Source code and instructions for running it locally:
+https://github.com/Archie0099/PDF-Extractor
+
+## Notes
+
+- Typed or born-digital pages are extracted instantly and exactly, with no OCR.
+- Scanned pages use PaddleOCR (English and Hindi).
+- For handwriting, the optional online OCR path (Google Gemini) is far more
+  accurate. It is off by default and needs your own free API key, which stays in
+  your browser.
+- Nothing is stored. Uploaded files are held in memory only while a job runs and
+  are dropped afterward.

app.py

@@ -0,0 +1,308 @@
+"""PDF text extraction app — FastAPI backend.
+
+Run locally with:
+    uvicorn app:app --reload
+(serves on http://127.0.0.1:8000)
+
+Local and CPU-only by default. An online OCR path (Google Gemini) is optional
+and off unless you supply your own API key.
+"""
+
+import io
+import json
+import asyncio
+from pathlib import Path
+
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException, Body
+from fastapi.responses import FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from pipeline.jobs import manager
+from pipeline.ocr_engine import engine
+from pipeline.export_docx import build_docx
+from pipeline.analyze import suggest_settings
+
+BASE_DIR = Path(__file__).resolve().parent
+STATIC_DIR = BASE_DIR / "static"
+INDEX_HTML = STATIC_DIR / "index.html"
+
+app = FastAPI(title="Local PDF Text Extractor")
+
+# Serve static assets (CSS/JS) locally — no external CDN/network dependency.
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+# Hold strong references to fire-and-forget background tasks: asyncio keeps only
+# a weak reference to a Task, so a bare create_task() result can in principle be
+# GC'd mid-flight ("Task was destroyed but it is pending"). Keeping them here and
+# discarding on completion makes the lifetime explicit.
+_BG_TASKS: set = set()
+
+
+def _spawn(coro) -> None:
+    task = asyncio.create_task(coro)
+    _BG_TASKS.add(task)
+    task.add_done_callback(_BG_TASKS.discard)
+
+
+def _parse_bool(value: str) -> bool:
+    """Parse a form string into a bool. true/1/yes (case-insensitive) -> True."""
+    return str(value).strip().lower() in ("true", "1", "yes")
+
+
+@app.on_event("startup")
+async def _startup() -> None:
+    # Preload the English PaddleOCR model at startup so the first request is fast
+    # (first ever run still downloads model weights from disk cache). This is
+    # best-effort: a failed/slow first-run download must NEVER abort startup —
+    # text-layer extraction and the online Gemini path don't need PaddleOCR at
+    # all. Run it in the OCR worker thread so a slow download can't block the
+    # event loop, and swallow any error (OCR lazy-loads on first real use).
+    from pipeline.jobs import _EXECUTOR
+
+    async def _safe_warmup() -> None:
+        try:
+            loop = asyncio.get_running_loop()
+            await loop.run_in_executor(_EXECUTOR, engine.warmup, "en")
+        except Exception:
+            pass
+
+    _spawn(_safe_warmup())
+
+
+@app.get("/")
+async def index():
+    """Serve the single-page front-end."""
+    return FileResponse(str(INDEX_HTML))
+
+
+@app.post("/api/upload")
+async def upload(
+    file: UploadFile = File(...),
+    mode: str = Form("max"),
+    lang: str = Form("en"),
+    preprocess: str = Form("true"),
+    binarize: str = Form("false"),
+    handwriting: str = Form("false"),
+    online: str = Form("false"),
+    online_key: str = Form(""),
+    online_model: str = Form(""),
+    force_ocr: str = Form("false"),
+    remove_headers: str = Form("true"),
+):
+    """Accept a PDF upload, create a job, and kick off background processing."""
+    pre = _parse_bool(preprocess)
+    binar = _parse_bool(binarize)
+    handw = _parse_bool(handwriting)
+    onl = _parse_bool(online)
+    okey = (online_key or "").strip()
+    omodel = (online_model or "").strip()
+    force = _parse_bool(force_ocr)
+    rm_headers = _parse_bool(remove_headers)
+
+    # Cheap validations BEFORE buffering the whole upload into memory, so a
+    # request that will be rejected anyway doesn't pay a full file read.
+    if onl and not okey:
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "Online OCR needs a Gemini API key. Enter your free key from "
+                "aistudio.google.com, or turn Online OCR off."
+            ),
+        )
+
+    if handw:
+        from pipeline.handwriting import is_available
+        if not is_available():
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    "Handwriting mode needs extra packages. In the project venv "
+                    "run: pip install transformers torch  (first use also "
+                    "downloads the TrOCR model, a few hundred MB)."
+                ),
+            )
+
+    pdf_bytes = await file.read()
+
+    # create_job opens the PDF with PyMuPDF to validate + count pages. Run it on
+    # the single OCR worker thread so ALL fitz access stays on one thread —
+    # PyMuPDF is not thread-safe even across separate Documents, and the event
+    # loop could otherwise call fitz.open here concurrently with another job's
+    # render on the worker thread (multi-file uploads run concurrently).
+    from pipeline.jobs import _EXECUTOR
+    loop = asyncio.get_running_loop()
+    try:
+        job = await loop.run_in_executor(
+            _EXECUTOR,
+            lambda: manager.create_job(
+                file.filename or "document.pdf",
+                pdf_bytes,
+                mode=mode,
+                lang=lang,
+                preprocess=pre,
+                binarize=binar,
+                handwriting=handw,
+                online=onl,
+                online_key=okey,
+                online_model=omodel,
+                force_ocr=force,
+                remove_headers=rm_headers,
+            ),
+        )
+    except ValueError as exc:
+        # encrypted / corrupt / otherwise unreadable PDF
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    # Launch processing as a background task; progress is streamed over SSE.
+    _spawn(manager.run(job))
+
+    return {
+        "job_id": job.job_id,
+        "filename": job.filename,
+        "total_pages": job.total_pages,
+        "status": job.status,
+    }
+
+
+@app.post("/api/online/validate")
+async def online_validate(api_key: str = Form(...)):
+    """Validate a Gemini API key and return the vision models it can use.
+
+    Lets the UI confirm the key works (and populate the model dropdown) before
+    the user runs a whole document. Never stores the key server-side.
+    """
+    from pipeline import online_ocr
+
+    def _check():
+        all_models = online_ocr.list_models(api_key)
+        supported = [m for m in online_ocr.SUPPORTED_MODELS if m in set(all_models)]
+        return {
+            "ok": True,
+            "supported": supported,
+            "recommended": online_ocr.best_available_model(all_models),
+        }
+
+    loop = asyncio.get_running_loop()
+    try:
+        return await loop.run_in_executor(None, _check)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception:  # never surface a bare 500 from a key check
+        raise HTTPException(
+            status_code=502, detail="Online key check failed unexpectedly."
+        )
+
+
+@app.post("/api/analyze")
+async def analyze(
+    file: UploadFile = File(...),
+    lang: str = Form("en"),
+):
+    """Sample 1-2 pages and recommend the best settings for THIS document.
+
+    Opt-in and fast. Runs the CPU-bound sweep in the OCR worker thread pool so
+    it never stalls the event loop / SSE streams, and so it never runs OCR
+    concurrently with a live extraction job (PaddleOCR is not thread-safe).
+    """
+    pdf_bytes = await file.read()
+    if not pdf_bytes:
+        raise HTTPException(status_code=400, detail="empty file")
+    from pipeline.jobs import _EXECUTOR
+    loop = asyncio.get_running_loop()
+    result = await loop.run_in_executor(
+        _EXECUTOR, lambda: suggest_settings(pdf_bytes, lang=lang)
+    )
+    return result
+
+
+@app.post("/api/export/docx")
+async def export_docx(payload: dict = Body(...)):
+    """Build a .docx from the posted extracted documents and stream it back."""
+    documents = payload.get("documents", []) if isinstance(payload, dict) else []
+    loop = asyncio.get_running_loop()
+    # build_docx is hardened to never raise on a malformed/hostile payload, but
+    # keep a belt-and-suspenders guard so a single bad export can't 500.
+    try:
+        data = await loop.run_in_executor(None, build_docx, documents)
+    except Exception:
+        raise HTTPException(status_code=400, detail="Could not build the Word document.")
+    return StreamingResponse(
+        io.BytesIO(data),
+        media_type=(
+            "application/vnd.openxmlformats-officedocument."
+            "wordprocessingml.document"
+        ),
+        headers={"Content-Disposition": 'attachment; filename="extraction.docx"'},
+    )
+
+
+@app.get("/api/jobs/{job_id}")
+async def get_job(job_id: str):
+    """Return the current full state of a job."""
+    job = manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    return job.to_dict()
+
+
+@app.get("/api/jobs/{job_id}/stream")
+async def stream_job(job_id: str):
+    """Stream per-page progress events as Server-Sent Events."""
+    job = manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+
+    async def event_generator():
+        async for event in manager.events(job_id):
+            yield f"data: {json.dumps(event)}\n\n"
+            etype = event.get("type")
+            if etype in ("done", "error", "cancelled"):
+                break
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@app.post("/api/jobs/{job_id}/cancel")
+async def cancel_job(job_id: str):
+    """Request cancellation of a running job."""
+    job = manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    manager.cancel(job_id)
+    return {"status": "cancelling"}
+
+
+@app.delete("/api/jobs/{job_id}")
+async def delete_job(job_id: str):
+    """Remove a job and free its in-memory PDF bytes. Idempotent (always 200)."""
+    manager.delete(job_id)
+    return {"status": "deleted"}
+
+
+@app.get("/api/jobs/{job_id}/pages/{n}/image")
+async def page_image(job_id: str, n: int, dpi: int = 150):
+    """Render a 1-based page to PNG and stream it back."""
+    job = manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    # Clamp DPI to a sane range so a degenerate ?dpi= (0, negative, or huge)
+    # can't crash the renderer (fitz error / giant allocation) into a 500.
+    dpi = max(36, min(600, dpi))
+    try:
+        # PNG raster + encode is CPU-bound; run it off the event loop. Use the
+        # SAME single-worker OCR executor so PyMuPDF rendering never runs
+        # concurrently with an OCR page render or another image render (fitz is
+        # not formally thread-safe even across separate Document objects).
+        from pipeline.jobs import _EXECUTOR
+        loop = asyncio.get_running_loop()
+        png = await loop.run_in_executor(
+            _EXECUTOR, manager.render_page_png, job_id, n, dpi
+        )
+    except (KeyError, IndexError, ValueError):
+        raise HTTPException(status_code=404, detail="page not found")
+    except Exception:
+        # A PyMuPDF render error (e.g. a page with a malformed embedded image
+        # raises fitz.FileDataError / RuntimeError) must not surface as a bare
+        # 500 — the frontend <img> onerror handles a non-image response.
+        raise HTTPException(status_code=404, detail="could not render page")
+    return StreamingResponse(io.BytesIO(png), media_type="image/png")

pipeline/analyze.py

@@ -0,0 +1,312 @@
+"""Per-document settings recommender.
+
+Samples the first 1-2 OCR-eligible pages, sweeps a small grid of already-supported
+configs, scores each by a COMPOSITE signal (mean confidence AND confident-line
+coverage AND text mass AND cross-config agreement), and recommends settings.
+
+Why not 'pick highest mean confidence': confidence-based auto-select was
+benchmarked and rejected — binarize can score HIGHER mean confidence on garbage
+while silently dropping faint text. The composite + coverage + a margin-handicap
+toward the validated grayscale default guard against that.
+
+This module only MEASURES already-supported, already-benchmarked configs and
+RECOMMENDS one with evidence. It never changes the extraction pipeline, uses the
+existing engine (det_limit_side_len stays 1536), and therefore cannot regress the
+CER benchmark.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+import fitz  # type: ignore
+
+from pipeline.extractor import render_page_image, DPI_MAX, DPI_FAST
+from pipeline.preprocess import preprocess_image
+from pipeline.ocr_engine import engine
+from pipeline.textlayer import has_text_layer
+
+# How many OCR-eligible pages to actually sample. Keep tiny: this runs PaddleOCR
+# several times per page on the CPU, so 1-2 pages is the speed/robustness sweet
+# spot. The first eligible page is usually representative of document "type".
+MAX_SAMPLE_PAGES = 2
+
+# Lines at/above this recognition confidence count as "real" content. Used for
+# the coverage and text-mass signals (the part confidence-alone ignored).
+CONFIDENT = 0.80
+
+# An alternative config must beat the validated grayscale default by at least
+# this much COMPOSITE margin to be recommended. The grayscale+tuned pipeline is
+# the benchmarked baseline; don't flip off it on noise.
+DECISIVE_MARGIN = 0.08
+MARGINAL_MARGIN = 0.03
+
+_WORD_RE = re.compile(r"[0-9a-zऀ-ॿ]+")  # latin digits/letters + devanagari
+
+
+def _tokens(text: str) -> set:
+    return set(_WORD_RE.findall((text or "").lower()))
+
+
+def _config_grid(lang: str) -> list:
+    """The SMALL grid we sweep. All are already-supported, already-benchmarked
+    knobs — no new pipeline behavior, no upscaling, no fused ensemble.
+
+    Order matters only for tie-stability; 'baseline' marks the validated default.
+    """
+    return [
+        # name, mode, preprocess, binarize, baseline?
+        {"name": "max_gray",     "mode": "max",  "preprocess": True,  "binarize": False, "baseline": True},
+        {"name": "max_gray_raw", "mode": "max",  "preprocess": False, "binarize": False, "baseline": False},
+        {"name": "max_binarize", "mode": "max",  "preprocess": True,  "binarize": True,  "baseline": False},
+        {"name": "fast_gray",    "mode": "fast", "preprocess": True,  "binarize": False, "baseline": False},
+    ]
+
+
+def _ocr_one(img_bgr, *, lang: str, use_angle_cls: bool):
+    """Run the SAME engine the real pipeline uses and return rich per-line stats.
+
+    Returns (text, mean_conf, n_confident_lines, confident_char_mass, confident_text).
+    """
+    lines = engine.ocr_lines(img_bgr, lang=lang, use_angle_cls=use_angle_cls)
+    if not lines:
+        return "", None, 0, 0, ""
+    text = "\n".join(ln["text"] for ln in lines)
+    mean_conf = sum(ln["confidence"] for ln in lines) / len(lines)
+    conf_lines = [ln for ln in lines if ln["confidence"] >= CONFIDENT]
+    n_conf = len(conf_lines)
+    mass = sum(len(ln["text"].strip()) for ln in conf_lines)
+    conf_text = " ".join(ln["text"] for ln in conf_lines)
+    return text, float(mean_conf), n_conf, mass, conf_text
+
+
+def _score_page(results: dict) -> dict:
+    """Given {config_name: per-config raw stats} for ONE page, compute a
+    normalized composite score per config.
+
+    Signals (all normalized to the best config ON THIS PAGE so absolute scale
+    doesn't matter), then weighted:
+      conf      0.30  mean line confidence
+      coverage  0.30  # confident lines (catches binarize dropping faint text)
+      mass      0.20  confident char count (don't reward tiny fragments)
+      agree     0.20  token overlap vs the union of all configs' confident text
+                      (a config that hallucinates differently is down-weighted)
+    """
+    names = list(results.keys())
+    confs = {n: (results[n]["mean_conf"] or 0.0) for n in names}
+    covs = {n: results[n]["n_conf"] for n in names}
+    mass = {n: results[n]["mass"] for n in names}
+
+    # cross-config agreement: the fraction of THIS config's confident tokens
+    # that are corroborated by at least one OTHER config. (Comparing against the
+    # union of ALL configs — including this one — is mathematically inert: it
+    # reduces to |toks[n]| / |union|, which actually REWARDS a config that
+    # hallucinates many unique tokens. We want the opposite: down-weight a config
+    # whose confident output nobody else agrees with.)
+    toks = {n: _tokens(results[n]["conf_text"]) for n in names}
+    agree = {}
+    for n in names:
+        others = set()
+        for m in names:
+            if m != n:
+                others |= toks[m]
+        agree[n] = (len(toks[n] & others) / len(toks[n])) if toks[n] else 0.0
+
+    def _norm(d):
+        hi = max(d.values()) if d else 0
+        if not hi:
+            return {k: 0.0 for k in d}
+        return {k: v / hi for k, v in d.items()}
+
+    nconf, ncov, nmass = _norm(confs), _norm(covs), _norm(mass)
+    out = {}
+    for n in names:
+        out[n] = (0.30 * nconf[n] + 0.30 * ncov[n] +
+                  0.20 * nmass[n] + 0.20 * agree[n])
+    return out
+
+
+def suggest_settings(pdf_bytes: bytes, *, lang: str = "en",
+                     max_pages: int = MAX_SAMPLE_PAGES) -> dict:
+    """Analyze a PDF and recommend extraction settings for THIS document.
+
+    Fast + opt-in: only renders/OCRs up to ``max_pages`` OCR-eligible pages.
+    Born-digital pages short-circuit to a 'no OCR needed' recommendation.
+
+    Returns a JSON-serializable dict. Never raises on a bad page; on total
+    failure returns a safe 'use defaults' recommendation.
+    """
+    t0 = time.time()
+    try:
+        doc = fitz.open(stream=pdf_bytes, filetype="pdf")
+    except Exception as exc:
+        return _fallback(f"Could not open PDF ({exc}); using defaults.", lang)
+
+    try:
+        if doc.needs_pass:
+            return _fallback("PDF is encrypted; using defaults.", lang)
+        total = doc.page_count
+        if total <= 0:
+            return _fallback("PDF has no pages; using defaults.", lang)
+
+        # --- Pass 1: classify pages cheaply (text-layer vs needs-OCR). -------
+        # Cap the scan to a small leading window so a 500-page born-digital PDF
+        # (which never accumulates OCR pages) isn't fully scanned — the first
+        # few pages define the document's type for "recommend settings".
+        text_pages, ocr_page_indices = 0, []
+        scan_cap = max_pages * 4
+        for i in range(total):
+            page = doc.load_page(i)
+            if has_text_layer(page):
+                text_pages += 1
+            else:
+                ocr_page_indices.append(i)
+            if len(ocr_page_indices) >= max_pages or i >= min(total - 1, scan_cap):
+                break
+
+        # --- Born-digital short-circuit: no OCR needed. ----------------------
+        if not ocr_page_indices:
+            return {
+                "ok": True,
+                "needs_ocr": False,
+                "decision": "decisive",
+                "rationale": "This PDF already has a real text layer on the sampled pages — "
+                             "it is extracted exactly, no OCR required.",
+                "total_pages": total,
+                "sampled_pages": [],
+                "text_layer_pages": text_pages,
+                "recommended": {
+                    "mode": "max", "lang": lang,
+                    "preprocess": True, "binarize": False, "handwriting": False,
+                },
+                "evidence": [],
+                "elapsed_sec": round(time.time() - t0, 2),
+            }
+
+        # --- Pass 2: sweep the small grid on up to max_pages OCR pages. ------
+        sample = ocr_page_indices[:max_pages]
+        if not sample:  # guards a direct max_pages<=0 call -> no ZeroDivision
+            return _fallback("No OCR-eligible pages sampled; using defaults.", lang)
+        grid = _config_grid(lang)
+        per_config_totals = {g["name"]: 0.0 for g in grid}
+        evidence_rows = {g["name"]: dict(g, mean_conf=[], n_conf=[], mass=[]) for g in grid}
+
+        for pidx in sample:
+            page = doc.load_page(pidx)
+            renders = {}
+            page_raw = {}
+            for g in grid:
+                dpi = DPI_MAX if g["mode"] == "max" else DPI_FAST
+                if dpi not in renders:
+                    renders[dpi] = render_page_image(page, dpi)
+                img = renders[dpi]
+                if g["preprocess"]:
+                    img = preprocess_image(img, mode=g["mode"], binarize=g["binarize"])
+                use_cls = (g["mode"] == "max")
+                text, mconf, ncf, mass, ctext = _ocr_one(
+                    img, lang=lang, use_angle_cls=use_cls
+                )
+                page_raw[g["name"]] = {
+                    "mean_conf": mconf, "n_conf": ncf, "mass": mass, "conf_text": ctext,
+                }
+                evidence_rows[g["name"]]["mean_conf"].append(mconf)
+                evidence_rows[g["name"]]["n_conf"].append(ncf)
+                evidence_rows[g["name"]]["mass"].append(mass)
+
+            page_scores = _score_page(page_raw)
+            for name, s in page_scores.items():
+                per_config_totals[name] += s
+
+        # Average composite across sampled pages.
+        n = len(sample)
+        composite = {k: v / n for k, v in per_config_totals.items()}
+
+        baseline_name = next(g["name"] for g in grid if g["baseline"])
+        base_score = composite[baseline_name]
+        alt_name = max((g["name"] for g in grid if not g["baseline"]),
+                       key=lambda k: composite[k])
+        alt_score = composite[alt_name]
+        margin = alt_score - base_score
+
+        if margin >= DECISIVE_MARGIN:
+            winner, decision = alt_name, "decisive"
+        elif margin >= MARGINAL_MARGIN:
+            winner, decision = alt_name, "marginal"
+        else:
+            winner, decision = baseline_name, "inconclusive"
+
+        win_cfg = next(g for g in grid if g["name"] == winner)
+        recommended = {
+            "mode": win_cfg["mode"], "lang": lang,
+            "preprocess": win_cfg["preprocess"],
+            "binarize": win_cfg["binarize"], "handwriting": False,
+        }
+
+        # Build a readable evidence table.
+        def _avg(xs):
+            xs = [x for x in xs if x is not None]
+            return round(sum(xs) / len(xs), 3) if xs else None
+        evidence = []
+        for g in grid:
+            r = evidence_rows[g["name"]]
+            evidence.append({
+                "name": g["name"],
+                "mode": g["mode"], "preprocess": g["preprocess"], "binarize": g["binarize"],
+                "baseline": g["baseline"],
+                "composite": round(composite[g["name"]], 3),
+                "mean_conf": _avg(r["mean_conf"]),
+                "confident_lines": round(sum(r["n_conf"]) / max(1, len(r["n_conf"])), 1),
+                "recommended": g["name"] == winner,
+            })
+        evidence.sort(key=lambda e: e["composite"], reverse=True)
+
+        rationale = _rationale(decision, winner, baseline_name, margin, win_cfg)
+        return {
+            "ok": True,
+            "needs_ocr": True,
+            "decision": decision,
+            "rationale": rationale,
+            "total_pages": total,
+            "sampled_pages": [p + 1 for p in sample],
+            "text_layer_pages": text_pages,
+            "recommended": recommended,
+            "evidence": evidence,
+            "elapsed_sec": round(time.time() - t0, 2),
+        }
+    except Exception as exc:  # never let analysis crash the request
+        return _fallback(f"Analysis failed ({exc}); using defaults.", lang)
+    finally:
+        try:
+            doc.close()
+        except Exception:
+            pass
+
+
+def _rationale(decision, winner, baseline_name, margin, cfg) -> str:
+    if decision == "inconclusive":
+        return ("No alternative clearly beat the validated default on the sampled "
+                "page(s); recommending the default (grayscale, max accuracy).")
+    knob = []
+    if cfg["binarize"]:
+        knob.append("binarize ON")
+    if not cfg["preprocess"]:
+        knob.append("preprocessing OFF")
+    if cfg["mode"] == "fast":
+        knob.append("Faster mode")
+    desc = ", ".join(knob) if knob else "the default settings"
+    strength = "clearly" if decision == "decisive" else "slightly"
+    return (f"On the sampled page(s), {desc} {strength} outscored the default "
+            f"(composite +{margin:.2f}: higher confident-line coverage/agreement, "
+            f"not just mean confidence). Verify against the original before trusting it.")
+
+
+def _fallback(msg: str, lang: str = "en") -> dict:
+    return {
+        "ok": True, "needs_ocr": True, "decision": "inconclusive",
+        "rationale": msg, "total_pages": None, "sampled_pages": [],
+        "text_layer_pages": None,
+        "recommended": {"mode": "max", "lang": lang,
+                        "preprocess": True, "binarize": False, "handwriting": False},
+        "evidence": [],
+    }

pipeline/export_docx.py

@@ -0,0 +1,96 @@
+"""Build a Word (.docx) document from extracted results.
+
+Uses python-docx (already a dependency). Pure-local, no network. Each uploaded
+document becomes a section with a filename heading, and each page a "Page N"
+heading (annotated with its source / OCR confidence) followed by its text.
+"""
+
+import io
+import math
+import re
+
+# Characters that are illegal in XML 1.0 (and so rejected by python-docx/lxml
+# with "All strings must be XML compatible"). We keep the only valid C0 controls
+# (tab, newline, carriage return) and strip the rest. A form-feed (U+000C) is the
+# common offender: PDF text layers emit it as a page/section separator, so it
+# reaches Word export organically and would otherwise 500 the whole export.
+_XML_ILLEGAL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f]")
+
+
+def _xml_safe(value) -> str:
+    """Coerce any value to an XML-safe string for python-docx."""
+    if value is None:
+        s = ""
+    elif isinstance(value, str):
+        s = value
+    else:
+        s = str(value)
+    return _XML_ILLEGAL.sub("", s)
+
+
+def build_docx(documents: list) -> bytes:
+    """Render extracted documents to .docx bytes.
+
+    ``documents`` is a list of ``{"filename": str, "pages": [
+        {"page": int, "source": "text"|"ocr"|None, "confidence": float|None,
+         "text": str}, ...]}``.
+
+    The whole payload is untrusted (it comes from an HTTP body), so this never
+    raises on a malformed shape, an XML-illegal control character in any string,
+    or a non-finite (NaN/Infinity) confidence — it degrades gracefully instead.
+    """
+    from docx import Document  # imported lazily so import of this module is cheap
+
+    doc = Document()
+    # Be defensive about the posted payload: the body comes from an untrusted
+    # HTTP request, so anything that isn't the expected shape (a list of dicts of
+    # dicts) is coerced/skipped instead of raising a 500. The frontend always
+    # sends well-formed data; a hand-crafted request must not crash the handler.
+    if not isinstance(documents, list):
+        documents = []
+    first = True
+    for d in documents:
+        if not isinstance(d, dict):
+            continue
+        if not first:
+            doc.add_page_break()
+        first = False
+        doc.add_heading(_xml_safe(d.get("filename") or "Document"), level=1)
+
+        pages = d.get("pages")
+        if not isinstance(pages, list):
+            pages = []
+        for p in pages:
+            if not isinstance(p, dict):
+                continue
+            source = p.get("source")
+            conf = p.get("confidence")
+            # Guard finiteness: json.loads accepts bare NaN/Infinity, and
+            # round(nan)/round(inf) raise — which would 500 the export.
+            if source == "ocr":
+                if (
+                    isinstance(conf, (int, float))
+                    and not isinstance(conf, bool)
+                    and math.isfinite(conf)
+                ):
+                    tag = " — OCR ({}%)".format(round(conf * 100))
+                else:
+                    tag = " — OCR"
+            elif source == "text":
+                tag = " — Text layer"
+            else:
+                tag = ""
+            doc.add_heading(_xml_safe("Page {}{}".format(p.get("page"), tag)), level=2)
+
+            text = _xml_safe(p.get("text"))
+            if text.strip():
+                # Preserve line structure: one paragraph per line.
+                for line in text.split("\n"):
+                    doc.add_paragraph(line)
+            else:
+                empty = doc.add_paragraph()
+                empty.add_run("(no text on this page)").italic = True
+
+    buf = io.BytesIO()
+    doc.save(buf)
+    return buf.getvalue()

pipeline/extractor.py

@@ -0,0 +1,150 @@
+"""Per-page extraction: text-layer when present, else render + OCR.
+
+Implements the project contract exactly:
+  DPI_MAX, DPI_FAST
+  render_page_image(page, dpi) -> BGR uint8 ndarray
+  extract_page(page, *, mode, lang, preprocess, min_chars=50) -> dict
+"""
+
+import numpy as np
+
+from pipeline.preprocess import preprocess_image
+from pipeline.ocr_engine import engine
+from pipeline.textlayer import has_text_layer, extract_text_layer
+
+# fitz is PyMuPDF; imported lazily-safe at module import.
+import fitz  # type: ignore
+
+
+DPI_MAX = 300
+DPI_FAST = 150
+
+
+def render_page_image(page, dpi: int) -> np.ndarray:
+    """Render a fitz.Page to an HxWx3 BGR uint8 ndarray at the given DPI.
+
+    Uses a pixmap with zoom = dpi/72. Handles RGB, grayscale and alpha
+    channels, always returning a 3-channel BGR image (OpenCV/PaddleOCR
+    convention).
+    """
+    zoom = float(dpi) / 72.0
+    matrix = fitz.Matrix(zoom, zoom)
+    # alpha=False keeps things simple, but some pages/pixmaps can still carry
+    # channel counts other than 3; normalise defensively below.
+    pix = page.get_pixmap(matrix=matrix, alpha=False)
+
+    # Build an ndarray view from the pixmap samples.
+    buf = np.frombuffer(pix.samples, dtype=np.uint8)
+    n = pix.n  # bytes per pixel (channels)
+    arr = buf.reshape(pix.height, pix.width, n)
+
+    if n == 1:
+        # Grayscale -> BGR
+        bgr = np.repeat(arr, 3, axis=2)
+    elif n == 3:
+        # PyMuPDF emits RGB; convert to BGR for OpenCV/PaddleOCR.
+        bgr = arr[:, :, ::-1]
+    elif n == 4:
+        # RGBA -> drop alpha, RGB -> BGR.
+        rgb = arr[:, :, :3]
+        bgr = rgb[:, :, ::-1]
+    else:
+        # CMYK or other exotic layouts: re-render forcing an RGB colorspace.
+        pix = page.get_pixmap(matrix=matrix, alpha=False, colorspace=fitz.csRGB)
+        buf = np.frombuffer(pix.samples, dtype=np.uint8)
+        arr = buf.reshape(pix.height, pix.width, pix.n)
+        bgr = arr[:, :, :3][:, :, ::-1]
+
+    # Ensure a contiguous, owned uint8 array (the buffer view is read-only).
+    return np.ascontiguousarray(bgr, dtype=np.uint8)
+
+
+def extract_page(
+    page,
+    *,
+    mode: str,
+    lang: str,
+    preprocess: bool,
+    binarize: bool = False,
+    handwriting: bool = False,
+    online: bool = False,
+    online_key: str = "",
+    online_model: str = "",
+    force_ocr: bool = False,
+    min_chars: int = 50,
+) -> dict:
+    """Extract text from a single page.
+
+    If the page has a usable text layer, return it directly (exact, so no
+    confidence is reported). Otherwise render the page to an image, optionally
+    preprocess (deskew + CLAHE + denoise), optionally binarize, and OCR it.
+
+    ``preprocess`` and ``binarize`` are independent: ``preprocess`` enables the
+    grayscale clean-up pipeline; ``binarize`` additionally Sauvola-thresholds
+    the image (only meaningful when ``preprocess`` is on).
+
+    Routing precedence for a page that needs reading: text-layer (unless
+    ``force_ocr``) -> online Gemini (if ``online`` + key) -> local handwriting
+    (if ``handwriting``) -> local OCR.
+
+    Returns a uniform dict from EVERY branch:
+    ``{"source": "text"|"ocr"|"online"|"handwriting", "text": str,
+    "confidence": float|None, "lines": list|None}``. ``confidence`` and
+    ``lines`` (per-line ``[{text, confidence}]``) are populated only for local
+    ``"ocr"``; the other sources set both to ``None`` so consumers never have to
+    guard for a missing key.
+    """
+    # "Force OCR" skips the text-layer shortcut so even born-digital pages are
+    # rendered + OCR'd (or sent online). Use it when the embedded text is
+    # garbled/wrong, or when text is trapped inside images on a text page.
+    if not force_ocr and has_text_layer(page, min_chars=min_chars):
+        return {
+            "source": "text",
+            "text": extract_text_layer(page),
+            "confidence": None,
+            "lines": None,
+        }
+
+    dpi = DPI_MAX if mode == "max" else DPI_FAST
+    img = render_page_image(page, dpi)
+
+    # Online vision path (opt-in): send the RAW page image to Google Gemini and
+    # let it transcribe (handwriting + printed). Takes precedence over the local
+    # OCR/handwriting engines for any page that needs OCR. The page bytes leave
+    # this machine — gated on an explicit api key, never the default. Errors
+    # propagate to the per-page handler with an actionable message.
+    if online:
+        from pipeline import online_ocr
+        if online_ocr.is_configured(online_key):
+            text = online_ocr.transcribe_image_bgr(
+                img, api_key=online_key, model=(online_model or None)
+            )
+            return {"source": "online", "text": text, "confidence": None, "lines": None}
+
+    # Handwriting path: detect lines with PaddleOCR, recognise with TrOCR.
+    # Crops are taken from the natural render (no binarization, which TrOCR
+    # dislikes). Slow on CPU; opt-in per document.
+    if handwriting:
+        from pipeline.handwriting import get_engine
+        # Line DETECTION stays on the script-agnostic "en" DB detector (it finds
+        # text regions regardless of script, and avoids pulling an extra
+        # PaddleOCR language model). Only the RECOGNISER is language-aware.
+        boxes = engine.detect_boxes(img, lang="en")
+        hw = get_engine(lang=lang)
+        text = hw.ocr_text(img, boxes)
+        return {"source": "handwriting", "text": text, "confidence": None, "lines": None}
+
+    if preprocess:
+        img = preprocess_image(img, mode=mode, binarize=binarize)
+
+    use_angle_cls = (mode == "max")
+    lines = engine.ocr_lines(img, lang=lang, use_angle_cls=use_angle_cls)
+    text = "\n".join(ln["text"] for ln in lines)
+    conf = (sum(ln["confidence"] for ln in lines) / len(lines)) if lines else None
+    # Per-line confidence so the UI can flag exactly which lines to double-check.
+    # Order matches the joined text (one entry per "\n"-separated line).
+    line_conf = [
+        {"text": ln["text"], "confidence": round(float(ln["confidence"]), 4)}
+        for ln in lines
+    ]
+    return {"source": "ocr", "text": text, "confidence": conf, "lines": line_conf}

pipeline/handwriting.py

@@ -0,0 +1,325 @@
+"""Local handwriting OCR using HuggingFace VisionEncoderDecoder models (offline, free).
+
+PaddleOCR's printed-text recogniser is weak on handwriting. This module pairs
+PaddleOCR's *detector* (to find text-line boxes) with a TrOCR-family handwriting
+*recogniser* (a local HuggingFace transformers model) to read each line.
+
+The recogniser is selected by language + an optional 'large' quality flag:
+
+  en  (default) -> microsoft/trocr-base-handwritten     (English, fast-ish)
+  en  + large   -> microsoft/trocr-large-handwritten    (English, slower, more accurate)
+  hi  (Hindi)   -> sabaridsnfuji/Hindi_Offline_Handwritten_OCR (Hindi, EXPERIMENTAL)
+  ne  (Nepali / generic Devanagari) -> aayushpuri01/TrOCR-Devanagari
+
+It is OPTIONAL and heavy: it needs ``transformers`` + ``torch`` installed and a
+one-time model download (hundreds of MB). It is slow on CPU and opt-in per
+document. If the deps/model are missing it raises a clear, actionable error
+instead of crashing, and unknown languages fall back to the English model.
+
+Backward compatibility: ``lang='en'`` + ``large=False`` (the defaults, and the
+module-level ``hw_engine`` singleton) behave byte-for-byte like the original
+single-model implementation.
+"""
+
+import os
+import threading
+
+import cv2
+import numpy as np
+
+# ----------------------------------------------------------------------------
+# Model registry. Each entry describes one recogniser.
+#
+#  id        : HuggingFace repo for the VisionEncoderDecoderModel weights.
+#  processor : how to build the TrOCRProcessor:
+#                "bundled"  -> TrOCRProcessor.from_pretrained(id)  (id ships the
+#                              preprocessor_config + tokenizer)
+#                ("manual", feat_repo, tok_repo) -> build from a ViT feature
+#                              extractor repo + a decoder tokenizer repo, because
+#                              the weights repo ships ONLY config + safetensors.
+#  max_new_tokens : decode cap (the Hindi model is trained for <=64 chars/crop).
+#  experimental   : True for models whose quality on this task is unvalidated.
+# ----------------------------------------------------------------------------
+_MODELS = {
+    "en": {
+        "id": "microsoft/trocr-base-handwritten",
+        "processor": "bundled",
+        "max_new_tokens": 96,
+        "experimental": False,
+    },
+    "en_large": {
+        "id": "microsoft/trocr-large-handwritten",
+        "processor": "bundled",
+        "max_new_tokens": 96,
+        "experimental": False,
+    },
+    "hi": {
+        # Only genuinely Hindi-trained option found. Repo ships weights only, so
+        # the processor must be assembled from the encoder + decoder base repos.
+        # Quality is modest and UNVALIDATED here — treat as experimental.
+        "id": "sabaridsnfuji/Hindi_Offline_Handwritten_OCR",
+        "processor": ("manual",
+                      "google/vit-base-patch16-224-in21k",
+                      "surajp/RoBERTa-hindi-guj-san"),
+        "max_new_tokens": 64,  # model is trained for <=64 chars per crop
+        "experimental": True,
+    },
+    "ne": {
+        # Nepali Devanagari; bundled processor, clean drop-in. Usable as a
+        # generic Devanagari fallback (reads many Hindi glyphs, Nepali-biased).
+        "id": "aayushpuri01/TrOCR-Devanagari",
+        "processor": "bundled",
+        "max_new_tokens": 64,
+        "experimental": True,
+    },
+}
+
+# Default fallback when a requested language has no handwriting model.
+_DEFAULT_KEY = "en"
+
+# Backwards-compat constant some callers/tests may import.
+MODEL_NAME = _MODELS[_DEFAULT_KEY]["id"]
+
+
+def _resolve_key(lang: str, large: bool) -> str:
+    """Map a (lang, large) request to a registry key, falling back to English.
+
+    Devanagari-family languages share script; 'hi'/'ne'/'devanagari' all route
+    to a Devanagari model. 'large' currently only applies to English (no large
+    Devanagari model exists), so it is ignored for non-English.
+    """
+    lang = (lang or "en").strip().lower()
+    if lang in ("en", "english"):
+        return "en_large" if large else "en"
+    if lang in ("hi", "hin", "hindi", "mr", "marathi", "sa"):
+        return "hi"
+    if lang in ("ne", "nep", "nepali", "devanagari"):
+        return "ne"
+    return _DEFAULT_KEY
+
+
+def is_available() -> bool:
+    """True if the optional handwriting dependencies are importable."""
+    try:
+        import torch  # noqa: F401
+        import transformers  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def _dist(a, b) -> float:
+    return float(np.hypot(a[0] - b[0], a[1] - b[1]))
+
+
+def _crop_quad(img: np.ndarray, box) -> np.ndarray:
+    """Perspective-warp a 4-point text box to an upright rectangle crop."""
+    pts = np.array(box, dtype="float32")
+    w = int(max(_dist(pts[0], pts[1]), _dist(pts[2], pts[3])))
+    h = int(max(_dist(pts[1], pts[2]), _dist(pts[3], pts[0])))
+    w = max(w, 1)
+    h = max(h, 1)
+    dst = np.array([[0, 0], [w, 0], [w, h], [0, h]], dtype="float32")
+    matrix = cv2.getPerspectiveTransform(pts, dst)
+    return cv2.warpPerspective(img, matrix, (w, h))
+
+
+class HandwritingEngine:
+    """Lazy-loaded TrOCR-family wrapper for ONE registry entry.
+
+    Thread-safe; one model instance reused. Construct via the module-level
+    ``get_engine(lang, large)`` factory so identical models are shared.
+    """
+
+    def __init__(self, key: str = _DEFAULT_KEY) -> None:
+        self._key = key if key in _MODELS else _DEFAULT_KEY
+        self._cfg = _MODELS[self._key]
+        self._lock = threading.Lock()
+        self._model = None
+        self._processor = None
+        self._loaded = False
+        self._error = None
+
+    @property
+    def model_id(self) -> str:
+        return self._cfg["id"]
+
+    @property
+    def experimental(self) -> bool:
+        return bool(self._cfg.get("experimental"))
+
+    def _build_processor(self):
+        from transformers import TrOCRProcessor
+
+        proc = self._cfg["processor"]
+        if proc == "bundled":
+            return TrOCRProcessor.from_pretrained(self._cfg["id"])
+        # ("manual", feature_extractor_repo, tokenizer_repo)
+        _, feat_repo, tok_repo = proc
+        from transformers import AutoTokenizer
+
+        # AutoImageProcessor is the modern name; in transformers 4.40.2
+        # AutoFeatureExtractor still resolves it fine as a fallback.
+        try:
+            from transformers import AutoImageProcessor as _FeatLoader
+        except Exception:  # very old fallback
+            from transformers import AutoFeatureExtractor as _FeatLoader
+
+        feature_extractor = _FeatLoader.from_pretrained(feat_repo)
+        tokenizer = AutoTokenizer.from_pretrained(tok_repo)
+        # TrOCRProcessor accepts an image processor as `image_processor=`; older
+        # transformers used `feature_extractor=`. 4.40.2 accepts both kwargs.
+        try:
+            return TrOCRProcessor(image_processor=feature_extractor,
+                                  tokenizer=tokenizer)
+        except TypeError:
+            return TrOCRProcessor(feature_extractor=feature_extractor,
+                                  tokenizer=tokenizer)
+
+    def _ensure(self) -> None:
+        if self._loaded:
+            if self._error:
+                raise RuntimeError(self._error)
+            return
+        with self._lock:
+            if self._loaded:
+                if self._error:
+                    raise RuntimeError(self._error)
+                return
+            try:
+                import torch
+                from transformers import VisionEncoderDecoderModel
+
+                torch.set_num_threads(max(1, os.cpu_count() or 1))
+                self._processor = self._build_processor()
+                self._model = VisionEncoderDecoderModel.from_pretrained(
+                    self._cfg["id"]
+                )
+                self._model.eval()
+                self._loaded = True
+            except (ImportError, ModuleNotFoundError) as exc:
+                # Missing deps are DETERMINISTIC — they won't fix themselves at
+                # runtime, so cache the failure permanently (fail fast).
+                self._error = (
+                    "Handwriting model '{}' unavailable ({}). Enable it with: "
+                    "pip install transformers torch  (first use downloads the "
+                    "model, a few hundred MB; non-English models also fetch a "
+                    "tokenizer/feature-extractor repo).".format(
+                        self._cfg["id"], exc
+                    )
+                )
+                self._loaded = True
+                raise RuntimeError(self._error)
+            except Exception as exc:
+                # TRANSIENT failure (network drop / partial HF download / HF
+                # outage / disk full). Do NOT poison the engine: leave _loaded
+                # False so the next request retries from_pretrained (which can
+                # resume the partial download). Otherwise the engine would be
+                # dead for the whole process until a server restart.
+                raise RuntimeError(
+                    "Handwriting model '{}' could not be loaded ({}). This is "
+                    "often a transient network/download issue — try again; a "
+                    "later request will retry the download.".format(
+                        self._cfg["id"], exc
+                    )
+                ) from exc
+
+    def _recognize(self, crop_bgr: np.ndarray) -> str:
+        import torch
+        from PIL import Image
+
+        rgb = cv2.cvtColor(crop_bgr, cv2.COLOR_BGR2RGB)
+        pil = Image.fromarray(rgb)
+        pixel_values = self._processor(
+            images=pil, return_tensors="pt"
+        ).pixel_values
+        with torch.no_grad():
+            generated = self._model.generate(
+                pixel_values, max_new_tokens=self._cfg["max_new_tokens"]
+            )
+        return self._processor.batch_decode(
+            generated, skip_special_tokens=True
+        )[0]
+
+    def ocr_text(self, img_bgr: np.ndarray, boxes: list) -> str:
+        """Recognize handwriting in ``img_bgr`` given detected line ``boxes``.
+
+        Boxes are ordered into reading order (top-to-bottom, left-to-right),
+        each cropped and passed through the recogniser, joined by newlines.
+        """
+        self._ensure()
+        if not boxes:
+            return ""
+
+        items = []
+        for box in boxes:
+            # Skip any malformed box (not a 4-point quad) so a single bad
+            # detection can't abort the whole page's handwriting OCR.
+            if not box or len(box) != 4:
+                continue
+            try:
+                ys = [p[1] for p in box]
+                xs = [p[0] for p in box]
+            except (TypeError, IndexError):
+                continue
+            items.append({
+                "box": box,
+                "cy": sum(ys) / len(ys),
+                "cx": sum(xs) / len(xs),
+                "h": max(ys) - min(ys),
+            })
+        if not items:
+            return ""
+        heights = [it["h"] for it in items if it["h"] > 0]
+        tol = max((float(np.median(heights)) if heights else 12.0) * 0.6, 8.0)
+        items.sort(key=lambda it: (it["cy"], it["cx"]))
+
+        rows = [[items[0]]]
+        cy = items[0]["cy"]
+        for it in items[1:]:
+            if abs(it["cy"] - cy) <= tol:
+                rows[-1].append(it)
+            else:
+                rows.append([it])
+                cy = it["cy"]
+
+        lines = []
+        for row in rows:
+            for it in sorted(row, key=lambda x: x["cx"]):
+                try:
+                    crop = _crop_quad(img_bgr, it["box"])
+                    if crop.size == 0:
+                        continue
+                    text = self._recognize(crop).strip()
+                except Exception:
+                    text = ""
+                if text:
+                    lines.append(text)
+        return "\n".join(lines)
+
+
+# ----------------------------------------------------------------------------
+# Factory: one cached engine per registry key (so 'en', 'en_large' and a
+# Devanagari model can coexist without reloading). Thread-safe.
+# ----------------------------------------------------------------------------
+_engines: dict = {}
+_engines_lock = threading.Lock()
+
+
+def get_engine(lang: str = "en", large: bool = False) -> "HandwritingEngine":
+    """Return a cached handwriting engine for the requested (lang, large)."""
+    key = _resolve_key(lang, large)
+    eng = _engines.get(key)
+    if eng is not None:
+        return eng
+    with _engines_lock:
+        eng = _engines.get(key)
+        if eng is None:
+            eng = HandwritingEngine(key)
+            _engines[key] = eng
+        return eng
+
+
+# Backwards-compatible module-level singleton (English base), so existing
+# `from pipeline.handwriting import hw_engine` callers keep working unchanged.
+hw_engine = get_engine("en", large=False)

pipeline/jobs.py

@@ -0,0 +1,529 @@
+"""Async job manager for PDF extraction.
+
+One job per uploaded file. Heavy CPU work (rendering + OCR) is serialized
+through a SINGLE-worker ThreadPoolExecutor via loop.run_in_executor so OCR
+never runs concurrently. Per-job progress is pushed to an asyncio.Queue that
+is consumed by the SSE endpoint.
+
+Implements the project contract exactly:
+  Job dataclass + to_dict()
+  JobManager.create_job / get / run / cancel / events / render_page_png
+  manager = JobManager()  module-level singleton
+"""
+
+import asyncio
+import threading
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Optional
+
+import fitz  # type: ignore
+
+from pipeline.extractor import extract_page
+
+
+# Single-worker executor: serializes all heavy CPU work (OCR is not
+# thread-safe and we want deterministic, low-memory CPU usage).
+_EXECUTOR = ThreadPoolExecutor(max_workers=1, thread_name_prefix="ocr-worker")
+
+
+# --- Job retention / eviction policy (in-memory only; single-user local) ------
+# A finished job keeps its full pdf_bytes in RAM. To bound memory across a long
+# session we evict the oldest / expired *finished, unsubscribed* jobs. Jobs that
+# are still pending/processing, or that have a live SSE subscriber, are NEVER
+# eviction candidates regardless of these limits.
+MAX_JOBS = 50                       # keep at most this many evictable jobs
+JOB_TTL_SECONDS = 2 * 60 * 60       # evict finished+idle jobs older than this
+_SWEEP_MIN_INTERVAL = 5.0           # throttle: don't sweep on get() more than
+                                    # once per this many seconds (monotonic)
+
+_TERMINAL_STATES = ("done", "error", "cancelled")
+
+
+@dataclass
+class PageResult:
+    page: int  # 1-based
+    source: Optional[str] = None  # "text" | "ocr" | None
+    text: str = ""
+    status: str = "pending"  # "pending" | "done" | "error"
+    error: Optional[str] = None
+    confidence: Optional[float] = None  # mean OCR confidence [0,1]; None for text-layer
+    lines: Optional[list] = None  # per-line [{text, confidence}] for OCR pages (else None)
+
+    def to_dict(self) -> dict:
+        return {
+            "page": self.page,
+            "source": self.source,
+            "text": self.text,
+            "status": self.status,
+            "error": self.error,
+            "confidence": self.confidence,
+            "lines": self.lines,
+        }
+
+
+@dataclass
+class Job:
+    job_id: str
+    filename: str
+    pdf_bytes: bytes
+    mode: str
+    lang: str
+    preprocess: bool
+    binarize: bool
+    handwriting: bool
+    online: bool
+    online_key: str  # NOT serialized in to_dict() — never leaked to the API
+    online_model: str
+    force_ocr: bool
+    remove_headers: bool
+    total_pages: int
+    pages: list = field(default_factory=list)  # list[PageResult]
+    status: str = "pending"  # pending|processing|done|error|cancelled
+    processed_pages: int = 0
+    error: Optional[str] = None
+
+    # Internals (not serialized). One asyncio.Queue per live SSE subscriber so
+    # progress is broadcast (fan-out), not consumed once — reconnects are safe.
+    subscribers: list = field(default_factory=list, repr=False)
+    cancel_event: "threading.Event" = field(default_factory=threading.Event, repr=False)
+    # Eviction bookkeeping (monotonic clock; immune to wall-clock changes).
+    created_at: float = field(default_factory=time.monotonic, repr=False)
+    last_access: float = field(default_factory=time.monotonic, repr=False)
+
+    def to_dict(self) -> dict:
+        return {
+            "job_id": self.job_id,
+            "filename": self.filename,
+            "status": self.status,
+            "total_pages": self.total_pages,
+            "processed_pages": self.processed_pages,
+            "pages": [p.to_dict() for p in self.pages],
+            "error": self.error,
+        }
+
+
+def _try_repair(pdf_bytes: bytes):
+    """Attempt to repair a PDF fitz can't open, using pikepdf. Returns clean
+    bytes on success, or None if repair is unavailable/failed."""
+    try:
+        import io as _io
+        import pikepdf  # optional; only used as a fallback
+
+        out = _io.BytesIO()
+        with pikepdf.open(_io.BytesIO(pdf_bytes)) as pdf:
+            pdf.save(out)
+        return out.getvalue()
+    except Exception:
+        return None
+
+
+class JobManager:
+    def __init__(self) -> None:
+        self._jobs: dict[str, Job] = {}
+        self._lock = threading.Lock()
+        # Throttle for get()-triggered sweeps (guarded by self._lock).
+        self._last_sweep: float = 0.0
+
+    # --- eviction internals --------------------------------------------------
+    @staticmethod
+    def _is_evictable(job: "Job") -> bool:
+        """A job may be evicted only if it has reached a terminal state AND has
+        no live SSE subscriber. pending/processing or subscribed jobs are never
+        touched, so eviction can't break an in-flight run or an open stream.
+
+        ``job.subscribers`` is mutated only on the event loop (events()); reading
+        its length here under self._lock is a plain, atomic CPython list read.
+        A momentarily-stale read is safe: worst case we *skip* evicting a job
+        that just lost its last subscriber, deferring it to the next sweep.
+        """
+        return job.status in _TERMINAL_STATES and not job.subscribers
+
+    def _evict_locked(self, now: float) -> None:
+        """Evict expired, then over-cap, evictable jobs. MUST hold self._lock.
+
+        1. TTL: drop evictable jobs whose last_access is older than the TTL.
+        2. Cap: if more than MAX_JOBS evictable jobs remain, drop the
+           least-recently-accessed ones until at most MAX_JOBS are left.
+        Non-evictable (active/subscribed) jobs are never removed and do not
+        count against the cap as targets — they're simply left in place.
+        """
+        self._last_sweep = now
+
+        # Pass 1 — TTL on evictable jobs.
+        if JOB_TTL_SECONDS > 0:
+            expired = [
+                jid
+                for jid, job in self._jobs.items()
+                if self._is_evictable(job)
+                and (now - job.last_access) > JOB_TTL_SECONDS
+            ]
+            for jid in expired:
+                del self._jobs[jid]
+
+        # Pass 2 — count cap on remaining evictable jobs (LRU by last_access).
+        if MAX_JOBS >= 0:
+            evictable = [
+                (job.last_access, jid)
+                for jid, job in self._jobs.items()
+                if self._is_evictable(job)
+            ]
+            overflow = len(evictable) - MAX_JOBS
+            if overflow > 0:
+                evictable.sort()  # oldest last_access first
+                for _, jid in evictable[:overflow]:
+                    job = self._jobs.get(jid)
+                    if job is not None and self._is_evictable(job):
+                        del self._jobs[jid]
+
+    def create_job(
+        self,
+        filename: str,
+        pdf_bytes: bytes,
+        *,
+        mode: str,
+        lang: str,
+        preprocess: bool,
+        binarize: bool = False,
+        handwriting: bool = False,
+        online: bool = False,
+        online_key: str = "",
+        online_model: str = "",
+        force_ocr: bool = False,
+        remove_headers: bool = True,
+    ) -> Job:
+        """Open the PDF to validate it and count pages, then register a Job.
+
+        Raises ValueError("encrypted") for password-protected PDFs and
+        ValueError(<msg>) for corrupt / unreadable PDFs.
+        """
+        usable_bytes = pdf_bytes
+        try:
+            doc = fitz.open(stream=usable_bytes, filetype="pdf")
+        except Exception as exc:  # corrupt / not a PDF — try to repair once
+            repaired = _try_repair(pdf_bytes)
+            if repaired is None:
+                raise ValueError(f"corrupt: {exc}") from exc
+            usable_bytes = repaired
+            try:
+                doc = fitz.open(stream=usable_bytes, filetype="pdf")
+            except Exception as exc2:
+                raise ValueError(f"corrupt: {exc2}") from exc2
+
+        try:
+            if doc.needs_pass:
+                raise ValueError("encrypted")
+            try:
+                total_pages = doc.page_count
+            except Exception as exc:
+                raise ValueError(f"corrupt: {exc}") from exc
+            if total_pages <= 0:
+                raise ValueError("corrupt: no pages")
+        finally:
+            doc.close()
+
+        job_id = uuid.uuid4().hex
+        job = Job(
+            job_id=job_id,
+            filename=filename,
+            pdf_bytes=usable_bytes,
+            mode=mode,
+            lang=lang,
+            preprocess=preprocess,
+            binarize=binarize,
+            handwriting=handwriting,
+            online=online,
+            online_key=online_key,
+            online_model=online_model,
+            force_ocr=force_ocr,
+            remove_headers=remove_headers,
+            total_pages=total_pages,
+            pages=[PageResult(page=i + 1) for i in range(total_pages)],
+            status="pending",
+        )
+
+        with self._lock:
+            self._evict_locked(time.monotonic())  # reclaim stale jobs first
+            self._jobs[job_id] = job
+        return job
+
+    def get(self, job_id: str) -> Optional[Job]:
+        now = time.monotonic()
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job is not None:
+                # Touch: keeps actively-used jobs (polling, image render, SSE
+                # reconnect) from aging out under the TTL.
+                job.last_access = now
+            # Throttled TTL sweep so idle sessions still reclaim memory even
+            # with no new uploads, without sweeping on every single get().
+            if now - self._last_sweep >= _SWEEP_MIN_INTERVAL:
+                self._evict_locked(now)
+            return job
+
+    @staticmethod
+    def _broadcast(job: Job, event: dict) -> None:
+        """Fan an event out to every live SSE subscriber's queue.
+
+        Runs on the event loop; queues are unbounded so put_nowait never
+        blocks. Each SSE connection drains its own queue independently.
+        """
+        for q in list(job.subscribers):
+            try:
+                q.put_nowait(event)
+            except Exception:
+                pass
+
+    async def run(self, job: Job) -> None:
+        """Process every page of the job sequentially.
+
+        Each page's extraction runs in the single-worker executor. The cancel
+        flag is checked between pages. Progress and terminal events are
+        broadcast to all subscriber queues for SSE consumption. The whole body
+        is guarded so the job always reaches a terminal state (no hung SSE).
+        """
+        loop = asyncio.get_running_loop()
+        job.status = "processing"
+
+        try:
+            # Open one document for the lifetime of the run. Do it ON the single
+            # OCR worker thread (not the event loop) so that every fitz call in
+            # the app — open, load_page, get_pixmap, close — happens on that one
+            # thread. PyMuPDF/MuPDF is not thread-safe even across separate
+            # Document objects, and concurrent multi-file uploads would otherwise
+            # let this run() open a doc on the event loop while another job
+            # renders on the worker thread.
+            try:
+                doc = await loop.run_in_executor(
+                    _EXECUTOR,
+                    lambda: fitz.open(stream=job.pdf_bytes, filetype="pdf"),
+                )
+            except Exception as exc:
+                job.status = "error"
+                job.error = f"corrupt: {exc}"
+                self._broadcast(job, {"type": "error", "error": job.error})
+                return
+
+            try:
+                for idx in range(job.total_pages):
+                    if job.cancel_event.is_set():
+                        job.status = "cancelled"
+                        self._broadcast(job, {"type": "cancelled"})
+                        return
+
+                    page_result = job.pages[idx]
+
+                    def _work(page_index: int = idx) -> dict:
+                        page = doc.load_page(page_index)
+                        return extract_page(
+                            page,
+                            mode=job.mode,
+                            lang=job.lang,
+                            preprocess=job.preprocess,
+                            binarize=job.binarize,
+                            handwriting=job.handwriting,
+                            online=job.online,
+                            online_key=job.online_key,
+                            online_model=job.online_model,
+                            force_ocr=job.force_ocr,
+                        )
+
+                    try:
+                        result = await loop.run_in_executor(_EXECUTOR, _work)
+                        page_result.source = result.get("source")
+                        page_result.text = result.get("text", "") or ""
+                        page_result.confidence = result.get("confidence")
+                        page_result.lines = result.get("lines")
+                        page_result.status = "done"
+                        page_result.error = None
+                    except Exception as exc:  # per-page failure: keep going
+                        page_result.source = None
+                        page_result.text = ""
+                        page_result.confidence = None
+                        page_result.lines = None
+                        page_result.status = "error"
+                        page_result.error = str(exc)
+
+                    job.processed_pages += 1
+
+                    self._broadcast(
+                        job,
+                        {
+                            "type": "progress",
+                            "processed": job.processed_pages,
+                            "total": job.total_pages,
+                            "page": page_result.to_dict(),
+                        },
+                    )
+
+                # Cross-page cleanup: strip running headers/footers + page
+                # numbers now that every page's text is available. Best-effort;
+                # never fail the job over it. Updated pages are re-broadcast so
+                # the live UI (and reconnect snapshot/exports) show cleaned text.
+                if job.remove_headers and not job.cancel_event.is_set():
+                    try:
+                        from pipeline.postprocess import (
+                            strip_running_headers_footers,
+                            realign_line_confidences,
+                        )
+                        originals = [p.text or "" for p in job.pages]
+                        cleaned, kept_indices = strip_running_headers_footers(
+                            originals, return_kept=True
+                        )
+                        for p, new_text, kept in zip(
+                            job.pages, cleaned, kept_indices
+                        ):
+                            if p.status == "done" and new_text != (p.text or ""):
+                                if p.lines:
+                                    # An OCR page's per-line list is 1:1 with its
+                                    # text lines, so map confidences to the EXACT
+                                    # surviving lines by their original index
+                                    # (correct even for identical-text duplicate
+                                    # lines). Fall back to the text matcher only
+                                    # if the indices don't line up with the
+                                    # cleaned text (rare blank-detection edge).
+                                    mapped = [
+                                        p.lines[i]
+                                        for i in kept
+                                        if 0 <= i < len(p.lines)
+                                    ]
+                                    if [
+                                        str(m.get("text", "")) for m in mapped
+                                    ] == new_text.split("\n"):
+                                        p.lines = mapped
+                                    else:
+                                        p.lines = realign_line_confidences(
+                                            new_text, p.lines
+                                        )
+                                p.text = new_text
+                                self._broadcast(
+                                    job,
+                                    {
+                                        "type": "progress",
+                                        "processed": job.processed_pages,
+                                        "total": job.total_pages,
+                                        "page": p.to_dict(),
+                                    },
+                                )
+                    except Exception:
+                        pass
+
+                # Completed all pages (unless cancelled above).
+                if job.cancel_event.is_set():
+                    job.status = "cancelled"
+                    self._broadcast(job, {"type": "cancelled"})
+                else:
+                    # If every page errored we still report done; the page
+                    # records carry the per-page error state. A whole-job error
+                    # is only for fatal failures handled above.
+                    job.status = "done"
+                    self._broadcast(job, {"type": "done"})
+            finally:
+                # Close on the worker thread too (same single-thread invariant),
+                # and never let a close error overwrite the terminal status.
+                try:
+                    await loop.run_in_executor(_EXECUTOR, doc.close)
+                except Exception:
+                    pass
+        except Exception as exc:  # never strand subscribers in a hung stream
+            job.status = "error"
+            job.error = str(exc)
+            self._broadcast(job, {"type": "error", "error": job.error})
+
+    def cancel(self, job_id: str) -> None:
+        job = self.get(job_id)
+        if job is not None:
+            job.cancel_event.set()
+
+    def delete(self, job_id: str) -> bool:
+        """Drop a job from the registry and request cancellation.
+
+        Removes the job from ``_jobs`` immediately (so it's no longer findable)
+        and sets its cancel flag. The PDF bytes are reclaimed once any in-flight
+        page finishes — cancellation is cooperative and checked between pages, so
+        a long page already running (e.g. a 120 s online-OCR call) keeps the
+        bytes alive until it returns. Idempotent — returns False if unknown.
+        """
+        with self._lock:
+            job = self._jobs.pop(job_id, None)
+        if job is not None:
+            job.cancel_event.set()
+            return True
+        return False
+
+    async def events(self, job_id: str):
+        """Async generator yielding SSE event dicts for a job.
+
+        On connect, replays a snapshot of every already-completed page so a
+        fresh OR reconnecting client catches up without losing progress. Then
+        streams live events from its own private subscriber queue until a
+        terminal {"type":"done"|"error"|"cancelled"} event. Duplicate page
+        events (snapshot + live) are harmless: the frontend keys pages by
+        number and re-renders idempotently.
+        """
+        job = self.get(job_id)
+        if job is None:
+            yield {"type": "error", "error": "not found"}
+            return
+
+        terminal_types = {"done", "error", "cancelled"}
+
+        # Subscribe BEFORE snapshotting so no event slips through the gap.
+        q: "asyncio.Queue" = asyncio.Queue()
+        job.subscribers.append(q)
+        try:
+            # Snapshot: replay completed pages for catch-up / reconnect.
+            for p in job.pages:
+                if p.status in ("done", "error"):
+                    yield {
+                        "type": "progress",
+                        "processed": job.processed_pages,
+                        "total": job.total_pages,
+                        "page": p.to_dict(),
+                    }
+            if job.status in terminal_types:
+                yield {"type": job.status, "error": job.error}
+                return
+
+            while True:
+                try:
+                    event = await asyncio.wait_for(q.get(), timeout=1.0)
+                except asyncio.TimeoutError:
+                    # If the job finished while we waited and our queue drained,
+                    # synthesize the terminal event so the client closes.
+                    if job.status in terminal_types and q.empty():
+                        yield {"type": job.status, "error": job.error}
+                        return
+                    continue
+
+                yield event
+                if event.get("type") in terminal_types:
+                    return
+        finally:
+            try:
+                job.subscribers.remove(q)
+            except ValueError:
+                pass
+
+    def render_page_png(self, job_id: str, page_no: int, dpi: int = 150) -> bytes:
+        """Render a 1-based page number to PNG bytes on demand."""
+        job = self.get(job_id)
+        if job is None:
+            raise KeyError("job not found")
+
+        doc = fitz.open(stream=job.pdf_bytes, filetype="pdf")
+        try:
+            if page_no < 1 or page_no > doc.page_count:
+                raise KeyError("page out of range")
+            page = doc.load_page(page_no - 1)
+            zoom = float(dpi) / 72.0
+            matrix = fitz.Matrix(zoom, zoom)
+            pix = page.get_pixmap(matrix=matrix, alpha=False)
+            return pix.tobytes("png")
+        finally:
+            doc.close()
+
+
+manager = JobManager()

pipeline/ocr_engine.py

@@ -0,0 +1,251 @@
+"""PaddleOCR engine wrapper.
+
+Caches one PaddleOCR instance per ``(lang, use_angle_cls)`` key and reuses it.
+All OCR predict calls are serialized with a threading.Lock because PaddleOCR's
+predictors are not safe to call concurrently from multiple threads.
+
+Targets the PaddleOCR 2.7.3 API:
+    PaddleOCR(use_angle_cls=<bool>, lang=<code>, show_log=False)
+    result = instance.ocr(img_bgr, cls=use_angle_cls)
+
+Result structure (PaddleOCR 2.7.x):
+    [
+        [
+            [box, (text, conf)],
+            ...
+        ]
+    ]
+where ``result[0]`` may be ``None`` when no text is detected.
+"""
+
+import threading
+
+import numpy as np
+
+
+class OCREngine:
+    """Singleton-style PaddleOCR wrapper with per-(lang, angle) caching."""
+
+    def __init__(self) -> None:
+        self._instances = {}
+        self._instances_lock = threading.Lock()
+        # Serializes all .ocr() predict calls across threads.
+        self._predict_lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Instance management
+    # ------------------------------------------------------------------
+    def _get_instance(self, lang: str, use_angle_cls: bool):
+        """Return a cached PaddleOCR instance, creating it on first use."""
+        key = (lang, bool(use_angle_cls))
+        # Fast path: already created.
+        instance = self._instances.get(key)
+        if instance is not None:
+            return instance
+
+        with self._instances_lock:
+            # Re-check inside the lock to avoid double construction.
+            instance = self._instances.get(key)
+            if instance is None:
+                # Imported lazily so importing this module is cheap and does
+                # not trigger PaddleOCR/Paddle initialization at import time.
+                from paddleocr import PaddleOCR
+
+                # Accuracy-oriented inference tuning (all valid PaddleOCR
+                # 2.7.3 args, no extra model downloads):
+                #  - det_limit_side_len 1536 (vs default 960): lets the
+                #    detector use our high-DPI render instead of shrinking it,
+                #    so small/dense text is found.
+                #  - det_db_unclip_ratio 1.8 (vs 1.5): expands detected boxes
+                #    so characters at box edges aren't clipped before recog.
+                #  - det_db_box_thresh 0.5 (vs 0.6): recovers fainter text.
+                #  - use_dilation: connects broken strokes in noisy scans.
+                instance = PaddleOCR(
+                    use_angle_cls=bool(use_angle_cls),
+                    lang=lang,
+                    show_log=False,
+                    det_limit_side_len=1536,
+                    det_limit_type="max",
+                    det_db_unclip_ratio=1.8,
+                    det_db_box_thresh=0.5,
+                    use_dilation=True,
+                )
+                self._instances[key] = instance
+            return instance
+
+    def detect_boxes(self, img_bgr: np.ndarray, *, lang: str = "en") -> list:
+        """Return text-line boxes (4-point polygons) for the image.
+
+        Used by the handwriting pipeline, which detects lines with PaddleOCR but
+        recognizes them with a handwriting model. We reuse the normal OCR call
+        and keep only its boxes — PaddleOCR 2.7.3's detection-only (``rec=False``)
+        path has a numpy truth-value bug, so we avoid it.
+        """
+        lines = self.ocr_lines(img_bgr, lang=lang, use_angle_cls=False)
+        return [line["box"] for line in lines]
+
+    def warmup(self, lang: str = "en") -> None:
+        """Preload a PaddleOCR instance (downloads weights on first run).
+
+        Called at application startup so the first real request does not pay
+        the model-load / weight-download cost. Runs a tiny dummy inference to
+        force lazy predictor initialization.
+        """
+        try:
+            # Construction (which on first run downloads model weights from the
+            # network) is the failure-prone step, so it MUST be inside the guard:
+            # a first-run download failure / corrupt model cache must not abort
+            # server startup. Lazy construction then retries on the first real
+            # OCR request, where jobs.py turns any failure into a per-page error.
+            instance = self._get_instance(lang, use_angle_cls=False)
+            dummy = np.full((32, 32, 3), 255, dtype=np.uint8)
+            with self._predict_lock:
+                instance.ocr(dummy, cls=False)
+        except Exception:
+            # Warmup is best-effort; a failure here must not crash startup.
+            pass
+
+    # ------------------------------------------------------------------
+    # OCR
+    # ------------------------------------------------------------------
+    def _run(self, img_bgr: np.ndarray, lang: str, use_angle_cls: bool):
+        """Run PaddleOCR under the predict lock and return the raw lines list.
+
+        Returns the list of ``[box, (text, conf)]`` entries (possibly empty).
+        """
+        instance = self._get_instance(lang, use_angle_cls)
+        with self._predict_lock:
+            result = instance.ocr(img_bgr, cls=bool(use_angle_cls))
+
+        if not result:
+            return []
+        page = result[0]
+        if page is None:
+            return []
+        return page
+
+    @staticmethod
+    def _line_y(box) -> float:
+        """Top-y coordinate of a detection box (4 [x, y] points)."""
+        return min(float(pt[1]) for pt in box)
+
+    @staticmethod
+    def _line_x(box) -> float:
+        """Left-x coordinate of a detection box (4 [x, y] points)."""
+        return min(float(pt[0]) for pt in box)
+
+    @staticmethod
+    def _line_height(box) -> float:
+        ys = [float(pt[1]) for pt in box]
+        return max(ys) - min(ys)
+
+    def ocr_lines(
+        self, img_bgr: np.ndarray, *, lang: str, use_angle_cls: bool
+    ) -> list:
+        """Return detected text lines in reading order.
+
+        Each element is ``{"text": str, "confidence": float, "box": list}``.
+        Lines are grouped into rows by their vertical position, and within a
+        row sorted left-to-right, approximating natural reading order.
+
+        NOTE: this assumes a SINGLE-column layout. On a multi-column scan,
+        side-by-side lines at the same vertical position are merged into one row
+        and emitted left-to-right, so the two columns come out interleaved. Real
+        column reconstruction (XY-cut / gutter detection) is not implemented yet.
+        Born-digital multi-column PDFs take the text-layer path (textlayer.py,
+        same single-column caveat) or the Gemini path.
+        """
+        raw = self._run(img_bgr, lang, use_angle_cls)
+
+        items = []
+        for entry in raw:
+            try:
+                box, payload = entry[0], entry[1]
+                text, conf = payload[0], payload[1]
+                if text is None or not box:
+                    continue
+                # Compute geometry inside the guard so a single malformed
+                # detection box is skipped rather than aborting the whole page.
+                y = self._line_y(box)
+                x = self._line_x(box)
+                h = self._line_height(box)
+            except (TypeError, IndexError, ValueError):
+                continue
+            items.append(
+                {
+                    "text": str(text),
+                    "confidence": float(conf),
+                    "box": box,
+                    "_y": y,
+                    "_x": x,
+                    "_h": h,
+                }
+            )
+
+        if not items:
+            return []
+
+        # Group items into rows: two items share a row if their top-y values
+        # are within a tolerance derived from the median glyph height.
+        heights = [it["_h"] for it in items if it["_h"] > 0]
+        median_h = float(np.median(heights)) if heights else 12.0
+        tol = max(median_h * 0.6, 6.0)
+
+        # Sort primarily by y so we can sweep rows top-to-bottom.
+        items.sort(key=lambda it: (it["_y"], it["_x"]))
+
+        rows = []
+        current = [items[0]]
+        current_y = items[0]["_y"]
+        for it in items[1:]:
+            if abs(it["_y"] - current_y) <= tol:
+                current.append(it)
+            else:
+                rows.append(current)
+                current = [it]
+                current_y = it["_y"]
+        rows.append(current)
+
+        ordered = []
+        for row in rows:
+            row.sort(key=lambda it: it["_x"])
+            for it in row:
+                ordered.append(
+                    {
+                        "text": it["text"],
+                        "confidence": it["confidence"],
+                        "box": it["box"],
+                    }
+                )
+        return ordered
+
+    def ocr_text(
+        self, img_bgr: np.ndarray, *, lang: str, use_angle_cls: bool
+    ) -> str:
+        """Return all detected text joined in reading order by newlines."""
+        text, _ = self.ocr_text_conf(
+            img_bgr, lang=lang, use_angle_cls=use_angle_cls
+        )
+        return text
+
+    def ocr_text_conf(
+        self, img_bgr: np.ndarray, *, lang: str, use_angle_cls: bool
+    ):
+        """Return ``(text, mean_confidence)`` for the image.
+
+        ``mean_confidence`` is the average per-line recognition confidence in
+        ``[0, 1]`` (or ``None`` if nothing was detected). It lets the UI flag
+        pages the OCR engine itself is unsure about.
+        """
+        lines = self.ocr_lines(
+            img_bgr, lang=lang, use_angle_cls=use_angle_cls
+        )
+        text = "\n".join(line["text"] for line in lines)
+        if not lines:
+            return text, None
+        conf = sum(line["confidence"] for line in lines) / len(lines)
+        return text, float(conf)
+
+
+# Module-level singleton.
+engine = OCREngine()

pipeline/online_ocr.py

@@ -0,0 +1,472 @@
+"""Optional ONLINE OCR via Google Gemini (handwriting + printed transcription).
+
+This is an OPT-IN, accuracy-first fallback for pages the local engines
+(PaddleOCR / TrOCR) read poorly. It sends a rendered PAGE IMAGE to Google's
+Gemini API and returns a verbatim transcription.
+
+PRIVACY: enabling this uploads page images to Google's servers — the bytes
+leave this machine. It is OFF by default and only runs when the caller passes
+a Gemini API key. Do not enable it for confidential documents you cannot send
+to a third party.
+
+SETUP: get a free API key from https://aistudio.google.com/ (Google AI Studio)
+and pass it as ``api_key`` (or wire it to a ``GEMINI_API_KEY`` env var in the
+caller). No extra pip dependency is needed: this module talks to the REST API
+with the Python standard library only (``urllib.request`` + ``json`` +
+``base64``). ``cv2`` is used to PNG-encode the OpenCV image.
+
+Importing this module performs NO network call and has no import-time side
+effects.
+"""
+
+import base64
+import json
+import urllib.error
+import urllib.request
+
+import cv2
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# Verified Gemini REST contract.
+# ---------------------------------------------------------------------------
+# Generation endpoint (non-streaming). The canonical reference path is
+# /v1beta/{model=models/*}:generateContent; the model name on the wire is
+# "models/<id>". {model} below is the BARE model id (e.g. "gemini-2.5-pro").
+_API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"
+_GENERATE_URL = _API_BASE + "/{model}:generateContent"
+
+# Auth header preferred over the legacy ?key= query param (keeps the key out of
+# URLs/logs). Header name is literally "x-goog-api-key".
+_API_KEY_HEADER = "x-goog-api-key"
+
+# Strong handwriting-capable models, FREE-TIER-FRIENDLY first. As of 2026 the
+# Pro models are NOT available on the API free tier (free-tier limit 0), so the
+# default auto-pick must be a Flash model — Flash is already excellent at
+# handwriting (benchmarked ~95% char-acc on a real cursive page). Users with
+# paid billing can still select a Pro model from the dropdown.
+SUPPORTED_MODELS = (
+    "gemini-2.5-flash",        # free-tier workhorse; strong handwriting
+    "gemini-3.5-flash",        # newer flash if the key exposes it
+    "gemini-2.5-flash-lite",   # free-tier, lighter/faster, slightly weaker
+    "gemini-3.1-flash-lite",
+    "gemini-2.5-pro",          # better accuracy but needs PAID billing (not free tier)
+    "gemini-3.1-pro-preview",
+)
+DEFAULT_MODEL = SUPPORTED_MODELS[0]
+
+# Verbatim-transcription instruction. The online path runs for ANY page that
+# needs OCR (handwritten OR printed), so this must NOT exclude printed text —
+# it covers both. Still ignores pre-printed page furniture (Date/Page stamps,
+# margin rules) which would otherwise leak into the output.
+DEFAULT_PROMPT = (
+    "Transcribe all text in this image verbatim — both printed and handwritten. "
+    "Preserve line breaks and spelling exactly; do not correct, summarize, or "
+    "add commentary. Ignore pre-printed page furniture such as 'Date'/'Page' "
+    "header labels, margin rules and ruled lines. Output only the transcription."
+)
+
+# Inline image payload cap. The TOTAL request (image + prompt, base64-expanded)
+# must stay under 20 MB; above that the Files API is required. We guard on the
+# base64 string length and surface an actionable error well before the wire.
+_MAX_INLINE_B64_BYTES = 20 * 1024 * 1024
+
+# Cap the longest image side sent to Gemini. Gemini internally tiles images
+# (~768 px tiles), so a huge 300-DPI render only inflates the upload with no
+# accuracy gain — and a multi-MB PNG over a slow connection causes "write
+# operation timed out" errors. Downscaling + JPEG keeps requests small and fast.
+_MAX_IMAGE_SIDE = 2048
+_JPEG_QUALITY = 90
+
+
+def is_configured(api_key) -> bool:
+    """True if a usable (non-empty) Gemini API key has been supplied.
+
+    Does NOT validate the key against the network — it only checks presence,
+    so calling it is free and side-effect-free.
+    """
+    return bool(api_key and str(api_key).strip())
+
+
+def _clean_key(api_key) -> str:
+    """Return the trimmed key, or raise a clean, KEY-FREE RuntimeError.
+
+    A key with an interior newline (pasted wrapped across two lines) or a
+    non-ASCII/control character would otherwise make http.client raise a raw
+    ValueError — whose message INCLUDES the full key value — or a
+    UnicodeEncodeError, neither of which subclasses HTTPError/URLError, so they
+    escape the documented "only ever raise a single-line RuntimeError" contract
+    and (for the ValueError case) echo the key into the per-page error text that
+    jobs.py broadcasts/stores. Validate up front and never put the key in the
+    message.
+    """
+    key = str(api_key).strip()
+    if not key.isascii() or any(ord(c) < 0x20 or ord(c) == 0x7F for c in key):
+        raise RuntimeError(
+            "The Gemini API key contains invalid characters (control or "
+            "non-ASCII). Re-copy it from https://aistudio.google.com/."
+        )
+    return key
+
+
+def _resolve_model(model) -> str:
+    """Return a clean bare model id, defaulting when unset.
+
+    Accepts either a bare id ("gemini-2.5-pro") or the "models/<id>" form and
+    normalizes to the bare id used in the URL placeholder.
+    """
+    name = (model or DEFAULT_MODEL).strip()
+    if name.startswith("models/"):
+        name = name[len("models/"):]
+    return name or DEFAULT_MODEL
+
+
+def _encode_image_b64(img_bgr: np.ndarray):
+    """Downscale a huge image, JPEG-encode it, return ``(base64_str, mime_type)``.
+
+    Caps the longest side at ``_MAX_IMAGE_SIDE`` and uses JPEG (much smaller than
+    PNG for scans/photos) so the request uploads quickly even on slow links.
+    """
+    if img_bgr is None or getattr(img_bgr, "size", 0) == 0:
+        raise RuntimeError(
+            "Online OCR received an empty image; nothing to transcribe."
+        )
+    h, w = img_bgr.shape[:2]
+    longest = max(h, w)
+    if longest > _MAX_IMAGE_SIDE:
+        scale = _MAX_IMAGE_SIDE / float(longest)
+        img_bgr = cv2.resize(
+            img_bgr,
+            (max(1, int(round(w * scale))), max(1, int(round(h * scale)))),
+            interpolation=cv2.INTER_AREA,
+        )
+    ok, buf = cv2.imencode(
+        ".jpg", img_bgr, [int(cv2.IMWRITE_JPEG_QUALITY), _JPEG_QUALITY]
+    )
+    if not ok:
+        raise RuntimeError(
+            "Online OCR could not encode the page image (cv2.imencode failed). "
+            "Check that the image is a valid HxWx3 uint8 array."
+        )
+    # Standard base64 of the raw JPEG file bytes — NOT a data: URI.
+    return base64.standard_b64encode(buf.tobytes()).decode("ascii"), "image/jpeg"
+
+
+def _build_request_body(image_b64: str, mime_type: str, prompt: str) -> dict:
+    """Assemble the generateContent request body per the verified contract."""
+    return {
+        "contents": [
+            {
+                "parts": [
+                    {
+                        "inline_data": {
+                            "mime_type": mime_type,
+                            "data": image_b64,
+                        }
+                    },
+                    {"text": prompt},
+                ]
+            }
+        ],
+        "generationConfig": {
+            "temperature": 0,
+            "responseMimeType": "text/plain",
+        },
+    }
+
+
+def _extract_text(payload: dict) -> str:
+    """Pull the transcription out of a generateContent response.
+
+    Concatenates the ``text`` of every part in ``candidates[0].content.parts``
+    (text output can be split across parts). Raises an actionable RuntimeError
+    when the response carries no usable text — e.g. a prompt-level block
+    (``promptFeedback.blockReason``) or a non-STOP ``finishReason`` such as
+    SAFETY / MAX_TOKENS / RECITATION.
+    """
+    # Prompt blocked before any candidate was produced.
+    feedback = payload.get("promptFeedback") or {}
+    block_reason = feedback.get("blockReason")
+    candidates = payload.get("candidates") or []
+    if not candidates:
+        if block_reason:
+            raise RuntimeError(
+                "Gemini blocked the request (promptFeedback.blockReason="
+                "{}). The page image or prompt tripped a safety filter; "
+                "online OCR is unavailable for this page.".format(block_reason)
+            )
+        raise RuntimeError(
+            "Gemini returned no candidates and no text. The response was "
+            "empty; try again or switch models."
+        )
+
+    candidate = candidates[0] or {}
+    finish_reason = candidate.get("finishReason")
+    content = candidate.get("content") or {}
+    parts = content.get("parts") or []
+    # ``part.get("text", "")`` only defaults when the key is ABSENT; an explicit
+    # ``{"text": null}`` would yield None and break the join. Coerce defensively.
+    text = "".join(
+        str(part.get("text") or "") for part in parts if isinstance(part, dict)
+    )
+
+    if not text.strip():
+        if finish_reason and finish_reason != "STOP":
+            raise RuntimeError(
+                "Gemini produced no text (finishReason={}). This usually "
+                "means the output was cut off (MAX_TOKENS) or filtered "
+                "(SAFETY/RECITATION); try a different page or model.".format(
+                    finish_reason
+                )
+            )
+        raise RuntimeError(
+            "Gemini returned an empty transcription for this page."
+        )
+
+    # On a clean STOP we return the text as-is; if truncated but non-empty we
+    # still return what we have (a partial transcription beats failing hard).
+    return text
+
+
+def _friendly_http_error(err: urllib.error.HTTPError) -> RuntimeError:
+    """Translate an HTTPError into an actionable RuntimeError.
+
+    Reads the JSON ``error`` body (code/message/status) to surface the API's
+    own message and maps the common status codes to plain guidance.
+    """
+    code = err.code
+    api_message = ""
+    api_status = ""
+    try:
+        raw = err.read()
+        if raw:
+            body = json.loads(raw.decode("utf-8", "replace"))
+            error_obj = body.get("error") or {}
+            api_message = str(error_obj.get("message") or "").strip()
+            api_status = str(error_obj.get("status") or "").strip()
+    except Exception:
+        # Body wasn't JSON or couldn't be read; fall back to the status code.
+        pass
+
+    detail = api_message or err.reason or "no detail provided"
+
+    if code in (401, 403):
+        return RuntimeError(
+            "Gemini rejected the API key (HTTP {} {}): {}. Check that "
+            "GEMINI_API_KEY is a valid, enabled key from "
+            "https://aistudio.google.com/ and has access to this model."
+            .format(code, api_status or "PERMISSION_DENIED", detail)
+        )
+    if code == 429:
+        return RuntimeError(
+            "Gemini rate limit / quota exceeded (HTTP 429 {}): {}. Slow down "
+            "requests, wait and retry, switch to a lighter model, or request "
+            "a quota increase in Google AI Studio."
+            .format(api_status or "RESOURCE_EXHAUSTED", detail)
+        )
+    if code == 400:
+        return RuntimeError(
+            "Gemini rejected the request (HTTP 400 {}): {}. This is usually a "
+            "malformed body, an unsupported model id, or (FAILED_PRECONDITION) "
+            "billing not enabled for your region."
+            .format(api_status or "INVALID_ARGUMENT", detail)
+        )
+    if code == 404:
+        return RuntimeError(
+            "Gemini model or resource not found (HTTP 404 {}): {}. Check the "
+            "model id ({}).".format(
+                api_status or "NOT_FOUND", detail, ", ".join(SUPPORTED_MODELS)
+            )
+        )
+    if code in (500, 503, 504):
+        return RuntimeError(
+            "Gemini server error (HTTP {} {}): {}. The service is overloaded "
+            "or timed out; retry in a moment or switch to another model."
+            .format(code, api_status or "UNAVAILABLE", detail)
+        )
+    return RuntimeError(
+        "Gemini request failed (HTTP {} {}): {}.".format(
+            code, api_status or "ERROR", detail
+        )
+    )
+
+
+def list_models(api_key, *, timeout=30) -> list:
+    """Validate the key and return available bare model ids (no network on import).
+
+    Calls ``GET /v1beta/models`` and returns the bare ids (``models/`` prefix
+    stripped) of models that support ``generateContent``. Doubles as a cheap
+    key-validation call for the UI. Raises an actionable RuntimeError on a bad
+    key / network failure, mirroring ``transcribe_image_bgr``.
+    """
+    if not is_configured(api_key):
+        raise RuntimeError(
+            "Online OCR needs a Gemini API key but none was provided. Get a "
+            "free key from https://aistudio.google.com/."
+        )
+    api_key = _clean_key(api_key)
+    request = urllib.request.Request(
+        _API_BASE,  # GET https://generativelanguage.googleapis.com/v1beta/models
+        method="GET",
+        headers={_API_KEY_HEADER: api_key},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read()
+    except urllib.error.HTTPError as err:
+        raise _friendly_http_error(err) from None
+    except urllib.error.URLError as err:
+        raise RuntimeError(
+            "Could not reach the Gemini API ({}). Check your internet "
+            "connection.".format(err.reason)
+        ) from None
+    except TimeoutError:
+        raise RuntimeError(
+            "The Gemini request timed out after {}s.".format(timeout)
+        ) from None
+    try:
+        payload = json.loads(raw.decode("utf-8", "replace"))
+    except (ValueError, AttributeError) as err:
+        raise RuntimeError(
+            "Gemini returned a non-JSON model list ({}).".format(err)
+        ) from None
+    if not isinstance(payload, dict):
+        raise RuntimeError(
+            "Gemini returned an unexpected model-list response (not a JSON object)."
+        )
+
+    out = []
+    for entry in payload.get("models") or []:
+        if not isinstance(entry, dict):
+            continue
+        methods = entry.get("supportedGenerationMethods") or []
+        if methods and "generateContent" not in methods:
+            continue
+        name = str(entry.get("name") or "")
+        if name.startswith("models/"):
+            name = name[len("models/"):]
+        if name:
+            out.append(name)
+    return out
+
+
+def best_available_model(available) -> str:
+    """Pick the strongest handwriting model we support that the key can access.
+
+    Falls back to :data:`DEFAULT_MODEL` if none of ``available`` is recognized.
+    """
+    avail = set(available or ())
+    for m in SUPPORTED_MODELS:
+        if m in avail:
+            return m
+    return DEFAULT_MODEL
+
+
+def transcribe_image_bgr(
+    img_bgr: np.ndarray,
+    *,
+    api_key,
+    model=None,
+    prompt=None,
+    timeout=120,
+) -> str:
+    """Transcribe an OpenCV BGR page image with Gemini and return the text.
+
+    Parameters
+    ----------
+    img_bgr : np.ndarray
+        An OpenCV ``HxWx3`` BGR ``uint8`` image (a rendered PDF page).
+    api_key : str
+        A Gemini API key from https://aistudio.google.com/. Required.
+    model : str, optional
+        A model id from :data:`SUPPORTED_MODELS` (bare id or "models/<id>").
+        Defaults to :data:`DEFAULT_MODEL`.
+    prompt : str, optional
+        Override the verbatim-transcription instruction
+        (:data:`DEFAULT_PROMPT`).
+    timeout : float, optional
+        Per-request socket timeout in seconds (default 120).
+
+    Returns
+    -------
+    str
+        The verbatim transcription (line breaks preserved).
+
+    Raises
+    ------
+    RuntimeError
+        With an actionable, single-line message (never a raw stack trace) for
+        a missing/empty key, an invalid key, a rate limit, a network/timeout
+        failure, or an empty/safety-blocked response.
+    """
+    if not is_configured(api_key):
+        raise RuntimeError(
+            "Online OCR needs a Gemini API key but none was provided. Get a "
+            "free key from https://aistudio.google.com/ and pass it as the "
+            "api_key argument (or set GEMINI_API_KEY)."
+        )
+
+    api_key = _clean_key(api_key)
+    model_id = _resolve_model(model)
+    prompt_text = prompt if (prompt and prompt.strip()) else DEFAULT_PROMPT
+
+    image_b64, mime_type = _encode_image_b64(img_bgr)
+    if len(image_b64) > _MAX_INLINE_B64_BYTES:
+        raise RuntimeError(
+            "Page image is too large for an inline Gemini request "
+            "(~{:.1f} MB base64; the 20 MB inline limit applies to the whole "
+            "request). Render the page at a lower DPI, or use Gemini's Files "
+            "API for payloads this big.".format(
+                len(image_b64) / (1024 * 1024)
+            )
+        )
+
+    body = _build_request_body(image_b64, mime_type, prompt_text)
+    data = json.dumps(body).encode("utf-8")
+    url = _GENERATE_URL.format(model=model_id)
+
+    request = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            _API_KEY_HEADER: api_key,  # already cleaned/validated above
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read()
+    except urllib.error.HTTPError as err:
+        # Non-2xx: surface the API's own error message via a friendly mapping.
+        raise _friendly_http_error(err) from None
+    except urllib.error.URLError as err:
+        # DNS failure, connection refused, TLS error, or a socket timeout
+        # (which arrives wrapped as URLError(reason=timeout)).
+        raise RuntimeError(
+            "Could not reach the Gemini API ({}). Check your internet "
+            "connection and that generativelanguage.googleapis.com is "
+            "reachable; the request may also have timed out (timeout={}s)."
+            .format(err.reason, timeout)
+        ) from None
+    except TimeoutError as err:  # bare socket timeout on some Python versions
+        raise RuntimeError(
+            "The Gemini request timed out after {}s. Try a smaller image, a "
+            "lighter model, or a longer timeout.".format(timeout)
+        ) from None
+
+    try:
+        payload = json.loads(raw.decode("utf-8", "replace"))
+    except (ValueError, AttributeError) as err:
+        raise RuntimeError(
+            "Gemini returned a response that was not valid JSON ({}). The "
+            "service may be having problems; retry shortly.".format(err)
+        ) from None
+    if not isinstance(payload, dict):
+        raise RuntimeError(
+            "Gemini returned an unexpected response (not a JSON object); "
+            "retry shortly."
+        )
+
+    return _extract_text(payload)

pipeline/postprocess.py

@@ -0,0 +1,176 @@
+"""Cross-page cleanup: strip running headers / footers and page numbers.
+
+Operates on the FULL list of per-page texts after extraction. A line is treated
+as a running header/footer only if a normalized version of it recurs in the top
+OR bottom band of a strong majority of pages — and it is removed ONLY from that
+band, never from a page body.
+
+Safety properties (each guards a real failure mode found in review):
+  * The top and bottom bands are DISJOINT and capped at half the page's
+    non-blank lines, so on short/sparse pages a body line can never be counted
+    as both header and footer (which previously emptied invoice/form pages).
+  * Digit normalization (so "Page 1"/"Page 2"/bare "12" match) is applied ONLY
+    to page-number-like lines; every other line is compared verbatim, so a
+    numbered heading ("Section 3 …") or a numeric data row ("Total: 1,234.56")
+    is never collapsed and stripped.
+  * A line must recur on a strong majority of pages (default 70%), so a real
+    heading that merely repeats on a couple of pages of a short doc is kept.
+  * A page is never reduced to nothing: if every candidate line would be
+    stripped, the page is left untouched.
+  * No-ops entirely on documents with fewer than ``min_pages`` pages.
+"""
+
+import math
+import re
+from collections import Counter
+
+_DIGITS = re.compile(r"\d+")
+_WS = re.compile(r"\s+")
+# Words that commonly accompany a page number ("Page 1 of 10", "pg. 3").
+_PAGEWORDS = re.compile(r"\b(?:page|pg|p|of|no)\b")
+
+
+def _key(line: str) -> str:
+    """Normalized match key.
+
+    Page-number-like lines (only page-words + digits + punctuation remain) get
+    their digits mapped to ``#`` so "Page 1"/"Page 2"/bare "12" all match. Every
+    other line is compared verbatim — so numbered headings and numeric data rows
+    are NOT collapsed together and erased.
+
+    The digit→``#`` collapse is gated to lines that are *plausibly a page
+    number*: at most ONE digit group, OR an explicit page-word ("Page", "of",
+    …). A bare MULTI-group value — an ISO date ``2026-06-01`` (``#-#-#``), a
+    currency amount ``1,234.56`` (``#,#.#``), a numeric code — is genuinely
+    distinct per page; collapsing its skeleton would let the recurrence test
+    delete real data from every page (e.g. a per-page date header or an invoice
+    amount footer). Those are compared verbatim so they are never stripped.
+    """
+    base = _WS.sub(" ", line.strip().lower()).strip()
+    probe = re.sub(r"[^\w\s]", "", _PAGEWORDS.sub(" ", base))
+    if _DIGITS.sub("", probe).strip() == "":  # nothing but page-words + digits
+        if len(_DIGITS.findall(base)) <= 1 or _PAGEWORDS.search(base):
+            return _WS.sub(" ", _DIGITS.sub("#", base)).strip()
+    return base
+
+
+def realign_line_confidences(cleaned_text, orig_lines):
+    """Map a stripped page's surviving lines back to their confidences.
+
+    Stripping only REMOVES whole lines (it never edits or reorders the survivors),
+    so a two-pointer walk over the original per-line list recovers each surviving
+    line's confidence. Returns a new ``[{text, confidence}]`` list aligned to
+    ``cleaned_text`` (lines that can't be matched get ``confidence=None``), or
+    ``None`` if there were no original lines.
+    """
+    if not orig_lines:
+        return None
+    cleaned = (cleaned_text or "").split("\n")
+    out, oi = [], 0
+    for cl in cleaned:
+        while oi < len(orig_lines) and (orig_lines[oi].get("text", "") != cl):
+            oi += 1
+        if oi < len(orig_lines):
+            out.append(orig_lines[oi])
+            oi += 1
+        else:
+            out.append({"text": cl, "confidence": None})
+    return out
+
+
+def _bands(nonblank, band):
+    """Disjoint (top, bottom) index lists, capped at half the non-blank lines.
+
+    Capping at ``len // 2`` guarantees the two bands never share an index, so
+    the page interior is never a header/footer candidate.
+    """
+    b = min(band, len(nonblank) // 2)
+    if b <= 0:
+        return [], []
+    return nonblank[:b], nonblank[len(nonblank) - b:]
+
+
+def strip_running_headers_footers(
+    page_texts,
+    *,
+    band: int = 3,
+    min_frac: float = 0.7,
+    min_pages: int = 3,
+    return_kept: bool = False,
+):
+    """Return cleaned copies of ``page_texts`` with running headers/footers gone.
+
+    Parameters
+    ----------
+    page_texts : list[str]
+        One extracted-text string per page, in page order.
+    band : int
+        Max non-blank lines at the top and bottom of each page to consider as
+        header/footer candidates (capped per page so top/bottom never overlap).
+    min_frac : float
+        A line must recur in its band on at least ``ceil(min_frac * n_pages)``
+        pages (min 2) to count as a running header/footer.
+    min_pages : int
+        Documents shorter than this are returned unchanged.
+    return_kept : bool
+        If True, return ``(cleaned_texts, kept_indices)`` where
+        ``kept_indices[p]`` is the list of ORIGINAL line indices (into
+        ``page_texts[p].split("\\n")``) that survived on page ``p``. This lets a
+        caller realign per-line metadata (OCR confidences) to the EXACT
+        surviving line — re-deriving the mapping by text equality misbinds
+        identical-text duplicate lines. Default False keeps the legacy
+        list-of-strings return.
+    """
+    n = len(page_texts)
+
+    def _all_indices():
+        return [list(range(len((t or "").split("\n")))) for t in page_texts]
+
+    if n < min_pages:
+        cleaned = list(page_texts)
+        return (cleaned, _all_indices()) if return_kept else cleaned
+
+    pages_lines = []
+    for txt in page_texts:
+        lines = (txt or "").split("\n")
+        nonblank = [i for i, ln in enumerate(lines) if ln.strip()]
+        pages_lines.append((lines, nonblank))
+
+    top_counter, bot_counter = Counter(), Counter()
+    for lines, nonblank in pages_lines:
+        top, bot = _bands(nonblank, band)
+        for k in {_key(lines[i]) for i in top}:
+            if k:
+                top_counter[k] += 1
+        for k in {_key(lines[i]) for i in bot}:
+            if k:
+                bot_counter[k] += 1
+
+    thresh = max(2, math.ceil(min_frac * n))
+    running_top = {k for k, c in top_counter.items() if c >= thresh}
+    running_bot = {k for k, c in bot_counter.items() if c >= thresh}
+    if not running_top and not running_bot:
+        cleaned = list(page_texts)
+        return (cleaned, _all_indices()) if return_kept else cleaned
+
+    out, kept_all = [], []
+    for lines, nonblank in pages_lines:
+        top, bot = _bands(nonblank, band)
+        strip_idx = set()
+        for i in top:
+            if _key(lines[i]) in running_top:
+                strip_idx.add(i)
+        for i in bot:
+            if _key(lines[i]) in running_bot:
+                strip_idx.add(i)
+        # Never reduce a page to nothing — if everything would go, keep it as-is.
+        if nonblank and set(nonblank).issubset(strip_idx):
+            out.append("\n".join(lines).strip("\n"))
+            kept_all.append(list(range(len(lines))))  # nothing actually removed
+            continue
+        kept_idx = [i for i in range(len(lines)) if i not in strip_idx]
+        kept = [lines[i] for i in kept_idx]
+        cleaned = re.sub(r"\n{3,}", "\n\n", "\n".join(kept).strip("\n"))
+        out.append(cleaned)
+        kept_all.append(kept_idx)
+    return (out, kept_all) if return_kept else out

pipeline/preprocess.py

@@ -0,0 +1,172 @@
+"""Image preprocessing utilities for the OCR pipeline.
+
+All functions operate on OpenCV-style ndarrays. ``preprocess_image`` always
+returns a 3-channel BGR uint8 image so that PaddleOCR accepts it directly.
+"""
+
+import cv2
+import numpy as np
+
+
+def estimate_skew_angle(gray: np.ndarray) -> float:
+    """Estimate the page skew angle (degrees) of a 2D uint8 grayscale image.
+
+    Uses the minimum-area rectangle enclosing the foreground (dark) pixels and
+    the OpenCV >= 4.5 angle convention (0, 90]. Clamped to ``[-15, 15]``; returns
+    ``0.0`` when there isn't enough foreground to estimate reliably.
+    """
+    if gray is None or gray.ndim != 2:
+        return 0.0
+    if gray.dtype != np.uint8:
+        gray = gray.astype(np.uint8)
+    h, w = gray.shape[:2]
+    if h == 0 or w == 0:
+        return 0.0
+
+    # Otsu on the inverted image: dark glyph pixels become nonzero coordinates.
+    _, thresh = cv2.threshold(
+        gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU
+    )
+    coords = cv2.findNonZero(thresh)
+    if coords is None or len(coords) < 10:
+        return 0.0
+
+    angle = cv2.minAreaRect(coords)[-1]
+    # OpenCV >= 4.5 returns the angle in (0, 90]; map to a small signed
+    # deviation from horizontal in (-45, 45].
+    if angle > 45:
+        angle -= 90.0
+    return float(max(-15.0, min(15.0, angle)))
+
+
+def _rotate(gray: np.ndarray, angle: float) -> np.ndarray:
+    """Rotate a 2D grayscale image by ``angle`` degrees, white-filling borders."""
+    h, w = gray.shape[:2]
+    rot_mat = cv2.getRotationMatrix2D((w / 2.0, h / 2.0), angle, 1.0)
+    return cv2.warpAffine(
+        gray, rot_mat, (w, h),
+        flags=cv2.INTER_CUBIC,
+        borderMode=cv2.BORDER_CONSTANT,
+        borderValue=255,
+    )
+
+
+def deskew(gray: np.ndarray) -> np.ndarray:
+    """Estimate and correct small page skew on a 2D uint8 grayscale image.
+
+    Only small angles are corrected (estimate clamped to ``[-15, 15]``) to avoid
+    catastrophic rotations on noisy inputs. Rotation fills exposed borders white.
+    """
+    if gray is None or gray.ndim != 2:
+        raise ValueError("deskew expects a 2D grayscale uint8 array")
+    if gray.dtype != np.uint8:
+        gray = gray.astype(np.uint8)
+    if gray.shape[0] == 0 or gray.shape[1] == 0:
+        return gray
+
+    angle = estimate_skew_angle(gray)
+    if abs(angle) < 0.1:
+        return gray
+    return _rotate(gray, angle)
+
+
+def _sauvola_binarize(gray: np.ndarray) -> np.ndarray:
+    """Binarize a grayscale image with Sauvola's local thresholding.
+
+    Sauvola adapts the threshold per-pixel using the local mean and standard
+    deviation, which handles uneven lighting and faint text far better than a
+    single global or simple adaptive-Gaussian threshold — the usual choice for
+    document OCR. Falls back to adaptive-Gaussian if scikit-image is missing.
+    """
+    try:
+        from skimage.filters import threshold_sauvola
+
+        # window_size must be odd; 25 suits body text at ~300 DPI.
+        thresh = threshold_sauvola(gray, window_size=25, k=0.2)
+        binary = (gray > thresh).astype(np.uint8) * 255
+        return binary
+    except Exception:
+        return cv2.adaptiveThreshold(
+            gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+            cv2.THRESH_BINARY, blockSize=31, C=15,
+        )
+
+
+def preprocess_image(
+    img_bgr: np.ndarray, *, mode: str, binarize: bool
+) -> np.ndarray:
+    """Preprocess a BGR image for OCR and return a 3-channel BGR uint8 image.
+
+    Steps (in order):
+      1. Convert to grayscale.
+      2. Deskew (small-angle correction with white border).
+      3. CLAHE contrast equalization (rescues faint / unevenly-lit scans).
+      4. Denoise via ``cv2.fastNlMeansDenoising`` ONLY when ``mode == "max"``.
+      5. Sauvola binarization ONLY when ``binarize`` is True.
+      6. Pad a white border so text touching the page edge is still detected.
+
+    The result is always converted back to 3-channel BGR so PaddleOCR accepts
+    it; this function never returns a 2D array.
+
+    Parameters
+    ----------
+    img_bgr:
+        HxWx3 BGR uint8 image.
+    mode:
+        ``"max"`` or ``"fast"``.
+    binarize:
+        Whether to apply Sauvola binarization.
+    """
+    if img_bgr is None:
+        raise ValueError("preprocess_image received None")
+
+    if img_bgr.dtype != np.uint8:
+        img_bgr = img_bgr.astype(np.uint8)
+
+    # 1. Grayscale.
+    if img_bgr.ndim == 2:
+        gray = img_bgr
+    elif img_bgr.ndim == 3 and img_bgr.shape[2] == 3:
+        gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2GRAY)
+    elif img_bgr.ndim == 3 and img_bgr.shape[2] == 4:
+        gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGRA2GRAY)
+    else:
+        raise ValueError("preprocess_image expects a BGR(A) or grayscale image")
+
+    # 2. Deskew — estimate the angle once so we can both correct it and decide
+    #    whether sharpening is safe below.
+    skew = estimate_skew_angle(gray)
+    if abs(skew) >= 0.1:
+        gray = _rotate(gray, skew)
+
+    # 3. CLAHE — local contrast equalization. Mild clip so clean renders are
+    #    barely touched while faint/grey scans get a real lift.
+    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+    gray = clahe.apply(gray)
+
+    # 4. Denoise (only in max mode — it is the slow step).
+    if mode == "max":
+        gray = cv2.fastNlMeansDenoising(gray, h=10)
+
+    # 4b. Unsharp-mask sharpening to crisp thin strokes — improves glyph
+    #     separation (e.g. capital "I" vs lowercase "l") on soft scans, which
+    #     measurably helped a real ID-card scan. ONLY when the page is near-flat:
+    #     on a heavily-skewed page, deskew's rotation leaves interpolation blur
+    #     that sharpening would amplify, hurting recognition. Benchmarked: gated
+    #     this way it helps flat scans with no regression on rotated pages.
+    if abs(skew) < 4.0:
+        _blur = cv2.GaussianBlur(gray, (0, 0), 3)
+        gray = cv2.addWeighted(gray, 1.5, _blur, -0.5, 0)
+
+    # 5. Sauvola binarize (only when requested).
+    if binarize:
+        gray = _sauvola_binarize(gray)
+
+    # 6. White border padding so edge-touching text isn't clipped by detection.
+    gray = cv2.copyMakeBorder(
+        gray, 16, 16, 16, 16, cv2.BORDER_CONSTANT, value=255
+    )
+
+    # Always return 3-channel BGR uint8.
+    bgr = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)
+    return bgr

pipeline/textlayer.py

@@ -0,0 +1,75 @@
+"""PyMuPDF text-layer extraction with reading-order reconstruction.
+
+These helpers operate on ``fitz.Page`` objects. ``has_text_layer`` decides
+whether the embedded text layer is rich enough to use directly, and
+``extract_text_layer`` reconstructs paragraphs in natural reading order from
+the page's structured ``"dict"`` output.
+"""
+
+
+def has_text_layer(page, *, min_chars: int = 50) -> bool:
+    """Return True if the page's text layer has enough alphanumeric content.
+
+    Counts alphanumeric characters in the stripped text layer and compares
+    against ``min_chars``. Whitespace and punctuation-only layers (common in
+    scanned PDFs with stray marks) are treated as having no usable text.
+    """
+    try:
+        text = page.get_text("text") or ""
+    except Exception:
+        return False
+
+    alnum = sum(1 for ch in text if ch.isalnum())
+    return alnum >= min_chars
+
+
+def extract_text_layer(page) -> str:
+    """Reconstruct page text in reading order from the structured dict.
+
+    Blocks are sorted by their bounding box ``(y0, x0)``. Within each block,
+    line order is preserved and the spans of a line are concatenated. Lines are
+    joined by ``"\n"`` and blocks are separated by ``"\n\n"`` to approximate
+    paragraph structure.
+
+    NOTE: the flat ``(y0, x0)`` sort assumes a SINGLE-column layout. On a
+    multi-column page, blocks at similar vertical positions in different columns
+    interleave, so the reconstructed text zig-zags between columns (every
+    character is captured, but the reading order is scrambled). Column-aware
+    reordering is not implemented yet.
+    """
+    try:
+        data = page.get_text("dict")
+    except Exception:
+        return ""
+
+    blocks = data.get("blocks", []) if isinstance(data, dict) else []
+
+    text_blocks = []
+    for block in blocks:
+        # Only text blocks have "lines"; image blocks (type 1) are skipped.
+        if block.get("type", 0) != 0:
+            continue
+        lines = block.get("lines")
+        if not lines:
+            continue
+
+        bbox = block.get("bbox", [0.0, 0.0, 0.0, 0.0])
+        y0 = float(bbox[1]) if len(bbox) > 1 else 0.0
+        x0 = float(bbox[0]) if len(bbox) > 0 else 0.0
+        text_blocks.append((y0, x0, lines))
+
+    # Sort blocks top-to-bottom, then left-to-right.
+    text_blocks.sort(key=lambda b: (b[0], b[1]))
+
+    block_texts = []
+    for _y0, _x0, lines in text_blocks:
+        line_texts = []
+        for line in lines:
+            spans = line.get("spans", [])
+            line_str = "".join(span.get("text", "") for span in spans)
+            line_texts.append(line_str)
+        block_str = "\n".join(line_texts).strip("\n")
+        if block_str.strip():
+            block_texts.append(block_str)
+
+    return "\n\n".join(block_texts)

requirements.txt

@@ -0,0 +1,12 @@
+paddleocr==2.7.3
+paddlepaddle==2.6.2
+pymupdf==1.24.9
+opencv-python-headless==4.10.0.84
+numpy==1.26.4
+scikit-image==0.25.2
+pillow==10.4.0
+fastapi==0.111.1
+uvicorn==0.30.3
+python-multipart==0.0.9
+python-docx==1.2.0
+pikepdf==10.8.0

static/app.js

@@ -0,0 +1,1114 @@
+"use strict";
+
+/* ============================================================
+   Local PDF Extractor — frontend logic (dependency-free)
+   ============================================================ */
+
+(function () {
+  // ---------- State ----------
+  const settings = { mode: "max", lang: "en", preprocess: true, binarize: false, handwriting: false, online: false, online_key: "", online_model: "", force_ocr: false, remove_headers: true };
+
+  // jobId -> { jobId, filename, totalPages, status, pages: Map<pageNo, pageData>,
+  //            el: {...}, source, es: EventSource }
+  const jobs = new Map();
+  let jobOrder = []; // preserve display order
+
+  // OCR lines below this confidence are highlighted as "to check".
+  const LOWCONF_THRESH = 0.85;
+
+  // ---------- Element refs ----------
+  const $ = (id) => document.getElementById(id);
+
+  const modeToggle = $("modeToggle");
+  const modeHint = $("modeHint");
+  const langSelect = $("langSelect");
+  const preprocessToggle = $("preprocessToggle");
+  const binarizeToggle = $("binarizeToggle");
+  const forceOcrToggle = $("forceOcrToggle");
+  const removeHeadersToggle = $("removeHeadersToggle");
+  const handwritingToggle = $("handwritingToggle");
+  const onlineToggle = $("onlineToggle");
+  const onlineRow = $("onlineRow");
+  const onlineKey = $("onlineKey");
+  const onlineCheck = $("onlineCheck");
+  const onlineStatus = $("onlineStatus");
+  const onlineModel = $("onlineModel");
+  const dropzone = $("dropzone");
+  const fileInput = $("fileInput");
+  const toolbar = $("toolbar");
+  const emptyState = $("emptyState");
+  const filesContainer = $("filesContainer");
+  const searchInput = $("searchInput");
+  const searchCount = $("searchCount");
+  const copyAllBtn = $("copyAllBtn");
+  const toast = $("toast");
+
+  const fileCardTpl = $("fileCardTemplate");
+  const pageCardTpl = $("pageCardTemplate");
+
+  // ---------- Settings UI ----------
+  modeToggle.addEventListener("click", (e) => {
+    const btn = e.target.closest(".seg");
+    if (!btn) return;
+    settings.mode = btn.dataset.mode;
+    modeToggle.querySelectorAll(".seg").forEach((b) => {
+      const active = b === btn;
+      b.classList.toggle("active", active);
+      b.setAttribute("aria-checked", active ? "true" : "false");
+    });
+    modeHint.textContent =
+      settings.mode === "max"
+        ? "Max accuracy is slower but renders at higher DPI and uses angle correction."
+        : "Faster mode renders at lower DPI and skips angle correction — quicker, slightly less accurate.";
+  });
+
+  langSelect.addEventListener("change", () => {
+    settings.lang = langSelect.value;
+  });
+
+  preprocessToggle.addEventListener("change", () => {
+    settings.preprocess = preprocessToggle.checked;
+    // Binarize only makes sense when preprocessing is on.
+    binarizeToggle.disabled = !preprocessToggle.checked;
+  });
+
+  binarizeToggle.addEventListener("change", () => {
+    settings.binarize = binarizeToggle.checked;
+  });
+
+  if (forceOcrToggle) {
+    forceOcrToggle.addEventListener("change", () => {
+      settings.force_ocr = forceOcrToggle.checked;
+    });
+  }
+
+  if (removeHeadersToggle) {
+    settings.remove_headers = removeHeadersToggle.checked;
+    removeHeadersToggle.addEventListener("change", () => {
+      settings.remove_headers = removeHeadersToggle.checked;
+    });
+  }
+
+  handwritingToggle.addEventListener("change", () => {
+    settings.handwriting = handwritingToggle.checked;
+  });
+
+  // ---------- Online vision OCR (Gemini, opt-in) ----------
+  const ONLINE_KEY_LS = "pdfx_gemini_key";
+  const ONLINE_MODEL_LS = "pdfx_gemini_model";
+
+  if (onlineToggle) {
+    // Restore a previously saved key/model (stored only in this browser).
+    try {
+      const savedKey = localStorage.getItem(ONLINE_KEY_LS) || "";
+      if (savedKey) {
+        onlineKey.value = savedKey;
+        settings.online_key = savedKey;
+      }
+      const savedModel = localStorage.getItem(ONLINE_MODEL_LS) || "";
+      if (savedModel) settings.online_model = savedModel;
+    } catch (_) {}
+
+    // Pre-populate the model dropdown with free-tier-friendly defaults so a
+    // model is always selectable, even before "Check key" runs (clicking
+    // "Check key" then refines the list to exactly what your key can use).
+    populateModels(["gemini-2.5-flash", "gemini-2.5-flash-lite"], "gemini-2.5-flash");
+
+    onlineToggle.addEventListener("change", () => {
+      settings.online = onlineToggle.checked;
+      onlineRow.hidden = !onlineToggle.checked;
+    });
+
+    onlineKey.addEventListener("input", () => {
+      settings.online_key = onlineKey.value.trim();
+      try {
+        localStorage.setItem(ONLINE_KEY_LS, settings.online_key);
+      } catch (_) {}
+      setOnlineStatus("", "");
+    });
+
+    onlineModel.addEventListener("change", () => {
+      settings.online_model = onlineModel.value;
+      try {
+        localStorage.setItem(ONLINE_MODEL_LS, settings.online_model);
+      } catch (_) {}
+    });
+
+    onlineCheck.addEventListener("click", checkOnlineKey);
+  }
+
+  function setOnlineStatus(msg, kind) {
+    if (!onlineStatus) return;
+    onlineStatus.textContent = msg;
+    onlineStatus.className = "online-status" + (kind ? " " + kind : "");
+  }
+
+  async function checkOnlineKey() {
+    const key = (onlineKey.value || "").trim();
+    if (!key) {
+      setOnlineStatus("Enter a key first.", "bad");
+      return;
+    }
+    onlineCheck.disabled = true;
+    setOnlineStatus("Checking…", "");
+    const form = new FormData();
+    form.append("api_key", key);
+    try {
+      const res = await fetch("/api/online/validate", { method: "POST", body: form });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        setOnlineStatus(data.detail ? shortErr(data.detail) : "Key check failed.", "bad");
+        return;
+      }
+      const models = data.supported && data.supported.length ? data.supported : [];
+      populateModels(models, data.recommended);
+      setOnlineStatus("✓ Key works · " + (models.length || "?") + " model(s)", "good");
+    } catch (e) {
+      setOnlineStatus("Network error checking key.", "bad");
+    } finally {
+      onlineCheck.disabled = false;
+    }
+  }
+
+  function populateModels(models, recommended) {
+    if (!onlineModel) return;
+    onlineModel.innerHTML = "";
+    const list = models && models.length ? models : recommended ? [recommended] : [];
+    list.forEach((m) => {
+      const opt = document.createElement("option");
+      opt.value = m;
+      opt.textContent = m;
+      onlineModel.appendChild(opt);
+    });
+    const saved = settings.online_model;
+    const choose =
+      saved && list.includes(saved)
+        ? saved
+        : recommended && list.includes(recommended)
+        ? recommended
+        : list[0] || "";
+    onlineModel.value = choose;
+    settings.online_model = choose;
+    try {
+      localStorage.setItem(ONLINE_MODEL_LS, choose);
+    } catch (_) {}
+  }
+
+  function shortErr(detail) {
+    const s = String(detail);
+    return s.length > 90 ? s.slice(0, 90) + "…" : s;
+  }
+
+  // ---------- Suggest best settings (opt-in) ----------
+  const suggestBtn = $("suggestBtn");
+  const suggestInput = $("suggestInput");
+  const suggestResult = $("suggestResult");
+  const suggestApply = $("suggestApply");
+  let lastRecommended = null;
+
+  if (suggestBtn) {
+    suggestBtn.addEventListener("click", () => suggestInput.click());
+    suggestInput.addEventListener("change", () => {
+      const f = suggestInput.files && suggestInput.files[0];
+      suggestInput.value = "";
+      if (f) analyzeFile(f);
+    });
+    suggestApply.addEventListener("click", () => {
+      if (lastRecommended) applyRecommended(lastRecommended);
+    });
+  }
+
+  async function analyzeFile(file) {
+    suggestBtn.disabled = true;
+    suggestBtn.textContent = "Analyzing 1–2 pages…";
+    suggestResult.hidden = true;
+    const form = new FormData();
+    form.append("file", file, file.name);
+    form.append("lang", settings.lang);
+    try {
+      const res = await fetch("/api/analyze", { method: "POST", body: form });
+      if (!res.ok) {
+        showToast("Analysis failed.");
+        return;
+      }
+      const data = await res.json();
+      renderSuggestion(data);
+    } catch (e) {
+      showToast("Analysis failed (network).");
+    } finally {
+      suggestBtn.disabled = false;
+      suggestBtn.textContent = "Suggest best settings";
+    }
+  }
+
+  function renderSuggestion(data) {
+    lastRecommended = data.recommended || null;
+    const rat = suggestResult.querySelector('[data-role="suggestRationale"]');
+    const ev = suggestResult.querySelector('[data-role="suggestEvidence"]');
+    if (data.needs_ocr === false) {
+      rat.textContent = data.rationale;
+      ev.innerHTML = "";
+      suggestApply.hidden = true; // nothing to apply; defaults are fine
+    } else {
+      rat.textContent = data.rationale || "";
+      suggestApply.hidden = false;
+      const rows = (data.evidence || []).map((r) => {
+        const tag = r.recommended ? " ★" : "";
+        const conf = r.mean_conf == null ? "–" : Math.round(r.mean_conf * 100) + "%";
+        const row = document.createElement("div");
+        row.className = "ev-row" + (r.recommended ? " best" : "");
+        [r.name + tag, "score " + r.composite, "conf " + conf, "lines " + r.confident_lines]
+          .forEach((t) => {
+            const s = document.createElement("span");
+            s.textContent = t;
+            row.appendChild(s);
+          });
+        return row;
+      });
+      ev.innerHTML = "";
+      rows.forEach((r) => ev.appendChild(r));
+      suggestApply.classList.toggle("btn-primary", data.decision === "decisive");
+    }
+    suggestResult.hidden = false;
+    showToast(
+      data.decision === "decisive"
+        ? "Found clearly better settings — review and Apply."
+        : "Recommendation ready."
+    );
+  }
+
+  function applyRecommended(rec) {
+    if (rec.mode) {
+      settings.mode = rec.mode;
+      modeToggle.querySelectorAll(".seg").forEach((b) => {
+        const active = b.dataset.mode === rec.mode;
+        b.classList.toggle("active", active);
+        b.setAttribute("aria-checked", active ? "true" : "false");
+      });
+    }
+    if (rec.lang) {
+      settings.lang = rec.lang;
+      langSelect.value = rec.lang;
+    }
+    settings.preprocess = !!rec.preprocess;
+    preprocessToggle.checked = settings.preprocess;
+    settings.binarize = !!rec.binarize;
+    binarizeToggle.checked = settings.binarize;
+    binarizeToggle.disabled = !settings.preprocess;
+    showToast("Applied recommended settings. Now drop your PDF to extract.");
+  }
+
+  // ---------- Drag & drop + picker ----------
+  dropzone.addEventListener("click", () => fileInput.click());
+  dropzone.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      fileInput.click();
+    }
+  });
+  fileInput.addEventListener("change", () => {
+    handleFiles(fileInput.files);
+    fileInput.value = "";
+  });
+
+  ["dragenter", "dragover"].forEach((ev) =>
+    dropzone.addEventListener(ev, (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dropzone.classList.add("dragover");
+    })
+  );
+  ["dragleave", "dragend"].forEach((ev) =>
+    dropzone.addEventListener(ev, (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dropzone.classList.remove("dragover");
+    })
+  );
+  dropzone.addEventListener("drop", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    dropzone.classList.remove("dragover");
+    if (e.dataTransfer && e.dataTransfer.files) handleFiles(e.dataTransfer.files);
+  });
+
+  // Prevent the browser from navigating when a file is dropped outside the zone.
+  ["dragover", "drop"].forEach((ev) =>
+    window.addEventListener(ev, (e) => {
+      if (!dropzone.contains(e.target)) e.preventDefault();
+    })
+  );
+
+  function handleFiles(fileList) {
+    const files = Array.from(fileList).filter(
+      (f) => f.type === "application/pdf" || /\.pdf$/i.test(f.name)
+    );
+    if (!files.length) {
+      showToast("Please choose PDF files only.");
+      return;
+    }
+    files.forEach(uploadFile);
+  }
+
+  // ---------- Upload ----------
+  async function uploadFile(file) {
+    const form = new FormData();
+    form.append("file", file, file.name);
+    form.append("mode", settings.mode);
+    form.append("lang", settings.lang);
+    form.append("preprocess", settings.preprocess ? "true" : "false");
+    form.append("binarize", settings.binarize ? "true" : "false");
+    form.append("handwriting", settings.handwriting ? "true" : "false");
+    form.append("online", settings.online ? "true" : "false");
+    form.append("online_key", settings.online_key || "");
+    form.append("online_model", settings.online_model || "");
+    form.append("force_ocr", settings.force_ocr ? "true" : "false");
+    form.append("remove_headers", settings.remove_headers ? "true" : "false");
+
+    // Optimistic card while uploading.
+    const placeholderId = "pending-" + Math.random().toString(36).slice(2);
+    const job = createFileCard({
+      jobId: placeholderId,
+      filename: file.name,
+      totalPages: 0,
+      status: "pending",
+    });
+    setFileStatus(job, "pending", "Uploading…");
+
+    let res;
+    try {
+      res = await fetch("/api/upload", { method: "POST", body: form });
+    } catch (err) {
+      failJob(job, "Network error during upload: " + (err && err.message ? err.message : err));
+      return;
+    }
+
+    if (!res.ok) {
+      let detail = "Upload failed (" + res.status + ")";
+      try {
+        const data = await res.json();
+        if (data && data.detail) detail = humanizeError(data.detail);
+      } catch (_) {}
+      failJob(job, detail);
+      return;
+    }
+
+    let data;
+    try {
+      data = await res.json();
+    } catch (err) {
+      failJob(job, "Invalid server response.");
+      return;
+    }
+
+    // If the user removed this card while it was still uploading, don't
+    // resurrect it: free the real server job (now that we know its id) and bail
+    // out before re-adding state / opening a stream.
+    if (job.removed) {
+      const id = data && data.job_id;
+      if (id) fetch("/api/jobs/" + encodeURIComponent(id), { method: "DELETE" }).catch(() => {});
+      return;
+    }
+
+    // Re-key the job from placeholder -> real job_id.
+    rekeyJob(job, placeholderId, data.job_id);
+    job.jobId = data.job_id;
+    job.filename = data.filename || file.name;
+    job.totalPages = data.total_pages || 0;
+    job.status = data.status || "processing";
+    job.el.fileName.textContent = job.filename;
+    setFileStatus(job, "processing", "Processing…");
+    updateProgress(job, 0, job.totalPages);
+
+    openStream(job);
+  }
+
+  function rekeyJob(job, oldId, newId) {
+    jobs.delete(oldId);
+    jobs.set(newId, job);
+    const idx = jobOrder.indexOf(oldId);
+    if (idx !== -1) jobOrder[idx] = newId;
+  }
+
+  // ---------- SSE stream ----------
+  function openStream(job) {
+    // Never (re)open a stream for a job the user removed or that's gone from
+    // state — a pollOnce reopen could otherwise leak an untracked EventSource.
+    if (job.removed || !jobs.has(job.jobId)) return;
+    if (job.es) {
+      job.es.close();
+      job.es = null;
+    }
+    const es = new EventSource("/api/jobs/" + encodeURIComponent(job.jobId) + "/stream");
+    job.es = es;
+
+    es.onmessage = (evt) => {
+      let payload;
+      try {
+        payload = JSON.parse(evt.data);
+      } catch (_) {
+        return;
+      }
+      handleEvent(job, payload);
+    };
+
+    es.onerror = () => {
+      // Network/stream dropped. If the job isn't terminal, fall back to polling once.
+      if (["done", "error", "cancelled"].includes(job.status)) {
+        es.close();
+        return;
+      }
+      es.close();
+      pollOnce(job);
+    };
+  }
+
+  function handleEvent(job, payload) {
+    if (payload.type === "progress") {
+      if (payload.page) applyPage(job, payload.page);
+      updateProgress(
+        job,
+        typeof payload.processed === "number" ? payload.processed : countDone(job),
+        typeof payload.total === "number" ? payload.total : job.totalPages
+      );
+    } else if (payload.type === "done") {
+      setFileStatus(job, "done", "Done");
+      closeStream(job);
+      refreshExportState();
+    } else if (payload.type === "error") {
+      failJob(job, payload.error ? humanizeError(payload.error) : "Processing failed.");
+      closeStream(job);
+    } else if (payload.type === "cancelled") {
+      setFileStatus(job, "cancelled", "Cancelled");
+      closeStream(job);
+    }
+  }
+
+  function closeStream(job) {
+    if (job.es) {
+      job.es.close();
+      job.es = null;
+    }
+    job.el.cancelBtn.disabled = true;
+  }
+
+  // Fallback: fetch the full job state once if the stream errored mid-flight.
+  async function pollOnce(job) {
+    // Bail if the user removed this card (or it's no longer tracked) so we don't
+    // resurrect a removed job's stream or render into a detached DOM subtree.
+    if (job.removed || !jobs.has(job.jobId)) return;
+    try {
+      const res = await fetch("/api/jobs/" + encodeURIComponent(job.jobId));
+      if (job.removed || !jobs.has(job.jobId)) return;
+      if (!res.ok) {
+        if (!["done", "error", "cancelled"].includes(job.status)) {
+          failJob(job, "Lost connection to the job stream.");
+        }
+        return;
+      }
+      const data = await res.json();
+      job.totalPages = data.total_pages || job.totalPages;
+      (data.pages || []).forEach((p) => {
+        if (p.status === "done" || p.status === "error") applyPage(job, p);
+      });
+      updateProgress(job, data.processed_pages || 0, job.totalPages);
+      if (data.status === "done") setFileStatus(job, "done", "Done");
+      else if (data.status === "error") failJob(job, data.error ? humanizeError(data.error) : "Processing failed.");
+      else if (data.status === "cancelled") setFileStatus(job, "cancelled", "Cancelled");
+      else {
+        // still processing — reopen the stream
+        openStream(job);
+      }
+      refreshExportState();
+    } catch (err) {
+      if (!["done", "error", "cancelled"].includes(job.status)) {
+        failJob(job, "Lost connection to the job stream.");
+      }
+    }
+  }
+
+  // ---------- Page rendering ----------
+  function applyPage(job, page) {
+    const pageNo = page.page;
+    let entry = job.pages.get(pageNo);
+    if (!entry) {
+      entry = buildPageCard(job, pageNo);
+      job.pages.set(pageNo, entry);
+      insertPageCardInOrder(job, entry);
+    }
+    entry.data = page;
+
+    // badge
+    const badge = entry.el.badge;
+    badge.className = "badge";
+    if (page.status === "error") {
+      badge.classList.add("error");
+      badge.textContent = "Error";
+    } else if (page.source === "text") {
+      badge.classList.add("text");
+      badge.textContent = "Text layer";
+    } else if (page.source === "handwriting") {
+      badge.classList.add("handwriting");
+      badge.textContent = "Handwriting";
+      badge.title = "Recognised with the local handwriting model (TrOCR).";
+    } else if (page.source === "online") {
+      badge.classList.add("online");
+      badge.textContent = "Gemini";
+      badge.title = "Transcribed online by Google Gemini.";
+    } else if (page.source === "ocr") {
+      badge.classList.add("ocr");
+      const conf = typeof page.confidence === "number" ? page.confidence : null;
+      if (conf !== null) {
+        const pct = Math.round(conf * 100);
+        badge.textContent = "OCR · " + pct + "%";
+        if (conf < LOWCONF_THRESH) {
+          badge.classList.add("lowconf");
+          badge.title = "Low OCR confidence — verify this page against the original image.";
+        } else {
+          badge.title = "Average OCR confidence " + pct + "%";
+        }
+      } else {
+        badge.textContent = "OCR";
+      }
+    } else {
+      badge.classList.add("pending");
+      badge.textContent = "Pending";
+    }
+
+    // text
+    const text = page.status === "error"
+      ? (page.error ? "Error: " + page.error : "Extraction failed for this page.")
+      : (page.text || "");
+    // Preserve a user's manual edits even if the server re-broadcasts this page
+    // (e.g. the header/footer cleanup pass at the end of a job). Also don't
+    // clobber text while the editor is OPEN (unsaved) — the textarea holds the
+    // user's in-progress value.
+    if (!entry.edited && !entry.editing) entry.text = text;
+
+    // "N to check": count low-confidence OCR lines (before any manual edit, and
+    // not while the editor is open so the chip doesn't flicker back mid-edit).
+    let lcCount = 0;
+    if (!entry.edited && !entry.editing && page.status === "done" && Array.isArray(page.lines)) {
+      lcCount = page.lines.filter(
+        (l) => l && typeof l.confidence === "number" && l.confidence < LOWCONF_THRESH
+      ).length;
+    }
+    if (entry.el.toCheck) {
+      if (lcCount > 0) {
+        entry.el.toCheck.hidden = false;
+        entry.el.toCheck.textContent = "⚠ " + lcCount + " to check";
+        entry.el.toCheck.title =
+          lcCount + " line(s) the OCR is unsure about — highlighted below. Click Edit to fix them.";
+      } else {
+        entry.el.toCheck.hidden = true;
+      }
+    }
+
+    const q = searchInput.value.trim();
+    if (q) {
+      // Re-run the whole search so the match count includes this newly arrived
+      // / re-broadcast page (renderPageBody alone wouldn't update searchCount).
+      runSearch();
+    } else {
+      renderPageBody(entry, "");
+    }
+  }
+
+  function buildPageCard(job, pageNo) {
+    const frag = pageCardTpl.content.cloneNode(true);
+    const root = frag.querySelector('[data-role="pageCard"]');
+    const el = {
+      pageNum: frag.querySelector('[data-role="pageNum"]'),
+      badge: frag.querySelector('[data-role="badge"]'),
+      toCheck: frag.querySelector('[data-role="toCheck"]'),
+      pageText: frag.querySelector('[data-role="pageText"]'),
+      pageEdit: frag.querySelector('[data-role="pageEdit"]'),
+      editBtn: frag.querySelector('[data-role="editBtn"]'),
+      toggleImg: frag.querySelector('[data-role="toggleImg"]'),
+      copyPage: frag.querySelector('[data-role="copyPage"]'),
+      imageWrap: frag.querySelector('[data-role="imageWrap"]'),
+    };
+    el.pageNum.textContent = "Page " + pageNo;
+
+    const entry = { pageNo, root, el, text: "", data: null, imgLoaded: false, edited: false, editing: false };
+
+    el.copyPage.addEventListener("click", () => {
+      copyText(entry.text || "");
+    });
+
+    // Edit: swap the read-only text for a textarea; saving updates the page's
+    // text so Copy and all exports use the corrected version.
+    el.editBtn.addEventListener("click", () => {
+      const editing = !el.pageEdit.hidden;
+      if (!editing) {
+        el.pageEdit.value = entry.text || "";
+        el.pageEdit.hidden = false;
+        el.pageText.hidden = true;
+        el.editBtn.textContent = "Done";
+        if (el.toCheck) el.toCheck.hidden = true;
+        entry.editing = true;         // a re-broadcast must not overwrite text / reshow the chip mid-edit
+        el.pageEdit.focus();
+      } else {
+        entry.text = el.pageEdit.value;
+        entry.edited = true;          // stop low-confidence highlighting; keep edits on re-broadcast
+        entry.editing = false;
+        el.pageEdit.hidden = true;
+        el.pageText.hidden = false;
+        el.editBtn.textContent = "Edit";
+        const q = searchInput.value.trim();
+        if (q) runSearch(); else renderPageBody(entry, "");
+        refreshExportState();
+        showToast("Saved — Copy and exports now use your edited text.");
+      }
+    });
+
+    el.toggleImg.addEventListener("click", () => {
+      const wrap = el.imageWrap;
+      const isHidden = wrap.hasAttribute("hidden");
+      if (isHidden) {
+        wrap.removeAttribute("hidden");
+        el.toggleImg.textContent = "Hide original page";
+        if (!entry.imgLoaded) {
+          entry.imgLoaded = true;
+          wrap.innerHTML = '<div class="img-loading">Rendering original page…</div>';
+          const img = new Image();
+          img.alt = "Original page " + pageNo;
+          img.onload = () => {
+            wrap.innerHTML = "";
+            wrap.appendChild(img);
+          };
+          img.onerror = () => {
+            wrap.innerHTML = '<div class="img-loading">Could not render this page.</div>';
+            entry.imgLoaded = false;
+          };
+          img.src =
+            "/api/jobs/" + encodeURIComponent(job.jobId) + "/pages/" + pageNo + "/image?dpi=150";
+        }
+      } else {
+        wrap.setAttribute("hidden", "");
+        el.toggleImg.textContent = "Show original page";
+      }
+    });
+
+    return entry;
+  }
+
+  function insertPageCardInOrder(job, entry) {
+    const container = job.el.pages;
+    // Insert keeping ascending page order.
+    let inserted = false;
+    const children = container.children;
+    for (let i = 0; i < children.length; i++) {
+      const otherNo = Number(children[i].dataset.pageNo);
+      if (otherNo > entry.pageNo) {
+        container.insertBefore(entry.root, children[i]);
+        inserted = true;
+        break;
+      }
+    }
+    entry.root.dataset.pageNo = String(entry.pageNo);
+    if (!inserted) container.appendChild(entry.root);
+  }
+
+  // ---------- File card ----------
+  function createFileCard(meta) {
+    const frag = fileCardTpl.content.cloneNode(true);
+    const el = {
+      root: frag.querySelector(".file-card"),
+      statusDot: frag.querySelector('[data-role="statusDot"]'),
+      fileName: frag.querySelector('[data-role="fileName"]'),
+      statusText: frag.querySelector('[data-role="statusText"]'),
+      cancelBtn: frag.querySelector('[data-role="cancelBtn"]'),
+      removeBtn: frag.querySelector('[data-role="removeBtn"]'),
+      progressFill: frag.querySelector('[data-role="progressFill"]'),
+      progressLabel: frag.querySelector('[data-role="progressLabel"]'),
+      fileError: frag.querySelector('[data-role="fileError"]'),
+      pages: frag.querySelector('[data-role="pages"]'),
+    };
+    el.fileName.textContent = meta.filename;
+
+    const job = {
+      jobId: meta.jobId,
+      filename: meta.filename,
+      totalPages: meta.totalPages || 0,
+      status: meta.status || "pending",
+      pages: new Map(),
+      es: null,
+      el,
+    };
+
+    el.cancelBtn.addEventListener("click", () => cancelJob(job));
+    if (el.removeBtn) el.removeBtn.addEventListener("click", () => removeJob(job));
+
+    jobs.set(job.jobId, job);
+    jobOrder.push(job.jobId);
+
+    emptyState.hidden = true;
+    toolbar.hidden = false;
+    filesContainer.appendChild(el.root);
+    return job;
+  }
+
+  // Remove a file card: stop its stream, free its memory on the server, and
+  // drop it from the UI/state. Works at any stage (also cancels if in-flight).
+  function removeJob(job) {
+    job.removed = true;  // upload continuation checks this to avoid resurrecting it
+    closeStream(job);
+    if (job.jobId && String(job.jobId).indexOf("pending-") !== 0) {
+      // Tell the server to drop the job (frees its in-memory PDF bytes).
+      fetch("/api/jobs/" + encodeURIComponent(job.jobId), { method: "DELETE" }).catch(() => {});
+    }
+    if (job.el && job.el.root && job.el.root.parentNode) {
+      job.el.root.parentNode.removeChild(job.el.root);
+    }
+    jobs.delete(job.jobId);
+    const idx = jobOrder.indexOf(job.jobId);
+    if (idx !== -1) jobOrder.splice(idx, 1);
+    if (jobs.size === 0) {
+      emptyState.hidden = false;
+      toolbar.hidden = true;
+    }
+    refreshExportState();
+  }
+
+  function setFileStatus(job, status, label) {
+    job.status = status;
+    job.el.statusText.textContent = label;
+    job.el.statusDot.className = "status-dot " + status;
+    if (status === "done" || status === "error" || status === "cancelled") {
+      job.el.cancelBtn.disabled = true;
+    }
+  }
+
+  function updateProgress(job, processed, total) {
+    total = total || job.totalPages || 0;
+    const pct = total > 0 ? Math.min(100, Math.round((processed / total) * 100)) : 0;
+    job.el.progressFill.style.width = pct + "%";
+    job.el.progressLabel.textContent = processed + " / " + total;
+  }
+
+  function failJob(job, message) {
+    setFileStatus(job, "error", "Error");
+    job.el.fileError.hidden = false;
+    job.el.fileError.textContent = message;
+    closeStream(job);
+  }
+
+  function countDone(job) {
+    let n = 0;
+    job.pages.forEach((p) => {
+      if (p.data && (p.data.status === "done" || p.data.status === "error")) n++;
+    });
+    return n;
+  }
+
+  async function cancelJob(job) {
+    if (["done", "error", "cancelled"].includes(job.status)) return;
+    job.el.cancelBtn.disabled = true;
+    setFileStatus(job, "processing", "Cancelling…");
+    try {
+      await fetch("/api/jobs/" + encodeURIComponent(job.jobId) + "/cancel", { method: "POST" });
+    } catch (_) {
+      showToast("Could not reach server to cancel.");
+    }
+  }
+
+  // ---------- Search & highlight ----------
+  let searchTimer = null;
+  searchInput.addEventListener("input", () => {
+    clearTimeout(searchTimer);
+    searchTimer = setTimeout(runSearch, 120);
+  });
+
+  function runSearch() {
+    const q = searchInput.value.trim();
+    let total = 0;
+    jobs.forEach((job) => {
+      job.pages.forEach((entry) => {
+        total += applySearchToEntry(entry, q);
+      });
+    });
+    if (q) {
+      searchCount.hidden = false;
+      searchCount.textContent = total + (total === 1 ? " match" : " matches");
+    } else {
+      searchCount.hidden = true;
+    }
+  }
+
+  // Render a page's text into its <pre>, applying BOTH low-confidence line
+  // highlighting (OCR pages, before the user edits) AND search highlighting.
+  // Returns the number of search matches.
+  function renderPageBody(entry, q) {
+    const target = entry.el.pageText;
+    const text = entry.text || "";
+    // Keep the element truly :empty for blank pages so the CSS
+    // "(no text on this page)" placeholder shows (an empty text node would
+    // defeat :empty).
+    if (!text) {
+      target.textContent = "";
+      return 0;
+    }
+    const ql = (q || "").toLowerCase();
+    const lines =
+      !entry.edited && entry.data && entry.data.status === "done" &&
+      Array.isArray(entry.data.lines)
+        ? entry.data.lines
+        : null;
+    const textLines = text.split("\n");
+    const frag = document.createDocumentFragment();
+    let count = 0;
+
+    textLines.forEach((ln, i) => {
+      const lc =
+        lines && lines[i] && typeof lines[i].confidence === "number" &&
+        lines[i].confidence < LOWCONF_THRESH;
+      let wrap = null;
+      let sink = frag;
+      if (lc) {
+        wrap = document.createElement("span");
+        wrap.className = "lc-line";
+        wrap.title =
+          "Low confidence (" + Math.round(lines[i].confidence * 100) +
+          "%) — double-check this line";
+        sink = wrap;
+      }
+      const lower = ln.toLowerCase();
+      if (ql && lower.length === ln.length && lower.includes(ql)) {
+        // Common case: lowercase preserves length, so indices in `lower` align
+        // 1:1 with `ln`. Use ql.length consistently for slice + advance.
+        let idx = 0;
+        while (true) {
+          const found = lower.indexOf(ql, idx);
+          if (found === -1) {
+            sink.appendChild(document.createTextNode(ln.slice(idx)));
+            break;
+          }
+          if (found > idx) sink.appendChild(document.createTextNode(ln.slice(idx, found)));
+          const mark = document.createElement("mark");
+          mark.textContent = ln.slice(found, found + ql.length);
+          sink.appendChild(mark);
+          count++;
+          idx = found + ql.length;
+        }
+      } else if (ql && lower.includes(ql)) {
+        // Rare: a character whose lowercase changes length (e.g. Turkish 'İ')
+        // makes `lower` indices misalign with `ln`. Count the matches but render
+        // the line plain rather than wrapping the wrong characters in <mark>.
+        let from = 0, f;
+        while ((f = lower.indexOf(ql, from)) !== -1) { count++; from = f + ql.length; }
+        sink.appendChild(document.createTextNode(ln));
+      } else {
+        sink.appendChild(document.createTextNode(ln));
+      }
+      if (wrap) frag.appendChild(wrap);
+      if (i < textLines.length - 1) frag.appendChild(document.createTextNode("\n"));
+    });
+
+    target.textContent = "";
+    target.appendChild(frag);
+    return count;
+  }
+
+  function applySearchToEntry(entry, q) {
+    return renderPageBody(entry, q);
+  }
+
+  // ---------- Copy ----------
+  copyAllBtn.addEventListener("click", () => {
+    const parts = [];
+    orderedJobs().forEach((job) => {
+      parts.push("===== " + job.filename + " =====");
+      orderedPages(job).forEach((entry) => {
+        parts.push("--- Page " + entry.pageNo + " ---");
+        parts.push(entry.text || "");
+      });
+      parts.push("");
+    });
+    copyText(parts.join("\n"));
+  });
+
+  function copyText(text) {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(
+        () => showToast("Copied to clipboard"),
+        () => fallbackCopy(text)
+      );
+    } else {
+      fallbackCopy(text);
+    }
+  }
+
+  function fallbackCopy(text) {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    try {
+      document.execCommand("copy");
+      showToast("Copied to clipboard");
+    } catch (_) {
+      showToast("Copy failed");
+    }
+    document.body.removeChild(ta);
+  }
+
+  // ---------- Export ----------
+  document.querySelectorAll("[data-export]").forEach((btn) => {
+    btn.addEventListener("click", () => exportAll(btn.dataset.export));
+  });
+
+  function exportAll(kind) {
+    const list = orderedJobs();
+    if (!list.length) {
+      showToast("Nothing to export yet.");
+      return;
+    }
+    if (kind === "docx") {
+      return exportDocx(list);
+    }
+    if (kind === "json") {
+      const data = list.map((job) => ({
+        filename: job.filename,
+        job_id: String(job.jobId),
+        status: job.status,
+        total_pages: job.totalPages,
+        pages: orderedPages(job).map((entry) => ({
+          page: entry.pageNo,
+          source: entry.data ? entry.data.source : null,
+          status: entry.data ? entry.data.status : "pending",
+          confidence: entry.data ? entry.data.confidence : null,
+          text: entry.text || "",
+        })),
+      }));
+      download("extraction.json", JSON.stringify(data, null, 2), "application/json");
+      return;
+    }
+
+    if (kind === "md") {
+      const parts = [];
+      list.forEach((job) => {
+        parts.push("# " + job.filename + "\n");
+        orderedPages(job).forEach((entry) => {
+          parts.push("## Page " + entry.pageNo + "\n");
+          parts.push((entry.text || "_(no text)_") + "\n");
+        });
+      });
+      download(baseName(list) + ".md", parts.join("\n"), "text/markdown");
+      return;
+    }
+
+    // txt
+    const parts = [];
+    list.forEach((job) => {
+      parts.push("===== " + job.filename + " =====\n");
+      orderedPages(job).forEach((entry) => {
+        parts.push("--- Page " + entry.pageNo + " ---");
+        parts.push((entry.text || "") + "\n");
+      });
+    });
+    download(baseName(list) + ".txt", parts.join("\n"), "text/plain");
+  }
+
+  async function exportDocx(list) {
+    const documents = list.map((job) => ({
+      filename: job.filename,
+      pages: orderedPages(job).map((entry) => ({
+        page: entry.pageNo,
+        source: entry.data ? entry.data.source : null,
+        confidence: entry.data ? entry.data.confidence : null,
+        text: entry.text || "",
+      })),
+    }));
+    try {
+      const res = await fetch("/api/export/docx", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ documents }),
+      });
+      if (!res.ok) {
+        showToast("Word export failed.");
+        return;
+      }
+      const blob = await res.blob();
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = (list.length === 1 ? baseName(list) : "extraction") + ".docx";
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      setTimeout(() => URL.revokeObjectURL(url), 1000);
+      showToast("Word document downloaded");
+    } catch (e) {
+      showToast("Word export failed.");
+    }
+  }
+
+  function baseName(list) {
+    if (list.length === 1) {
+      return list[0].filename.replace(/\.pdf$/i, "") || "extraction";
+    }
+    return "extraction";
+  }
+
+  function download(filename, content, mime) {
+    const blob = new Blob([content], { type: mime + ";charset=utf-8" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+  }
+
+  // ---------- Ordering helpers ----------
+  function orderedJobs() {
+    const out = [];
+    jobOrder.forEach((id) => {
+      const j = jobs.get(id);
+      if (j) out.push(j);
+    });
+    return out;
+  }
+
+  function orderedPages(job) {
+    return Array.from(job.pages.values()).sort((a, b) => a.pageNo - b.pageNo);
+  }
+
+  function refreshExportState() {
+    // Export/copy always available once there is at least one job; nothing to gate.
+  }
+
+  // ---------- Misc ----------
+  function humanizeError(detail) {
+    const d = String(detail).toLowerCase();
+    if (d.includes("encrypt") || d.includes("password") || d.includes("needs_pass")) {
+      return "This PDF is encrypted / password-protected and cannot be processed.";
+    }
+    if (d.includes("corrupt") || d.includes("cannot open") || d.includes("damaged")) {
+      return "This file appears to be corrupt or is not a valid PDF.";
+    }
+    return String(detail);
+  }
+
+  let toastTimer = null;
+  function showToast(msg) {
+    toast.textContent = msg;
+    toast.hidden = false;
+    // force reflow so the transition runs
+    void toast.offsetWidth;
+    toast.classList.add("show");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => {
+      toast.classList.remove("show");
+      setTimeout(() => {
+        toast.hidden = true;
+      }, 220);
+    }, 1800);
+  }
+})();

static/index.html

@@ -0,0 +1,258 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Local PDF Extractor</title>
+  <link rel="stylesheet" href="/static/styles.css" />
+</head>
+<body>
+  <header class="app-header">
+    <div class="brand">
+      <div class="brand-mark" aria-hidden="true">
+        <svg viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="logo">
+          <rect x="5" y="3" width="18" height="26" rx="3" fill="currentColor" opacity="0.15"></rect>
+          <rect x="5" y="3" width="18" height="26" rx="3" fill="none" stroke="currentColor" stroke-width="2"></rect>
+          <line x1="9" y1="11" x2="19" y2="11" stroke="currentColor" stroke-width="2" stroke-linecap="round"></line>
+          <line x1="9" y1="16" x2="19" y2="16" stroke="currentColor" stroke-width="2" stroke-linecap="round"></line>
+          <line x1="9" y1="21" x2="15" y2="21" stroke="currentColor" stroke-width="2" stroke-linecap="round"></line>
+        </svg>
+      </div>
+      <div class="brand-text">
+        <h1>Local PDF Extractor</h1>
+        <p class="tagline">Extract text from typed, scanned &amp; handwritten PDFs</p>
+      </div>
+    </div>
+  </header>
+
+  <main class="layout">
+    <!-- Sidebar: settings + drop zone -->
+    <aside class="sidebar">
+      <section class="panel">
+        <h2 class="panel-title">Settings</h2>
+
+        <div class="setting">
+          <label class="setting-label">Accuracy</label>
+          <div class="segmented" id="modeToggle" role="radiogroup" aria-label="Accuracy">
+            <button type="button" class="seg active" data-mode="max" role="radio" aria-checked="true">Max accuracy</button>
+            <button type="button" class="seg" data-mode="fast" role="radio" aria-checked="false">Faster</button>
+          </div>
+          <p class="hint" id="modeHint">Max accuracy is slower but renders at higher DPI and uses angle correction.</p>
+        </div>
+
+        <div class="setting">
+          <label class="setting-label" for="langSelect">Language</label>
+          <select id="langSelect" class="select">
+            <option value="en" selected>English</option>
+            <option value="hi">Hindi (Devanagari)</option>
+          </select>
+        </div>
+
+        <div class="setting-group-label">Image &amp; pages</div>
+
+        <div class="setting setting-row">
+          <div>
+            <label class="setting-label" for="preprocessToggle">Preprocessing</label>
+            <p class="hint">Deskew, contrast-boost &amp; denoise before OCR. Best left on.</p>
+          </div>
+          <label class="switch">
+            <input type="checkbox" id="preprocessToggle" checked />
+            <span class="slider" aria-hidden="true"></span>
+          </label>
+        </div>
+
+        <div class="setting setting-row">
+          <div>
+            <label class="setting-label" for="binarizeToggle">Binarize</label>
+            <p class="hint">Force black-and-white. Helps some clean/high-contrast scans; usually leave off (grayscale is more accurate on most documents).</p>
+          </div>
+          <label class="switch">
+            <input type="checkbox" id="binarizeToggle" />
+            <span class="slider" aria-hidden="true"></span>
+          </label>
+        </div>
+
+        <div class="setting setting-row">
+          <div>
+            <label class="setting-label" for="forceOcrToggle">Force OCR</label>
+            <p class="hint">Re-read every page as an image, even pages that already have selectable text. Use only when the embedded text is wrong/garbled, or text is trapped inside images. Slower; off by default.</p>
+          </div>
+          <label class="switch">
+            <input type="checkbox" id="forceOcrToggle" />
+            <span class="slider" aria-hidden="true"></span>
+          </label>
+        </div>
+
+        <div class="setting setting-row">
+          <div>
+            <label class="setting-label" for="removeHeadersToggle">Remove headers &amp; footers</label>
+            <p class="hint">Strip repeating page headers, footers &amp; page numbers from multi-page documents (3+ pages). On by default; turn off to keep every line exactly as on the page.</p>
+          </div>
+          <label class="switch">
+            <input type="checkbox" id="removeHeadersToggle" checked />
+            <span class="slider" aria-hidden="true"></span>
+          </label>
+        </div>
+
+        <div class="setting-group-label">OCR engine</div>
+
+        <div class="setting setting-row">
+          <div>
+            <label class="setting-label" for="handwritingToggle">Handwriting (local) <span class="beta-tag">beta</span></label>
+            <p class="hint">Read handwritten pages with a local model (English, ~73% on real cursive). Much slower; first use downloads a model once. For far better handwriting, use Online Gemini below instead &mdash; you don't need both.</p>
+          </div>
+          <label class="switch">
+            <input type="checkbox" id="handwritingToggle" />
+            <span class="slider" aria-hidden="true"></span>
+          </label>
+        </div>
+
+        <div class="setting setting-row">
+          <div>
+            <label class="setting-label" for="onlineToggle">Online vision OCR (Gemini)</label>
+            <p class="hint">Far higher accuracy on handwriting &amp; hard scans, via Google Gemini.
+               <strong>Sends your page images to Google</strong> &mdash; off by default. Needs a free API key.</p>
+          </div>
+          <label class="switch">
+            <input type="checkbox" id="onlineToggle" />
+            <span class="slider" aria-hidden="true"></span>
+          </label>
+        </div>
+        <div class="setting setting-sub" id="onlineRow" hidden>
+          <label class="setting-label" for="onlineKey">Gemini API key</label>
+          <input type="password" id="onlineKey" class="select online-input" placeholder="paste key from aistudio.google.com" autocomplete="off" spellcheck="false" />
+          <div class="online-key-actions">
+            <button type="button" class="btn btn-ghost btn-sm" id="onlineCheck">Check key</button>
+            <span class="online-status" id="onlineStatus" data-role="onlineStatus"></span>
+          </div>
+          <label class="setting-label" for="onlineModel" style="margin-top:8px;">Model</label>
+          <select id="onlineModel" class="select"></select>
+          <p class="hint">Your key is stored only in this browser and sent with each upload &mdash; never saved on the server.
+             Pages with a real text layer are still read locally (not sent).</p>
+        </div>
+
+        <div class="setting-group-label">Tools</div>
+
+        <div class="setting">
+          <button type="button" class="btn btn-ghost" id="suggestBtn">Suggest best settings</button>
+          <p class="hint">Samples 1&ndash;2 pages of the next file you pick and recommends settings.
+             Opt-in &middot; can take up to a minute on the CPU &middot; nothing is applied until you click Apply.</p>
+          <input type="file" id="suggestInput" accept="application/pdf,.pdf" hidden />
+        </div>
+        <div class="setting" id="suggestResult" hidden>
+          <div class="suggest-card">
+            <p class="suggest-rationale" data-role="suggestRationale"></p>
+            <div class="suggest-evidence" data-role="suggestEvidence"></div>
+            <button type="button" class="btn btn-primary btn-sm" id="suggestApply">Apply recommended</button>
+          </div>
+        </div>
+      </section>
+
+      <section
+        class="dropzone"
+        id="dropzone"
+        tabindex="0"
+        role="button"
+        aria-label="Drop PDF files here or click to browse">
+        <svg viewBox="0 0 24 24" width="40" height="40" aria-hidden="true" class="dz-icon">
+          <path d="M12 16V4m0 0l-4 4m4-4l4 4" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path>
+          <path d="M4 16v2a2 2 0 002 2h12a2 2 0 002-2v-2" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path>
+        </svg>
+        <p class="dz-primary">Drop PDF files here</p>
+        <p class="dz-secondary">or <span class="dz-link">browse</span> &middot; multiple files supported</p>
+        <input type="file" id="fileInput" accept="application/pdf,.pdf" multiple hidden />
+      </section>
+
+      <section class="notes" aria-label="Honesty notes">
+        <h3 class="notes-title">Good to know</h3>
+        <ul>
+          <li>Typed / born-digital pages are extracted instantly and exactly &mdash; no OCR.</li>
+          <li>OCR accuracy depends on scan quality; handwriting is the hardest.</li>
+          <li>For the best handwriting, use Online Gemini; everything else runs on your machine.</li>
+          <li>The first local-OCR run downloads model weights once, then caches them.</li>
+        </ul>
+      </section>
+    </aside>
+
+    <!-- Main work area -->
+    <section class="work">
+      <div class="toolbar" id="toolbar" hidden>
+        <div class="search-wrap">
+          <svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true" class="search-icon">
+            <circle cx="11" cy="11" r="7" fill="none" stroke="currentColor" stroke-width="2"></circle>
+            <line x1="16.5" y1="16.5" x2="21" y2="21" stroke="currentColor" stroke-width="2" stroke-linecap="round"></line>
+          </svg>
+          <input type="search" id="searchInput" class="search-input" placeholder="Search across all extracted text…" autocomplete="off" />
+          <span class="search-count" id="searchCount" hidden></span>
+        </div>
+        <div class="toolbar-actions">
+          <button type="button" class="btn btn-ghost" id="copyAllBtn">Copy all</button>
+          <div class="export-group">
+            <button type="button" class="btn btn-ghost" data-export="txt">.txt</button>
+            <button type="button" class="btn btn-ghost" data-export="md">.md</button>
+            <button type="button" class="btn btn-ghost" data-export="docx">.docx</button>
+            <button type="button" class="btn btn-ghost" data-export="json">.json</button>
+          </div>
+        </div>
+      </div>
+
+      <div class="empty-state" id="emptyState">
+        <svg viewBox="0 0 64 64" width="72" height="72" aria-hidden="true">
+          <rect x="14" y="8" width="36" height="48" rx="4" fill="none" stroke="currentColor" stroke-width="2.5"></rect>
+          <line x1="22" y1="22" x2="42" y2="22" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"></line>
+          <line x1="22" y1="30" x2="42" y2="30" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"></line>
+          <line x1="22" y1="38" x2="34" y2="38" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"></line>
+        </svg>
+        <h2>No documents yet</h2>
+        <p>Drop one or more PDFs to extract their text.</p>
+      </div>
+
+      <div id="filesContainer" class="files-container"></div>
+    </section>
+  </main>
+
+  <!-- Templates -->
+  <template id="fileCardTemplate">
+    <article class="file-card">
+      <div class="file-head">
+        <div class="file-meta">
+          <span class="status-dot" data-role="statusDot"></span>
+          <h3 class="file-name" data-role="fileName"></h3>
+        </div>
+        <div class="file-head-right">
+          <span class="status-text" data-role="statusText">Pending</span>
+          <button type="button" class="btn btn-danger btn-sm" data-role="cancelBtn">Cancel</button>
+          <button type="button" class="btn btn-ghost btn-sm btn-remove" data-role="removeBtn" title="Remove this file" aria-label="Remove this file">&times;</button>
+        </div>
+      </div>
+      <div class="progress-row">
+        <div class="progress-track"><div class="progress-fill" data-role="progressFill"></div></div>
+        <span class="progress-label" data-role="progressLabel">0 / 0</span>
+      </div>
+      <div class="file-error" data-role="fileError" hidden></div>
+      <div class="pages" data-role="pages"></div>
+    </article>
+  </template>
+
+  <template id="pageCardTemplate">
+    <div class="page-card" data-role="pageCard">
+      <div class="page-head">
+        <span class="page-num" data-role="pageNum"></span>
+        <span class="badge" data-role="badge"></span>
+        <span class="to-check" data-role="toCheck" hidden></span>
+        <span class="page-spacer"></span>
+        <button type="button" class="btn btn-ghost btn-sm" data-role="toggleImg">Show original page</button>
+        <button type="button" class="btn btn-ghost btn-sm" data-role="editBtn">Edit</button>
+        <button type="button" class="btn btn-ghost btn-sm" data-role="copyPage">Copy</button>
+      </div>
+      <pre class="page-text" data-role="pageText"></pre>
+      <textarea class="page-edit" data-role="pageEdit" spellcheck="false" hidden></textarea>
+      <div class="page-image-wrap" data-role="imageWrap" hidden></div>
+    </div>
+  </template>
+
+  <div class="toast" id="toast" role="status" aria-live="polite" hidden></div>
+
+  <script src="/static/app.js"></script>
+</body>
+</html>

static/styles.css

@@ -0,0 +1,427 @@
+:root {
+  --bg: #0f1115;
+  --bg-soft: #161a22;
+  --panel: #1b212c;
+  --panel-2: #212835;
+  --border: #2a3342;
+  --border-soft: #232b38;
+  --text: #e7ecf3;
+  --text-dim: #9aa6b8;
+  --text-faint: #6b7686;
+  --accent: #6c8cff;
+  --accent-2: #5a78f0;
+  --green: #2ecc8f;
+  --green-soft: rgba(46, 204, 143, 0.15);
+  --amber: #f5a623;
+  --amber-soft: rgba(245, 166, 35, 0.15);
+  --red: #ff5d6c;
+  --red-soft: rgba(255, 93, 108, 0.13);
+  --radius: 12px;
+  --radius-sm: 8px;
+  --shadow: 0 6px 24px rgba(0, 0, 0, 0.35);
+  --mono: "SFMono-Regular", "Consolas", "Liberation Mono", Menlo, monospace;
+  --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  padding: 0;
+  background: var(--bg);
+  color: var(--text);
+  font-family: var(--sans);
+  font-size: 15px;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+body {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  background:
+    radial-gradient(1200px 600px at 90% -10%, rgba(108, 140, 255, 0.08), transparent 60%),
+    radial-gradient(900px 500px at -10% 110%, rgba(46, 204, 143, 0.06), transparent 55%),
+    var(--bg);
+}
+
+h1, h2, h3 { margin: 0; font-weight: 650; letter-spacing: -0.01em; }
+
+/* ---------- Header ---------- */
+.app-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 24px;
+  border-bottom: 1px solid var(--border-soft);
+  background: rgba(15, 17, 21, 0.7);
+  backdrop-filter: blur(8px);
+  position: sticky;
+  top: 0;
+  z-index: 20;
+}
+.brand { display: flex; align-items: center; gap: 14px; }
+.brand-mark { color: var(--accent); display: flex; }
+.brand-text h1 { font-size: 19px; }
+.tagline { margin: 2px 0 0; font-size: 12.5px; color: var(--text-dim); }
+.offline-pill {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--green);
+  background: var(--green-soft);
+  border: 1px solid rgba(46, 204, 143, 0.3);
+  padding: 5px 12px;
+  border-radius: 999px;
+}
+
+/* ---------- Layout ---------- */
+.layout {
+  display: grid;
+  grid-template-columns: 320px 1fr;
+  gap: 24px;
+  padding: 24px;
+  flex: 1;
+  max-width: 1400px;
+  width: 100%;
+  margin: 0 auto;
+}
+
+/* ---------- Sidebar ---------- */
+.sidebar { display: flex; flex-direction: column; gap: 18px; }
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 18px;
+}
+.panel-title { font-size: 14px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--text-dim); margin-bottom: 14px; }
+
+.setting { margin-bottom: 18px; }
+.setting:last-child { margin-bottom: 0; }
+.setting-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.setting-label { display: block; font-size: 13px; font-weight: 600; margin-bottom: 8px; color: var(--text); }
+.hint { margin: 6px 0 0; font-size: 12px; color: var(--text-faint); line-height: 1.45; }
+
+.segmented {
+  display: flex;
+  background: var(--bg-soft);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 3px;
+  gap: 3px;
+}
+.seg {
+  flex: 1;
+  border: none;
+  background: transparent;
+  color: var(--text-dim);
+  font: inherit;
+  font-size: 13px;
+  font-weight: 600;
+  padding: 7px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: background 0.15s, color 0.15s;
+}
+.seg:hover { color: var(--text); }
+.seg.active { background: var(--accent); color: #fff; box-shadow: 0 2px 8px rgba(108, 140, 255, 0.35); }
+
+.select {
+  width: 100%;
+  background: var(--bg-soft);
+  border: 1px solid var(--border);
+  color: var(--text);
+  font: inherit;
+  font-size: 14px;
+  padding: 9px 11px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+}
+.select:focus { outline: 2px solid var(--accent); outline-offset: 1px; }
+
+/* switch */
+.switch { position: relative; display: inline-block; width: 44px; height: 24px; flex: none; }
+.switch input { opacity: 0; width: 0; height: 0; }
+.slider {
+  position: absolute; inset: 0; cursor: pointer;
+  background: var(--border); border-radius: 999px; transition: background 0.18s;
+}
+.slider::before {
+  content: ""; position: absolute; height: 18px; width: 18px; left: 3px; top: 3px;
+  background: #fff; border-radius: 50%; transition: transform 0.18s;
+}
+.switch input:checked + .slider { background: var(--accent); }
+.switch input:checked + .slider::before { transform: translateX(20px); }
+.switch input:focus + .slider { box-shadow: 0 0 0 2px var(--accent); }
+
+/* dropzone */
+.dropzone {
+  border: 2px dashed var(--border);
+  border-radius: var(--radius);
+  padding: 28px 18px;
+  text-align: center;
+  cursor: pointer;
+  transition: border-color 0.18s, background 0.18s, transform 0.05s;
+  color: var(--text-dim);
+  background: var(--panel);
+}
+.dropzone:hover { border-color: var(--accent); background: var(--panel-2); }
+.dropzone:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.dropzone.dragover { border-color: var(--accent); background: rgba(108, 140, 255, 0.08); transform: scale(1.01); }
+.dz-icon { color: var(--accent); margin-bottom: 8px; }
+.dz-primary { margin: 0; font-weight: 600; color: var(--text); font-size: 15px; }
+.dz-secondary { margin: 6px 0 0; font-size: 13px; }
+.dz-link { color: var(--accent); text-decoration: underline; }
+
+/* notes */
+.notes {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 16px 18px;
+}
+.notes-title { font-size: 13px; color: var(--text-dim); margin-bottom: 10px; }
+.notes ul { margin: 0; padding-left: 18px; }
+.notes li { font-size: 12.5px; color: var(--text-faint); margin-bottom: 6px; line-height: 1.5; }
+
+/* ---------- Work area ---------- */
+.work { min-width: 0; display: flex; flex-direction: column; gap: 18px; }
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 12px 14px;
+  position: sticky;
+  top: 78px;
+  z-index: 10;
+}
+.search-wrap { position: relative; flex: 1; min-width: 220px; display: flex; align-items: center; }
+.search-icon { position: absolute; left: 11px; color: var(--text-faint); pointer-events: none; }
+.search-input {
+  width: 100%;
+  background: var(--bg-soft);
+  border: 1px solid var(--border);
+  color: var(--text);
+  font: inherit;
+  font-size: 14px;
+  padding: 9px 12px 9px 34px;
+  border-radius: var(--radius-sm);
+}
+.search-input:focus { outline: 2px solid var(--accent); outline-offset: 1px; }
+.search-count { position: absolute; right: 12px; font-size: 12px; color: var(--text-faint); }
+.toolbar-actions { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.export-group { display: flex; gap: 4px; background: var(--bg-soft); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 3px; }
+
+/* buttons */
+.btn {
+  border: 1px solid var(--border);
+  background: var(--panel-2);
+  color: var(--text);
+  font: inherit;
+  font-size: 13px;
+  font-weight: 600;
+  padding: 8px 13px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: background 0.15s, border-color 0.15s, color 0.15s, opacity 0.15s;
+}
+.btn:hover { background: var(--border); }
+.btn:active { transform: translateY(1px); }
+.btn:disabled { opacity: 0.45; cursor: not-allowed; }
+.btn-sm { padding: 5px 10px; font-size: 12px; }
+.btn-ghost { background: transparent; border-color: transparent; color: var(--text-dim); }
+.btn-ghost:hover { background: var(--border-soft); color: var(--text); }
+.export-group .btn-ghost { border: none; }
+.btn-danger { color: var(--red); border-color: rgba(255, 93, 108, 0.4); background: transparent; }
+.btn-danger:hover { background: var(--red-soft); }
+
+/* empty state */
+/* The HTML `hidden` attribute must always win — otherwise an explicit
+   `display:` rule (e.g. .empty-state below) keeps a "hidden" element visible. */
+[hidden] { display: none !important; }
+
+.empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  padding: 80px 24px;
+  color: var(--text-faint);
+  border: 1px dashed var(--border);
+  border-radius: var(--radius);
+}
+.empty-state svg { color: var(--border); margin-bottom: 16px; }
+.empty-state h2 { font-size: 18px; color: var(--text-dim); margin-bottom: 6px; }
+.empty-state p { margin: 0; max-width: 360px; font-size: 14px; }
+
+/* files */
+.files-container { display: flex; flex-direction: column; gap: 18px; }
+.file-card {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow: hidden;
+}
+.file-head {
+  display: flex; align-items: center; justify-content: space-between; gap: 12px;
+  padding: 14px 16px; border-bottom: 1px solid var(--border-soft);
+}
+.file-meta { display: flex; align-items: center; gap: 10px; min-width: 0; }
+.file-name { font-size: 15px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.file-head-right { display: flex; align-items: center; gap: 12px; flex: none; }
+.status-text { font-size: 12.5px; color: var(--text-dim); }
+.status-dot { width: 9px; height: 9px; border-radius: 50%; background: var(--text-faint); flex: none; }
+.status-dot.processing { background: var(--accent); animation: pulse 1.2s infinite; }
+.status-dot.done { background: var(--green); }
+.status-dot.error { background: var(--red); }
+.status-dot.cancelled { background: var(--amber); }
+@keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.35; } }
+
+.progress-row { display: flex; align-items: center; gap: 12px; padding: 12px 16px; }
+.progress-track { flex: 1; height: 7px; background: var(--bg-soft); border-radius: 999px; overflow: hidden; }
+.progress-fill { height: 100%; width: 0%; background: linear-gradient(90deg, var(--accent-2), var(--accent)); border-radius: 999px; transition: width 0.3s ease; }
+.progress-label { font-size: 12px; color: var(--text-dim); font-variant-numeric: tabular-nums; flex: none; }
+
+.file-error {
+  margin: 0 16px 14px;
+  padding: 10px 12px;
+  background: var(--red-soft);
+  border: 1px solid rgba(255, 93, 108, 0.35);
+  border-radius: var(--radius-sm);
+  color: var(--red);
+  font-size: 13px;
+}
+
+.pages { display: flex; flex-direction: column; gap: 12px; padding: 4px 16px 16px; }
+
+/* page card */
+.page-card {
+  border: 1px solid var(--border-soft);
+  border-radius: var(--radius-sm);
+  background: var(--bg-soft);
+  overflow: hidden;
+}
+.page-head { display: flex; align-items: center; gap: 10px; padding: 9px 12px; border-bottom: 1px solid var(--border-soft); }
+.page-num { font-size: 13px; font-weight: 700; color: var(--text-dim); }
+.page-spacer { flex: 1; }
+.badge { font-size: 11px; font-weight: 700; padding: 3px 9px; border-radius: 999px; text-transform: uppercase; letter-spacing: 0.03em; }
+.badge.text { color: var(--green); background: var(--green-soft); border: 1px solid rgba(46, 204, 143, 0.35); }
+.badge.ocr { color: var(--amber); background: var(--amber-soft); border: 1px solid rgba(245, 166, 35, 0.35); }
+.badge.ocr.lowconf { color: var(--red); background: var(--red-soft); border-color: rgba(255, 93, 108, 0.35); }
+.badge.handwriting { color: #b98cff; background: rgba(160, 120, 255, 0.15); border: 1px solid rgba(160, 120, 255, 0.4); }
+.badge.online { color: #4fc3f7; background: rgba(79, 195, 247, 0.14); border: 1px solid rgba(79, 195, 247, 0.4); }
+.beta-tag { font-size: 9px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; color: var(--accent); background: rgba(108,140,255,0.16); padding: 1px 5px; border-radius: 999px; vertical-align: middle; }
+.badge.error { color: var(--red); background: var(--red-soft); border: 1px solid rgba(255, 93, 108, 0.35); }
+.badge.pending { color: var(--text-faint); background: var(--border-soft); border: 1px solid var(--border); }
+
+.page-text {
+  margin: 0;
+  padding: 14px 16px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--text);
+  max-height: 460px;
+  overflow: auto;
+}
+.page-text:empty::before { content: "(no text on this page)"; color: var(--text-faint); font-style: italic; }
+.page-text mark { background: var(--amber); color: #1a1a1a; border-radius: 2px; padding: 0 1px; }
+.page-text mark.active { background: #ffd86b; outline: 1px solid var(--amber); }
+
+/* Low-confidence line highlight ("which lines to check") */
+.lc-line { background: rgba(245, 166, 35, 0.16); border-bottom: 1px dashed rgba(245, 166, 35, 0.7); border-radius: 2px; }
+
+/* "N to check" chip in the page header */
+.to-check { font-size: 11px; font-weight: 600; color: var(--amber); background: var(--amber-soft); border: 1px solid rgba(245, 166, 35, 0.35); border-radius: 999px; padding: 2px 8px; white-space: nowrap; }
+
+/* Inline edit box — matches the read-only text view */
+.page-edit {
+  width: 100%; box-sizing: border-box; margin: 0;
+  padding: 14px 16px; min-height: 180px; max-height: 460px; resize: vertical;
+  white-space: pre-wrap; word-break: break-word;
+  font-family: var(--mono); font-size: 13px; line-height: 1.6;
+  color: var(--text); background: var(--bg-soft);
+  border: 1px solid var(--accent); border-radius: 0 0 var(--radius-sm) var(--radius-sm);
+  outline: none;
+}
+
+.page-image-wrap { padding: 12px 16px; border-top: 1px solid var(--border-soft); background: var(--panel); }
+.page-image-wrap img { max-width: 100%; border-radius: 6px; border: 1px solid var(--border); display: block; }
+.page-image-wrap .img-loading { color: var(--text-faint); font-size: 13px; }
+
+/* toast */
+.toast {
+  position: fixed;
+  bottom: 24px;
+  left: 50%;
+  transform: translateX(-50%) translateY(10px);
+  background: var(--panel-2);
+  border: 1px solid var(--border);
+  color: var(--text);
+  padding: 11px 18px;
+  border-radius: 999px;
+  font-size: 13.5px;
+  font-weight: 600;
+  box-shadow: var(--shadow);
+  opacity: 0;
+  transition: opacity 0.2s, transform 0.2s;
+  z-index: 50;
+  pointer-events: none;
+}
+.toast.show { opacity: 1; transform: translateX(-50%) translateY(0); }
+
+/* responsive */
+@media (max-width: 900px) {
+  .layout { grid-template-columns: 1fr; padding: 16px; gap: 18px; }
+  .toolbar { position: static; }
+  .sidebar { order: 2; }
+  .work { order: 1; }
+}
+@media (max-width: 520px) {
+  .app-header { padding: 12px 16px; }
+  .brand-text h1 { font-size: 17px; }
+  .toolbar-actions { width: 100%; justify-content: space-between; }
+}
+
+/* scrollbars */
+.page-text::-webkit-scrollbar { width: 10px; height: 10px; }
+.page-text::-webkit-scrollbar-thumb { background: var(--border); border-radius: 999px; border: 2px solid var(--bg-soft); }
+.page-text::-webkit-scrollbar-track { background: transparent; }
+
+/* Large-handwriting sub-setting: indented under the handwriting toggle */
+.setting-sub { margin-left: 14px; padding-left: 10px; border-left: 2px solid var(--border-soft); }
+
+/* "Suggest best settings" recommendation panel */
+.btn-primary { background: var(--accent); color: #fff; border-color: var(--accent); }
+.btn-primary:hover { background: var(--accent-2); }
+.suggest-card { margin-top: 6px; padding: 10px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--bg-soft); }
+.suggest-rationale { font-size: 12px; line-height: 1.45; margin: 0 0 8px; color: var(--text-dim); }
+.suggest-evidence { font-size: 11px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; margin-bottom: 8px; }
+.ev-row { display: grid; grid-template-columns: 1.5fr 1fr 0.9fr 0.9fr; gap: 6px; padding: 2px 0; opacity: 0.75; }
+.ev-row.best { opacity: 1; font-weight: 600; color: var(--text); }
+
+/* Online (Gemini) settings */
+.online-input { width: 100%; margin-bottom: 6px; font-family: ui-monospace, monospace; font-size: 12px; }
+.online-key-actions { display: flex; align-items: center; gap: 8px; }
+.online-status { font-size: 11px; }
+.online-status.good { color: var(--green); }
+.online-status.bad { color: var(--red); }
+
+/* Remove (×) button on a file card */
+.btn-remove { color: var(--text-dim); font-size: 18px; line-height: 1; padding: 3px 9px; font-weight: 700; }
+.btn-remove:hover { color: var(--red); background: var(--red-soft); }
+
+/* Settings group sub-headings */
+.setting-group-label {
+  font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.08em;
+  color: var(--text-faint); margin: 18px 0 4px; padding-top: 14px;
+  border-top: 1px solid var(--border-soft);
+}