page tweaks

.github/instructions/ui.instructions.md

@@ -0,0 +1,6 @@
+---
+description: Copilot rules for modifying the UI
+applyTo: 'src/transcription/ui/**/*.py'
+---
+
+The UI is forbidden from directly touching the database. All interactions should be done using the [services](../../src/transcription/services/)

src/transcription/app.py

@@ -8,6 +8,7 @@ from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from fastapi import status
 from fastapi.responses import RedirectResponse
+from fastapi.staticfiles import StaticFiles
 
 from .api.errors import register_error_handlers
 from .api.health import router as health_router
@@ -25,7 +26,7 @@ from .worker import worker_consumer_lifespan
 async def _lifespan(app: FastAPI):
     configure_logging()
 
-    settings = get_settings()
+    settings = getattr(app.state, "settings", None) or get_settings()
     app.state.settings = settings
     app.state.services = ServiceBundle()
     app.state.runtime = initialize_database_runtime(settings=settings)
@@ -52,6 +53,13 @@ async def _lifespan(app: FastAPI):
 def create_app() -> FastAPI:
     """Create and configure the FastAPI application."""
     app = FastAPI(title="Transcription", lifespan=_lifespan)
+    settings = get_settings()
+    app.state.settings = settings
+    app.mount(
+        "/uploads",
+        StaticFiles(directory=settings.upload_dir, check_dir=False),
+        name="uploads",
+    )
 
     @app.get("/", include_in_schema=False)
     async def root_redirect() -> RedirectResponse:

src/transcription/models.py

@@ -1,16 +1,16 @@
 """SQLModel domain models for the transcription system.
 
 Three models capture the MVP lifecycle:
-  Document  ->  one-to-many  ->  Job  ->  one-to-one  ->  Transcript
+    Document  ->  one-to-many  ->  Job  ->  one-to-many  ->  Transcript
 """
 
 from datetime import UTC
 from datetime import datetime
 from enum import StrEnum
-from typing import Optional
 from uuid import UUID
 from uuid import uuid4
 
+from sqlalchemy import UniqueConstraint
 from sqlmodel import Field
 from sqlmodel import Relationship
 from sqlmodel import SQLModel
@@ -47,7 +47,7 @@ class Job(SQLModel, table=True):
 
     # --- relationships ---
     document: Document = Relationship(back_populates="jobs")
-    transcript: Optional["Transcript"] = Relationship(back_populates="job")
+    transcripts: list["Transcript"] = Relationship(back_populates="job")
 
     @property
     def filename(self) -> str:
@@ -59,8 +59,10 @@ class Transcript(SQLModel, table=True):
     """The output of a transcription job."""
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
-    job_id: UUID = Field(foreign_key="job.id", unique=True)
+    job_id: UUID = Field(foreign_key="job.id")
-    """ID for the associated job. There's a 1-1 relationship bewteen transcripts and jobs."""
+    """ID for the associated job."""
+    revision: int = Field(default=0, ge=0)
+    """Revision number for this job's transcript history, starting at 0."""
     provider: str
     """Name of the transcription provider used to generate this transcript."""
     prompt_name: str
@@ -71,5 +73,7 @@ class Transcript(SQLModel, table=True):
     """Details of any error that occurred during transcription."""
     created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
+    __table_args__ = (UniqueConstraint("job_id", "revision", name="uq_transcript_job_revision"),)
+
     # --- relationships ---
-    job: Job = Relationship(back_populates="transcript")
+    job: Job = Relationship(back_populates="transcripts")

src/transcription/services/transcription.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 import logging
 import mimetypes
+from collections.abc import Sequence
 from contextlib import contextmanager
 from pathlib import Path
 from uuid import UUID
 
+from sqlalchemy import func
 from sqlalchemy.ext.asyncio import async_sessionmaker
 from sqlalchemy.orm import selectinload
 from sqlmodel import select
@@ -108,38 +110,76 @@ class TranscriptionService(ServiceBase):
             settings=self.settings,
             provider=self.provider,
         )
-        await self.create_transcript(transcript=result.to_transcript(job_id=job_id), session=session)
+        await self.create_transcript_for_job(
+            job_id=job_id,
+            text=result.text,
+            provider=result.provider,
+            prompt_name=result.prompt_name,
+            session=session,
+        )
 
