Tidy up template and gap docs

Author: vinniefalco

paperworks/CLAUDE.md

@@ -88,10 +88,12 @@ The paper inventory correlates three sources:
 - Events: job_queued, job_started, job_completed, job_failed, queue_drained
 - NEVER bypass the queue. NEVER call the session directly.
 
-## Two Pages
+## Tabs
 
-- `/` - Dashboard: top bar (auth + summary pills), paper table, log, bottom status bar
-- `/settings` - Settings: output dir, watch dirs, credentials, style
+- **Folio** - paper inventory table with status badges, detail rows, upload
+- **Render** - card-based drop targets for one-off preview rendering
+- **Settings** - output dirs (folio + render), watch dirs, style, fonts, credentials
+- **Log** - activity log with dimming
 
 Both pages use SSE (`/api/events`) for live updates. The SSE
 connection is per-page - it reconnects on navigation. State is
@@ -103,33 +105,50 @@ markdown changed -> watchdog -> render worker -> PDF created ->
 PDF watchdog -> dirty flag -> user clicks Upload -> IsoCppSession
 queue -> isocpp.org
 
-## Button UX Rules (TODO - not yet fully implemented)
+## Button UX Rules
 
-Buttons that submit work to the IsoCppSession queue (docketeer)
-or to the render worker follow this pattern:
+Buttons that submit work follow this pattern:
 
 1. **Press** -> button enters working state immediately:
    - Disabled (no re-click)
    - Animated glowing border (badge-working style)
    - 70% opacity
 2. **Log** -> IsoCppSession's on_event fires job_queued, which
    the server logs automatically. Render worker logs "Starting..."
-3. **Event** -> button stays working until an SSE event confirms
-   completion (job_completed, job_failed, rendered, render_done)
-4. **Done** -> log entry for completion, button re-enables
-5. **Log styling** -> completion entries at 50% opacity to
+3. **Event** -> button stays working until completion is
+   confirmed (SSE event or HTTP response)
+4. **Done** -> log entry for completion, button re-enables,
+   `_workingSet` cleared for the doc number
+5. **Failure** -> toast shown, button re-enables, working
+   state cleared. Both HTTP errors and SSE failures clear state.
+6. **Log styling** -> completion entries at 50% opacity to
    distinguish from active/error entries
 
-Buttons that go through the queue:
-- Upload (IsoCppSession.submit upload - syncs title, author, abstract + PDF)
+Queue-based buttons (SSE confirms completion):
+- Upload (IsoCppSession.submit upload - syncs title, author,
+  abstract + PDF)
 - Draft/Review transition (IsoCppSession.submit transition)
-- Render per-paper (render worker)
-- Render All (render worker)
-- Log In (blocks on login request, not queued but same UX)
+- Render per-paper (render worker via batch queue)
+- Render All (render worker via batch queue)
 
-Buttons that do NOT go through the queue (instant, no working
-state needed): Log Out, Clear Log, Open Folder, Shut Down,
-Save (settings), tab switches.
+Synchronous buttons (HTTP response confirms completion):
+- Render tab preview cards (render-preview endpoint with
+  `_preview_lock` serialization)
+- Log In (blocks on login request)
+
+Instant buttons (no working state needed): Log Out, Clear Log,
+Shut Down, Save (settings), tab switches.
+
+## Render Serialization
+
+All `build_pdf` calls are serialized through `_preview_lock`.
+The batch render worker acquires it per file. The preview
+endpoint acquires it for the full render. This prevents
+concurrent ReportLab font registration corruption.
+
+`build_pdf` is self-contained: it loads the font manifest,
+downloads missing fonts, registers them, and builds the PDF.
+Callers only need to provide a style dict.
 
 ## No Public Scraping
 

paperworks/lib/inventory.py

@@ -3,7 +3,9 @@
 Source priority (highest to lowest):
   1. Markdown front matter + body - authoritative for all metadata
   2. Rendered PDF - fallback when markdown is absent
-  3. isocpp.org - remote status only, never a metadata source
+  3. isocpp.org - remote status and form URLs only. Title and author
+     from isocpp.org are used as last-resort fallback when neither
+     markdown nor PDF exists for a paper.
 
 D/P prefixes are interchangeable for matching: D4007R0 and P4007R0
 refer to the same paper.

