mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/mentions.py

@@ -0,0 +1,57 @@
+"""Figure mention extraction and linking."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from mednotes.domains.wiki.capabilities.pdf import figure_ids
+
+
+@dataclass(frozen=True)
+class Mention:
+    page_number: int
+    figure_id: str
+    sentence: str
+    paragraph: str = ""
+    section_path_guess: list[str] = field(default_factory=list)
+    offset_start: int = 0
+    offset_end: int = 0
+
+
+def extract_mentions(text: str, *, page_number: int, section_path_guess: list[str] | None = None) -> list[Mention]:
+    mentions: list[Mention] = []
+    for _raw, normalized, start, end in figure_ids.find_ids(text):
+        sentence = _sentence_around(text, start, end)
+        mentions.append(
+            Mention(
+                page_number=page_number,
+                figure_id=normalized,
+                sentence=sentence,
+                paragraph=sentence,
+                section_path_guess=list(section_path_guess or []),
+                offset_start=start,
+                offset_end=end,
+            )
+        )
+    return mentions
+
+
+def link_mentions(caption_page: int, caption_section: list[str], candidates: list[Mention], *, figure_id: str, window_pages: int = 20) -> list[Mention]:
+    linked: list[Mention] = []
+    for mention in candidates:
+        if mention.figure_id != figure_id:
+            continue
+        same_section = bool(caption_section and mention.section_path_guess and caption_section[:1] == mention.section_path_guess[:1])
+        near = abs(mention.page_number - caption_page) <= window_pages
+        if same_section or near:
+            linked.append(mention)
+    return linked
+
+
+def _sentence_around(text: str, start: int, end: int) -> str:
+    left = max(text.rfind(".", 0, start), text.rfind("\n", 0, start))
+    right_dot = text.find(".", end)
+    right_newline = text.find("\n", end)
+    candidates = [idx for idx in (right_dot, right_newline) if idx != -1]
+    right = min(candidates) if candidates else min(len(text), end + 180)
+    return re.sub(r"\s+", " ", text[left + 1 : right + 1]).strip()

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/ocr.py

@@ -0,0 +1,71 @@
+"""OCR state machine and Tesseract seam."""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class OcrOutcome:
+    status: str
+    text: str
+    confidence: float | None
+    error_code: str = ""
+    retry_eligible: bool = False
+
+
+class OcrRunner(Protocol):
+    def run(self, image_path: Path, languages: list[str]) -> OcrOutcome:
+        ...
+
+
+class MissingTesseractRunner:
+    def run(self, image_path: Path, languages: list[str]) -> OcrOutcome:
+        return OcrOutcome(status="blocked", text="", confidence=None, error_code="missing_binary", retry_eligible=True)
+
+
+class TesseractRunner:
+    def run(self, image_path: Path, languages: list[str]) -> OcrOutcome:
+        if shutil.which("tesseract") is None:
+            return MissingTesseractRunner().run(image_path, languages)
+        try:
+            import pytesseract
+            from PIL import Image
+        except Exception:
+            return OcrOutcome("failed", "", None, "engine_error", True)
+        try:
+            text = str(pytesseract.image_to_string(Image.open(image_path), lang="+".join(languages)))
+        except pytesseract.TesseractError as exc:
+            message = str(exc).lower()
+            if "failed loading language" in message or "could not initialize tesseract" in message:
+                return OcrOutcome("blocked", "", None, "missing_language", True)
+            return OcrOutcome("failed", "", None, "engine_error", True)
+        except Exception:
+            return OcrOutcome("failed", "", None, "engine_error", True)
+        stripped = text.strip()
+        return OcrOutcome("complete" if stripped else "failed", stripped, None, "" if stripped else "engine_error", not bool(stripped))
+
+
+def ocr_page(image_path: Path, *, languages: list[str], runner: OcrRunner | None = None) -> OcrOutcome:
+    return (runner or TesseractRunner()).run(image_path, languages)
+
+
+def aggregate_status(outcomes: list[OcrOutcome]) -> tuple[str, str, int]:
+    if not outcomes:
+        return "not_needed", "", 0
+    statuses = {outcome.status for outcome in outcomes}
+    retry = 1 if any(outcome.retry_eligible for outcome in outcomes) else 0
+    error = next((outcome.error_code for outcome in outcomes if outcome.error_code), "")
+    if statuses == {"blocked"}:
+        return "blocked", error, retry
+    if statuses == {"failed"}:
+        return "failed", error, retry
+    if "complete" in statuses and statuses <= {"complete", "not_needed"}:
+        return "complete", "", retry
+    if "complete" in statuses:
+        return "partial", error, retry
+    if "blocked" in statuses:
+        return "blocked", error, retry
+    return "needed", error, retry

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/paths.py

@@ -0,0 +1,35 @@
+"""Paths for the local PDF library state."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+APP_STATE_SUBDIR = Path(".mednotes")
+PDF_LIBRARY_SUBDIR = Path("pdf-library")
+
+
+def home_dir() -> Path:
+    return Path(os.environ.get("HOME") or os.environ.get("USERPROFILE") or Path.home()).expanduser()
+
+
+def app_state_dir() -> Path:
+    return home_dir() / APP_STATE_SUBDIR
+
+
+def app_home() -> Path:
+    return app_state_dir() / PDF_LIBRARY_SUBDIR
+
+
+def app_config_path() -> Path:
+    return app_state_dir() / "config.toml"
+
+
+def database_path(base: Path | None = None) -> Path:
+    root = base or app_home()
+    return root / "library.sqlite3"
+
+
+def extension_root() -> Path:
+    from mednotes.platform.paths import extension_root as _root
+
+    return _root()

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/pdf_engine.py

