Add persistent book page scope, safe titles, and OCR stall guards

smoke_signal/scripts/font_library.py

@@ -0,0 +1,423 @@
+"""
+Smoke Signal — Font Detection + Font-Aware OCR Helpers
+======================================================
+Lightweight utilities for:
+1) identifying page fonts via MixFont Lens API
+2) maintaining per-font OCR preference metadata
+3) selecting per-font custom Tesseract models when available
+4) exposing font-specific punctuation-map paths
+
+This module is intentionally defensive:
+- if MixFont key is missing, it degrades gracefully
+- if no custom .traineddata exists, it falls back to "eng"
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+SS_ROOT = Path(os.environ.get("SS_DATA_ROOT", os.environ.get("SS_ROOT", "/tmp/smoke_signal")))
+CALIBRATION_DIR = SS_ROOT / "calibration"
+FONTS_DIR = SS_ROOT / "fonts"
+TESSDATA_DIR = SS_ROOT / "tessdata"
+REPO_TESSDATA_DIR = Path(__file__).resolve().parents[1] / "tessdata"
+FONT_REGISTRY_PATH = CALIBRATION_DIR / "font_registry.json"
+
+for _dir in (CALIBRATION_DIR, FONTS_DIR, TESSDATA_DIR, REPO_TESSDATA_DIR):
+    _dir.mkdir(parents=True, exist_ok=True)
+
+MIXFONT_API_KEY = os.environ.get("MIXFONT_API_KEY", "").strip()
+# MixFont Lens API docs endpoint.
+MIXFONT_API_URL = os.environ.get("MIXFONT_API_URL", "https://www.mixfont.com/v1/api/lens").strip()
+try:
+    MIXFONT_TIMEOUT_SEC = max(1.0, float(os.environ.get("MIXFONT_TIMEOUT_SEC", "4")))
+except Exception:
+    MIXFONT_TIMEOUT_SEC = 4.0
+
+
+def _slug_font_name(font_name: str) -> str:
+    cleaned = "".join(ch.lower() if ch.isalnum() else "_" for ch in (font_name or "").strip())
+    while "__" in cleaned:
+        cleaned = cleaned.replace("__", "_")
+    return cleaned.strip("_")
+
+
+def _load_registry() -> dict:
+    if not FONT_REGISTRY_PATH.exists():
+        return {}
+    try:
+        return json.loads(FONT_REGISTRY_PATH.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _save_registry(registry: dict) -> None:
+    FONT_REGISTRY_PATH.write_text(
+        json.dumps(registry, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+
+
+def _ensure_registry_entry(font_name: str) -> dict:
+    registry = _load_registry()
+    entry = registry.get(font_name, {})
+    if not entry:
+        entry = {
+            "identified_count": 0,
+            "status": "unknown",  # unknown | available | missing | specimen_only
+            "preferred_engine": "surya",  # surya | tesseract
+            "tesseract_model": None,
+            "avg_confidence_surya": None,
+            "avg_confidence_tess": None,
+            "last_identified_at": None,
+        }
+        registry[font_name] = entry
+        _save_registry(registry)
+    return entry
+
+
+def _build_public_image_url(local_image_path: str) -> Optional[str]:
+    """
+    Construct a publicly reachable URL for a local rendered page image.
+    Priority:
+      1) MIXFONT_IMAGE_URL_TEMPLATE with {path} placeholder
+      2) MIXFONT_IMAGE_BASE_URL + /gradio_api/file=<abs_path>
+      3) SPACE_HOST + /gradio_api/file=<abs_path>
+      4) HF_SPACE_URL + /gradio_api/file=<abs_path>
+    """
+    raw_path = str(Path(local_image_path).resolve())
+    encoded_path = urllib.parse.quote(raw_path, safe="")
+
+    template = os.environ.get("MIXFONT_IMAGE_URL_TEMPLATE", "").strip()
+    if template:
+        if "{path}" in template:
+            return template.replace("{path}", encoded_path)
+        return template
+
+    base = (
+        os.environ.get("MIXFONT_IMAGE_BASE_URL", "").strip()
+        or os.environ.get("HF_SPACE_URL", "").strip()
+        or ""
+    )
+    if not base:
+        space_id = os.environ.get("SPACE_ID", "").strip()
+        if space_id:
+            base = f"https://huggingface.co/spaces/{space_id}"
+    if not base:
+        space_host = os.environ.get("SPACE_HOST", "").strip()
+        if space_host:
+            if space_host.startswith("http://") or space_host.startswith("https://"):
+                base = space_host
+            else:
+                base = f"https://{space_host}"
+
+    if not base:
+        return None
+
+    return f"{base.rstrip('/')}/gradio_api/file={encoded_path}"
+
+
+def mixfont_preflight() -> dict:
+    """
+    Return runtime readiness checks for MixFont integration.
+    """
+    template = os.environ.get("MIXFONT_IMAGE_URL_TEMPLATE", "").strip()
+    base = (
+        os.environ.get("MIXFONT_IMAGE_BASE_URL", "").strip()
+        or os.environ.get("HF_SPACE_URL", "").strip()
+        or ""
+    )
+    if not base:
+        space_id = os.environ.get("SPACE_ID", "").strip()
+        if space_id:
+            base = f"https://huggingface.co/spaces/{space_id}"
+    space_host = os.environ.get("SPACE_HOST", "").strip()
+    has_public_source = bool(template or base or space_host)
+    return {
+        "api_key_set": bool(MIXFONT_API_KEY),
+        "api_url": MIXFONT_API_URL,
+        "image_url_template_set": bool(template),
+        "image_base_set": bool(base),
+        "space_host_set": bool(space_host),
+        "public_image_url_source_available": has_public_source,
+    }
+
+
+def identify_page_font(image_path: str, image_url: Optional[str] = None) -> dict:
+    """
+    Identify font via MixFont Lens API.
+    Returns:
+      {
+        "font_name": str|None,
+        "confidence": float,
+        "alternatives": list[str],
+        "image_url": str|None,
+        "error": str|None
+      }
+    """
+    if not MIXFONT_API_KEY:
+        return {
+            "font_name": None,
+            "confidence": 0.0,
+            "alternatives": [],
+            "image_url": image_url,
+            "error": "MIXFONT_API_KEY not set",
+        }
+
+    path_obj = Path(image_path)
+    if not path_obj.exists():
+        return {
+            "font_name": None,
+            "confidence": 0.0,
+            "alternatives": [],
+            "image_url": image_url,
+            "error": f"image not found: {image_path}",
+        }
+
+    resolved_url = image_url or _build_public_image_url(str(path_obj))
+    if not resolved_url:
+        return {
+            "font_name": None,
+            "confidence": 0.0,
+            "alternatives": [],
+            "image_url": None,
+            "error": "no public image URL (set MIXFONT_IMAGE_BASE_URL or MIXFONT_IMAGE_URL_TEMPLATE)",
+        }
+
+    payload = json.dumps({"image_url": resolved_url}).encode("utf-8")
+    request = urllib.request.Request(
+        MIXFONT_API_URL,
+        data=payload,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "x-api-key": MIXFONT_API_KEY,
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=MIXFONT_TIMEOUT_SEC) as response:
+            body = response.read().decode("utf-8", errors="replace")
+        data = json.loads(body)
+    except Exception as e:
+        return {
+            "font_name": None,
+            "confidence": 0.0,
+            "alternatives": [],
+            "image_url": resolved_url,
+            "error": str(e),
+        }
+
+    matches = data.get("font_matches", [])
+    if not isinstance(matches, list):
+        matches = []
+
+    top = matches[0] if matches else {}
+    if not isinstance(top, dict):
+        top = {}
+
+    font_name = str(top.get("name") or "").strip() or None
+    try:
+        confidence = float(top.get("confidence", 0.0))
+    except Exception:
+        confidence = 0.0
+
+    alternatives = []
+    for match in matches[1:4]:
+        if isinstance(match, dict):
+            name = str(match.get("name") or "").strip()
+            if name:
+                alternatives.append(name)
+
+    if font_name:
+        registry = _load_registry()
+        entry = registry.get(font_name, _ensure_registry_entry(font_name))
+        entry["identified_count"] = int(entry.get("identified_count", 0)) + 1
+        entry["last_identified_at"] = str(data.get("datetime") or "")
+        registry[font_name] = entry
+        _save_registry(registry)
+
+    return {
+        "font_name": font_name,
+        "confidence": round(confidence, 4),
+        "alternatives": alternatives,
+        "image_url": resolved_url,
+        "error": None,
+    }
+
+
+def register_font_model(
+    font_name: str,
+    model_name: Optional[str] = None,
+    preferred_engine: str = "tesseract",
+    status: str = "available",
+) -> dict:
+    """
+    Manually register a font->tesseract model mapping.
+    Use this for bespoke fonts where only a specimen-based traineddata exists.
+    """
+    if not font_name:
+        return {"ok": False, "error": "font_name required"}
+
+    model = (model_name or _slug_font_name(font_name) or "eng").strip()
+    registry = _load_registry()
+    entry = registry.get(font_name, _ensure_registry_entry(font_name))
+    entry["tesseract_model"] = model
+    entry["preferred_engine"] = preferred_engine if preferred_engine in {"surya", "tesseract"} else "tesseract"
+    entry["status"] = status
+    registry[font_name] = entry
+    _save_registry(registry)
+    return {"ok": True, "font_name": font_name, "tesseract_model": model}
+
+
+def resolve_tesseract_lang(font_name: Optional[str]) -> str:
+    """
+    Return best tesseract language/model to use for this font.
+    Defaults to "eng" if no custom traineddata is available.
+    """
+    if not font_name:
+        return "eng"
+
+    registry = _load_registry()
+    entry = registry.get(font_name, {})
+    candidates = []
+
+    explicit_model = str(entry.get("tesseract_model") or "").strip()
+    if explicit_model:
+        candidates.append(explicit_model)
+
+    slug = _slug_font_name(font_name)
+    if slug:
+        candidates.append(slug)
+        candidates.append(slug.replace("_", ""))
+
+    # unique keep order
+    seen = set()
+    deduped = []
+    for c in candidates:
+        if c and c not in seen:
+            deduped.append(c)
+            seen.add(c)
+
+    tess_dirs = [TESSDATA_DIR, REPO_TESSDATA_DIR]
+    for model_name in deduped:
+        if any((tess_dir / f"{model_name}.traineddata").exists() for tess_dir in tess_dirs):
+            if entry:
+                entry["status"] = "available"
+                entry["preferred_engine"] = "tesseract"
+                entry["tesseract_model"] = model_name
+                registry[font_name] = entry
+                _save_registry(registry)
+            return model_name
+
+    # Common misplacement: .traineddata.otf (font file, not Tesseract model)
+    otf_like_candidates = []
+    for model_name in deduped:
+        otf_like_candidates.extend(
+            [
+                REPO_TESSDATA_DIR / f"{model_name}.traineddata.otf",
+                TESSDATA_DIR / f"{model_name}.traineddata.otf",
+                REPO_TESSDATA_DIR / f"{model_name}.otf",
+                TESSDATA_DIR / f"{model_name}.otf",
+            ]
+        )
+    if any(path.exists() for path in otf_like_candidates):
+        if entry:
+            entry["status"] = "font_file_only"
+            entry["preferred_engine"] = "surya"
+            registry[font_name] = entry
+            _save_registry(registry)
+
+    # If a specimen exists but no model compiled yet, make that explicit in registry.
+    if (FONTS_DIR / "gruffalo_specimen.png").exists():
+        if entry:
+            entry["status"] = entry.get("status") or "specimen_only"
+            if entry["status"] == "unknown":
+                entry["status"] = "specimen_only"
+            registry[font_name] = entry
+            _save_registry(registry)
+
+    return "eng"
+
+
+def resolve_tessdata_dir(model_name: Optional[str]) -> Optional[str]:
+    if not model_name:
+        return None
+    model = str(model_name).strip()
+    if not model:
+        return None
+    for tess_dir in (TESSDATA_DIR, REPO_TESSDATA_DIR):
+        if (tess_dir / f"{model}.traineddata").exists():
+            return str(tess_dir)
+    return None
+
+
+def update_font_engine_stats(font_name: Optional[str], surya_conf: float, tess_conf: float) -> None:
+    if not font_name:
+        return
+    registry = _load_registry()
+    entry = registry.get(font_name, _ensure_registry_entry(font_name))
+    alpha = 0.3
+
+    prev_surya = entry.get("avg_confidence_surya")
+    prev_tess = entry.get("avg_confidence_tess")
+    try:
+        prev_surya_val = float(prev_surya) if prev_surya is not None else None
+    except Exception:
+        prev_surya_val = None
+    try:
+        prev_tess_val = float(prev_tess) if prev_tess is not None else None
+    except Exception:
+        prev_tess_val = None
+
+    surya_new = float(surya_conf or 0.0)
+    tess_new = float(tess_conf or 0.0)
+
+    surya_avg = surya_new if prev_surya_val is None else round(alpha * surya_new + (1 - alpha) * prev_surya_val, 4)
+    tess_avg = tess_new if prev_tess_val is None else round(alpha * tess_new + (1 - alpha) * prev_tess_val, 4)
+
+    entry["avg_confidence_surya"] = surya_avg
+    entry["avg_confidence_tess"] = tess_avg
+    entry["preferred_engine"] = "tesseract" if tess_avg > surya_avg else "surya"
+    if entry.get("status") == "unknown":
+        entry["status"] = "available"
+
+    registry[font_name] = entry
+    _save_registry(registry)
+
+
+def font_correction_map_path(font_name: Optional[str]) -> Path:
+    """
+    Font-specific punctuation learning map path.
+    """
+    if not font_name:
+        return CALIBRATION_DIR / "punct_correction_map.json"
+    safe = _slug_font_name(font_name) or "unknown"
+    return CALIBRATION_DIR / f"punct_correction_map_{safe}.json"
+
+
+def font_registry_summary() -> list[dict]:
+    registry = _load_registry()
+    rows = []
+    for name, row in sorted(
+        registry.items(),
+        key=lambda x: int(x[1].get("identified_count", 0)),
+        reverse=True,
+    ):
+        rows.append(
+            {
+                "font_name": name,
+                "pages_seen": int(row.get("identified_count", 0)),
+                "status": str(row.get("status", "unknown")),
+                "preferred_engine": str(row.get("preferred_engine", "surya")),
+                "tesseract_model": row.get("tesseract_model"),
+                "surya_avg": row.get("avg_confidence_surya"),
+                "tess_avg": row.get("avg_confidence_tess"),
+            }
+        )
+    return rows

smoke_signal/scripts/punct_corrector.py

@@ -38,17 +38,36 @@ KNOWN_SUBSTITUTIONS: dict[str, str] = {
 MIN_PUNCT_PER_10_WORDS = 0.8
 
 
-def _load_correction_map() -> dict[str, dict[str, int]]:
-    if CORRECTION_MAP_PATH.exists():
+def _resolve_map_path(font_name: Optional[str] = None, map_path: Optional[Path] = None) -> Path:
+    if map_path is not None:
+        return Path(map_path)
+    if font_name:
         try:
-            return json.loads(CORRECTION_MAP_PATH.read_text(encoding="utf-8"))
+            from smoke_signal.scripts.font_library import font_correction_map_path
+            return Path(font_correction_map_path(font_name))
+        except Exception:
+            pass
+    return CORRECTION_MAP_PATH
+
+
+def _load_correction_map(font_name: Optional[str] = None, map_path: Optional[Path] = None) -> dict[str, dict[str, int]]:
+    target = _resolve_map_path(font_name=font_name, map_path=map_path)
+    if target.exists():
+        try:
+            return json.loads(target.read_text(encoding="utf-8"))
         except Exception:
             return {}
     return {}
 
 
-def _save_correction_map(cmap: dict[str, dict[str, int]]) -> None:
-    CORRECTION_MAP_PATH.write_text(json.dumps(cmap, indent=2, ensure_ascii=False), encoding="utf-8")
+def _save_correction_map(
+    cmap: dict[str, dict[str, int]],
+    font_name: Optional[str] = None,
+    map_path: Optional[Path] = None,
+) -> None:
+    target = _resolve_map_path(font_name=font_name, map_path=map_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(cmap, indent=2, ensure_ascii=False), encoding="utf-8")
 
 
 def _top_substitution(cmap: dict[str, dict[str, int]], raw_char: str) -> Optional[str]:
@@ -153,7 +172,13 @@ def _align_chars(raw: str, gold: str) -> list[tuple[str, str]]:
     return out
 
 
-def record_punctuation_correction(raw_text: str, gold_text: str, book_id: str = "") -> int:
+def record_punctuation_correction(
+    raw_text: str,
+    gold_text: str,
+    book_id: str = "",
+    font_name: Optional[str] = None,
+    map_path: Optional[Path] = None,
+) -> int:
     if not raw_text or not gold_text or raw_text == gold_text:
         return 0
 
@@ -161,12 +186,12 @@ def record_punctuation_correction(raw_text: str, gold_text: str, book_id: str =
     if not pairs:
         return 0
 
-    cmap = _load_correction_map()
+    cmap = _load_correction_map(font_name=font_name, map_path=map_path)
     for raw_char, gold_char in pairs:
         if raw_char not in cmap:
             cmap[raw_char] = {}
         cmap[raw_char][gold_char] = int(cmap[raw_char].get(gold_char, 0)) + 1
-    _save_correction_map(cmap)
+    _save_correction_map(cmap, font_name=font_name, map_path=map_path)
 
     entry = {
         "ts": datetime.now(timezone.utc).isoformat(),
@@ -179,12 +204,17 @@ def record_punctuation_correction(raw_text: str, gold_text: str, book_id: str =
     return len(pairs)
 
 
-def apply_punctuation_corrections(raw_text: str, book_id: str = "") -> tuple[str, list[dict], float]:
+def apply_punctuation_corrections(
+    raw_text: str,
+    book_id: str = "",
+    font_name: Optional[str] = None,
+    map_path: Optional[Path] = None,
+) -> tuple[str, list[dict], float]:
     _ = book_id
     if not raw_text:
         return raw_text, [], 1.0
 
-    cmap = _load_correction_map()
+    cmap = _load_correction_map(font_name=font_name, map_path=map_path)
 
     lines = raw_text.splitlines()
     corrected_lines: list[str] = []
@@ -219,8 +249,8 @@ def apply_punctuation_corrections(raw_text: str, book_id: str = "") -> tuple[str
     return text, flags, punct_score
 
 
-def correction_map_summary() -> dict:
-    cmap = _load_correction_map()
+def correction_map_summary(font_name: Optional[str] = None, map_path: Optional[Path] = None) -> dict:
+    cmap = _load_correction_map(font_name=font_name, map_path=map_path)
     pairs: list[dict] = []
     for raw_char, golds in cmap.items():
         for gold_char, count in golds.items():
@@ -229,5 +259,5 @@ def correction_map_summary() -> dict:
     return {
         "total_pairs": len(pairs),
         "top_substitutions": pairs[:20],
-        "map_path": str(CORRECTION_MAP_PATH),
+        "map_path": str(_resolve_map_path(font_name=font_name, map_path=map_path)),
     }

smoke_signal/tessdata/README.md

@@ -0,0 +1,22 @@
+# Smoke Signal Tessdata Drop Folder
+
+Put custom Tesseract model files here as `.traineddata`.
+
+Naming rule:
+- Use lowercase + underscores based on detected font name.
+- Example: `Gill Sans Infant` -> `gill_sans_infant.traineddata`
+
+The OCR runtime will auto-pick models from either:
+- `/tmp/smoke_signal/tessdata/`
+- `smoke_signal/tessdata/` (this folder)
+
+Important:
+- `.otf` / `.ttf` files are not Tesseract models.
+- A file like `gill_sans_infant.traineddata.otf` is still a font file, not usable by Tesseract OCR.
+
+If your model name is custom and does not match slug, register it once:
+
+```python
+from smoke_signal.scripts.font_library import register_font_model
+register_font_model("Gill Sans Infant", model_name="my_model_name")
+```

smoke_signal_tab.py

@@ -27,6 +27,7 @@ import hashlib
 import importlib.util
 import json
 import os
+import re
 import tempfile
 import threading
 import time
@@ -60,6 +61,21 @@ DECISIONS_CSV = REVIEW_DIR / "review_decisions.csv"
 QUEUE_CSV    = REVIEW_DIR / "review_queue.csv"
 BANNER_DATA_URI_FILE = Path(__file__).resolve().parent / "assets" / "smoke_signal_banner_data_uri.txt"
 PUNCT_CORRECTOR_PATH = Path(__file__).resolve().parent / "smoke_signal" / "scripts" / "punct_corrector.py"
+FONT_LIBRARY_PATH = Path(__file__).resolve().parent / "smoke_signal" / "scripts" / "font_library.py"
+
+MANIFEST_COLUMNS = [
+    "book_id",
+    "filename",
+    "sha256",
+    "page_count",
+    "rights_class",
+    "status",
+    "acquisition_date",
+    "notes",
+    "story_pages_include",
+    "story_pages_exclude",
+    "safe_title",
+]
 
 
 def _load_banner_image_css() -> str:
@@ -83,6 +99,8 @@ SS_BANNER_IMAGE_CSS = _load_banner_image_css()
 
 _PUNCT_MODULE = None
 _PUNCT_MODULE_ERROR = None
+_FONT_MODULE = None
+_FONT_MODULE_ERROR = None
 
 
 def _load_punct_module():
@@ -108,12 +126,39 @@ def _load_punct_module():
         return None
 
 
-def _apply_punctuation_corrections(text: str, book_id: str) -> tuple[str, list, float]:
+def _load_font_module():
+    global _FONT_MODULE, _FONT_MODULE_ERROR
+    if _FONT_MODULE is not None:
+        return _FONT_MODULE
+    if _FONT_MODULE_ERROR is not None:
+        return None
+    if not FONT_LIBRARY_PATH.exists():
+        _FONT_MODULE_ERROR = f"not found: {FONT_LIBRARY_PATH}"
+        return None
+    try:
+        spec = importlib.util.spec_from_file_location("smoke_signal_font_library", str(FONT_LIBRARY_PATH))
+        if spec is None or spec.loader is None:
+            _FONT_MODULE_ERROR = "invalid import spec"
+            return None
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        _FONT_MODULE = module
+        return _FONT_MODULE
+    except Exception as e:
+        _FONT_MODULE_ERROR = str(e)
+        return None
+
+
+def _apply_punctuation_corrections(text: str, book_id: str, font_name: Optional[str] = None) -> tuple[str, list, float]:
     module = _load_punct_module()
     if module is None:
         return text, [], 1.0
     try:
-        corrected, flags, score = module.apply_punctuation_corrections(text or "", book_id=book_id)
+        corrected, flags, score = module.apply_punctuation_corrections(
+            text or "",
+            book_id=book_id,
+            font_name=font_name,
+        )
         return corrected, flags, float(score)
     except Exception:
         return text, [], 1.0
@@ -129,16 +174,126 @@ def _punctuation_confidence_penalty(text: str, confidence: float) -> float:
         return float(confidence)
 
 
-def _record_punctuation_correction(raw_text: str, gold_text: str, book_id: str) -> int:
+def _record_punctuation_correction(
+    raw_text: str,
+    gold_text: str,
+    book_id: str,
+    font_name: Optional[str] = None,
+) -> int:
     module = _load_punct_module()
     if module is None:
         return 0
     try:
-        return int(module.record_punctuation_correction(raw_text or "", gold_text or "", book_id=book_id))
+        return int(
+            module.record_punctuation_correction(
+                raw_text or "",
+                gold_text or "",
+                book_id=book_id,
+                font_name=font_name,
+            )
+        )
     except Exception:
         return 0
 
 
+def _identify_page_font(render_abs_path: str) -> dict:
+    module = _load_font_module()
+    if module is None:
+        return {
+            "font_name": None,
+            "confidence": 0.0,
+            "alternatives": [],
+            "image_url": None,
+            "error": _FONT_MODULE_ERROR or "font module unavailable",
+        }
+    try:
+        result = module.identify_page_font(render_abs_path)
+        return result if isinstance(result, dict) else {
+            "font_name": None,
+            "confidence": 0.0,
+            "alternatives": [],
+            "image_url": None,
+            "error": "invalid response from font module",
+        }
+    except Exception as e:
+        return {
+            "font_name": None,
+            "confidence": 0.0,
+            "alternatives": [],
+            "image_url": None,
+            "error": str(e),
+        }
+
+
+def _resolve_tesseract_lang(font_name: Optional[str]) -> str:
+    module = _load_font_module()
+    if module is None:
+        return "eng"
+    try:
+        lang = str(module.resolve_tesseract_lang(font_name) or "").strip()
+        return lang if lang else "eng"
+    except Exception:
+        return "eng"
+
+
+def _resolve_tessdata_dir(model_name: Optional[str]) -> Optional[str]:
+    module = _load_font_module()
+    if module is None:
+        return None
+    try:
+        value = module.resolve_tessdata_dir(model_name)
+        return str(value) if value else None
+    except Exception:
+        return None
+
+
+def _update_font_engine_stats(font_name: Optional[str], surya_conf: float, tess_conf: float) -> None:
+    module = _load_font_module()
+    if module is None:
+        return
+    try:
+        module.update_font_engine_stats(font_name, surya_conf, tess_conf)
+    except Exception:
+        return
+
+
+def _mixfont_preflight() -> dict:
+    module = _load_font_module()
+    if module is None:
+        return {
+            "api_key_set": False,
+            "api_url": "",
+            "image_url_template_set": False,
+            "image_base_set": False,
+            "space_host_set": False,
+            "public_image_url_source_available": False,
+            "error": _FONT_MODULE_ERROR or "font module unavailable",
+        }
+    try:
+        data = module.mixfont_preflight()
+        if not isinstance(data, dict):
+            return {
+                "api_key_set": False,
+                "api_url": "",
+                "image_url_template_set": False,
+                "image_base_set": False,
+                "space_host_set": False,
+                "public_image_url_source_available": False,
+                "error": "invalid preflight response",
+            }
+        return data
+    except Exception as e:
+        return {
+            "api_key_set": False,
+            "api_url": "",
+            "image_url_template_set": False,
+            "image_base_set": False,
+            "space_host_set": False,
+            "public_image_url_source_available": False,
+            "error": str(e),
+        }
+
+
 def _punctuation_map_summary() -> dict:
     module = _load_punct_module()
     if module is None:
@@ -591,15 +746,19 @@ def sha256_file(path: Path) -> str:
 
 def load_manifest_df() -> pd.DataFrame:
     if not MANIFEST_CSV.exists():
-        return pd.DataFrame(columns=[
-            "book_id","filename","sha256","page_count","rights_class",
-            "status","acquisition_date","notes"
-        ])
-    return pd.read_csv(MANIFEST_CSV)
+        return pd.DataFrame(columns=MANIFEST_COLUMNS)
+    df = pd.read_csv(MANIFEST_CSV)
+    for col in MANIFEST_COLUMNS:
+        if col not in df.columns:
+            df[col] = ""
+    return df[MANIFEST_COLUMNS]
 
 
 def save_manifest_df(df: pd.DataFrame) -> None:
-    df.to_csv(MANIFEST_CSV, index=False)
+    for col in MANIFEST_COLUMNS:
+        if col not in df.columns:
+            df[col] = ""
+    df[MANIFEST_COLUMNS].to_csv(MANIFEST_CSV, index=False)
 
 
 def next_book_id(df: pd.DataFrame) -> str:
@@ -673,6 +832,72 @@ def _parse_page_selection(spec: str, max_page: int | None = None) -> tuple[set[i
     return out, None
 
 
+def _safe_title_slug(title: str) -> str:
+    raw = str(title or "").strip().lower()
+    if not raw:
+        return ""
+    slug = re.sub(r"[^a-z0-9]+", "-", raw).strip("-")
+    return slug[:120]
+
+
+def _clean_page_spec(spec: str) -> str:
+    raw = (spec or "").strip().lower()
+    if raw in ("", "all", "*", "none", "-"):
+        return ""
+    parsed, err = _parse_page_selection(raw)
+    if err:
+        raise ValueError(err)
+    if parsed is None:
+        return ""
+    return ",".join(str(p) for p in sorted(parsed))
+
+
+def _normalize_saved_spec(value) -> str:
+    raw = str(value if value is not None else "").strip().lower()
+    if raw in ("", "nan", "none", "null", "-", "all", "*"):
+        return ""
+    return raw
+
+
+def save_book_scope(book_id: str, include_spec: str, exclude_spec: str, safe_title: str) -> tuple:
+    df = load_manifest_df()
+    bid = (book_id or "").strip()
+    if df.empty or not bid:
+        return _ingest_status_html("idle"), df, "Book ID is required."
+    if bid not in df["book_id"].values:
+        return _ingest_status_html("idle"), df, f"Book ID {bid} not found."
+
+    try:
+        include_clean = _clean_page_spec(include_spec)
+    except ValueError as e:
+        return _ingest_status_html("idle"), df, f"Invalid include pages: {e}"
+
+    try:
+        exclude_clean = _clean_page_spec(exclude_spec)
+    except ValueError as e:
+        return _ingest_status_html("idle"), df, f"Invalid exclude pages: {e}"
+
+    title_raw = (safe_title or "").strip()
+    if title_raw:
+        safe = _safe_title_slug(title_raw)
+    else:
+        filename = str(df.loc[df["book_id"] == bid, "filename"].values[0] or "")
+        stem = Path(filename).stem if filename else bid
+        safe = _safe_title_slug(stem)
+
+    df.loc[df["book_id"] == bid, "story_pages_include"] = include_clean
+    df.loc[df["book_id"] == bid, "story_pages_exclude"] = exclude_clean
+    df.loc[df["book_id"] == bid, "safe_title"] = safe
+    save_manifest_df(df)
+
+    line1 = log_line(f"✓ Saved scope for {bid}")
+    line2 = log_line(
+        f"ℹ include={include_clean or 'all'} · exclude={exclude_clean or 'none'} · safe_title={safe}"
+    )
+    msg = f"{line1}\n{line2}"
+    return _ingest_status_html("done"), load_manifest_df(), msg
+
+
 # ── Step 1: INGEST ─────────────────────────────────────────────────────────────
 def ingest_pdfs(files, rights_class: str, notes: str) -> tuple:
     """Register uploaded PDFs into the source manifest."""
@@ -734,6 +959,9 @@ def ingest_pdfs(files, rights_class: str, notes: str) -> tuple:
             "status":           "pending",
             "acquisition_date": datetime.utcnow().date().isoformat(),
             "notes":            notes,
+            "story_pages_include": "",
+            "story_pages_exclude": "",
+            "safe_title": _safe_title_slug(Path(path.name).stem),
         }])
         df = pd.concat([df, new_row], ignore_index=True)
         log.append(log_line(f"✓ Registered {book_id} — {path.name} ({page_count or '?'} pages)"))
@@ -960,6 +1188,14 @@ try:
     SS_TESSERACT_BATCH_HARD_TIMEOUT_SEC = max(15, int(os.environ.get("SS_TESSERACT_BATCH_HARD_TIMEOUT_SEC", "45")))
 except Exception:
     SS_TESSERACT_BATCH_HARD_TIMEOUT_SEC = 45
+try:
+    SS_MIXFONT_MAX_DETECT_PAGES = max(1, int(os.environ.get("SS_MIXFONT_MAX_DETECT_PAGES", "2")))
+except Exception:
+    SS_MIXFONT_MAX_DETECT_PAGES = 2
+try:
+    SS_MIXFONT_MAX_ERRORS = max(1, int(os.environ.get("SS_MIXFONT_MAX_ERRORS", "1")))
+except Exception:
+    SS_MIXFONT_MAX_ERRORS = 1
 
 
 def _load_surya_runtime():
@@ -1107,7 +1343,11 @@ def _regions_from_page_result(page_result):
     return regions, conf
 
 
-def _run_tesseract_batch(images):
+def _run_tesseract_batch(
+    images,
+    langs: Optional[list[str]] = None,
+    tessdata_dirs: Optional[list[Optional[str]]] = None,
+):
     """
     Tesseract fallback for OCR when Surya is unavailable/slow.
     Returns list of dicts with regions/confidence/method aligned to input order.
