feat(schemas): IIIF-native Sprint 1 — schema evolution for streaming architecture

Foundation for IIIF-native image streaming (no local image storage):

- ImageInfo: add iiif_service_url (IIIF Image Service URL for tiled zoom)
and manifest_url (provenance). All new fields have None defaults for
100% backward compatibility with existing master.json files.
- ImageSourceInfo: new companion schema for the pipeline — describes image
source without local file paths (iiif_service_url, is_iiif flag).
- PageModel: add iiif_service_url, canvas_width, canvas_height, manifest_url
columns (all nullable) for storing IIIF metadata at ingestion time.
- PageResponse: expose new fields to frontend in both pages.py and manuscripts.py.
- Frontend api.ts: add IIIF fields to Page and ImageInfo interfaces.
- 6 new tests: backward compat (v1.0 without IIIF fields validates),
IIIF-native ImageInfo, ImageSourceInfo with/without service.

569 tests pass (+6 new), 0 regressions. TypeScript clean.

https://claude.ai/code/session_01UB4he7RdRPHLvNjky4X8Sw

backend/app/api/v1/manuscripts.py

@@ -24,6 +24,10 @@ class PageResponse(BaseModel):
     folio_label: str
     sequence: int
     image_master_path: str | None
+    iiif_service_url: str | None = None
+    canvas_width: int | None = None
+    canvas_height: int | None = None
+    manifest_url: str | None = None
     processing_status: str
     confidence_summary: float | None
 

backend/app/api/v1/pages.py

@@ -64,6 +64,10 @@ class PageResponse(BaseModel):
     folio_label: str
     sequence: int
     image_master_path: str | None
+    iiif_service_url: str | None = None
+    canvas_width: int | None = None
+    canvas_height: int | None = None
+    manifest_url: str | None = None
     processing_status: str
     confidence_summary: float | None
 

backend/app/models/corpus.py

@@ -74,6 +74,10 @@ class PageModel(Base):
     folio_label: Mapped[str] = mapped_column(String, nullable=False)
     sequence: Mapped[int] = mapped_column(Integer, nullable=False)
     image_master_path: Mapped[str | None] = mapped_column(Text, nullable=True)
+    iiif_service_url: Mapped[str | None] = mapped_column(Text, nullable=True)
+    canvas_width: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    canvas_height: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    manifest_url: Mapped[str | None] = mapped_column(Text, nullable=True)
     processing_status: Mapped[str] = mapped_column(
         String, nullable=False, default="CREATED"
     )

backend/app/schemas/image.py

@@ -1,12 +1,19 @@
 """
-Schéma Pydantic pour les métadonnées du dérivé image produit par le pipeline.
+Schémas Pydantic pour les métadonnées image du pipeline.
+
+Deux schémas coexistent :
+- ImageDerivativeInfo : dérivés stockés sur disque (upload de fichiers)
+- ImageSourceInfo     : source IIIF sans stockage local (mode natif)
 """
 # 2. third-party
 from pydantic import BaseModel
 
 
 class ImageDerivativeInfo(BaseModel):
-    """Résultat de la normalisation d'une image : dimensions originales et chemins des dérivés."""
+    """Résultat de la normalisation d'une image : dimensions originales et chemins des dérivés.
+
+    Utilisé pour les images uploadées via /ingest/files (stockage local).
+    """
 
     original_url: str
     original_width: int
@@ -17,3 +24,19 @@ class ImageDerivativeInfo(BaseModel):
     thumbnail_path: str
     thumbnail_width: int
     thumbnail_height: int
+
+
+class ImageSourceInfo(BaseModel):
+    """Source d'image IIIF — pas de stockage local.
+
+    Utilisé pour les images ingérées via manifest ou URLs IIIF.
+    Les bytes ne sont jamais écrits sur disque : téléchargés en RAM
+    pour l'IA, puis jetés.
+    """
+
+    original_url: str                     # URL statique de l'image (fallback)
+    iiif_service_url: str | None = None   # URL du service IIIF Image API
+    manifest_url: str | None = None       # URL du manifest source
+    is_iiif: bool = False                 # a un IIIF Image Service détecté ?
+    original_width: int
+    original_height: int

backend/app/schemas/page_master.py

@@ -38,14 +38,23 @@ class Region(BaseModel):
 
 
 class ImageInfo(BaseModel):
