document-ocr 0.0.0-stage → 3.1.3

package/python/core/preprocessor.py

@@ -0,0 +1,297 @@
+"""
+Image preprocessing for passport OCR.
+
+Accepts a raw image (file path or bytes). Returns a clean, normalised image
+ready for OCR after document detection, perspective correction, and
+quality checks.
+"""
+
+from __future__ import annotations
+
+import io
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Union
+
+import cv2
+import numpy as np
+from PIL import Image, ImageOps, UnidentifiedImageError
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MIN_RESOLUTION = 600          # shortest dimension must be >= this
+BLUR_THRESHOLD = 80           # Laplacian variance below this → blurry
+GLARE_V_THRESHOLD = 250       # HSV V channel threshold for glare
+GLARE_PIXEL_RATIO = 0.15      # reject if > 15 % pixels exceed V threshold
+TARGET_WIDTH = 1600            # normalise output to this width
+CLAHE_CLIP = 2.0
+CLAHE_GRID = (8, 8)
+
+# Document-detection sanity thresholds. Polygon approximation can produce
+# degenerate quads from noise (perforations, watermarks, form-field rectangles).
+# A real document boundary should cover most of the frame and be roughly
+# convex with a passport-like aspect ratio.
+MIN_QUAD_AREA_RATIO = 0.30    # quad must cover ≥ 30 % of image area
+MIN_QUAD_ASPECT = 0.5         # reject very narrow / very tall quads
+MAX_QUAD_ASPECT = 3.0
+MIN_WARPED_AREA_RATIO = 0.50  # if perspective-corrected image is < 50 %
+                              # of the input area, discard and use raw
+
+
+# ---------------------------------------------------------------------------
+# Result type
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PreprocessResult:
+    image: np.ndarray
+    warnings: list[str] = field(default_factory=list)
+    # Same geometry and resolution as image, without contrast enhancement.
+    # Retained for bounded rereads when security backgrounds worsen with CLAHE.
+    unenhanced_image: Optional[np.ndarray] = field(default=None, repr=False)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_image(source: Union[str, bytes, Path]) -> np.ndarray:
+    """Load image from file path, bytes, or Path and return BGR numpy array."""
+    # Decode paths and uploads identically: OpenCV's path/byte decoders do not
+    # consistently handle EXIF orientation or HEIF, especially for phone photos.
+    data = Path(source).read_bytes() if isinstance(source, (str, Path)) else source
+    if data.startswith(b"%PDF-"):
+        return _load_pdf_first_page(data)
+    try:
+        try:
+            image = Image.open(io.BytesIO(data))
+        except UnidentifiedImageError:
+            import pillow_heif
+
+            pillow_heif.register_heif_opener()
+            image = Image.open(io.BytesIO(data))
+        with image:
+            if image.width * image.height > 40_000_000:
+                raise ImageQualityError("IMAGE_TOO_LARGE")
+            oriented = ImageOps.exif_transpose(image)
+            pixels = np.asarray(oriented)
+            if pixels.dtype.kind == "u" and pixels.dtype.itemsize == 2:
+                # Pillow's direct RGB conversion clips 16-bit grayscale at 255,
+                # erasing nearly all contrast. Match 8-bit image decoding by
+                # retaining the high byte across the full 16-bit range.
+                oriented = Image.fromarray((pixels >> 8).astype(np.uint8))
+            return cv2.cvtColor(np.array(oriented.convert("RGB")), cv2.COLOR_RGB2BGR)
+    except Image.DecompressionBombError as exc:
+        raise ImageQualityError("IMAGE_TOO_LARGE") from exc
+    except (OSError, ValueError) as exc:
+        raise ImageQualityError("INVALID_IMAGE") from exc
+
+
+def _load_pdf_first_page(source: Union[str, bytes, Path]) -> np.ndarray:
+    """Render a bounded first PDF page in the common 1600-pixel coordinate plane."""
+    from .document_input import input_bytes, pdf_pages
+    return pdf_pages(input_bytes(source), first_only=True)[0].image
+
+
+def _check_resolution(img: np.ndarray) -> None:
+    h, w = img.shape[:2]
+    # Card scans can retain readable text at ~800 x 480. Keep the existing
+    # general threshold while admitting a bounded compact-card size; blur and
+    # extraction completeness still have to pass independently.
+    compact_card = min(h, w) >= 450 and max(h, w) >= 750
+    if min(h, w) < MIN_RESOLUTION and not compact_card:
+        raise ImageQualityError("RESOLUTION_TOO_LOW")
+
+
+def _check_blur(img: np.ndarray, threshold: float = BLUR_THRESHOLD) -> None:
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    variance = cv2.Laplacian(gray, cv2.CV_64F).var()
+    if variance < threshold:
+        raise ImageQualityError("IMAGE_TOO_BLURRY")
+
+
+def _check_glare(img: np.ndarray) -> Optional[str]:
+    hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
+    v_channel = hsv[:, :, 2]
+    ratio = np.count_nonzero(v_channel > GLARE_V_THRESHOLD) / v_channel.size
+    if ratio > GLARE_PIXEL_RATIO:
+        return "GLARE_DETECTED"
+    return None
+
+
+def _detect_document(img: np.ndarray) -> tuple[np.ndarray | None, list[str]]:
+    """Find the document quadrilateral. Returns (corners, warnings).
+
+    Only accepts a 4-corner approximation that is plausibly an entire
+    document: large enough, convex, and with a passport-like aspect ratio.
+    Without these checks, polygon approximation of noise contours
+    (perforations, form-field rectangles, watermark edges) can produce
+    degenerate quads that destroy the image during perspective correction.
+    """
+    warnings: list[str] = []
+    h, w = img.shape[:2]
+    img_area = float(h * w)
+
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+    edges = cv2.Canny(blurred, 50, 150)
+
+    # dilate to close gaps
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
+    edges = cv2.dilate(edges, kernel, iterations=1)
+
+    contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+    if not contours:
+        warnings.append("NO_DOCUMENT_BOUNDARY_DETECTED")
+        return None, warnings
+
+    # sort by area descending
+    contours = sorted(contours, key=cv2.contourArea, reverse=True)
+
+    for cnt in contours[:5]:
+        peri = cv2.arcLength(cnt, True)
+        approx = cv2.approxPolyDP(cnt, 0.02 * peri, True)
+        if len(approx) != 4:
+            continue
+        if _is_plausible_document_quad(approx, img_area):
+            return approx.reshape(4, 2).astype(np.float32), warnings
+
+    warnings.append("NO_DOCUMENT_BOUNDARY_DETECTED")
+    return None, warnings
+
+
+def _is_plausible_document_quad(approx: np.ndarray, img_area: float) -> bool:
+    """A real document quad covers most of the image, is convex, and has a
+    sane aspect ratio. Anything else is almost certainly a noise contour."""
+    if not cv2.isContourConvex(approx):
+        return False
+    if cv2.contourArea(approx) < img_area * MIN_QUAD_AREA_RATIO:
+        return False
+    _, _, bw, bh = cv2.boundingRect(approx)
+    if bw <= 0 or bh <= 0:
+        return False
+    aspect = bw / bh
+    return MIN_QUAD_ASPECT <= aspect <= MAX_QUAD_ASPECT
+
+
+def _order_points(pts: np.ndarray) -> np.ndarray:
+    """Order points: top-left, top-right, bottom-right, bottom-left."""
+    # Sorting each extremum separately can select the same vertex twice when
+    # sums/differences tie (for example a document rotated by 45 degrees).
+    points = np.asarray(pts, dtype=np.float32).reshape(4, 2)
+    center = points.mean(axis=0)
+    angles = np.arctan2(points[:, 1] - center[1], points[:, 0] - center[0])
+    ordered = points[np.argsort(angles)]
+    start = np.lexsort((ordered[:, 0], ordered[:, 1], ordered.sum(axis=1)))[0]
+    return np.roll(ordered, -start, axis=0)
+
+
+def _perspective_correct(img: np.ndarray, corners: np.ndarray) -> np.ndarray:
+    """Apply perspective transform to produce a flat, top-down crop."""
+    rect = _order_points(corners)
+    (tl, tr, br, bl) = rect
+
+    width_a = np.linalg.norm(br - bl)
+    width_b = np.linalg.norm(tr - tl)
+    max_w = int(max(width_a, width_b))
+
+    height_a = np.linalg.norm(tr - br)
+    height_b = np.linalg.norm(tl - bl)
+    max_h = int(max(height_a, height_b))
+
+    dst = np.array([
+        [0, 0],
+        [max_w - 1, 0],
+        [max_w - 1, max_h - 1],
+        [0, max_h - 1],
+    ], dtype=np.float32)
+
+    matrix = cv2.getPerspectiveTransform(rect, dst)
+    return cv2.warpPerspective(img, matrix, (max_w, max_h))
+
+
+def _resize(img: np.ndarray) -> np.ndarray:
+    """Use the same coordinate plane for enhanced and original-color reads."""
+    h, w = img.shape[:2]
+    if w > TARGET_WIDTH:
+        ratio = TARGET_WIDTH / w
+        new_h = int(h * ratio)
+        img = cv2.resize(img, (TARGET_WIDTH, new_h), interpolation=cv2.INTER_LANCZOS4)
+    return img
+
+
+def _normalise(img: np.ndarray) -> np.ndarray:
+    """Downscale to standard width (if larger) and apply CLAHE contrast enhancement."""
+    return enhance_contrast(_resize(img))
+
+
+def enhance_contrast(img: np.ndarray) -> np.ndarray:
+    """Enhance contrast without resizing or moving any evidence coordinates."""
+
+    # CLAHE on L channel in LAB
+    lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
+    l, a, b = cv2.split(lab)
+    clahe = cv2.createCLAHE(clipLimit=CLAHE_CLIP, tileGridSize=CLAHE_GRID)
+    l = clahe.apply(l)
+    lab = cv2.merge([l, a, b])
+    return cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+class ImageQualityError(Exception):
+    """Raised when image quality is insufficient for OCR."""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def preprocess(
+    source: Union[str, bytes, Path],
+    *,
+    blur_threshold: float = BLUR_THRESHOLD,
+) -> PreprocessResult:
+    """
+    Full preprocessing pipeline.
+
+    1. Load image
+    2. Resolution check
+    3. Blur detection
+    4. Glare detection
+    5. Document detection + perspective correction
+    6. Normalisation (resize + CLAHE)
+    """
+    img = _load_image(source)
+    _check_resolution(img)
+    _check_blur(img, threshold=blur_threshold)
+    glare_warning = _check_glare(img)
+
+    corners, warnings = _detect_document(img)
+    if min(img.shape[:2]) < MIN_RESOLUTION:
+        warnings.append("COMPACT_CARD_RESOLUTION")
+
+    if glare_warning:
+        warnings.append(glare_warning)
+
+    if corners is not None:
+        original_area = img.shape[0] * img.shape[1]
+        warped = _perspective_correct(img, corners)
+        warped_area = warped.shape[0] * warped.shape[1]
+        if warped_area >= original_area * MIN_WARPED_AREA_RATIO:
+            img = warped
+        else:
+            # Perspective transform produced a degenerate strip — the detected
+            # quad must have been bogus. Discard it and use the raw image.
+            warnings.append("PERSPECTIVE_CORRECTION_DISCARDED")
+
+    unenhanced = _resize(img)
+    img = _normalise(unenhanced)
+
+    return PreprocessResult(image=img, warnings=warnings, unenhanced_image=unenhanced)