@@ -1115,17 +1355,28 @@ def _run_tesseract_batch(images):
     try:
         import pytesseract
     except Exception as e:
-        return [{"regions": [], "confidence": 0.0, "method": f"error-no-tesseract ({e})"} for _ in images]
+        return [
+            {
+                "regions": [],
+                "confidence": 0.0,
+                "method": f"error-no-tesseract ({e})",
+                "tesseract_lang": (langs[idx] if langs and idx < len(langs) else "eng"),
+            }
+            for idx, _ in enumerate(images)
+        ]
 
     # Prefer parallel image-level OCR with single-threaded internal OpenMP for better CPU utilization.
     os.environ.setdefault("OMP_THREAD_LIMIT", "1")
 
-    def _ocr_single(img):
+    def _ocr_single(img, lang_hint: str, tessdata_dir: Optional[str]):
         try:
+            config = f"--oem 1 --psm {SS_TESSERACT_PSM}"
+            if tessdata_dir:
+                config = f"{config} --tessdata-dir \"{tessdata_dir}\""
             data = pytesseract.image_to_data(
                 img,
-                lang="eng",
-                config=f"--oem 1 --psm {SS_TESSERACT_PSM}",
+                lang=lang_hint or "eng",
+                config=config,
                 output_type=pytesseract.Output.DICT,
                 timeout=SS_TESSERACT_TIMEOUT_SEC,
             )