-    """Métadonnées image — CLAUDE.md §4.2."""
-
-    master: str
-    derivative_web: str | None = None
-    thumbnail: str | None = None
-    iiif_base: str | None = None
-    width: int
-    height: int
+    """Métadonnées image — CLAUDE.md §4.2.
+
+    Supporte deux modes :
+    - IIIF natif : iiif_service_url renseigné, images streamées depuis le serveur
+      d'origine (pas de stockage local). derivative_web / thumbnail = None.
+    - Upload local : master = chemin local, derivative_web / thumbnail = chemins
+      des dérivés sur disque (mode legacy ou upload de fichiers).
+    """
+
+    master: str                           # URL source (service IIIF ou statique) ou chemin local
+    derivative_web: str | None = None     # chemin dérivé 1500px (legacy/upload)
+    thumbnail: str | None = None          # chemin thumbnail 256px (legacy/upload)
+    iiif_base: str | None = None          # compat arrière
+    iiif_service_url: str | None = None   # URL du IIIF Image Service (zoom tuilé)
+    manifest_url: str | None = None       # URL du manifest source (provenance)
+    width: int                            # largeur du canvas original
+    height: int                           # hauteur du canvas original
 
 
 class OCRResult(BaseModel):

backend/tests/test_schemas.py

@@ -300,3 +300,85 @@ def test_annotation_layer_all_layer_types():
             created_at=datetime(2026, 3, 16, tzinfo=timezone.utc),
         )
         assert layer.layer_type == layer_type
+
+
+# ---------------------------------------------------------------------------
+# ImageInfo — compatibilité arrière et champs IIIF natifs
+# ---------------------------------------------------------------------------
+
+from app.schemas.page_master import ImageInfo
+from app.schemas.image import ImageSourceInfo
+
+
+def test_image_info_backward_compat_without_iiif_fields():
+    """Un ImageInfo sans les nouveaux champs IIIF doit toujours valider."""
+    info = ImageInfo.model_validate({
+        "master": "data/corpora/test/masters/0001r.tif",
+        "derivative_web": "data/corpora/test/derivatives/0001r.jpg",
+        "width": 2000,
+        "height": 3000,
+    })
+    assert info.iiif_service_url is None
+    assert info.manifest_url is None
+
+
+def test_image_info_with_iiif_service_url():
+    """Un ImageInfo avec iiif_service_url doit valider."""
+    info = ImageInfo.model_validate({
+        "master": "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29/full/max/0/default.jpg",
+        "iiif_service_url": "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29",
+        "manifest_url": "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/manifest.json",
+        "width": 3543,
+        "height": 4724,
+    })
+    assert info.iiif_service_url == "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29"
+    assert info.manifest_url is not None
+    assert info.derivative_web is None
+    assert info.thumbnail is None
+
+
+def test_image_info_iiif_native_no_local_paths():
+    """En mode IIIF natif, derivative_web et thumbnail sont None."""
+    info = ImageInfo(
+        master="https://example.com/image.jpg",
+        iiif_service_url="https://example.com/iiif/img1",
+        width=5000,
+        height=7000,
+    )
+    assert info.derivative_web is None
+    assert info.thumbnail is None
+    assert info.width == 5000
+    assert info.height == 7000
+
+
+def test_page_master_backward_compat_v10(minimal_page_master):
+    """Un PageMaster v1.0 (sans champs IIIF) doit toujours valider."""
+    pm = PageMaster.model_validate(minimal_page_master)
+    assert pm.schema_version == "1.0"
+    assert pm.image.iiif_service_url is None
+
+
+def test_image_source_info_iiif():
+    """ImageSourceInfo avec service IIIF détecté."""
+    info = ImageSourceInfo(
+        original_url="https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29/full/max/0/default.jpg",
+        iiif_service_url="https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29",
+        manifest_url="https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/manifest.json",
+        is_iiif=True,
+        original_width=3543,
+        original_height=4724,
+    )
+    assert info.is_iiif is True
+    assert "gallica" in info.iiif_service_url
+
+
+def test_image_source_info_static_fallback():
+    """ImageSourceInfo sans service IIIF (image statique)."""
+    info = ImageSourceInfo(
+        original_url="https://example.com/static/page1.jpg",
+        is_iiif=False,
+        original_width=2000,
+        original_height=3000,
+    )
+    assert info.is_iiif is False
+    assert info.iiif_service_url is None

frontend/src/lib/api.ts

@@ -83,6 +83,10 @@ export interface Page {
   folio_label: string
   sequence: number
   image_master_path: string | null
+  iiif_service_url: string | null
+  canvas_width: number | null
+  canvas_height: number | null
+  manifest_url: string | null
   processing_status: string
   confidence_summary: number | null
 }
@@ -150,6 +154,8 @@ export interface ImageInfo {
   derivative_web?: string | null
   thumbnail?: string | null
   iiif_base?: string | null
+  iiif_service_url?: string | null
+  manifest_url?: string | null
   width: number
   height: number
 }