@@ -0,0 +1,77 @@
+"""Lazy PyMuPDF boundary."""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class PdfImageBlock:
+    bbox: tuple[float, float, float, float]
+    image_sha256: str
+    crop_path: Path
+    width_px: int
+    height_px: int
+
+
+@dataclass(frozen=True)
+class PdfPageExtract:
+    pdf_sha256: str
+    page_number: int
+    width_px: int
+    height_px: int
+    text: str
+    has_text_layer: bool
+    image_blocks: list[PdfImageBlock] = field(default_factory=list)
+    thumbnail_path: Path | None = None
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def extract_pages(pdf_path: Path, *, app_home: Path) -> tuple[str, int, list[PdfPageExtract]]:
+    import fitz
+
+    pdf_sha = sha256_file(pdf_path)
+    pages: list[PdfPageExtract] = []
+    thumb_dir = app_home / "thumbnails" / pdf_sha
+    thumb_dir.mkdir(parents=True, exist_ok=True)
+    doc = fitz.open(pdf_path)
+    try:
+        for page_index in range(len(doc)):
+            index = page_index + 1
+            page = doc[page_index]
+            raw_text = page.get_text("text")
+            text = raw_text if isinstance(raw_text, str) else ""
+            rect = page.rect
+            thumb_path = thumb_dir / f"page-{index}.png"
+            try:
+                pix = page.get_pixmap(matrix=fitz.Matrix(0.35, 0.35), alpha=False)
+                pix.save(str(thumb_path))
+                width_px = int(pix.width)
+                height_px = int(pix.height)
+            except Exception:
+                width_px = int(rect.width)
+                height_px = int(rect.height)
+                thumb_path = None
+            pages.append(
+                PdfPageExtract(
+                    pdf_sha256=pdf_sha,
+                    page_number=index,
+                    width_px=width_px,
+                    height_px=height_px,
+                    text=text.strip(),
+                    has_text_layer=bool(text.strip()),
+                    image_blocks=[],
+                    thumbnail_path=thumb_path,
+                )
+            )
+    finally:
+        doc.close()
+    return pdf_sha, len(pages), pages

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/schema.py

