deeptutor-reading 1.7.0__py3-none-any.whl

deeptutor/api/routers/reading.py

@@ -0,0 +1,1572 @@
+"""Immersive reading API — materials, unit text, annotations, export.
+
+A thin adapter over :mod:`deeptutor.reading`: it validates HTTP inputs, maps
+engine errors to status codes, and streams bytes. No reading logic lives here,
+so the router and the capability's tools cannot drift apart — both call the same
+service functions.
+
+Per-user isolation comes from the path service, exactly as for notebooks: the
+store resolves ``<user workspace>/reading`` at call time, so a request already
+scoped to a user by the auth dependency reaches only that user's materials.
+
+The raw-file route returns a ``FileResponse``, which serves HTTP Range requests.
+That matters: it is what lets pdf.js load a large PDF incrementally instead of
+pulling the whole file before rendering page one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+from pathlib import Path
+import shutil
+import tempfile
+from typing import Any, Literal
+from urllib.parse import quote
+import uuid
+
+from fastapi import APIRouter, BackgroundTasks, HTTPException, Query, UploadFile
+from fastapi.params import File
+from fastapi.responses import FileResponse, Response
+from pydantic import BaseModel, Field, model_validator
+
+from deeptutor.learning.storage import LearningStore
+from deeptutor.multi_user.learning_access import (
+    assert_learning_material,
+    assert_learning_material_mutation,
+    current_learning_policy,
+)
+from deeptutor.reading import (
+    ANNOTATION_COLORS,
+    Annotation,
+    IngestionStatus,
+    MaterialNotFound,
+    ReadingCatalogStore,
+    ReadingError,
+    ReadingPosition,
+    ReadingStore,
+    ReadingUpgradeConflict,
+    SourceKind,
+    export_material,
+    render_outline,
+)
+from deeptutor.reading.captions import caption_material_media, captions_enabled
+from deeptutor.reading.ingestion import (
+    MAX_TRANSCRIPT_BYTES,
+    ReadingIngestionService,
+    url_material_id,
+)
+from deeptutor.reading.knowledge_capture import (
+    organize_workspace_notes,
+    send_workspace_to_notebook,
+)
+from deeptutor.reading.models import MAX_TEXT_SELECTOR_CHARS
+from deeptutor.services.session.workspace_preferences import WORKSPACE_MODE_READING
+from deeptutor.utils.document_validator import DocumentValidator
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Streaming upload ceiling. Same number the extractor enforces, so a file that
+# passes here cannot then be rejected deeper in with a less helpful message.
+MAX_MATERIAL_BYTES = DocumentValidator.MAX_FILE_SIZE
+_UPLOAD_CHUNK = 1024 * 1024
+_MEDIA_EXTENSIONS = {
+    ".mp4",
+    ".mov",
+    ".mkv",
+    ".webm",
+    ".m4v",
+    ".mp3",
+    ".m4a",
+    ".wav",
+    ".aac",
+    ".ogg",
+    ".flac",
+}
+
+
+def _store() -> ReadingStore:
+    return ReadingStore()
+
+
+def _record_reading_position(material_id: str, *, locator: int, percentage: float) -> None:
+    LearningStore().record_reading_position(
+        material_id,
+        locator=locator,
+        percentage=percentage,
+    )
+
+
+def _catalog() -> ReadingCatalogStore:
+    return ReadingCatalogStore()
+
+
+def _ingestion() -> ReadingIngestionService:
+    catalog = _catalog()
+    return ReadingIngestionService(ReadingStore(catalog.root), catalog)
+
+
+def _new_material_id() -> str:
+    return f"rm_{uuid.uuid4().hex[:12]}"
+
+
+def _schedule_media_captions(
+    background_tasks: BackgroundTasks, store: ReadingStore, material_id: str
+) -> None:
+    """Best-effort: caption a material's embedded figures after ingest.
+
+    The vision model writes one sentence per image back into the store's media
+    index so a text-only model can still describe every figure in the book.
+    This must never affect the upload result or the ingest status, so any
+    failure is only logged.
+    """
+    if not captions_enabled():
+        return
+    background_tasks.add_task(_caption_material_best_effort, store, material_id)
+
+
+async def _caption_material_best_effort(store: ReadingStore, material_id: str) -> None:
+    """Run the caption pass without ever letting an error escape."""
+    if not captions_enabled():
+        return
+    try:
+        await caption_material_media(material_id, store=store)
+    except Exception:  # noqa: BLE001 - captioning is best-effort
+        logger.warning("Image captioning failed for %s", material_id, exc_info=True)
+
+
+def _content_facts(store: ReadingStore, record: Any) -> tuple[int, int]:
+    """Stored size and extracted unit count, or zeros while still processing."""
+    if getattr(record.status, "value", record.status) != "ready":
+        return 0, 0
+    try:
+        manifest = store.manifest(record.material_id)
+    except Exception:  # noqa: BLE001 - a missing manifest is a zero, not a 500
+        return 0, 0
+    return int(manifest.byte_size), int(manifest.unit_count)
+
+
+def _http_error(exc: Exception) -> HTTPException:
+    """Map an engine error to the status code that describes it.
+
+    404 for "no such material", 400 for everything the caller can fix (bad
+    locator, unsupported format, no extractable text). A 500 is reserved for
+    failures that are genuinely ours.
+    """
+    if isinstance(exc, PermissionError):
+        return HTTPException(status_code=403, detail=str(exc))
+    if isinstance(exc, MaterialNotFound):
+        return HTTPException(status_code=404, detail=str(exc))
+    if isinstance(exc, ReadingUpgradeConflict):
+        return HTTPException(status_code=409, detail=str(exc))
+    if isinstance(exc, ReadingError):
+        return HTTPException(status_code=400, detail=str(exc))
+    logger.warning("unexpected reading error", exc_info=True)
+    return HTTPException(status_code=500, detail="The reader could not complete that request.")
+
+
+def _assigned_material_ids() -> set[str] | None:
+    """Return the account allowlist, or ``None`` for unrestricted accounts."""
+    policy = current_learning_policy()
+    if policy is None:
+        return None
+    reading = policy.get("reading")
+    if not isinstance(reading, dict):
+        return {"*"}
+    assigned = set(reading.get("material_ids") or [])
+    return None if "*" in assigned else assigned
+
+
+def _material_allowed(material_id: str) -> bool:
+    assigned = _assigned_material_ids()
+    return assigned is None or material_id in assigned
+
+
+def _enforce_learning_materials(*material_ids: str) -> None:
+    for material_id in material_ids:
+        if material_id:
+            assert_learning_material(material_id)
+
+
+def _workspace_payload(row: Any) -> dict[str, Any]:
+    """Hide tabs that are no longer assigned to a learning account."""
+    payload = row.to_dict()
+    assigned = _assigned_material_ids()
+    if assigned is None:
+        return payload
+    payload["tabs"] = [
+        tab
+        for tab in payload.get("tabs", [])
+        if tab.get("material", {}).get("material_id") in assigned
+    ]
+    if payload.get("active_material_id") not in assigned:
+        payload["active_material_id"] = None
+    return payload
+
+
+# === Models ===================================================================
+
+
+class MaterialInfo(BaseModel):
+    material_id: str
+    filename: str
+    unit: str
+    unit_count: int
+    mime: str = ""
+    title: str = ""
+    byte_size: int = 0
+    char_count: int = 0
+    created_at: float = 0.0
+    has_raw_view: bool = False
+    render_mode: Literal["text", "pdf", "epub", "video", "audio"] = "text"
+    extractor: str = ""
+    content_format: Literal["plain_text", "web_markdown"] = "plain_text"
+    source_type: str = "upload"
+    source_url: str = ""
+    revision: int = 1
+    annotation_count: int = 0
+
+
+class MaterialDetail(MaterialInfo):
+    outline: list[dict[str, Any]] = Field(default_factory=list)
+    outline_text: str = ""
+    unit_refs: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class UnitText(BaseModel):
+    locator: int
+    unit: str
+    text: str
+
+
+class TextQuoteSelectorPayload(BaseModel):
+    type: Literal["TextQuoteSelector"]
+    exact: str = Field(min_length=1, max_length=2000)
+    prefix: str = Field(default="", max_length=128)
+    suffix: str = Field(default="", max_length=128)
+
+
+class TextPositionSelectorPayload(BaseModel):
+    type: Literal["TextPositionSelector"]
+    start: int = Field(ge=0)
+    end: int = Field(gt=0)
+
+    @model_validator(mode="after")
+    def ordered(self) -> "TextPositionSelectorPayload":
+        if self.end <= self.start:
+            raise ValueError("selector end must be greater than start")
+        if self.end - self.start > MAX_TEXT_SELECTOR_CHARS:
+            raise ValueError(f"selector span must not exceed {MAX_TEXT_SELECTOR_CHARS} characters")
+        return self
+
+
+class AnnotationPayload(BaseModel):
+    """An annotation as the reader sends it.
+
+    ``rects`` are normalised to the unit box (0..1, origin top-left) by the
+    client, because only the client knows the rendered geometry. They are still
+    re-validated server-side — an inverted or out-of-range rectangle is ordered
+    and clipped rather than trusted.
+    """
+
+    annotation_id: str = ""
+    locator: int = Field(ge=1)
+    kind: Literal["highlight", "underline", "note", "citation"] = "highlight"
+    color: str = "yellow"
+    quote: str = Field(default="", max_length=2000)
+    note: str = ""
+    rects: list[list[float]] = Field(default_factory=list)
+    source_anchor: str = Field(default="", max_length=4096)
+    selectors: list[TextQuoteSelectorPayload | TextPositionSelectorPayload] = Field(
+        default_factory=list,
+        max_length=2,
+    )
+
+    def to_annotation(self) -> Annotation:
+        return Annotation.from_dict(
+            {
+                "annotation_id": self.annotation_id,
+                "locator": self.locator,
+                "kind": self.kind,
+                "color": self.color if self.color in ANNOTATION_COLORS else "yellow",
+                "quote": self.quote,
+                "note": self.note,
+                "rects": self.rects,
+                "source_anchor": self.source_anchor,
+                "selectors": [selector.model_dump() for selector in self.selectors],
+                "author": "user",
+            }
+        )
+
+
+class AnnotationInfo(BaseModel):
+    annotation_id: str
+    locator: int
+    material_revision: int = 1
+    kind: str
+    color: str
+    quote: str
+    note: str
+    rects: list[list[float]]
+    source_anchor: str = ""
+    selectors: list[dict[str, Any]] = Field(default_factory=list)
+    author: str
+    created_at: float
+    updated_at: float
+
+
+class PositionPayload(BaseModel):
+    locator: int = Field(ge=1)
+    source_anchor: str = Field(default="", max_length=4096)
+    percentage: float | None = Field(default=None, ge=0.0, le=1.0)
+
+
+class PositionInfo(PositionPayload):
+    percentage: float = 0.0
+    updated_at: float = 0.0
+
+
+class BookmarkPayload(BaseModel):
+    locator: int = Field(ge=1)
+    label: str = Field(default="", max_length=200)
+    source_anchor: str = Field(default="", max_length=4096)
+
+
+class BookmarkInfo(BookmarkPayload):
+    bookmark_id: str
+    created_at: float = 0.0
+
+
+class BookmarkList(BaseModel):
+    bookmarks: list[BookmarkInfo]
+
+
+class SupportedFormats(BaseModel):
+    extensions: list[str]
+    max_bytes: int
+    raw_view_extensions: list[str]
+
+
+class EpubPairingRequest(BaseModel):
+    english_material_id: str
+    chinese_material_id: str
+
+
+class UrlImportRequest(BaseModel):
+    urls: list[str] = Field(min_length=1, max_length=50)
+    workspace_id: str = ""
+    workspace_title: str = ""
+
+
+class ZimArticleImportRequest(BaseModel):
+    kb_ref: str = Field(min_length=1, max_length=300)
+    article_path: str = Field(min_length=1, max_length=2048)
+    title: str = Field(default="", max_length=300)
+    workspace_id: str = ""
+
+
+class WorkspaceCreateRequest(BaseModel):
+    title: str = Field(default="Untitled collection", max_length=300)
+    description: str = Field(default="", max_length=2000)
+    color: str = Field(default="", max_length=32)
+    material_ids: list[str] = Field(default_factory=list, max_length=100)
+
+
+class WorkspaceUpdateRequest(BaseModel):
+    title: str | None = Field(default=None, max_length=300)
+    description: str | None = Field(default=None, max_length=2000)
+    color: str | None = Field(default=None, max_length=32)
+
+
+class WorkspaceMaterialRequest(BaseModel):
+    material_id: str
+    make_active: bool = False
+
+
+class WorkspaceReorderRequest(BaseModel):
+    material_ids: list[str] = Field(min_length=1, max_length=100)
+
+
+class ReadingSessionCreateRequest(BaseModel):
+    title: str = Field(default="New reading conversation", max_length=100)
+    active_material_id: str = ""
+
+
+class ReadingSessionRenameRequest(BaseModel):
+    title: str = Field(min_length=1, max_length=100)
+
+
+class ReadingSessionLinkRequest(BaseModel):
+    target_session_id: str
+
+
+class DuplicateFileQuery(BaseModel):
+    filename: str = Field(default="", max_length=512)
+    # sha256(bytes)[:16], computed by the browser with the store's algorithm.
+    content_id: str = Field(default="", max_length=64)
+    size_bytes: int = 0
+    mime: str = Field(default="", max_length=128)
+
+
+class DuplicateCheckRequest(BaseModel):
+    files: list[DuplicateFileQuery] = Field(default_factory=list, max_length=50)
+    urls: list[str] = Field(default_factory=list, max_length=50)
+
+
+class OrganizeNotesRequest(BaseModel):
+    material_ids: list[str] = Field(default_factory=list, max_length=100)
+
+
+class NotebookCaptureRequest(OrganizeNotesRequest):
+    notebook_ids: list[str] = Field(min_length=1, max_length=20)
+    title: str = Field(default="", max_length=300)
+    summary: str = Field(default="", max_length=1000)
+
+
+# === Routes ===================================================================
+
+
+@router.get("/library/materials")
+async def list_library_materials(
+    search: str = Query(default="", max_length=200),
+    status: Literal["queued", "processing", "ready", "failed"] | None = None,
+    library_filter: Literal["all", "unassigned", "processing", "failed"] = Query(
+        default="all", alias="filter"
+    ),
+) -> dict[str, Any]:
+    """Every material the owner has, with the collections holding each one.
+
+    Membership travels with the row because the library view exists to answer
+    "where is this used, and what did I upload that is used nowhere" — a
+    question the client cannot ask one material at a time.
+    """
+    catalog = _catalog()
+    store = _store()
+    try:
+        for manifest in store.list_materials():
+            if catalog.get_material(manifest.material_id) is None:
+                catalog.register_manifest(manifest)
+        rows = [
+            row
+            for row in catalog.list_materials(
+                search=search, status=status, library_filter=library_filter
+            )
+            if _material_allowed(row.material_id)
+        ]
+        membership = catalog.collections_for_materials([row.material_id for row in rows])
+        from deeptutor.services.session import get_sqlite_session_store
+
+        reward_totals = await get_sqlite_session_store().reading_quiz_reward_totals(
+            [row.material_id for row in rows]
+        )
+        materials: list[dict[str, Any]] = []
+        for row in rows:
+            payload = row.to_dict()
+            payload["collections"] = membership.get(row.material_id, [])
+            size_bytes, unit_count = _content_facts(store, row)
+            payload["size_bytes"] = size_bytes
+            payload["unit_count"] = unit_count
+            payload["quiz_stars"] = reward_totals.get(row.material_id, 0)
+            materials.append(payload)
+        # Counts describe every material this account may see, not only the
+        # filtered page and never revoked or unassigned learner material.
+        assigned = _assigned_material_ids()
+        return {
+            "materials": materials,
+            "counts": catalog.library_counts(None if assigned is None else sorted(assigned)),
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/library/duplicate-check")
+async def duplicate_check(payload: DuplicateCheckRequest) -> dict[str, Any]:
+    """Say what the library already holds, before anything is uploaded.
+
+    Identical bytes are answered from the content id the browser computed;
+    a same-name-different-content upload is the genuinely ambiguous case and
+    is reported separately so the client can ask instead of guessing.
+    """
+    catalog = _catalog()
+    store = _store()
+
+    def described(record: Any) -> dict[str, Any]:
+        """The match, with the facts that let a user tell two copies apart."""
+        payload_row = record.to_dict()
+        size_bytes, unit_count = _content_facts(store, record)
+        payload_row["size_bytes"] = size_bytes
+        payload_row["unit_count"] = unit_count
+        return payload_row
+
+    try:
+        matches: list[dict[str, Any]] = []
+        for item in payload.files:
+            kind = "same_content"
+            record = catalog.find_material_by_content(item.content_id) if item.content_id else None
+            if record is None and item.filename:
+                record = catalog.find_ready_material_by_filename(item.filename, mime=item.mime)
+                kind = "same_name"
+            if record is None or not _material_allowed(record.material_id):
+                continue
+            matches.append(
+                {
+                    "query": {"filename": item.filename, "url": ""},
+                    "kind": kind,
+                    "material": described(record),
+                    "collections": catalog.collections_for_material(record.material_id),
+                }
+            )
+        for url in payload.urls:
+            try:
+                material_id = url_material_id(url)
+            except Exception:  # noqa: BLE001 - a malformed URL is simply not a match
+                continue
+            record = catalog.get_material(material_id)
+            if record is None or not _material_allowed(record.material_id):
+                continue
+            matches.append(
+                {
+                    "query": {"filename": "", "url": url},
+                    "kind": "same_content",
+                    "material": described(record),
+                    "collections": catalog.collections_for_material(record.material_id),
+                }
+            )
+        return {"matches": matches}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/library/import-urls", status_code=202)
+async def import_urls(
+    payload: UrlImportRequest, background_tasks: BackgroundTasks
+) -> dict[str, Any]:
+    """Queue safe webpage, YouTube, or Bilibili imports into a workspace."""
+    try:
+        assert_learning_material("", upload=True)
+    except PermissionError as exc:
+        raise _http_error(exc) from exc
+    service = _ingestion()
+    try:
+        materials = [service.queue_url(url) for url in payload.urls]
+        workspace_id = payload.workspace_id.strip()
+        if workspace_id:
+            for material in materials:
+                service.catalog.add_material(workspace_id, material.material_id)
+            workspace = service.catalog.get_workspace(workspace_id)
+        else:
+            # Naming the collection after its first material is what keeps a
+            # library from filling up with rows all called "Imported reading".
+            workspace = service.catalog.create_workspace(
+                payload.workspace_title
+                or (materials[0].title if materials else "Reading collection"),
+                [row.material_id for row in materials],
+            )
+        for material in materials:
+            background_tasks.add_task(service.process_url, material.material_id)
+        return {
+            "materials": [row.to_dict() for row in materials],
+            "workspace": workspace.to_dict() if workspace else None,
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/library/import-zim-article")
+async def import_zim_article(payload: ZimArticleImportRequest) -> dict[str, Any]:
+    """Open one selected Kiwix article in Immersive Reading.
+
+    Only its bounded text snapshot enters the reading store.  The ZIM archive
+    stays on the existing kiwix-serve instance, without bulk extraction.
+    """
+    from deeptutor.multi_user.knowledge_access import manager_for_resource, resolve_kb
+    from deeptutor.reading.catalog_models import IngestionStatus, SourceKind
+    from deeptutor.reading.extract import split_markdown_by_headings
+    from deeptutor.services.rag.pipelines.kiwix.client import (
+        KiwixClient,
+        KiwixError,
+        validate_article_path,
+    )
+    from deeptutor.services.workspace.knowledge import library_request
+
+    try:
+        assert_learning_material("", upload=True)
+        # Knowledge Center browses the account library outside the current
+        # conversation's selected KB list. Resolve the source with that same
+        # access scope, then restore the Reading workspace for storage.
+        token = library_request.set(True)
+        try:
+            resource = resolve_kb(payload.kb_ref)
+            entry = manager_for_resource(resource).get_metadata(resource.name)
+        finally:
+            library_request.reset(token)
+        if not isinstance(entry, dict) or entry.get("type") != "kiwix":
+            raise ReadingError("Select a connected Kiwix knowledge base.")
+        path = validate_article_path(payload.article_path)
+        client = KiwixClient(entry["server_url"], entry["zim_name"])
+        text = await client.read_article(path)
+        units, outline = split_markdown_by_headings(text)
+        if not units:
+            raise ReadingError("The selected ZIM article has no readable text.")
+        title = payload.title.strip() or path.rsplit("/", 1)[-1].replace("_", " ")
+        material_id = hashlib.sha256(f"{resource.id}\0{path}".encode()).hexdigest()[:16]
+        catalog = _catalog()
+        store = ReadingStore(catalog.root)
+        source_url = f"{client.base_url}/content/{client.zim_name}/" + "/".join(
+            quote(segment, safe="") for segment in path.split("/")
+        )
+        store.ingest_units(
+            material_id,
+            filename=f"{title[:150]}.md",
+            units=units,
+            unit="section",
+            title=title,
+            mime="text/markdown",
+            extractor="kiwix-article",
+            content_format="plain_text",
+            source_type="zim_article",
+            source_url=source_url,
+            outline=outline or None,
+        )
+        material = catalog.upsert_material(
+            content_id=material_id,
+            material_id=material_id,
+            filename=f"{title[:150]}.md",
+            title=title,
+            source_kind=SourceKind.WEB,
+            source_url=source_url,
+            mime="text/markdown",
+            render_mode="text",
+            status=IngestionStatus.READY,
+        )
+        if payload.workspace_id.strip():
+            catalog.add_material(payload.workspace_id.strip(), material_id)
+            workspace = catalog.get_workspace(payload.workspace_id.strip())
+        else:
+            workspace = catalog.create_workspace(title, [material_id])
+        return {
+            "material": material.to_dict(),
+            "workspace": workspace.to_dict() if workspace else None,
+        }
+    except HTTPException:
+        raise
+    except (KiwixError, KeyError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/materials/{material_id}/retry", status_code=202)
+async def retry_import(material_id: str, background_tasks: BackgroundTasks) -> dict[str, Any]:
+    service = _ingestion()
+    try:
+        assert_learning_material(material_id)
+        material = service.catalog.get_material(material_id)
+        if material is None:
+            raise MaterialNotFound(f"material {material_id!r} not found")
+        service.catalog.update_material_status(material_id, "queued", progress=0)
+        background_tasks.add_task(service.retry, material_id)
+        return {"material": service.catalog.get_material(material_id).to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/workspaces")
+async def list_workspaces(
+    search: str = Query(default="", max_length=200),
+) -> dict[str, Any]:
+    try:
+        rows = _catalog().list_workspaces(search=search)
+        return {"workspaces": [_workspace_payload(row) for row in rows]}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/workspaces/index")
+async def list_workspace_index() -> dict[str, Any]:
+    """Just enough to *name* a collection: id and title.
+
+    The sidebar groups reading conversations under their collection and
+    refreshes on every stream end. ``/workspaces`` answers with each
+    collection's whole tab list — every material, its cover, its unit
+    count — none of which a group heading renders.
+
+    Declared above ``/workspaces/{workspace_id}``: that route matches any
+    single segment, so a literal path below it would never be reached.
+    """
+    try:
+        return {
+            "collections": [
+                {"workspace_id": row.workspace_id, "title": row.title}
+                for row in _catalog().list_workspaces()
+            ]
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/workspaces", status_code=201)
+async def create_workspace(payload: WorkspaceCreateRequest) -> dict[str, Any]:
+    try:
+        _enforce_learning_materials(*payload.material_ids)
+        row = _catalog().create_workspace(
+            payload.title,
+            payload.material_ids,
+            description=payload.description,
+            color=payload.color,
+        )
+        return {"workspace": row.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/workspaces/{workspace_id}")
+async def get_workspace(workspace_id: str) -> dict[str, Any]:
+    try:
+        catalog = _catalog()
+        row = catalog.get_workspace(workspace_id)
+        if row is None:
+            raise MaterialNotFound(f"reading workspace {workspace_id!r} not found")
+        return {
+            "workspace": _workspace_payload(row),
+            "sessions": [session.to_dict() for session in catalog.list_sessions(workspace_id)],
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/workspaces/{workspace_id}/ask-hint")
+async def get_workspace_ask_hint(
+    workspace_id: str,
+    session_id: str = "",
+    locator: int | None = None,
+    selection: str = "",
+) -> dict[str, Any]:
+    """One question the learner could ask about their current reading context."""
+    from deeptutor.services.reading_hints import get_ask_hint
+
+    return await get_ask_hint(workspace_id, session_id, locator, selection)
+
+
+@router.patch("/workspaces/{workspace_id}")
+async def update_workspace(workspace_id: str, payload: WorkspaceUpdateRequest) -> dict[str, Any]:
+    try:
+        row = _catalog().update_workspace(
+            workspace_id,
+            title=payload.title,
+            description=payload.description,
+            color=payload.color,
+        )
+        return {"workspace": row.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.delete("/workspaces/{workspace_id}")
+async def delete_workspace(workspace_id: str) -> dict[str, Any]:
+    from deeptutor.services.session import get_session_store
+
+    try:
+        catalog = _catalog()
+        sessions = catalog.list_sessions(workspace_id)
+        if not catalog.delete_workspace(workspace_id):
+            raise MaterialNotFound(f"reading workspace {workspace_id!r} not found")
+        session_store = get_session_store()
+        for session in sessions:
+            await session_store.delete_session(session.session_id)
+        return {"status": "ok", "workspace_id": workspace_id}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/workspaces/{workspace_id}/materials")
+async def add_workspace_material(
+    workspace_id: str, payload: WorkspaceMaterialRequest
+) -> dict[str, Any]:
+    try:
+        assert_learning_material(payload.material_id)
+        row = _catalog().add_material(
+            workspace_id, payload.material_id, make_active=payload.make_active
+        )
+        return {"workspace": row.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.put("/workspaces/{workspace_id}/materials/order")
+async def reorder_workspace_materials(
+    workspace_id: str, payload: WorkspaceReorderRequest
+) -> dict[str, Any]:
+    try:
+        _enforce_learning_materials(*payload.material_ids)
+        row = _catalog().reorder_materials(workspace_id, payload.material_ids)
+        return {"workspace": row.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.put("/workspaces/{workspace_id}/materials/{material_id}/active")
+async def activate_workspace_material(workspace_id: str, material_id: str) -> dict[str, Any]:
+    try:
+        assert_learning_material(material_id)
+        row = _catalog().set_active_material(workspace_id, material_id)
+        return {"workspace": row.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.delete("/workspaces/{workspace_id}/materials/{material_id}")
+async def remove_workspace_material(workspace_id: str, material_id: str) -> dict[str, Any]:
+    try:
+        assert_learning_material(material_id)
+        row = _catalog().remove_material(workspace_id, material_id)
+        return {"workspace": row.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/workspaces/{workspace_id}/sessions")
+async def list_reading_sessions(workspace_id: str) -> dict[str, Any]:
+    from deeptutor.services.session import get_session_store
+
+    try:
+        catalog = _catalog()
+        rows = catalog.list_sessions(workspace_id)
+        # The catalog stores the title a conversation was attached with, which
+        # is the placeholder every conversation starts life as: the real name
+        # is written by the title model *after* that first turn finishes, into
+        # the session store. Read it from there so the reader sees the same
+        # name the sidebar does instead of a list of "New conversation".
+        titles: dict[str, str] = {}
+        try:
+            summaries = await get_session_store().get_session_summaries(
+                [row.session_id for row in rows]
+            )
+            titles = {
+                str(summary.get("session_id") or summary.get("id") or ""): str(
+                    summary.get("title") or ""
+                )
+                for summary in summaries
+            }
+        except Exception:
+            logger.debug("reading sessions: live titles unavailable", exc_info=True)
+        return {
+            "sessions": [
+                row.to_dict()
+                | {
+                    "title": titles.get(row.session_id) or row.title,
+                    "linked_session_ids": catalog.list_session_links(workspace_id, row.session_id),
+                }
+                for row in rows
+            ]
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/workspaces/{workspace_id}/sessions", status_code=201)
+async def create_reading_session(
+    workspace_id: str, payload: ReadingSessionCreateRequest
+) -> dict[str, Any]:
+    from deeptutor.services.session import get_session_store
+
+    catalog = _catalog()
+    try:
+        if payload.active_material_id:
+            assert_learning_material(payload.active_material_id)
+        workspace = catalog.get_workspace(workspace_id)
+        if workspace is None:
+            raise MaterialNotFound(f"reading workspace {workspace_id!r} not found")
+        active_material_id = payload.active_material_id or workspace.active_material_id
+        if active_material_id and active_material_id not in {
+            tab.material.material_id for tab in workspace.tabs
+        }:
+            raise ReadingError("active material does not belong to this reading workspace")
+        session_store = get_session_store()
+        session = await session_store.create_session(title=payload.title)
+        await session_store.update_session_preferences(
+            session["id"],
+            {
+                "capability": "immersive_reading",
+                "workspace_mode": WORKSPACE_MODE_READING,
+                "session_kind": "immersive_reading",
+                "reading_workspace_id": workspace_id,
+                "reading_material_id": active_material_id or "",
+            },
+        )
+        reading_session = catalog.attach_session(
+            workspace_id,
+            session["id"],
+            title=payload.title,
+            active_material_id=active_material_id,
+        )
+        return {"session": reading_session.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.patch("/workspaces/{workspace_id}/sessions/{session_id}")
+async def rename_reading_session(
+    workspace_id: str, session_id: str, payload: ReadingSessionRenameRequest
+) -> dict[str, Any]:
+    from deeptutor.services.session import get_session_store
+
+    try:
+        catalog = _catalog()
+        row = catalog.rename_session(workspace_id, session_id, payload.title)
+        await get_session_store().update_session_title(session_id, payload.title)
+        return {"session": row.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.delete("/workspaces/{workspace_id}/sessions/{session_id}")
+async def delete_reading_session(workspace_id: str, session_id: str) -> dict[str, Any]:
+    from deeptutor.services.session import get_session_store
+
+    try:
+        catalog = _catalog()
+        if not catalog.detach_session(workspace_id, session_id):
+            raise MaterialNotFound("reading session not found")
+        await get_session_store().delete_session(session_id)
+        return {"status": "ok", "session_id": session_id}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/workspaces/{workspace_id}/sessions/{session_id}/links")
+async def link_reading_session(
+    workspace_id: str, session_id: str, payload: ReadingSessionLinkRequest
+) -> dict[str, Any]:
+    try:
+        catalog = _catalog()
+        catalog.link_session(workspace_id, session_id, payload.target_session_id)
+        return {
+            "session_id": session_id,
+            "linked_session_ids": catalog.list_session_links(workspace_id, session_id),
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.delete("/workspaces/{workspace_id}/sessions/{session_id}/links/{target_session_id}")
+async def unlink_reading_session(
+    workspace_id: str, session_id: str, target_session_id: str
+) -> dict[str, Any]:
+    try:
+        catalog = _catalog()
+        catalog.unlink_session(workspace_id, session_id, target_session_id)
+        return {
+            "session_id": session_id,
+            "linked_session_ids": catalog.list_session_links(workspace_id, session_id),
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/workspaces/{workspace_id}/notes/organize")
+async def organize_reading_notes(
+    workspace_id: str, payload: OrganizeNotesRequest
+) -> dict[str, Any]:
+    try:
+        _enforce_learning_materials(*payload.material_ids)
+        catalog = _catalog()
+        notes = await asyncio.to_thread(
+            organize_workspace_notes,
+            workspace_id,
+            material_ids=payload.material_ids,
+            catalog=catalog,
+            reading_store=ReadingStore(catalog.root),
+        )
+        return {"notes": notes.to_dict()}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/workspaces/{workspace_id}/notebook")
+async def capture_reading_to_notebook(
+    workspace_id: str, payload: NotebookCaptureRequest
+) -> dict[str, Any]:
+    try:
+        _enforce_learning_materials(*payload.material_ids)
+        catalog = _catalog()
+        result = await asyncio.to_thread(
+            send_workspace_to_notebook,
+            workspace_id,
+            payload.notebook_ids,
+            material_ids=payload.material_ids,
+            title=payload.title,
+            summary=payload.summary,
+            catalog=catalog,
+            reading_store=ReadingStore(catalog.root),
+        )
+        return {"success": True, **result}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/supported-formats", response_model=SupportedFormats)
+async def supported_formats() -> SupportedFormats:
+    """What the reader accepts — the single source of truth for the file picker."""
+    from deeptutor.reading.extract import RAW_VIEW_EXTENSIONS
+    from deeptutor.utils.document_extractor import SUPPORTED_DOC_EXTENSIONS
+
+    return SupportedFormats(
+        extensions=sorted(set(SUPPORTED_DOC_EXTENSIONS) | _MEDIA_EXTENSIONS),
+        max_bytes=MAX_MATERIAL_BYTES,
+        raw_view_extensions=sorted(set(RAW_VIEW_EXTENSIONS) | _MEDIA_EXTENSIONS),
+    )
+
+
+@router.get("/materials", response_model=list[MaterialInfo])
+async def list_materials() -> list[MaterialInfo]:
+    store = _store()
+    try:
+        return [
+            _info(store, manifest)
+            for manifest in store.list_materials()
+            if _material_allowed(manifest.material_id)
+        ]
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.post("/materials", response_model=MaterialDetail)
+async def upload_material(
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(...),  # noqa: B008
+    reuse: bool = Query(default=True),
+) -> MaterialDetail:
+    """Ingest an uploaded document and return it ready to read.
+
+    The upload is streamed to a temp file with a running size check, so an
+    oversized file is rejected before it is fully buffered rather than after.
+
+    Audio and video answer as soon as the file is stored and transcription is
+    queued, the same shape as a URL import. Holding the request open for the
+    length of a lecture meant no progress could reach the client, the browser
+    or a proxy could time the upload out after the transcription had already
+    been paid for, and nothing was left on disk to retry from.
+    """
+    try:
+        assert_learning_material("", upload=True)
+    except PermissionError as exc:
+        raise _http_error(exc) from exc
+    filename = (file.filename or "").strip()
+    if not filename:
+        raise HTTPException(status_code=400, detail="The upload has no filename.")
+    if filename.lower().endswith(".epub.zip"):
+        filename = filename[: -len(".zip")]
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="dt-reading-"))
+    tmp_path = tmp_dir / Path(filename).name
+    written = 0
+    try:
+        with tmp_path.open("wb") as sink:
+            while chunk := await file.read(_UPLOAD_CHUNK):
+                written += len(chunk)
+                if written > MAX_MATERIAL_BYTES:
+                    raise HTTPException(
+                        status_code=413,
+                        detail=(
+                            f"{filename} exceeds the "
+                            f"{MAX_MATERIAL_BYTES // (1024 * 1024)} MB limit."
+                        ),
+                    )
+                sink.write(chunk)
+        if written == 0:
+            raise HTTPException(status_code=400, detail=f"{filename} is empty.")
+
+        store = _store()
+        if Path(filename).suffix.lower() in _MEDIA_EXTENSIONS:
+            service = ReadingIngestionService(store, _catalog())
+            record = await service.queue_media(tmp_path, filename=filename)
+            background_tasks.add_task(service.process_media, record.material_id)
+            return _detail(store, store.manifest(record.material_id))
+        else:
+            manifest = store.ingest(tmp_path, filename=filename)
+            catalog = _catalog()
+            if reuse or catalog.get_material(manifest.material_id) is None:
+                catalog.register_manifest(manifest)
+                _schedule_media_captions(background_tasks, store, manifest.material_id)
+                return _detail(store, manifest)
+            # A separate material over the same extracted content: the bytes
+            # are stored once, while annotations and reading position are kept
+            # apart because the user asked for a second, independent copy.
+            record = catalog.upsert_material(
+                content_id=manifest.material_id,
+                material_id=_new_material_id(),
+                filename=manifest.filename,
+                title=manifest.title,
+                source_kind=SourceKind.FILE,
+                mime=manifest.mime,
+                render_mode=manifest.render_mode,
+                status=IngestionStatus.READY,
+            )
+            _schedule_media_captions(background_tasks, store, record.material_id)
+            return _detail(store, store.manifest(record.material_id))
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+@router.get("/materials/{material_id}", response_model=MaterialDetail)
+async def get_material(material_id: str) -> MaterialDetail:
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        return _detail(store, store.manifest(material_id))
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/materials/{material_id}/epub-pairing-candidates")
+async def epub_pairing_candidates(material_id: str) -> list[dict[str, Any]]:
+    from deeptutor.reading.epub_bilingual import recommend_epub_candidates
+
+    try:
+        assert_learning_material(material_id)
+        return await asyncio.to_thread(recommend_epub_candidates, _store(), material_id)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/epub-pairings")
+async def epub_pairings() -> list[dict[str, Any]]:
+    from deeptutor.reading.epub_bilingual import list_epub_pairings
+
+    return list_epub_pairings(_store())
+
+
+@router.post("/epub-pairings")
+async def create_epub_pairing(payload: EpubPairingRequest) -> dict[str, Any]:
+    from deeptutor.reading.epub_bilingual import create_epub_pairing
+
+    try:
+        _enforce_learning_materials(payload.english_material_id, payload.chinese_material_id)
+        pairing = await asyncio.to_thread(
+            create_epub_pairing,
+            _store(),
+            payload.english_material_id,
+            payload.chinese_material_id,
+        )
+        return {"pairing": pairing}
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.delete("/epub-pairings/{pairing_id}")
+async def remove_epub_pairing(pairing_id: str) -> dict[str, Any]:
+    from deeptutor.reading.epub_bilingual import delete_epub_pairing
+
+    try:
+        removed = await asyncio.to_thread(delete_epub_pairing, _store(), pairing_id)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    if not removed:
+        raise HTTPException(status_code=404, detail="EPUB pairing not found")
+    return {"status": "ok", "pairing_id": pairing_id}
+
+
+@router.delete("/materials/{material_id}")
+async def delete_material(material_id: str) -> dict[str, Any]:
+    store = _store()
+    catalog = _catalog()
+    record = catalog.get_material(material_id)
+    removed_from = catalog.collections_for_material(material_id) if record else []
+    try:
+        assert_learning_material_mutation(material_id)
+        shared = record is not None and catalog.count_materials_for_content(record.content_id) > 1
+        if shared and record is not None:
+            # A sibling material still reads this content: drop this row and
+            # only the annotations that belong to it.
+            store.delete_material_state(material_id, content_id=record.content_id)
+            removed = catalog.delete_material(material_id)
+        else:
+            with store.staged_delete(material_id) as staged:
+                if staged:
+                    catalog.delete_material(material_id)
+            removed = staged or bool(record and catalog.delete_material(material_id))
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    if not removed:
+        raise HTTPException(status_code=404, detail=f"material {material_id!r} not found")
+    return {
+        "status": "ok",
+        "deleted": True,
+        "material_id": material_id,
+        "removed_from": removed_from,
+    }
+
+
+@router.get("/materials/{material_id}/transcript")
+async def get_transcript(material_id: str) -> dict[str, Any]:
+    """Every transcript segment of a timed material, in one response.
+
+    The reader's transcript panel needs all of them at once. Fetching them one
+    locator at a time meant a request per segment — fine when a segment was ten
+    minutes long, wasteful now that they follow the speaker's own sentences.
+    """
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        manifest = store.manifest(material_id)
+        if manifest.render_mode not in {"video", "audio"}:
+            raise ReadingError("this material has no timed transcript")
+        refs = {row.locator: row for row in store.unit_references(material_id)}
+        segments: list[dict[str, Any]] = []
+        budget = MAX_TRANSCRIPT_BYTES
+        for locator, text in store.iter_units(material_id):
+            budget -= len(text.encode("utf-8"))
+            if budget < 0:
+                break
+            ref = refs.get(locator)
+            segments.append(
+                {
+                    "locator": locator,
+                    "text": text,
+                    "title": ref.title if ref else "",
+                    "source_href": ref.source_href if ref else "",
+                }
+            )
+        return {
+            "material_id": material_id,
+            "revision": manifest.revision,
+            "unit_count": manifest.unit_count,
+            "truncated": len(segments) < manifest.unit_count,
+            "segments": segments,
+        }
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/materials/{material_id}/units/{locator}", response_model=UnitText)
+async def get_unit(material_id: str, locator: int) -> UnitText:
+    """One unit's text — the reader's text view, and the only view for non-PDFs."""
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        manifest = store.manifest(material_id)
+        return UnitText(
+            locator=locator,
+            unit=manifest.unit,
+            text=store.unit_text(material_id, locator),
+        )
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/materials/{material_id}/revisions")
+async def list_material_revisions(material_id: str) -> list[dict[str, Any]]:
+    """Prior immutable snapshots retained when a URL is cleaned/refetched."""
+    store = _store()
+    try:
+        return [row.to_dict() for row in store.revisions(material_id)]
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get(
+    "/materials/{material_id}/revisions/{revision}/units/{locator}",
+    response_model=UnitText,
+)
+async def get_revision_unit(material_id: str, revision: int, locator: int) -> UnitText:
+    store = _store()
+    try:
+        manifest = next(
+            (row for row in store.revisions(material_id) if row.revision == revision),
+            None,
+        )
+        if manifest is None:
+            raise MaterialNotFound(f"revision {revision} not found")
+        return UnitText(
+            locator=locator,
+            unit=manifest.unit,
+            text=store.revision_unit_text(material_id, revision, locator),
+        )
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/materials/{material_id}/raw")
+async def get_raw(material_id: str) -> FileResponse:
+    """The original bytes, for the faithful viewer. Serves Range requests."""
+    return _material_file_response(material_id, browser_ready=False)
+
+
+@router.get("/materials/{material_id}/render")
+async def get_render(material_id: str) -> FileResponse:
+    """Serve a browser-ready EPUB archive, or the original for other formats."""
+    return _material_file_response(material_id, browser_ready=True)
+
+
+def _material_file_response(material_id: str, *, browser_ready: bool) -> FileResponse:
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        manifest = store.manifest(material_id)
+        path = store.render_path(material_id) if browser_ready else store.raw_path(material_id)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    if path is None or not path.is_file():
+        raise HTTPException(
+            status_code=404,
+            detail=f"{manifest.filename} has no stored original to render.",
+        )
+    return FileResponse(
+        path,
+        media_type=manifest.mime or "application/octet-stream",
+        filename=manifest.filename,
+        content_disposition_type="inline",
+    )
+
+
+@router.get("/materials/{material_id}/assets/{asset_name}")
+async def get_snapshot_asset(material_id: str, asset_name: str) -> FileResponse:
+    """Serve one authenticated, MIME-sniffed image captured with a web page."""
+    from deeptutor.services.web_source.snapshot_assets import snapshot_asset_mime
+
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        path = store.asset_path(material_id, asset_name)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    if path is None:
+        raise HTTPException(status_code=404, detail="Snapshot image not found.")
+    data = path.read_bytes()
+    mime = snapshot_asset_mime(data)
+    if mime is None:
+        raise HTTPException(status_code=404, detail="Snapshot image is invalid.")
+    return FileResponse(
+        path,
+        media_type=mime,
+        filename=path.name,
+        content_disposition_type="inline",
+        headers={
+            "Cache-Control": "private, max-age=31536000, immutable",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
+@router.get("/materials/{material_id}/media")
+async def list_material_media(material_id: str) -> list[dict[str, Any]]:
+    """The embedded-image index (name / locator / mime / size), empty if none."""
+    store = _store()
+    try:
+        return store.media_items(material_id)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/materials/{material_id}/media/{name}")
+async def get_material_media(material_id: str, name: str) -> FileResponse:
+    """One embedded image's bytes, for the reader pane's media strip."""
+    store = _store()
+    try:
+        path = store.media_path(material_id, name)
+        mime = next(
+            (row.get("mime") for row in store.media_items(material_id) if row.get("name") == name),
+            "",
+        )
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    if path is None:
+        raise HTTPException(status_code=404, detail="No such image in this material.")
+    return FileResponse(
+        path,
+        media_type=mime or "image/png",
+        filename=name,
+        content_disposition_type="inline",
+    )
+
+
+@router.get("/materials/{material_id}/annotations", response_model=list[AnnotationInfo])
+async def list_annotations(material_id: str) -> list[AnnotationInfo]:
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        return [_annotation_info(row) for row in store.annotations(material_id)]
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/materials/{material_id}/position", response_model=PositionInfo)
+async def get_position(material_id: str) -> PositionInfo:
+    """Return the user's last durable viewport for this material."""
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        return PositionInfo(**store.position(material_id).to_dict())
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.put("/materials/{material_id}/position", response_model=PositionInfo)
+async def save_position(material_id: str, payload: PositionPayload) -> PositionInfo:
+    """Persist a validated numeric locator plus an optional renderer anchor."""
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        saved = store.save_position(
+            material_id,
+            ReadingPosition(
+                locator=payload.locator,
+                source_anchor=payload.source_anchor,
+                percentage=(
+                    payload.percentage
+                    if payload.percentage is not None
+                    else store.position(material_id).percentage
+                ),
+            ),
+        )
+        try:
+            await asyncio.to_thread(
+                _record_reading_position,
+                material_id,
+                locator=saved.locator,
+                percentage=saved.percentage,
+            )
+        except Exception:
+            logger.exception("Reading position saved, but learning activity recording failed")
+        return PositionInfo(**saved.to_dict())
+    except Exception as exc:
+        raise _http_error(exc) from exc
+
+
+@router.get("/materials/{material_id}/bookmarks", response_model=BookmarkList)
+async def list_bookmarks(material_id: str) -> BookmarkList:
+    """Every place the reader has kept in this material, in reading order."""
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        rows = store.bookmarks(material_id)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    return BookmarkList(bookmarks=[BookmarkInfo(**row.to_dict()) for row in rows])
+
+
+@router.post("/materials/{material_id}/bookmarks", response_model=BookmarkInfo)
+async def add_bookmark(material_id: str, payload: BookmarkPayload) -> BookmarkInfo:
+    """Keep one place. Bookmarking an already-kept locator returns that one."""
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        saved = store.add_bookmark(
+            material_id,
+            payload.locator,
+            payload.label,
+            payload.source_anchor,
+        )
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    return BookmarkInfo(**saved.to_dict())
+
+
+@router.delete("/materials/{material_id}/bookmarks/{bookmark_id}")
+async def delete_bookmark(material_id: str, bookmark_id: str) -> dict[str, bool]:
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        removed = store.delete_bookmark(material_id, bookmark_id)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    if not removed:
+        raise HTTPException(status_code=404, detail="Bookmark not found")
+    return {"ok": True}
+
+
+@router.put("/materials/{material_id}/annotations", response_model=AnnotationInfo)
+async def save_annotation(material_id: str, payload: AnnotationPayload) -> AnnotationInfo:
+    """Create or update one annotation (id absent = create)."""
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        saved = store.save_annotation(material_id, payload.to_annotation())
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    return _annotation_info(saved)
+
+
+@router.delete("/materials/{material_id}/annotations/{annotation_id}")
+async def delete_annotation(material_id: str, annotation_id: str) -> dict[str, Any]:
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        removed = store.delete_annotation(material_id, annotation_id)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    if not removed:
+        raise HTTPException(status_code=404, detail="annotation not found")
+    return {"status": "ok", "annotation_id": annotation_id}
+
+
+@router.get("/materials/{material_id}/export")
+async def export(
+    material_id: str,
+    fmt: Literal["auto", "pdf", "markdown"] = Query("auto"),
+) -> Response:
+    """Download the material with its annotations applied.
+
+    ``pdf`` writes real PDF annotations into a copy of the original, so the
+    export keeps working outside DeepTutor; ``markdown`` returns the marks as
+    text, which is what every non-PDF format gets.
+    """
+    store = _store()
+    try:
+        assert_learning_material(material_id)
+        result = export_material(store, material_id, fmt=fmt)
+    except Exception as exc:
+        raise _http_error(exc) from exc
+    return Response(
+        content=result.data,
+        media_type=result.media_type,
+        headers={
+            "Content-Disposition": _attachment_header(result.filename),
+            "Content-Length": str(result.byte_size),
+        },
+    )
+
+
+# === Helpers ==================================================================
+
+
+def _info(store: ReadingStore, manifest: Any) -> MaterialInfo:
+    return MaterialInfo(
+        **manifest.to_dict() | {"annotation_count": len(store.annotations(manifest.material_id))}
+    )
+
+
+def _detail(store: ReadingStore, manifest: Any) -> MaterialDetail:
+    outline = store.outline(manifest.material_id)
+    return MaterialDetail(
+        **manifest.to_dict()
+        | {
+            "annotation_count": len(store.annotations(manifest.material_id)),
+            "outline": [entry.to_dict() for entry in outline],
+            "outline_text": render_outline(store, manifest.material_id),
+            "unit_refs": [entry.to_dict() for entry in store.unit_references(manifest.material_id)],
+        }
+    )
+
+
+def _annotation_info(row: Annotation) -> AnnotationInfo:
+    return AnnotationInfo(**row.to_dict())
+
+
+def _attachment_header(filename: str) -> str:
+    """RFC 5987 disposition so non-ASCII names survive the round trip."""
+    from urllib.parse import quote
+
+    ascii_fallback = filename.encode("ascii", "ignore").decode("ascii") or "export"
+    return f"attachment; filename=\"{ascii_fallback}\"; filename*=UTF-8''{quote(filename)}"
+
+
+__all__ = ["MAX_MATERIAL_BYTES", "router"]