package/python/core/recovery_budget.py

@@ -0,0 +1,67 @@
+"""Request-scoped time budget for optional recovery OCR passes.
+
+Recovery re-reads damaged rows after the base passes have run. Each re-read is
+optional, so a scan stops starting new ones once the budget measured from the
+start of the scan is spent, and returns the best evidence it already has. A
+pass that has started always finishes; the budget bounds when passes may begin.
+
+    DOCUMENT_OCR_RECOVERY_BUDGET_SECONDS=5   # default; 0 disables recovery
+    DOCUMENT_OCR_RECOVERY_BUDGET_SECONDS=off # no limit
+"""
+from __future__ import annotations
+
+import contextvars
+import logging
+import os
+import time
+from contextlib import contextmanager
+from typing import Iterator, Optional
+
+logger = logging.getLogger("document-ocr.recovery_budget")
+
+BUDGET_ENV = "DOCUMENT_OCR_RECOVERY_BUDGET_SECONDS"
+DEFAULT_BUDGET_SECONDS = 5.0
+
+_deadline: contextvars.ContextVar[Optional[float]] = contextvars.ContextVar(
+    "document_ocr_recovery_deadline", default=None)
+
+
+def configured_budget(raw: Optional[str] = None) -> Optional[float]:
+    """Seconds allowed from scan start, or None for no limit."""
+    value = (os.getenv(BUDGET_ENV) if raw is None else raw) or ""
+    value = value.strip().lower()
+    if not value:
+        return DEFAULT_BUDGET_SECONDS
+    if value in {"off", "none", "unlimited"}:
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        # A typo in deployment config must not fail every scan.
+        logger.warning("%s=%r is not a number of seconds or 'off'; using %s",
+                       BUDGET_ENV, value, DEFAULT_BUDGET_SECONDS)
+        return DEFAULT_BUDGET_SECONDS
+    return max(seconds, 0.0)
+
+
+@contextmanager
+def recovery_deadline(start: float) -> Iterator[None]:
+    """Bound optional recovery for the scan that began at ``start`` (monotonic).
+
+    A nested call inside an active scan keeps the outer deadline.
+    """
+    if _deadline.get() is not None:
+        yield
+        return
+    budget = configured_budget()
+    token = _deadline.set(None if budget is None else start + budget)
+    try:
+        yield
+    finally:
+        _deadline.reset(token)
+
+
+def recovery_allowed() -> bool:
+    """True while an optional recovery pass may still start."""
+    deadline = _deadline.get()
+    return deadline is None or time.monotonic() < deadline