@@ -0,0 +1,155 @@
+"""SQLite schema for the PDF library."""
+from __future__ import annotations
+
+SCHEMA_VERSION = "1"
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS metadata (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS documents (
+  pdf_sha256 TEXT PRIMARY KEY,
+  path TEXT NOT NULL,
+  filename TEXT NOT NULL,
+  title_guess TEXT NOT NULL DEFAULT '',
+  page_count INTEGER NOT NULL,
+  has_text_layer INTEGER NOT NULL DEFAULT 0,
+  ocr_status TEXT NOT NULL CHECK (ocr_status IN ('not_needed','needed','blocked','partial','complete','failed')),
+  ocr_error_code TEXT NOT NULL DEFAULT '',
+  ocr_retry_eligible INTEGER NOT NULL DEFAULT 0 CHECK (ocr_retry_eligible IN (0, 1)),
+  source_mtime_ns INTEGER NOT NULL,
+  source_size_bytes INTEGER NOT NULL,
+  indexed_at TEXT NOT NULL,
+  removed_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS pages (
+  pdf_sha256 TEXT NOT NULL REFERENCES documents(pdf_sha256) ON DELETE CASCADE,
+  page_number INTEGER NOT NULL,
+  text_source TEXT NOT NULL CHECK (text_source IN ('digital','ocr','none')),
+  text TEXT NOT NULL DEFAULT '',
+  ocr_confidence REAL,
+  ocr_status TEXT NOT NULL CHECK (ocr_status IN ('not_needed','needed','blocked','partial','complete','failed')),
+  ocr_error_code TEXT NOT NULL DEFAULT '',
+  ocr_retry_eligible INTEGER NOT NULL DEFAULT 0 CHECK (ocr_retry_eligible IN (0, 1)),
+  section_path_guess TEXT NOT NULL DEFAULT '[]',
+  page_thumbnail_path TEXT NOT NULL DEFAULT '',
+  width_px INTEGER NOT NULL DEFAULT 0,
+  height_px INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (pdf_sha256, page_number)
+);
+
+CREATE TABLE IF NOT EXISTS figures (
+  figure_uid TEXT PRIMARY KEY,
+  pdf_sha256 TEXT NOT NULL REFERENCES documents(pdf_sha256) ON DELETE CASCADE,
+  page_number INTEGER NOT NULL,
+  bbox_json TEXT NOT NULL DEFAULT '[]',
+  crop_path TEXT NOT NULL DEFAULT '',
+  thumbnail_path TEXT NOT NULL DEFAULT '',
+  image_sha256 TEXT NOT NULL DEFAULT '',
+  figure_id TEXT NOT NULL DEFAULT '',
+  display_label TEXT NOT NULL DEFAULT '',
+  caption TEXT NOT NULL DEFAULT '',
+  caption_bbox_json TEXT NOT NULL DEFAULT '[]',
+  visual_quality_score REAL NOT NULL DEFAULT 0,
+  evidence_level TEXT NOT NULL CHECK (evidence_level IN ('caption_and_mentions','caption_only','mentions_only','page_context_only','visual_only')),
+  is_low_confidence INTEGER NOT NULL DEFAULT 1,
+  conflict_reason TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS mentions (
+  mention_uid TEXT PRIMARY KEY,
+  pdf_sha256 TEXT NOT NULL REFERENCES documents(pdf_sha256) ON DELETE CASCADE,
+  figure_uid TEXT REFERENCES figures(figure_uid) ON DELETE SET NULL,
+  page_number INTEGER NOT NULL,
+  figure_id TEXT NOT NULL DEFAULT '',
+  display_label TEXT NOT NULL DEFAULT '',
+  sentence TEXT NOT NULL DEFAULT '',
+  paragraph TEXT NOT NULL DEFAULT '',
+  section_path_guess TEXT NOT NULL DEFAULT '[]',
+  offset_start INTEGER NOT NULL DEFAULT 0,
+  offset_end INTEGER NOT NULL DEFAULT 0,
+  confidence REAL NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS anchor_cache (
+  cache_key TEXT NOT NULL,
+  note_sha256 TEXT NOT NULL,
+  anchor_id TEXT NOT NULL,
+  note_path TEXT NOT NULL DEFAULT '',
+  section_path_json TEXT NOT NULL DEFAULT '[]',
+  concept TEXT NOT NULL,
+  visual_type TEXT NOT NULL,
+  search_queries_json TEXT NOT NULL DEFAULT '[]',
+  provider TEXT NOT NULL DEFAULT '',
+  model_id TEXT NOT NULL DEFAULT '',
+  preferred_language TEXT NOT NULL DEFAULT '',
+  max_anchors INTEGER NOT NULL DEFAULT 0,
+  prompt_version TEXT NOT NULL DEFAULT 'pdf-library-anchors-v1',
+  created_at TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  PRIMARY KEY (cache_key, anchor_id)
+);
+
+CREATE TABLE IF NOT EXISTS search_receipts (
+  receipt_uid TEXT PRIMARY KEY,
+  query_text TEXT NOT NULL DEFAULT '',
+  note_path TEXT NOT NULL DEFAULT '',
+  anchor_id TEXT NOT NULL DEFAULT '',
+  provider TEXT NOT NULL DEFAULT 'local',
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  payload_json TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS embedding_runs (
+  run_uid TEXT PRIMARY KEY,
+  provider TEXT NOT NULL,
+  model_id TEXT NOT NULL,
+  dimensions INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL DEFAULT 'reserved',
+  created_at TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS page_fts USING fts5(
+  pdf_sha256 UNINDEXED,
+  page_number UNINDEXED,
+  title_guess,
+  section_path_guess,
+  text,
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS figure_fts USING fts5(
+  figure_uid UNINDEXED,
+  pdf_sha256 UNINDEXED,
+  figure_id,
+  display_label,
+  caption,
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS mention_fts USING fts5(
+  mention_uid UNINDEXED,
+  pdf_sha256 UNINDEXED,
+  figure_id,
+  sentence,
+  paragraph,
+  section_path_guess,
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+
+CREATE INDEX IF NOT EXISTS idx_documents_path ON documents(path);
+CREATE INDEX IF NOT EXISTS idx_pages_pdf_page ON pages(pdf_sha256, page_number);
+CREATE INDEX IF NOT EXISTS idx_figures_pdf_page ON figures(pdf_sha256, page_number);
+CREATE INDEX IF NOT EXISTS idx_figures_figure_id ON figures(pdf_sha256, figure_id);
+CREATE INDEX IF NOT EXISTS idx_mentions_figure_id ON mentions(pdf_sha256, figure_id);
+CREATE INDEX IF NOT EXISTS idx_anchor_cache_note ON anchor_cache(note_sha256);
+"""

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/search.py

@@ -0,0 +1,188 @@
+"""Local PDF library search and ranking."""
+from __future__ import annotations
+
+import json
+import sqlite3
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from mednotes.domains.wiki.capabilities.pdf import cloud, db, paths
+from mednotes.kernel.base import JsonObject, JsonObjectAdapter, JsonValue
+
+SCHEMA = "medical-notes-workbench.pdf-library-search-results.v1"
+
+
+@dataclass(frozen=True)
+class SearchHit:
+    figure_uid: str
+    score: float
+    why: list[str]
+    evidence_level: str
+    is_low_confidence: bool
+    provider_receipts: list[dict[str, object]] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class SearchRequest:
+    query_text: str = ""
+    note_path: Path | None = None
+    anchor_id: str = ""
+    provider: str = "local"
+    top_k: int = 20
+
+
+def search(request: SearchRequest, *, app_home: Path | None = None) -> dict[str, Any]:
+    provider = cloud.resolve_provider(request.provider)
+    if provider["status"] == "blocked":
+        return {
+            "schema": SCHEMA,
+            "status": "blocked",
+            "phase": "search",
+            "blocked_reason": provider["blocked_reason"],
+            "next_action": provider["next_action"],
+            "provider_receipts": [provider],
+        }
+    query = request.query_text.strip()
+    if not query and request.note_path is not None:
+        query = _query_from_note_anchor(request, app_home=app_home)
+        if not query:
+            return _blocked("anchor_not_found", "choose an existing anchor or pass --query")
+    if not query:
+        return _blocked("missing_query_or_note", "pass --query TEXT or --note NOTE")
+    root = app_home or paths.app_home()
+    conn = db.open_database(paths.database_path(root))
+    hits = _local_search(conn, query, request.top_k)
+    payload = {
+        "schema": SCHEMA,
+        "status": "ok",
+        "phase": "search",
+        "query_text": query,
+        "results": [hit.__dict__ for hit in hits],
+        "provider_receipts": [] if request.provider == "local" else [provider],
+    }
+    _record_receipt(conn, request, payload)
+    return payload
+
+
+def _local_search(conn: sqlite3.Connection, query: str, top_k: int) -> list[SearchHit]:
+    scores: dict[str, float] = {}
+    why: dict[str, set[str]] = {}
+    for source, table, uid_col, reason in (
+        ("figure", "figure_fts", "figure_uid", "caption match"),
+        ("mention", "mention_fts", "mention_uid", "mention match"),
+        ("page", "page_fts", "page_number", "page text match"),
+    ):
+        try:
+            rows = conn.execute(f"SELECT * FROM {table} WHERE {table} MATCH ? LIMIT 100", (query,)).fetchall()
+        except sqlite3.OperationalError:
+            rows = []
+        for row in rows:
+            if source == "figure":
+                figure_uid = str(row[uid_col])
+            elif source == "mention":
+                mention = conn.execute("SELECT figure_uid FROM mentions WHERE mention_uid = ?", (row[uid_col],)).fetchone()
+                if not mention or not mention["figure_uid"]:
+                    continue
+                figure_uid = str(mention["figure_uid"])
+            else:
+                figure = conn.execute(
+                    "SELECT figure_uid FROM figures WHERE pdf_sha256 = ? AND page_number = ? LIMIT 1",
+                    (row["pdf_sha256"], row["page_number"]),
+                ).fetchone()
+                if not figure:
+                    continue
+                figure_uid = str(figure["figure_uid"])
+            scores[figure_uid] = scores.get(figure_uid, 0.0) + (7.0 if source == "figure" else 4.0 if source == "mention" else 1.5)
+            why.setdefault(figure_uid, set()).add(reason)
+    if not scores:
+        like = f"%{query}%"
+        for row in conn.execute(
+            """
+            SELECT figure_uid FROM figures
+            JOIN documents USING(pdf_sha256)
+            WHERE documents.removed_at IS NULL AND (caption LIKE ? OR display_label LIKE ?)
+            LIMIT 100
+            """,
+            (like, like),
+        ):
+            scores[str(row["figure_uid"])] = 3.0
+            why.setdefault(str(row["figure_uid"]), set()).add("caption contains query")
+    hits: list[SearchHit] = []
+    for figure_uid, score in scores.items():
+        row = conn.execute(
+            """
+            SELECT figures.figure_uid, figures.evidence_level, figures.is_low_confidence, figures.conflict_reason
+            FROM figures JOIN documents USING(pdf_sha256)
+            WHERE figures.figure_uid = ? AND documents.removed_at IS NULL
+            """,
+            (figure_uid,),
+        ).fetchone()
+        if not row:
+            continue
+        evidence = str(row["evidence_level"])
+        if evidence == "caption_and_mentions":
+            score += 4
+        if evidence == "visual_only":
+            score -= 3
+        if row["conflict_reason"]:
+            score -= 4
+        hits.append(
+            SearchHit(
+                figure_uid=figure_uid,
+                score=round(score, 3),
+                why=sorted(why.get(figure_uid, set())),
+                evidence_level=evidence,
+                is_low_confidence=bool(row["is_low_confidence"]),
+            )
+        )
+    return sorted(hits, key=lambda hit: hit.score, reverse=True)[:top_k]
+
+
+def _query_from_note_anchor(request: SearchRequest, *, app_home: Path | None) -> str:
+    if request.note_path is None:
+        return ""
+    conn = db.open_database(paths.database_path(app_home or paths.app_home()))
+    note_path = str(request.note_path)
+    row = conn.execute(
+        "SELECT payload_json FROM anchor_cache WHERE note_path = ? AND anchor_id = ? LIMIT 1",
+        (note_path, request.anchor_id),
+    ).fetchone()
+    if not row:
+        return ""
+    payload = JsonObjectAdapter.validate_python(json.loads(str(row["payload_json"])))
+    queries = payload.get("search_queries")
+    if isinstance(queries, list) and queries:
+        return str(queries[0])
+    return str(payload.get("concept") or "")
+
+
+def _optional_path_text(path: Path | None) -> str:
+    return str(path) if path is not None else ""
+
+
+def _record_receipt(conn: sqlite3.Connection, request: SearchRequest, payload: JsonObject) -> None:
+    with conn:
+        conn.execute(
+            "INSERT INTO search_receipts(receipt_uid, query_text, note_path, anchor_id, provider, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                str(uuid.uuid4()),
+                request.query_text,
+                _optional_path_text(request.note_path),
+                request.anchor_id,
+                request.provider,
+                str(_json_field(payload, "status")),
+                datetime.now(UTC).isoformat(),
+                json.dumps(payload, ensure_ascii=False),
+            ),
+        )
+
+
+def _blocked(reason: str, next_action: str) -> JsonObject:
+    return {"schema": SCHEMA, "status": "blocked", "phase": "search", "blocked_reason": reason, "next_action": next_action}
+
+
+def _json_field(source: JsonObject, key: str, default: JsonValue = None) -> JsonValue:
+    return source.get(key, default)

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/tui/__init__.py

@@ -0,0 +1 @@
+"""Textual UI for the PDF library."""

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/pdf/tui/app.py

@@ -0,0 +1,89 @@
+"""Minimal functional Textual review app for the PDF library."""
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.widgets import Footer, Static
+
+from mednotes.domains.wiki.capabilities.pdf.tui import image_backend as image_backend_mod
+from mednotes.domains.wiki.capabilities.pdf.tui.state import PdfLibraryState
+
+
+class RenderableStatic(Static):
+    @property
+    def renderable(self) -> str:
+        return str(self.content)
+
+
+class PdfLibraryApp(App[None]):
+    BINDINGS = [
+        ("i", "ingest", "Ingest"),
+        ("s", "search", "Search"),
+        ("enter", "select_first", "Select"),
+        ("p", "preview", "Preview"),
+        ("d", "doctor", "Doctor"),
+        ("q", "quit", "Quit"),
+    ]
+
+    CSS = """
+    Screen { layout: vertical; }
+    #screen-title { height: 3; padding: 1 2; text-style: bold; }
+    #body { padding: 1 2; }
+    """
+
+    def __init__(self, *, state: PdfLibraryState | None = None, image_backend: str = "auto") -> None:
+        super().__init__()
+        self.state = state or PdfLibraryState()
+        self.backend = image_backend_mod.detect(preferred=image_backend)
+
+    def compose(self) -> ComposeResult:
+        yield RenderableStatic(self._title(), id="screen-title")
+        yield Static(self._body(), id="body")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._refresh()
+
+    def action_doctor(self) -> None:
+        self.state.active_screen = "doctor"
+        self._refresh()
+
+    def action_ingest(self) -> None:
+        self.state.active_screen = "ingest"
+        self._refresh()
+
+    def action_search(self) -> None:
+        self.state.active_screen = "search"
+        self._refresh()
+
+    def action_select_first(self) -> None:
+        if self.state.search_results:
+            self.state.select_figure(self.state.search_results[0].figure_uid)
+            self.state.active_screen = "figure_review"
+        self._refresh()
+
+    def action_preview(self) -> None:
+        self.state.active_screen = "insert_preview"
+        self._refresh()
+
+    def _refresh(self) -> None:
+        self.query_one("#screen-title", Static).update(self._title())
+        self.query_one("#body", Static).update(self._body())
+
+    def _title(self) -> str:
+        labels = {
+            "doctor": "Doctor / Setup",
+            "ingest": "Ingest Queue",
+            "search": "Search",
+            "figure_review": "Figure Review",
+            "insert_preview": "Insert Preview",
+        }
+        return labels.get(self.state.active_screen, self.state.active_screen)
+
+    def _body(self) -> str:
+        return (
+            f"Backend: {self.backend.name}\n"
+            f"Note: {self.state.selected_note or '-'}\n"
+            f"Queued PDFs: {len(self.state.ingest_queue)}\n"
+            f"Results: {len(self.state.search_results)}\n"
+            f"Selected figure: {self.state.selected_figure_uid or '-'}"
+        )