-    async def upsert_transcript_by_job(
+    async def create_transcript_for_job(
         self,
         *,
         job_id: UUID,
         text: str | None,
-        error_detail: str | None,
+        error_detail: str | None = None,
         provider: str | None = None,
         prompt_name: str = DEFAULT_PROMPT_FILE,
         session: AsyncSession | None = None,
     ) -> Transcript:
-        """Create or update a transcript for a job id."""
+        """Create a new transcript revision for a job id."""
         async with self._session_scope(session) as _session:
-            transcript = (await _session.exec(select(Transcript).where(Transcript.job_id == job_id))).first()
+            rev_query = select(func.max(Transcript.revision)).where(Transcript.job_id == job_id)
-            if transcript is None:
+            rev_result = await _session.exec(rev_query)
+            max_revision = -1 if (rev := rev_result.one_or_none()) is None else rev
+            next_revision = max_revision + 1
+
             transcript = Transcript(
                 job_id=job_id,
+                revision=next_revision,
                 provider=provider or self.settings.provider.value,
                 prompt_name=prompt_name,
+                text=text,
+                error_detail=error_detail,
             )
-
-            transcript.text = text
-            transcript.error_detail = error_detail
-            if provider is not None:
-                transcript.provider = provider
-            transcript.prompt_name = prompt_name
-
             _session.add(transcript)
             await self._finalize(session=_session, caller_session=session, refresh=(transcript,))
             return transcript
 
+    async def read_latest_transcript_by_job(
+        self,
+        job_id: UUID,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Transcript | None:
+        """Read the latest transcript revision for a job id."""
+        async with self._session_scope(session) as _session:
+            query = _transcript_job_query(job_id=job_id).limit(1)
+            result = await _session.exec(query)
+            return result.one_or_none()
+
+    async def list_transcripts_by_job(
+        self,
+        job_id: UUID,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Sequence[Transcript]:
+        """List transcript revisions for a job id in ascending revision order."""
+        async with self._session_scope(session) as _session:
+            query = _transcript_job_query(job_id=job_id)
+            result = await _session.exec(query)
+            return result.all()
+
+
+def _transcript_job_query(job_id: UUID):
+    return (
+        select(Transcript)
+        .where(Transcript.job_id == job_id)
+        .options(selectinload(Transcript.job))  # pyright: ignore[reportArgumentType]
+        .order_by(Transcript.revision)  # pyright: ignore[reportArgumentType]
+    )  # fmt: skip
+
 
 async def transcribe_document_image(
     image_path: str | Path,

src/transcription/services/workflows.py

@@ -121,7 +121,7 @@ async def _finalize_transcribed(
     """Transaction B: transcript + TRANSCRIBED in one commit."""
     if session is None:
         async with services.jobs._session_scope() as local_session:
-            await services.transcriptions.upsert_transcript_by_job(
+            await services.transcriptions.create_transcript_for_job(
                 job_id=job.id,
                 text=result.text,
                 error_detail=None,
@@ -137,7 +137,7 @@ async def _finalize_transcribed(
             await local_session.commit()
             return updated_job
 
-    await services.transcriptions.upsert_transcript_by_job(
+    await services.transcriptions.create_transcript_for_job(
         job_id=job.id,
         text=result.text,
         error_detail=None,
@@ -165,7 +165,7 @@ async def _finalize_retry(
     """Transaction C: transcript error + QUEUED + retry increment in one commit."""
     if session is None:
         async with services.jobs._session_scope() as local_session:
-            await services.transcriptions.upsert_transcript_by_job(
+            await services.transcriptions.create_transcript_for_job(
                 job_id=job.id,
                 text=None,
                 error_detail=format_error_detail(error),
@@ -180,7 +180,7 @@ async def _finalize_retry(
             )
             await local_session.commit()
     else:
-        await services.transcriptions.upsert_transcript_by_job(
+        await services.transcriptions.create_transcript_for_job(
             job_id=job.id,
             text=None,
             error_detail=format_error_detail(error),
@@ -210,7 +210,7 @@ async def _finalize_failed(
     """Transaction B: transcript error + FAILED in one commit."""
     if session is None:
         async with services.jobs._session_scope() as local_session:
-            await services.transcriptions.upsert_transcript_by_job(
+            await services.transcriptions.create_transcript_for_job(
                 job_id=job.id,
                 text=None,
                 error_detail=format_error_detail(error),
@@ -225,7 +225,7 @@ async def _finalize_failed(
             await local_session.commit()
             return updated_job
 
-    await services.transcriptions.upsert_transcript_by_job(
+    await services.transcriptions.create_transcript_for_job(
         job_id=job.id,
         text=None,
         error_detail=format_error_detail(error),

src/transcription/ui/__init__.py

@@ -1,14 +1,45 @@
 """UI page registration exports."""
 
+from pathlib import Path
+
 from fastapi import FastAPI
+from nicegui import app as nicegui_app
 from nicegui import ui
 
 from transcription.ui.pages.jobs_page import register_page as register_jobs_page
 from transcription.ui.pages.upload_page import register_page as register_upload_page
 
+_THEME_REGISTERED_STATE_KEY = "transcription_ui_theme_registered"
+
+_THEME_COLORS: dict[str, str] = {
+    "primary": "#6f97e8",
+    "secondary": "#92b5f5",
+    "accent": "#7fc0de",
+    "dark": "#22304a",
+    "dark_page": "#1a2538",
+    "positive": "#86c8ad",
+    "negative": "#d98a9a",
+    "info": "#7ebdda",
+    "warning": "#e2c083",
+}
+
+
+def _register_global_styles(app: FastAPI) -> None:
+    if getattr(app.state, _THEME_REGISTERED_STATE_KEY, False):
+        return
+
+    nicegui_app.colors(**_THEME_COLORS)
+
+    css_path = Path(__file__).resolve().parent / "static" / "colors.css"
+    if css_path.exists():
+        ui.add_css(css_path, shared=True)
+
+    setattr(app.state, _THEME_REGISTERED_STATE_KEY, True)
+
 
 def register_pages(app: FastAPI) -> None:
     """Register all NiceGUI pages and mount them onto the FastAPI app."""
+    _register_global_styles(app)
     register_upload_page()
     register_jobs_page()
-    ui.run_with(app, mount_path="/ui", show_welcome_message=False)
+    ui.run_with(app, mount_path="/ui", show_welcome_message=False, dark=True)

src/transcription/ui/components/__init__.py

@@ -0,0 +1,7 @@
+"""Reusable UI component exports."""
+
+from transcription.ui.components.app_shell import NAV_ITEMS
+from transcription.ui.components.app_shell import render_navigation_header
+from transcription.ui.components.document_panzoom import render_document_panzoom
+
+__all__ = ["NAV_ITEMS", "render_document_panzoom", "render_navigation_header"]

src/transcription/ui/components/app_shell.py

@@ -0,0 +1,59 @@
+"""Reusable app shell primitives for page-level layout."""
+
+from __future__ import annotations
+
+from nicegui import ui
+
+NAV_ITEMS: tuple[tuple[str, str, str], ...] = (
+    ("Upload", "/upload", "upload_file"),
+    ("Jobs", "/jobs", "work_history"),
+)
+
+
+def _is_active_path(*, current_path: str, item_path: str) -> bool:
+    if item_path == "/jobs":
+        return current_path == "/jobs" or current_path.startswith("/jobs/")
+    return current_path == item_path
+
+
+def _button_props(*, icon: str, is_active: bool) -> str:
+    if is_active:
+        return f"icon={icon} no-caps unelevated color=primary text-color=white"
+    return f"icon={icon} no-caps outline color=secondary text-color=secondary"
+
+
+def _button_classes(*, is_active: bool) -> str:
+    base = "w-full sm:w-auto min-h-[40px] px-3 rounded-lg text-body2 text-weight-medium"
+    if is_active:
+        return f"{base}"
+    return f"{base}"
+
+
+def _render_nav_button(*, label: str, path: str, icon: str, current_path: str) -> None:
+    is_active = _is_active_path(current_path=current_path, item_path=path)
+    button = ui.button(
+        label,
+        icon=icon,
+        on_click=lambda _=None, route=path: ui.navigate.to(route),
+    )
+    button.props(_button_props(icon=icon, is_active=is_active)).classes(_button_classes(is_active=is_active))
+
+
+def _normalize_path(current_path: str | None) -> str:
+    normalized = (current_path or "").strip()
+    if not normalized:
+        return "/upload"
+    return normalized.rstrip("/") or "/"
+
+
+def render_navigation_header(*, current_path: str | None = None) -> None:
+    """Render a shared app header with links for top-level pages."""
+    normalized_path = _normalize_path(current_path)
+
+    with (
+        ui.header(elevated=True).props("bordered").classes("bg-dark text-white q-px-sm q-py-xs"),
+        ui.row().classes("w-full items-center justify-end q-gutter-xs"),
+        ui.element("div").classes("w-full grid grid-cols-2 gap-2 sm:flex sm:justify-start sm:gap-2"),
+    ):
+        for label, path, icon in NAV_ITEMS:
+            _render_nav_button(label=label, path=path, icon=icon, current_path=normalized_path)

src/transcription/ui/components/document_panzoom.py

@@ -0,0 +1,235 @@
+"""Panzoom-backed document preview component."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from urllib.parse import quote
+from uuid import uuid4
+
+from nicegui import ui
+
+from transcription.config import get_settings
+from transcription.models import Document
+
+PANGOZOOM_CDN_URL = "https://unpkg.com/@panzoom/[email protected]/dist/panzoom.min.js"
+UPLOADS_URL_PREFIX = "/uploads"
+
+
+def _document_url(document: Document) -> str:
+    file_path = Path(document.file_path)
+    upload_dir = get_settings().upload_dir
+
+    relative_path: Path
+    try:
+        relative_path = file_path.resolve().relative_to(upload_dir.resolve())
+    except ValueError:
+        parts = file_path.parts
+        if "uploads" in parts:
+            uploads_index = parts.index("uploads")
+            relative_path = Path(*parts[uploads_index + 1 :])
+        else:
+            relative_path = Path(file_path.name)
+
+    encoded_relative_path = "/".join(quote(part) for part in relative_path.parts)
+    return f"{UPLOADS_URL_PREFIX}/{encoded_relative_path}"
+
+
+def _document_kind(document: Document) -> str:
+    suffix = Path(document.file_path).suffix.lower()
+    if suffix == ".pdf":
+        return "pdf"
+    return "image"
+
+
+@lru_cache(maxsize=1)
+def _register_panzoom_assets() -> None:
+    ui.add_head_html(
+        f'<script src="{PANGOZOOM_CDN_URL}"></script>',
+        shared=True,
+    )
+    ui.add_head_html(
+        """
+        <style>
+            .document-panzoom-host {
+                overflow: hidden;
+                touch-action: none;
+            }
+
+            .document-panzoom-surface {
+                width: 100%;
+                height: 100%;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+            }
+
+            .document-panzoom-media {
+                width: auto;
+                height: auto;
+                display: block;
+                max-width: none;
+                max-height: none;
+                user-select: none;
+                -webkit-user-drag: none;
+            }
+
+            .document-panzoom-iframe {
+                width: 100%;
+                height: 100%;
+                border: 0;
+                pointer-events: none;
+                background: white;
+            }
+        </style>
+        """,
+        shared=True,
+    )
+
+
+def _attach_panzoom(host_id: str) -> None:
+    ui.run_javascript(
+        f"""
+        (function() {{
+            if (!window.Panzoom) return;
+            window.__transcriptionPanzoom = window.__transcriptionPanzoom || {{}};
+            const host = document.getElementById({host_id!r});
+            if (!host) return;
+            const target = host.querySelector('[data-panzoom-target]');
+            const media = host.querySelector('[data-panzoom-media]');
+            if (!target) return;
+
+            const computeFitScale = () => {{
+                const hostRect = host.getBoundingClientRect();
+                if (hostRect.width <= 0 || hostRect.height <= 0) return 1;
+
+                if (media && media.tagName === 'IMG') {{
+                    if (media.naturalWidth <= 0 || media.naturalHeight <= 0) return 1;
+                    return Math.min(
+                        hostRect.width / media.naturalWidth,
+                        hostRect.height / media.naturalHeight
+                    );
+                }}
+
+                if (target.tagName === 'IFRAME') {{
+                    const targetRect = target.getBoundingClientRect();
+                    if (targetRect.width <= 0 || targetRect.height <= 0) return 1;
+                    return hostRect.height / targetRect.height;
+                }}
+
+                return 1;
+            }};
+
+            const initPanzoom = () => {{
+                if (window.__transcriptionPanzoom[{host_id!r}]) {{
+                    window.__transcriptionPanzoom[{host_id!r}].destroy();
+                }}
+
+                if (host.__transcriptionWheelHandler) {{
+                    host.removeEventListener('wheel', host.__transcriptionWheelHandler);
+                    host.__transcriptionWheelHandler = null;
+                }}
+
+                let fitScale = computeFitScale();
+
+                if (!Number.isFinite(fitScale) || fitScale <= 0) {{
+                    fitScale = 1;
+                }}
+
+                const startScale = fitScale;
+                const minScale = 0.01;
+                const instance = Panzoom(target, {{
+                    maxScale: 32,
+                    minScale: minScale,
+                    startScale: startScale,
+                    step: 0.18,
+                    contain: 'inside',
+                    roundPixels: true,
+                    overflow: 'hidden',
+                }});
+
+                window.__transcriptionPanzoom[{host_id!r}] = instance;
+
+                requestAnimationFrame(() => {{
+                    instance.reset({{ animate: false, force: true }});
+                    instance.setOptions({{ contain: undefined }});
+                }});
+
+                const wheelHandler = (event) => instance.zoomWithWheel(event);
+                host.__transcriptionWheelHandler = wheelHandler;
+                host.addEventListener('wheel', wheelHandler, {{ passive: false }});
+            }};
+
+            if (media && media.tagName === 'IMG' && !media.complete) {{
+                media.addEventListener('load', initPanzoom, {{ once: true }});
+                return;
+            }}
+
+            if ((media && media.tagName === 'IMG' && (host.clientWidth <= 0 || host.clientHeight <= 0)) ||
+                (target.tagName === 'IFRAME' && (host.clientWidth <= 0 || host.clientHeight <= 0))) {{
+                requestAnimationFrame(initPanzoom);
+                return;
+            }}
+
+            initPanzoom();
+        }})();
+        """
+    )
+
+
+def render_document_panzoom(*, document: Document, height: str = "640px") -> None:
+    """Render a document preview with pan and zoom interactions."""
+    _register_panzoom_assets()
+
+    host_id = f"document-panzoom-{uuid4().hex}"
+    document_url = _document_url(document)
+    document_kind = _document_kind(document)
+
+    with ui.card().classes("w-full bg-blue-grey-10 text-grey-1 q-pa-md"):
+        with ui.row().classes("w-full items-center justify-between q-gutter-sm"):
+            with ui.column().classes("q-gutter-none"):
+                ui.label("Document preview").classes("text-subtitle1 text-weight-medium")
+                ui.label(document.filename).classes("text-caption text-grey-4")
+
+            with ui.button_group().props("flat outline"):
+                ui.button(
+                    "Zoom In",
+                    icon="add",
+                    on_click=lambda: ui.run_javascript(f"window.__transcriptionPanzoom[{host_id!r}]?.zoomIn()"),
+                )
+                ui.button(
+                    "Zoom Out",
+                    icon="remove",
+                    on_click=lambda: ui.run_javascript(f"window.__transcriptionPanzoom[{host_id!r}]?.zoomOut()"),
+                )
+                ui.button(
+                    "Reset",
+                    icon="restart_alt",
+                    on_click=lambda: ui.run_javascript(f"window.__transcriptionPanzoom[{host_id!r}]?.reset()"),
+                )
+
+        ui.label("Scroll, pinch, or use the buttons to inspect the document.").classes(
+            "text-caption text-grey-4 q-mt-sm"
+        )
+
+        with (
+            ui.element("div")
+            .classes("w-full document-panzoom-host bg-blue-grey-9 rounded-borders q-mt-md")
+            .style(f"height: {height};") as host
+        ):
+            host.props(f"id={host_id}")
+            with ui.element("div").classes("document-panzoom-surface"):
+                if document_kind == "pdf":
+                    ui.html(
+                        f'<iframe class="document-panzoom-iframe" '
+                        f'src="{document_url}" title="{document.filename}" '
+                        "data-panzoom-target></iframe>"
+                    )
+                else:
+                    ui.html(
+                        f'<img class="document-panzoom-media" '
+                        f'src="{document_url}" alt="{document.filename}" '
+                        "data-panzoom-target data-panzoom-media />"
+                    )
+
+    _attach_panzoom(host_id)

src/transcription/ui/components/job_detail.py

@@ -2,11 +2,14 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
+
 from nicegui import ui
 
 from transcription.models import Document
 from transcription.models import Job
 from transcription.models import Transcript
+from transcription.ui.components.document_panzoom import render_document_panzoom
 
 
 def _status_chip_classes(status: str) -> str:
@@ -22,56 +25,61 @@ def _status_chip_classes(status: str) -> str:
 
 
 def _metadata_row(label: str, value: str) -> None:
-    with ui.row().classes("w-full items-start justify-between no-wrap q-gutter-x-md"):
+    with ui.row().classes("w-full items-start justify-between q-gutter-x-md"):
-        ui.label(label).classes("text-caption text-grey-7 text-uppercase")
+        ui.label(label).classes("text-caption text-grey-5 text-uppercase w-28")
-        ui.label(value).classes("text-body2 text-right")
+        ui.label(value).classes("text-body2 text-right text-grey-1 break-all")
 
 
 def _render_document_section(document: Document) -> None:
-    with ui.card().classes("w-full bg-grey-1 q-pa-md"):
+    with ui.card().classes("w-full bg-blue-grey-10 text-grey-1 q-pa-md"):
         ui.label("Document").classes("text-subtitle1 text-weight-medium")
-        ui.separator().classes("q-my-sm")
+        ui.separator().classes("q-my-sm bg-blue-grey-7")
         with ui.column().classes("w-full q-gutter-y-xs"):
             _metadata_row("Filename", document.filename)
             _metadata_row("File path", document.file_path)
 
+        ui.separator().classes("q-my-md bg-blue-grey-7")
+        render_document_panzoom(document=document)
 
-def _render_transcript_section(transcript: Transcript | None) -> None:
-    with ui.card().classes("w-full q-pa-md"):
-        ui.label("Transcript").classes("text-subtitle1 text-weight-medium")
-        ui.separator().classes("q-my-sm")
 
-        if transcript is None:
+def _render_transcript_section(transcripts: Sequence[Transcript]) -> None:
-            ui.label("Transcript not available yet.").classes("text-body2 text-grey-8")
+    with ui.card().classes("w-full bg-blue-grey-10 text-grey-1 q-pa-md"):
+        ui.label("Transcripts").classes("text-subtitle1 text-weight-medium")
+        ui.separator().classes("q-my-sm bg-blue-grey-7")
+
+        if not transcripts:
+            ui.label("Transcript history is not available yet.").classes("text-body2 text-grey-3")
             return
 
+        for transcript in transcripts:
             with ui.column().classes("w-full q-gutter-y-xs"):
+                _metadata_row("Revision", str(transcript.revision))
                 _metadata_row("Provider", transcript.provider)
                 _metadata_row("Prompt", transcript.prompt_name)
                 _metadata_row("Created", transcript.created_at.isoformat())
 
             if transcript.text:
-            ui.separator().classes("q-my-sm")
+                ui.separator().classes("q-my-sm bg-blue-grey-7")
-            with ui.card().classes("w-full bg-grey-1 q-pa-sm"):
+                with ui.card().classes("w-full bg-blue-grey-9 text-grey-1 q-pa-sm"):
-                ui.markdown(transcript.text)
+                    ui.markdown(transcript.text).classes("text-grey-1")
-            return
+            elif transcript.error_detail:
-
+                ui.separator().classes("q-my-sm bg-blue-grey-7")
-        if transcript.error_detail:
-            ui.separator().classes("q-my-sm")
                 with ui.card().classes("w-full bg-red-1 text-red-10 q-pa-sm"):
                     ui.label("Failure detail").classes("text-caption text-uppercase")
                     ui.label(transcript.error_detail).classes("text-body2")
 
+            ui.separator().classes("q-my-md bg-blue-grey-7")
 
-def render_job_detail(*, job: Job, document: Document | None, transcript: Transcript | None) -> None:
+
+def render_job_detail(*, job: Job, document: Document | None, transcripts: Sequence[Transcript]) -> None:
     """Render all sections for the job detail page."""
     status_text = job.status.value
     with ui.column().classes("w-full max-w-4xl q-gutter-md"):
-        with ui.card().classes("w-full q-pa-lg"):
+        with ui.card().classes("w-full bg-blue-grey-10 text-grey-1 q-pa-lg"):
             with ui.row().classes("w-full items-center justify-between q-gutter-md"):
                 with ui.column().classes("q-gutter-none"):
                     ui.label("Job overview").classes("text-h6 text-weight-bold")
-                    ui.label(str(job.id)).classes("text-caption text-grey-7")
+                    ui.label(str(job.id)).classes("text-caption text-grey-5")
                 status_chip_classes = (
                     "q-px-sm q-py-xs rounded-borders "
                     "text-weight-medium text-capitalize "
@@ -79,7 +87,7 @@ def render_job_detail(*, job: Job, document: Document | None, transcript: Transc
                 )
                 ui.label(status_text).classes(status_chip_classes)
 
-            ui.separator().classes("q-my-md")
+            ui.separator().classes("q-my-md bg-blue-grey-7")
             with ui.column().classes("w-full q-gutter-y-xs"):
                 _metadata_row("Created", job.created_at.isoformat())
                 _metadata_row("Updated", job.updated_at.isoformat())
@@ -88,4 +96,4 @@ def render_job_detail(*, job: Job, document: Document | None, transcript: Transc
         if document is not None:
             _render_document_section(document)
 
-        _render_transcript_section(transcript)
+        _render_transcript_section(transcripts)

src/transcription/ui/components/table/common.py

@@ -1,11 +1,14 @@
 """Common logic for generating table widgets."""
 
+import logging
 from collections.abc import Callable
 from typing import Any
 
 from nicegui import events
 from nicegui import ui
 
+logger = logging.getLogger(__name__)
+
 
 def _extract_row_id(args: Any) -> str | None:
     if isinstance(args, dict):
@@ -37,6 +40,7 @@ def _bind_row_click_handler(
         on_row_click_id(row_id)
 
     table.on("rowClick", handle_row_click)
+    logger.debug("Row click handler bound to table")
 
 
 def build_table(
@@ -63,6 +67,7 @@ def build_table(
         .classes(classes)
         .props('table-style="table-layout: fixed; width: 100%;"')
     )
+    logger.info("Table built with %d rows and %d columns", len(rows), len(columns))
     if on_row_click_id is not None:
         _bind_row_click_handler(table, on_row_click_id=on_row_click_id)
     return table

src/transcription/ui/pages/jobs_page.py

@@ -4,33 +4,31 @@ from __future__ import annotations
 
 from uuid import UUID
 
+from fastapi import Request
 from nicegui import ui
-from sqlalchemy.orm import selectinload
-from sqlmodel import desc
-from sqlmodel import select
 
-from transcription.db import get_session
+from transcription.app_state import resolve_session_factory
-from transcription.models import Document
+from transcription.services.jobs import JobService
-from transcription.models import Job
+from transcription.services.transcription import TranscriptionService
-from transcription.models import Transcript
+from transcription.ui.components.app_shell import render_navigation_header
-from transcription.ui.components.error_presenter import show_error
-from transcription.ui.components.error_presenter import summarize_error
 from transcription.ui.components.job_detail import render_job_detail
-from transcription.ui.components.table.jobs import JobTableRow
 from transcription.ui.components.table.jobs import render_jobs_table
 
+from ..components.table.jobs import JobTableRow
 
-async def fetch_job_rows() -> list[JobTableRow]:
+
-    """Return jobs for display in most-recent-first order."""
+def register_page() -> None:
-    async with get_session() as session:
+    """Register jobs list and detail routes."""
-        jobs = (
+
-            await session.exec(
+    @ui.page("/jobs")
-                select(Job)
+    async def jobs_page(request: Request) -> None:
-                .options(selectinload(Job.document))  # pyright: ignore[reportArgumentType]
+        session_factory = resolve_session_factory(request.app.state)
-                .order_by(desc(Job.created_at))
+        jobs_service = JobService(session_factory=session_factory)
-            )
+        render_navigation_header(current_path="/jobs")
-        ).all()
+
-        return [
+        @ui.refreshable
+        async def render_table() -> None:
+            jobs = [
                 JobTableRow(
                     id=job.id,
                     status=job.status.value,
@@ -39,50 +37,20 @@ async def fetch_job_rows() -> list[JobTableRow]:
                     created_at=job.created_at.isoformat(),
                     updated_at=job.updated_at.isoformat(),
                 )
-            for job in jobs
+                for job in await jobs_service.list_jobs()
             ]
-
-
-async def fetch_job_detail(job_id: UUID) -> tuple[Job | None, Document | None, Transcript | None]:
-    """Return job, document, and transcript for detail view."""
-    async with get_session() as session:
-        job = await session.get(Job, job_id)
-        if job is None:
-            return None, None, None
-        document = await session.get(Document, job.document_id)
-        transcript = (await session.exec(select(Transcript).where(Transcript.job_id == job.id))).first()
-        return job, document, transcript
-
-
-def register_page() -> None:
-    """Register jobs list and detail routes."""
-
-    @ui.page("/jobs")
-    async def jobs_page() -> None:
-        ui.label("Transcription Jobs")
-        status = ui.label("Ready")
-
-        @ui.refreshable
-        async def render_table() -> None:
-            jobs = await fetch_job_rows()
             render_jobs_table(jobs)
 
-        async def refresh() -> None:
+        ui.button("Refresh", on_click=render_table.refresh, icon="refresh")
-            status.text = "Refreshing..."
-            try:
-                await render_table.refresh()
-                status.text = "Refreshed"
-            except Exception as exc:  # noqa: BLE001
-                status.text = f"Refresh failed: {summarize_error(exc, operation='jobs.refresh')}"
-                show_error(exc, title="Jobs refresh failed", operation="jobs.refresh")
-
-        ui.button("Refresh", on_click=refresh)
         await render_table()
-        ui.link("Back to upload", "/upload")
 
     @ui.page("/jobs/{job_id}")
-    async def job_detail_page(job_id: str) -> None:
+    async def job_detail_page(job_id: str, request: Request) -> None:
-        ui.label("Job Detail")
+        session_factory = resolve_session_factory(request.app.state)
+        jobs_service = JobService(session_factory=session_factory)
+        transcription_service = TranscriptionService(session_factory=session_factory)
+        render_navigation_header(current_path="/jobs")
+        ui.button(icon="arrow_back", on_click=ui.navigate.back)
         try:
             parsed_id = UUID(job_id)
         except ValueError:
@@ -90,12 +58,14 @@ def register_page() -> None:
             ui.link("Back to jobs", "/jobs")
             return
 
-        job, document, transcript = await fetch_job_detail(parsed_id)
+        try:
-        if job is None:
+            job = await jobs_service.read_job(job_id=parsed_id)
+        except ValueError:
             ui.label("Job not found")
             ui.link("Back to jobs", "/jobs")
             return
 
-        render_job_detail(job=job, document=document, transcript=transcript)
+        transcripts = list(await transcription_service.list_transcripts_by_job(parsed_id))
+        render_job_detail(job=job, document=job.document, transcripts=transcripts)
 
         ui.link("Back to jobs", "/jobs")

src/transcription/ui/pages/upload_page.py

@@ -8,6 +8,7 @@ from nicegui import ui
 from transcription.app_state import resolve_session_factory
 from transcription.db import get_session
 from transcription.services.store import create_upload_job
+from transcription.ui.components.app_shell import render_navigation_header
 from transcription.ui.components.upload import render_upload_widget
 from transcription.worker import resolve_worker_notifier
 
@@ -17,6 +18,7 @@ def register_page() -> None:
 
     @ui.page("/upload", title="Upload Document")
     def upload_page(request: Request) -> None:
+        render_navigation_header(current_path="/upload")
         session_factory = resolve_session_factory(request.app.state)
 
         async def submit_upload(filename: str, file_bytes: bytes):
@@ -29,6 +31,3 @@ def register_page() -> None:
 
         notify_worker = resolve_worker_notifier(request.app.state)
         render_upload_widget(submitter=submit_upload, notifier=notify_worker)
-
-        with ui.row():
-            ui.link("View jobs", "/jobs")

src/transcription/ui/static/colors.css

@@ -0,0 +1,30 @@
+:root {
+	/* Soft blue-night palette tokens */
+	--ctp-rosewater: #f2dde5;
+	--ctp-flamingo: #edcfd8;
+	--ctp-pink: #dcc7de;
+	--ctp-mauve: #a9bde5;
+	--ctp-red: #d98a9a;
+	--ctp-maroon: #d39aa5;
+	--ctp-peach: #d7af8c;
+	--ctp-yellow: #e2c083;
+	--ctp-green: #86c8ad;
+	--ctp-teal: #77bfbe;
+	--ctp-sky: #7ebdda;
+	--ctp-sapphire: #74aed0;
+	--ctp-blue: #92b5f5;
+	--ctp-lavender: #6f97e8;
+	--ctp-text: #d8e2f5;
+	--ctp-subtext1: #bfcae0;
+	--ctp-subtext0: #a9b6cf;
+	--ctp-overlay2: #95a3bf;
+	--ctp-overlay1: #7c8ca9;
+	--ctp-overlay0: #657490;
+	--ctp-surface2: #4d5f7c;
+	--ctp-surface1: #394a65;
+	--ctp-surface0: #2a3954;
+	--ctp-base: #1f2b42;
+	--ctp-mantle: #1a2538;
+	--ctp-crust: #141e30;
+
+}

tests/ui/conftest.py

@@ -0,0 +1,79 @@
+"""Shared fixtures for UI integration tests."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from pathlib import Path
+from uuid import UUID
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from transcription.app import create_app
+from transcription.config import Settings
+from transcription.config import _settings
+from transcription.db import get_session
+from transcription.models import Document
+from transcription.models import Job
+from transcription.models import JobStatus
+from transcription.models import Transcript
+
+
+@pytest.fixture
+def app_client(tmp_path: Path) -> tuple[FastAPI, TestClient]:
+    """Provide a real application and test client backed by in-memory SQLite."""
+    settings = Settings(
+        openrouter_api_key="test-key",
+        database_url="sqlite:///:memory:",
+        environment="test",
+        upload_dir=tmp_path / "uploads",
+        prompt_dir=tmp_path / "prompts",
+    )
+    _settings.set(settings)
+
+    app = create_app()
+    with TestClient(app) as client:
+        yield app, client
+
+
+@pytest.fixture
+def seed_job(app_client: tuple[FastAPI, TestClient]) -> Callable[..., UUID]:
+    """Return a helper for inserting a document/job/transcript trio."""
+    app, _ = app_client
+
+    def _seed(
+        *,
+        filename: str = "sample.pdf",
+        status: JobStatus = JobStatus.TRANSCRIBED,
+        transcript_text: str | None = "Sample transcript text",
+        error_detail: str | None = None,
+    ) -> UUID:
+        async def _insert() -> UUID:
+            async with get_session(session_factory=app.state.runtime.session_factory) as session:
+                document = Document(filename=filename, file_path=f"uploads/{filename}")
+                session.add(document)
+                await session.flush()
+
+                job = Job(document_id=document.id, status=status, retry_count=0)
+                session.add(job)
+                await session.flush()
+
+                if transcript_text is not None or error_detail is not None:
+                    session.add(
+                        Transcript(
+                            job_id=job.id,
+                            provider="openrouter",
+                            prompt_name="transcribe_document",
+                            text=transcript_text,
+                            error_detail=error_detail,
+                        )
+                    )
+
+                await session.commit()
+                return job.id
+
+        return asyncio.run(_insert())
+
+    return _seed

tests/ui/test_jobs_page.py

@@ -1,11 +1,14 @@
 """Tests for the jobs page route."""
 
+from uuid import UUID
+
 import pytest
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
 
 from transcription.ui import register_pages
 from transcription.ui.pages import jobs_page
+from transcription.ui.pages.jobs_page import JobTableRow
 
 
 @pytest.fixture
@@ -13,7 +16,16 @@ def client(monkeypatch):
     """Provide a minimal app client with jobs data patched for rendering."""
 
     async def _fetch_jobs_stub():
-        return []
+        return [
+            JobTableRow(
+                id=UUID("00000000-0000-0000-0000-000000000001"),
+                status="queued",
+                filename="sample.pdf",
+                retry_count=2,
+                created_at="2026-01-01T12:00:00+00:00",
+                updated_at="2026-01-01T12:01:00+00:00",
+            )
+        ]
 
     monkeypatch.setattr(jobs_page, "fetch_jobs", _fetch_jobs_stub)
 
@@ -27,11 +39,15 @@ def client(monkeypatch):
 class TestPageRendering:
     """Verify the jobs page is available and includes the main controls."""
 
-    def test_jobs_page_renders_expected_controls(self, client):
+    def test_jobs_page_renders_expected_controls(self, client, monkeypatch):
         """GET /ui/jobs returns the page shell and jobs controls."""
         response = client.get("/ui/jobs")
 
+        async def _fetch_jobs_empty():
+            return []
+
+        monkeypatch.setattr(jobs_page, "fetch_jobs", _fetch_jobs_empty)
+        response = client.get("/ui/jobs")
+
         assert response.status_code == 200
-        assert "Transcription Jobs" in response.text
+        assert "No jobs yet." in response.text
-        assert "Refresh" in response.text
-        assert "Back to upload" in response.text

tests/ui/test_pages_registration.py

@@ -25,8 +25,9 @@ class TestPageRegistration:
             *,
             mount_path: str,
             show_welcome_message: bool,
+            dark: bool,
         ) -> None:
-            calls.append(f"run_with:{mount_path}:{show_welcome_message}")
+            calls.append(f"run_with:{mount_path}:{show_welcome_message}:{dark}")
 
         monkeypatch.setattr("transcription.ui.register_upload_page", _record_upload)
         monkeypatch.setattr("transcription.ui.register_jobs_page", _record_jobs)
@@ -35,4 +36,4 @@ class TestPageRegistration:
         app = FastAPI()
         register_pages(app)
 
-        assert calls == ["upload", "jobs", "run_with:/ui:False"]
+        assert calls == ["upload", "jobs", "run_with:/ui:False:True"]

tests/ui/test_upload_page.py

@@ -52,4 +52,4 @@ class TestPageRendering:
         assert response.status_code == 200
         assert "Upload Document" in response.text
         assert "Select document file" in response.text
-        assert "View jobs" in response.text
+        assert "Jobs" in response.text