package/python/core/redaction.py

@@ -0,0 +1,48 @@
+"""Burn caller-reviewed redaction polygons into a metadata-free PNG raster."""
+import json
+import math
+
+import cv2
+import numpy as np
+
+from .pipeline import preview_image
+
+
+def render_preview(data: bytes) -> bytes:
+    return _png(preview_image(data))
+
+
+def redact(data: bytes, boxes: str | list) -> bytes:
+    if isinstance(boxes, str):
+        try:
+            boxes = json.loads(boxes)
+        except ValueError as exc:
+            raise ValueError('INVALID_REDACTION_BOXES') from exc
+    if not isinstance(boxes, list) or not 1 <= len(boxes) <= 200:
+        raise ValueError('INVALID_REDACTION_BOXES')
+    image = preview_image(data).copy()
+    height, width = image.shape[:2]
+    for box in boxes:
+        if not isinstance(box, list) or len(box) != 4:
+            raise ValueError('INVALID_REDACTION_BOXES')
+        for point in box:
+            if (not isinstance(point, list) or len(point) != 2
+                or any(isinstance(x, bool) or not isinstance(x, (float, int)) or not math.isfinite(x) for x in point)
+                or not (0 <= point[0] <= width and 0 <= point[1] <= height)):
+                raise ValueError('INVALID_REDACTION_BOXES')
+        points = np.array(box, dtype=np.int32)
+        if abs(cv2.contourArea(points)) < 1:
+            raise ValueError('INVALID_REDACTION_BOXES')
+        # Bounding rectangles intentionally cover the entire text quad with a
+        # small ink margin. PNG output has no retained PDF text layer or EXIF.
+        x0, y0 = np.maximum(points.min(axis=0) - 3, 0)
+        x1, y1 = np.minimum(points.max(axis=0) + 4, (width, height))
+        image[y0:y1, x0:x1] = 0
+    return _png(image)
+
+
+def _png(image) -> bytes:
+    ok, encoded = cv2.imencode('.png', image)
+    if not ok:
+        raise ValueError('IMAGE_ENCODING_FAILED')
+    return encoded.tobytes()