@@ -1167,7 +1418,12 @@ def _run_tesseract_batch(images):
 
             # Hard gate for fallback quality: do not keep OCR text below minimum page confidence.
             if regions and avg_conf < SS_TESSERACT_MIN_CONF_KEEP:
-                return {"regions": [], "confidence": 0.0, "method": "tesseract-lowconf-filtered"}
+                return {
+                    "regions": [],
+                    "confidence": 0.0,
+                    "method": "tesseract-lowconf-filtered",
+                    "tesseract_lang": lang_hint or "eng",
+                }
 
             # Filter obvious OCR noise from illustration texture (common in no-text pages).
             full_text = " ".join(r["text"] for r in regions).strip()
@@ -1177,24 +1433,62 @@ def _run_tesseract_batch(images):
             tokens = [t for t in full_text.split() if t]
             avg_token_len = (sum(len(t) for t in tokens) / len(tokens)) if tokens else 0.0
             if regions and avg_conf <= 0.42 and alpha_ratio < 0.62 and avg_token_len < 3.2:
-                return {"regions": [], "confidence": 0.0, "method": "tesseract-noise-filtered"}
+                return {
+                    "regions": [],
+                    "confidence": 0.0,
+                    "method": "tesseract-noise-filtered",
+                    "tesseract_lang": lang_hint or "eng",
+                }
 