paperworks/lib/isocpp.py

@@ -125,9 +125,7 @@ def login(self, username, password):
             if "invalid" in r.text.lower() or "incorrect" in r.text.lower():
                 return False, "Invalid username or password"
 
-            self._authenticated = True
-            self._username = username
-            return True, "Logged in"
+            return False, "Unexpected response - login may have failed"
 
     def logout(self):
         with self._lock:
@@ -240,6 +238,7 @@ def _run_worker(self):
 
             with self._pending_lock:
                 self._pending.pop(job_id, None)
+                drained = len(self._pending) == 0
 
             self._active_job = None
 
@@ -256,7 +255,7 @@ def _run_worker(self):
                 payload["error"] = message
             self._emit(payload)
 
-            if self._queue.empty():
+            if drained:
                 self._emit({"event": "queue_drained"})
 
     def _emit(self, event):

paperworks/lib/pdf_reader.py

@@ -5,14 +5,14 @@
 
 
 _DOC_NUM_RE = re.compile(
-    r"\b([DPN]\d{4,5}R\d+)\b"
-    r"|\b([DPN]\d{4,5})\b"
-    r"|\b(N\d{4,5})\b",
+    r"\b([DPN]\d{3,5}R\d+)\b"
+    r"|\b([DPN]\d{3,5})\b"
+    r"|\b(N\d{3,5})\b",
     re.IGNORECASE,
 )
 
 _DOC_FIELD_RE = re.compile(
-    r"Document\s+Number[:\s]+([DPN]\d{4,5}(?:R\d+)?|N\d{4,5})",
+    r"Document\s+Number[:\s]+([DPN]\d{3,5}(?:R\d+)?|N\d{3,5})",
     re.IGNORECASE,
 )
 
@@ -44,13 +44,13 @@ def _extract_doc_number(text):
 
 def _doc_number_from_filename(path):
     stem = Path(path).stem.lower()
-    m = re.match(r"([dpn]\d{4,5}(?:r\d+)?)", stem)
+    m = re.match(r"([dpn]\d{3,5}(?:r\d+)?)", stem)
     if m:
         return m.group(1).upper()
     return None
 
 
-def _extract_title(text, lines):
+def _extract_title(lines):
     for line in lines[:20]:
         stripped = line.strip()
         if len(stripped) > 10 and not _DOC_NUM_RE.match(stripped):
@@ -73,11 +73,15 @@ def _extract_authors(text):
 
 
 def _extract_abstract_from_doc(doc):
-    """Scan pages 1-4 for the abstract body (page 0 has the TOC entry).
+    """Scan pages for the abstract body.
+
+    For multi-page documents, starts at page 1 (page 0 typically has
+    the TOC entry). For single-page documents, scans page 0.
 
     Returns (brutal_summary, full_abstract) or (None, None).
     """
-    for pg_num in range(1, min(5, doc.page_count)):
+    start = 0 if doc.page_count == 1 else 1
+    for pg_num in range(start, min(5, doc.page_count)):
         text = doc[pg_num].get_text()
         lines = text.split("\n")
         for i, line in enumerate(lines):
@@ -127,15 +131,15 @@ def read_pdf(path):
     try:
         import fitz
         doc = fitz.open(str(path))
-        if doc.page_count == 0:
+        try:
+            if doc.page_count == 0:
+                result["doc_number"] = _doc_number_from_filename(path)
+                return result
+
+            first_page = doc[0].get_text()
+            brutal, abstract = _extract_abstract_from_doc(doc)
+        finally:
             doc.close()
-            result["doc_number"] = _doc_number_from_filename(path)
-            return result
-
-        first_page = doc[0].get_text()
-
-        brutal, abstract = _extract_abstract_from_doc(doc)
-        doc.close()
     except Exception:
         result["doc_number"] = _doc_number_from_filename(path)
         return result
@@ -144,7 +148,7 @@ def read_pdf(path):
     text = first_page[:3000]
 
     result["doc_number"] = _extract_doc_number(text) or _doc_number_from_filename(path)
-    result["title"] = _extract_title(text, lines)
+    result["title"] = _extract_title(lines)
     result["authors"] = _extract_authors(text)
     result["abstract"] = abstract
     result["brutal_summary"] = brutal