package/python/core/review.html

@@ -0,0 +1,244 @@
+<!doctype html>
+<html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Document OCR · Review</title>
+<style>
+:root{font-family:system-ui,sans-serif;color:#162333;background:#f4f6f8}body{max-width:1280px;margin:auto;padding:28px}h1{font-size:28px;margin:0 0 6px}p{color:#566576;line-height:1.5}header{margin-bottom:24px}.controls{display:flex;gap:12px;flex-wrap:wrap;align-items:end;padding:20px;background:white;border-radius:12px}label{font-size:13px;display:block}input,select,button{font:inherit;padding:10px;border:1px solid #c7d0d8;border-radius:6px;max-width:100%;box-sizing:border-box}button{cursor:pointer;background:#183c5e;color:white}button:disabled{opacity:.5;cursor:default}input[type=checkbox]{width:18px;height:18px}.workspace{display:grid;grid-template-columns:1.2fr 1fr;gap:20px;margin-top:20px}.panel{background:white;border-radius:12px;padding:20px;min-width:0}.image-wrap{position:relative;overflow:auto;max-height:75vh}canvas{max-width:100%;height:auto;display:block}.row{display:grid;grid-template-columns:22px 1fr;gap:10px;margin-bottom:16px}.row input[type=text]{width:100%;margin-top:5px}.source{font-size:12px;color:#647486;white-space:pre-wrap;overflow-wrap:anywhere;margin-top:4px}.status{white-space:pre-wrap;margin:18px 0;color:#183c5e}details{margin-top:16px}pre{max-height:300px;overflow:auto;font-size:12px;white-space:pre-wrap}.exports{display:flex;gap:8px;flex-wrap:wrap}.note{font-size:12px}@media(max-width:800px){body{padding:16px}.workspace{grid-template-columns:1fr}}
+</style>
+<header><h1>Review a document</h1><p>Inspect extracted values and their source regions. Corrections stay in this browser tab until you export them.</p></header>
+<div class="controls">
+<label>Image or PDF<input id="file" type="file" accept="image/*,application/pdf"></label>
+<label>API token<input id="token" type="password" autocomplete="off" placeholder="If configured"></label>
+<label>Country<select id="country"><option value="">Auto detect</option value="US">United States</option><option value="IN">India</option></select></label>
+<label>Document<select id="type"><option value="">Auto detect</option></select></label>
+<button id="scan">Extract</button><button id="clear">Clear</button>
+</div>
+<p class="note">This screen reviews one image or the first PDF page. Use the SDK’s scanDocument method for grouped pages. A successful extraction does not establish document authenticity.</p>
+<div id="status" class="status" role="status" aria-live="polite">Choose a document to begin.</div>
+<div class="workspace">
+<section class="panel"><div class="image-wrap"><canvas id="canvas" aria-label="Document with highlighted source region"></canvas></div></section>
+<section class="panel"><div id="fields"></div><div class="exports"><button id="json" disabled>Export JSON</button><button id="csv" disabled>Export CSV</button><button id="redact" disabled>Redact checked fields</button></div><p class="note">Redaction produces a PNG of the normalized first page. Check the downloaded image before sharing; unrecognized text, photos and unselected fields remain visible.</p><details><summary>Original extraction</summary><pre id="raw"></pre></details></section>
+</div>
+<script>
+const $ = id => document.getElementById(id);
+let result = null, scannedFile = null, preview = null;
+let original = {}, corrected = {};
+let selected = new Set(), objectURLs = [];
+let generation = 0, controller = null;
+
+function headers() {
+  return $('token').value ? { Authorization: 'Bearer ' + $('token').value } : {};
+}
+function form(file = scannedFile) {
+  const data = new FormData();
+  data.append('image', file);
+  return data;
+}
+function say(text) { $('status').textContent = text; }
+function enableExports(enabled) {
+  for (const key of ['json', 'csv', 'redact']) $(key).disabled = !enabled;
+}
+function showImage(boxes = []) {
+  const canvas = $('canvas'), context = canvas.getContext('2d');
+  if (!preview) {
+    context.clearRect(0, 0, canvas.width, canvas.height);
+    return;
+  }
+  canvas.width = preview.width;
+  canvas.height = preview.height;
+  context.drawImage(preview, 0, 0);
+  context.strokeStyle = '#d94e22';
+  context.fillStyle = '#fb9c4030';
+  context.lineWidth = 3;
+  for (const box of boxes) {
+    if (!box.length) continue;
+    context.beginPath();
+    box.forEach((point, index) => index ? context.lineTo(...point) : context.moveTo(...point));
+    context.closePath();
+    context.fill();
+    context.stroke();
+  }
+}
+function releaseURLs() {
+  for (const url of objectURLs) URL.revokeObjectURL(url);
+  objectURLs = [];
+}
+function download(blob, name) {
+  const url = URL.createObjectURL(blob);
+  objectURLs.push(url);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = name;
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+async function readResponse(response) {
+  const data = await response.json();
+  if (!response.ok && !data.documentType) {
+    throw new Error(data.detail || data.error || 'Request failed');
+  }
+  return data;
+}
+async function catalog() {
+  try {
+    const response = await fetch('/documents', { headers: headers() });
+    if (!response.ok) return;
+    const data = await response.json();
+    $('type').replaceChildren(new Option('Auto detect', ''));
+    for (const doc of data.documents) {
+      $('type').add(new Option(doc.label + (doc.experimental ? ' · experimental' : ''), doc.documentType));
+    }
+  } catch { /* The scan endpoint will report connection or authentication errors. */ }
+}
+$('token').addEventListener('change', catalog);
+catalog();
+
+function renderFields() {
+  for (const [key, value] of Object.entries(original)) {
+    const row = document.createElement('div');
+    row.className = 'row';
+    const check = document.createElement('input');
+    check.type = 'checkbox';
+    check.setAttribute('aria-label', 'Redact ' + key);
+    const evidence = result.fieldEvidence?.[key] || [];
+    check.disabled = !evidence.length;
+    check.onchange = () => {
+      if (check.checked) selected.add(key); else selected.delete(key);
+      showImage([...selected].flatMap(field => (result.fieldEvidence?.[field] || []).map(item => item.bbox)));
+    };
+    const block = document.createElement('div'), label = document.createElement('label');
+    label.textContent = key;
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.value = value === null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
+    input.oninput = () => { corrected[key] = input.value; };
+    input.onfocus = () => showImage(evidence.map(item => item.bbox));
+    label.append(input);
+    block.append(label);
+    const source = document.createElement('div');
+    source.className = 'source';
+    source.textContent = evidence.length
+      ? evidence.map(item => `${item.source} · ${Math.round(item.confidence * 100)}% · ${item.text}`).join('\n')
+      : 'No matched source region';
+    block.append(source);
+    row.append(check, block);
+    $('fields').append(row);
+  }
+}
+
+$('scan').onclick = async () => {
+  const file = $('file').files[0];
+  if (!file) { say('Choose an image or PDF first.'); return; }
+  controller?.abort();
+  const requestController = new AbortController();
+  controller = requestController;
+  const current = ++generation;
+  const requestHeaders = headers();
+  $('scan').disabled = true;
+  result = preview = scannedFile = null;
+  original = {}; corrected = {};
+  selected.clear();
+  releaseURLs();
+  $('fields').replaceChildren();
+  $('raw').textContent = '';
+  showImage();
+  enableExports(false);
+  try {
+    say('Extracting document…');
+    const data = form(file);
+    data.append('include_evidence', 'true');
+    if ($('country').value) data.append('country', $('country').value);
+    if ($('type').value) data.append('document_type', $('type').value);
+    const extracted = await readResponse(await fetch('/scan', {
+      method: 'POST', headers: requestHeaders, body: data, signal: requestController.signal,
+    }));
+    if (current !== generation) return;
+    const imageResponse = await fetch('/preview', {
+      method: 'POST', headers: requestHeaders, body: form(file), signal: requestController.signal,
+    });
+    if (current !== generation) return;
+    let loadedImage = null;
+    if (imageResponse.ok) {
+      const blob = await imageResponse.blob();
+      if (current !== generation) return;
+      const url = URL.createObjectURL(blob);
+      objectURLs.push(url);
+      loadedImage = await new Promise((resolve, reject) => {
+        const image = new Image();
+        image.onload = () => resolve(image);
+        image.onerror = reject;
+        image.src = url;
+      });
+      if (current !== generation) { URL.revokeObjectURL(url); return; }
+    }
+    result = extracted;
+    scannedFile = file;
+    preview = loadedImage;
+    original = { ...(result.documentFields || {}) };
+    corrected = { ...original };
+    $('raw').textContent = JSON.stringify(result, null, 2);
+    showImage();
+    renderFields();
+    enableExports(true);
+    say(`${result.documentType} · ${result.status} · confidence ${Math.round(result.confidence * 100)}%\n` +
+        [...(result.errors || []), ...(result.warnings || [])].join(', '));
+  } catch (error) {
+    if (current === generation && error.name !== 'AbortError') {
+      say(error.message || 'Unable to extract document');
+    }
+  } finally {
+    if (current === generation) $('scan').disabled = false;
+  }
+};
+
+function changes() {
+  return Object.keys(corrected)
+    .filter(key => JSON.stringify(corrected[key]) !== JSON.stringify(original[key]))
+    .map(field => ({ field, original: original[field], corrected: corrected[field] }));
+}
+$('json').onclick = () => download(new Blob([JSON.stringify({
+  extraction: result,
+  review: { correctedFields: corrected, changes: changes(), reviewedAt: new Date().toISOString() },
+}, null, 2)], { type: 'application/json' }), 'reviewed-document.json');
+function csv(value) {
+  let text = typeof value === 'object' ? JSON.stringify(value) : String(value ?? '');
+  if (/^[=+@\-\t\r]/.test(text)) text = "'" + text;
+  return '"' + text.replaceAll('"', '""') + '"';
+}
+$('csv').onclick = () => download(new Blob(['field,original,corrected\r\n' +
+  Object.keys(corrected).map(key => [key, original[key], corrected[key]].map(csv).join(',')).join('\r\n')],
+  { type: 'text/csv' }), 'reviewed-document.csv');
+$('redact').onclick = async () => {
+  const boxes = [...selected].flatMap(key => (result.fieldEvidence?.[key] || []).map(item => item.bbox));
+  if (!boxes.length) { say('Check at least one field with source evidence to redact.'); return; }
+  const current = generation;
+  try {
+    const data = form(scannedFile);
+    data.append('boxes', JSON.stringify(boxes));
+    const response = await fetch('/redact', { method: 'POST', headers: headers(), body: data, signal: controller.signal });
+    if (current !== generation) return;
+    if (!response.ok) throw new Error((await response.json()).error || 'Redaction failed');
+    const blob = await response.blob();
+    if (current !== generation) return;
+    download(blob, 'redacted.png');
+    say('Redacted PNG exported. Inspect it before sharing.');
+  } catch (error) {
+    if (current === generation && error.name !== 'AbortError') say(error.message);
+  }
+};
+$('clear').onclick = () => {
+  ++generation;
+  controller?.abort();
+  controller = null;
+  result = preview = scannedFile = null;
+  original = {}; corrected = {};
+  selected.clear();
+  $('file').value = '';
+  $('fields').replaceChildren();
+  $('raw').textContent = '';
+  showImage();
+  releaseURLs();
+  enableExports(false);
+  $('scan').disabled = false;
+  say('Document cleared.');
+};
+</script></html>