-            return {"regions": regions, "confidence": avg_conf, "method": "tesseract"}
+            return {
+                "regions": regions,
+                "confidence": avg_conf,
+                "method": "tesseract",
+                "tesseract_lang": lang_hint or "eng",
+            }
         except RuntimeError as e:
-            return {"regions": [], "confidence": 0.0, "method": f"error-tesseract-timeout ({e})"}
+            return {
+                "regions": [],
+                "confidence": 0.0,
+                "method": f"error-tesseract-timeout ({e})",
+                "tesseract_lang": lang_hint or "eng",
+            }
         except Exception as e:
-            return {"regions": [], "confidence": 0.0, "method": f"error-tesseract ({e})"}
+            return {
+                "regions": [],
+                "confidence": 0.0,
+                "method": f"error-tesseract ({e})",
+                "tesseract_lang": lang_hint or "eng",
+            }
 
     if not images:
         return []
 
     max_workers = min(SS_TESSERACT_WORKERS, len(images), max(1, os.cpu_count() or 1))
+    lang_list = list(langs) if langs else []
+    if len(lang_list) < len(images):
+        lang_list.extend(["eng"] * (len(images) - len(lang_list)))
+    elif len(lang_list) > len(images):
+        lang_list = lang_list[: len(images)]
+
+    tess_dir_list = list(tessdata_dirs) if tessdata_dirs else []
+    if len(tess_dir_list) < len(images):
+        tess_dir_list.extend([None] * (len(images) - len(tess_dir_list)))
+    elif len(tess_dir_list) > len(images):
+        tess_dir_list = tess_dir_list[: len(images)]
+
     if max_workers <= 1:
