Disable local handwriting gracefully when packages absent

app.py

@@ -75,6 +75,34 @@ async def index():
     return FileResponse(str(INDEX_HTML))
 
 
+# Cache the (deterministic) optional-feature probe so torch/transformers are
+# imported at most once.
+_CAPABILITIES: dict = {}
+
+
+@app.get("/api/capabilities")
+async def capabilities():
+    """Report which optional features are usable in THIS deployment.
+
+    Local handwriting (TrOCR) needs torch + transformers, which the lean hosted
+    build omits. The front-end reads this to disable the handwriting toggle
+    gracefully and point users to online OCR, instead of letting a page fail
+    mid-extraction with a missing-dependency error.
+    """
+    if "handwriting" not in _CAPABILITIES:
+        from pipeline.jobs import _EXECUTOR
+        from pipeline.handwriting import is_available
+
+        loop = asyncio.get_running_loop()
+        try:
+            _CAPABILITIES["handwriting"] = await loop.run_in_executor(
+                _EXECUTOR, is_available
+            )
+        except Exception:
+            _CAPABILITIES["handwriting"] = False
+    return {"handwriting": bool(_CAPABILITIES["handwriting"])}
+
+
 @app.post("/api/upload")
 async def upload(
     file: UploadFile = File(...),

static/index.html

@@ -18,12 +18,29 @@
       }
       document.addEventListener("DOMContentLoaded", function () {
         var btn = document.getElementById("themeToggle");
-        if (!btn) return;
-        btn.addEventListener("click", function () {
-          var next = root.getAttribute("data-theme") === "light" ? "dark" : "light";
-          root.setAttribute("data-theme", next);
-          try { localStorage.setItem("theme", next); } catch (e) {}
-        });
+        if (btn) {
+          btn.addEventListener("click", function () {
+            var next = root.getAttribute("data-theme") === "light" ? "dark" : "light";
+            root.setAttribute("data-theme", next);
+            try { localStorage.setItem("theme", next); } catch (e) {}
+          });
+        }
+
+        /* Disable local-handwriting gracefully where its packages aren't
+           installed (e.g. the lean hosted build) and point users to Gemini,
+           instead of letting a page fail mid-extraction. */
+        fetch("/api/capabilities")
+          .then(function (r) { return r.json(); })
+          .then(function (caps) {
+            if (!caps || caps.handwriting !== false) return;
+            var hw = document.getElementById("handwritingToggle");
+            if (hw) { hw.checked = false; hw.disabled = true; }
+            var row = document.getElementById("handwritingRow");
+            if (row) row.classList.add("is-unavailable");
+            var note = document.getElementById("hwUnavailable");
+            if (note) note.hidden = false;
+          })
+          .catch(function () {});
       });
     })();
   </script>
@@ -140,7 +157,7 @@
             <svg class="accordion-chevron" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 9l6 6 6-6"></path></svg>
           </summary>
           <div class="accordion-body">
-            <div class="setting setting-row">
+            <div class="setting setting-row" id="handwritingRow">
               <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>
@@ -150,6 +167,7 @@
                 <span class="slider" aria-hidden="true"></span>
               </label>
             </div>
+            <p class="hint hw-note" id="hwUnavailable" hidden>Local handwriting isn't installed in this build &mdash; use <strong>Online vision OCR (Gemini)</strong> below for handwriting.</p>
 
             <div class="setting setting-row">
               <div>

static/styles.css

@@ -294,6 +294,12 @@ html[data-theme="light"] .theme-toggle .icon-moon { display: block; }
 }
 .switch input:checked + .slider::before { transform: translateX(20px); }
 .switch input:focus-visible + .slider { box-shadow: 0 0 0 3px var(--accent-ring); }
+.switch input:disabled + .slider { opacity: 0.45; cursor: not-allowed; }
+
+/* a feature that isn't available in this build */
+.setting-row.is-unavailable .setting-label { color: var(--text-dim); }
+.hw-note { color: var(--accent); }
+.hw-note strong { color: var(--accent); font-weight: 700; }
 
 /* ---------------- Work area ---------------- */
 .work { min-width: 0; display: flex; flex-direction: column; gap: 18px; }