-        return [_ocr_single(img) for img in images]
+        return [
+            _ocr_single(img, lang_list[idx], tess_dir_list[idx])
+            for idx, img in enumerate(images)
+        ]
 
     outputs = [None] * len(images)
     executor = concurrent.futures.ThreadPoolExecutor(max_workers=max_workers)
-    futures = {executor.submit(_ocr_single, img): idx for idx, img in enumerate(images)}
+    futures = {
+        executor.submit(_ocr_single, img, lang_list[idx], tess_dir_list[idx]): idx
+        for idx, img in enumerate(images)
+    }
     pending = set(futures.keys())
     batch_timeout = max(
         SS_TESSERACT_BATCH_HARD_TIMEOUT_SEC,
@@ -1225,6 +1519,7 @@ def _run_tesseract_batch(images):
                     "regions": [],
                     "confidence": 0.0,
                     "method": f"error-tesseract-batch-timeout ({batch_timeout}s)",
+                    "tesseract_lang": lang_list[idx] if idx < len(lang_list) else "eng",
                 }
                 future.cancel()
     finally:
@@ -1233,7 +1528,12 @@ def _run_tesseract_batch(images):
 
     for i, out in enumerate(outputs):
         if out is None:
-            outputs[i] = {"regions": [], "confidence": 0.0, "method": "error-tesseract-missing-output"}
+            outputs[i] = {
+                "regions": [],
+                "confidence": 0.0,
+                "method": "error-tesseract-missing-output",
+                "tesseract_lang": lang_list[i] if i < len(lang_list) else "eng",
+            }
 
     return outputs
 
@@ -1269,8 +1569,10 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
     selection_set, selection_error = _parse_page_selection(page_selection)
     if selection_error:
         return _ocr_status_html(), f"{debug}Invalid page selection: {selection_error}"
+    manual_selection = selection_set is not None
     exclusion_spec = (page_exclusion or "").strip().lower()
     exclusion_request = None if exclusion_spec in ("", "none", "-") else exclusion_spec
+    manual_exclusion = exclusion_request is not None
     if exclusion_request is not None:
         exclusion_set, exclusion_error = _parse_page_selection(exclusion_request)
         if exclusion_error:
@@ -1310,6 +1612,23 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
         log.append(log_line(f"⚠ Punctuation corrector unavailable ({_PUNCT_MODULE_ERROR or 'unknown'})"))
     else:
         log.append(log_line("✓ Punctuation corrector active (rule-check + confidence penalty + learning map)"))
+    font_mod = _load_font_module()
+    mixfont_enabled = False
+    if font_mod is None:
+        log.append(log_line(f"⚠ Font library unavailable ({_FONT_MODULE_ERROR or 'unknown'})"))
+    else:
+        preflight = _mixfont_preflight()
+        if preflight.get("api_key_set") and preflight.get("public_image_url_source_available"):
+            log.append(log_line("✓ MixFont detection enabled (per-page font routing)"))
+            mixfont_enabled = True
+        else:
+            missing = []
+            if not preflight.get("api_key_set"):
+                missing.append("MIXFONT_API_KEY")
+            if not preflight.get("public_image_url_source_available"):
+                missing.append("MIXFONT_IMAGE_BASE_URL (or MIXFONT_IMAGE_URL_TEMPLATE/SPACE_HOST)")
+            missing_text = ", ".join(missing) if missing else "unknown config"
+            log.append(log_line(f"ℹ MixFont disabled this run — missing {missing_text}"))
 
     for _, row in eligible.iterrows():
         book_id = row["book_id"]
@@ -1343,11 +1662,31 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
             if excluded_pages_for_book is None:
                 excluded_pages_for_book = set(page_numbers)
 
+        saved_include_spec = _normalize_saved_spec(row.get("story_pages_include", ""))
+        if saved_include_spec and not manual_selection:
+            saved_include_set, saved_inc_err = _parse_page_selection(saved_include_spec, max_page=max_page)
+            if saved_inc_err:
+                log.append(log_line(f"⚠ {book_id}: invalid saved include pages '{saved_include_spec}' ({saved_inc_err})"))
+            elif saved_include_set is not None:
+                selected_pages_for_book = set(selected_pages_for_book) & set(saved_include_set)
+
+        saved_exclude_spec = _normalize_saved_spec(row.get("story_pages_exclude", ""))
+        if saved_exclude_spec and not manual_exclusion:
+            saved_exclude_set, saved_exc_err = _parse_page_selection(saved_exclude_spec, max_page=max_page)
+            if saved_exc_err:
+                log.append(log_line(f"⚠ {book_id}: invalid saved exclude pages '{saved_exclude_spec}' ({saved_exc_err})"))
+            elif saved_exclude_set is not None:
+                excluded_pages_for_book = set(excluded_pages_for_book) | set(saved_exclude_set)
+
         selected_pages_for_book = set(selected_pages_for_book) - set(excluded_pages_for_book)
         if not selected_pages_for_book:
             log.append(log_line(f"⚠ {book_id}: no pages left after applying selection/exclusion"))
             continue
 
+        if saved_include_spec and not manual_selection:
+            log.append(log_line(f"ℹ {book_id}: saved include pages {saved_include_spec}"))
+        if saved_exclude_spec and not manual_exclusion:
+            log.append(log_line(f"ℹ {book_id}: saved exclude pages {saved_exclude_spec}"))
         selected_preview = ",".join(str(p) for p in sorted(selected_pages_for_book))
         log.append(log_line(f"ℹ {book_id}: effective selected pages {selected_preview}"))
         processed_books.append(book_id)
@@ -1369,9 +1708,14 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
         # First pass: render OCR/hybrid pages once and keep PIL images for batch OCR.
         ocr_targets = []
         render_dpi = SS_RENDER_DPI_SURYA if surya is not None else SS_RENDER_DPI_FALLBACK
+        book_detected_font = None
+        mixfont_attempts = 0
+        mixfont_errors = 0
+        mixfont_disabled_for_book = not mixfont_enabled
         for page_data in profile.get("pages", []):
             page_num = page_data["page_number"]
             route = page_data["route"]
+            font_name = page_data.get("font_name")
             if selected_pages_for_book is not None and int(page_num) not in selected_pages_for_book:
                 continue
 
@@ -1415,10 +1759,41 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                 except Exception as e:
                     log.append(log_line(f"  ⚠ {book_id} p{page_num}: render failed ({e})"))
 
+            font_name = page_data.get("font_name")
+            if (not font_name) and book_detected_font:
+                page_data["font_name"] = book_detected_font
+                font_name = book_detected_font
+
+            if (
+                (not font_name)
+                and render_path is not None
+                and (not mixfont_disabled_for_book)
+                and mixfont_attempts < SS_MIXFONT_MAX_DETECT_PAGES
+            ):
+                mixfont_attempts += 1
+                font_result = _identify_page_font(str(render_path))
+                detected_font = font_result.get("font_name")
+                if detected_font:
+                    page_data["font_name"] = detected_font
+                    page_data["font_confidence"] = float(font_result.get("confidence", 0.0) or 0.0)
+                    page_data["font_detected_at"] = datetime.utcnow().isoformat() + "Z"
+                    book_detected_font = detected_font
+                    font_name = detected_font
+                    log.append(log_line(f"ℹ {book_id}: detected font '{detected_font}'"))
+                else:
+                    page_data["font_name"] = None
+                    page_data["font_detect_error"] = font_result.get("error")
+                    mixfont_errors += 1
+                    if mixfont_errors >= SS_MIXFONT_MAX_ERRORS:
+                        mixfont_disabled_for_book = True
+                        err_txt = page_data.get("font_detect_error") or "unknown"
+                        log.append(log_line(f"⚠ {book_id}: MixFont disabled for this run ({err_txt})"))
+
             ocr_targets.append({
                 "page_num": page_num,
                 "route": route,
                 "render_path": page_data.get("render_path"),
+                "font_name": page_data.get("font_name"),
             })
 
         # Batch OCR for non-embedded pages.
@@ -1430,6 +1805,8 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                 batch_pages = [item["page_num"] for item in batch]
                 batch_images = []
                 batch_items_with_images = []
+                batch_tess_langs = []
+                batch_tess_dirs = []
                 try:
                     from PIL import Image
                 except Exception as e:
@@ -1460,6 +1837,9 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                             img = Image.open(render_abs).convert("RGB")
                             batch_images.append(img)
                             batch_items_with_images.append(item)
+                            lang_model = _resolve_tesseract_lang(item.get("font_name"))
+                            batch_tess_langs.append(lang_model)
+                            batch_tess_dirs.append(_resolve_tessdata_dir(lang_model))
                         except Exception as e:
                             ocr_lookup[item["page_num"]] = {
                                 "regions": [],
@@ -1481,7 +1861,7 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                                 "method": "surya",
                             }
                     else:
-                        fallback_preds = _run_tesseract_batch(batch_images)
+                        fallback_preds = _run_tesseract_batch(batch_images, batch_tess_langs, batch_tess_dirs)
                         timeout_count = sum(1 for pred in fallback_preds if "batch-timeout" in str(pred.get("method", "")))
                         for item, pred in zip(batch_items_with_images, fallback_preds):
                             ocr_lookup[item["page_num"]] = pred
@@ -1496,7 +1876,7 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                     # If Surya batch fails, try Tesseract for this batch before giving up.
                     if surya is not None:
                         log.append(log_line(f"  ⚠ {book_id} batch {batch_pages[0]}-{batch_pages[-1]} Surya error: {e}; retrying with Tesseract"))
-                        fallback_preds = _run_tesseract_batch(batch_images)
+                        fallback_preds = _run_tesseract_batch(batch_images, batch_tess_langs, batch_tess_dirs)
                         timeout_count = sum(1 for pred in fallback_preds if "batch-timeout" in str(pred.get("method", "")))
                         for item, pred in zip(batch_items_with_images, fallback_preds):
                             ocr_lookup[item["page_num"]] = pred
@@ -1552,8 +1932,17 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                 method = "skipped-no-surya"
 
             raw_text = " ".join(r["text"] for r in regions)[:500]
-            corrected_text, punct_flags, punct_score = _apply_punctuation_corrections(raw_text, book_id)
+            corrected_text, punct_flags, punct_score = _apply_punctuation_corrections(
+                raw_text,
+                book_id,
+                font_name=font_name,
+            )
             conf_adjusted = _punctuation_confidence_penalty(corrected_text, conf)
+            if font_name:
+                if str(method).startswith("tesseract"):
+                    _update_font_engine_stats(font_name, 0.0, conf)
+                elif str(method).startswith("surya"):
+                    _update_font_engine_stats(font_name, conf, 0.0)
 
             if method in ("tesseract-noise-filtered", "tesseract-lowconf-filtered") and not regions:
                 conf_class = "auto-accept"
@@ -1585,6 +1974,8 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                 "extraction_method": method,
                 "punctuation_score": punct_score,
                 "punctuation_flags": punct_flags,
+                "font_name": font_name,
+                "tesseract_lang": ocr_lookup.get(page_num, {}).get("tesseract_lang"),
                 "render_path": page_data.get("render_path"),
                 "ocred_at": datetime.utcnow().isoformat() + "Z",
             })
@@ -1605,6 +1996,8 @@ def run_ocr(page_selection: str = "", page_exclusion: str = "", replace_book_que
                     "confidence_class": conf_class,
                     "punct_score": punct_score,
                     "punct_flags_count": len(punct_flags),
+                    "font_name": font_name or "",
+                    "tesseract_lang": ocr_lookup.get(page_num, {}).get("tesseract_lang", ""),
                     "status": "quarantine" if conf_class == "quarantine" else "pending",
                     "reviewer": "",
                     "correction": "",
@@ -1739,8 +2132,9 @@ def get_review_item(idx: int) -> tuple:
             except Exception:
                 img_path = None
 
+    font_suffix = f" · font: {item.get('font_name')}" if str(item.get("font_name", "")).strip() else ""
     info = (f"<div style='font-family:monospace;font-size:11px;color:var(--ss-muted)'>"
-            f"{item['book_id']} · page {item['page']} · "
+            f"{item['book_id']} · page {item['page']}{font_suffix} · "
             f"conf: <b style='color:{'var(--ss-red)' if float(item.get('confidence',0)) < 0.6 else 'var(--ss-gold)'}'>"
             f"{float(item.get('confidence',0)):.0%}</b></div>")
 
@@ -1782,6 +2176,7 @@ def save_review_decision(idx: int, final_text: str, action: str, reviewer: str,
         "raw_text_original": raw_text_original,
         "reason_code": reason,
         "reviewer":    reviewer or "reviewer",
+        "font_name":   item.get("font_name", ""),
         "was_correct": was_correct,
         "decided_at":  datetime.utcnow().isoformat() + "Z",
     }
@@ -1816,7 +2211,12 @@ def save_review_decision(idx: int, final_text: str, action: str, reviewer: str,
 
     learned_pairs = 0
     if action == "edited":
-        learned_pairs = _record_punctuation_correction(raw_text_original, final_text, item.get("book_id", ""))
+        learned_pairs = _record_punctuation_correction(
+            raw_text_original,
+            final_text,
+            item.get("book_id", ""),
+            font_name=item.get("font_name"),
+        )
 
     cal         = load_calibration()
     default     = cal.get("_default", DEFAULT_CALIBRATION["_default"])
@@ -1878,6 +2278,7 @@ def run_export() -> tuple:
 
         records.append({
             "book_id":          book_id,
+            "safe_title":       manifest_row.get("safe_title","") if isinstance(manifest_row, pd.Series) else "",
             "source_hash":      manifest_row.get("sha256","") if isinstance(manifest_row, pd.Series) else "",
             "page_number":      dec["page"],
             "region_id":        dec["region_id"],
@@ -1997,7 +2398,7 @@ def smoke_signal_tab():
                     interactive=False,
                     wrap=True,
                 )
-                ingest_log = gr.Textbox(label="Log", lines=6, interactive=False, elem_classes=["ss-log"])
+                ingest_log = gr.Textbox(label="Log", lines=6, interactive=False, elem_classes=["ss-log"], show_copy_button=True)
                 refresh_btn = gr.Button("↻ Refresh Manifest", size="sm")
                 refresh_btn.click(lambda: load_manifest_df(), outputs=[manifest_table])
 
@@ -2017,6 +2418,19 @@ def smoke_signal_tab():
                     outputs=[ingest_status, manifest_table, ingest_log],
                 )
 
+                gr.Markdown("**Save Book Pages + Safe Title (persisted):**")
+                with gr.Row():
+                    scope_book_id = gr.Textbox(label="Book ID", placeholder="SS-BOOK-0001", scale=1)
+                    scope_include = gr.Textbox(label="Story Pages Include", placeholder="all or 7-27 or 7,8,9,11-27", scale=1)
+                    scope_exclude = gr.Textbox(label="Story Pages Exclude", placeholder="e.g. 1,2,3,17,25", scale=1)
+                    scope_title = gr.Textbox(label="Safe Book Title", placeholder="e.g. the-gruffalo", scale=1)
+                scope_save_btn = gr.Button("Save Book Pages →", size="sm")
+                scope_save_btn.click(
+                    save_book_scope,
+                    inputs=[scope_book_id, scope_include, scope_exclude, scope_title],
+                    outputs=[ingest_status, manifest_table, ingest_log],
+                )
+
                 ingest_btn.click(
                     ingest_pdfs,
                     inputs=[pdf_upload, rights_dd, ingest_notes],
@@ -2035,7 +2449,7 @@ def smoke_signal_tab():
 
                 profile_status = gr.HTML(_profile_status_html())
                 profile_btn    = gr.Button("Re-run Profiler (Optional) →", elem_classes=["ss-btn-run"])
-                profile_log    = gr.Textbox(label="Log", lines=10, interactive=False, elem_classes=["ss-log"])
+                profile_log    = gr.Textbox(label="Log", lines=10, interactive=False, elem_classes=["ss-log"], show_copy_button=True)
 
                 profile_btn.click(run_profile, outputs=[profile_status, profile_log])
 
@@ -2073,13 +2487,13 @@ def smoke_signal_tab():
                     value=True,
                 )
                 ocr_btn = gr.Button("Run OCR →", elem_classes=["ss-btn-run"])
-                ocr_log = gr.Textbox(label="Log", lines=10, interactive=False, elem_classes=["ss-log"])
+                ocr_log = gr.Textbox(label="Log", lines=10, interactive=False, elem_classes=["ss-log"], show_copy_button=True)
 
                 ocr_run_event = ocr_btn.click(
                     run_ocr,
                     inputs=[ocr_page_selection, ocr_page_exclusion, ocr_replace_queue],
                     outputs=[ocr_status, ocr_log],
-                    show_progress="minimal",
+                    show_progress="hidden",
                 )
 
             # ── STEP 4: REVIEW ────────────────────────────────────────────────
@@ -2178,7 +2592,7 @@ def smoke_signal_tab():
                 ocr_run_event.then(
                     load_review,
                     outputs=review_load_outputs,
-                    show_progress="minimal",
+                    show_progress="hidden",
                 )
                 accept_btn.click(do_accept, inputs=[current_idx, final_text_box, reviewer_name, reason_code], outputs=action_outputs)
                 edit_btn.click(do_accept, inputs=[current_idx, final_text_box, reviewer_name, reason_code], outputs=action_outputs)