From 65c1fc41041a4ff344301b51a0e2ef327fdb5dbc Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Tue, 20 Oct 2026 13:51:03 -0700
Subject: [PATCH 01/13] Link folios to IIIF canvases by canvas ID

---
 manuscript/admin.py                           |  45 +++-
 .../commands/link_folio_canvases.py           | 215 +++++++++++++++++
 .../migrations/0128_folio_iiif_canvas.py      |  65 +++++
 manuscript/models.py                          |  46 +++-
 manuscript/tests.py                           | 228 +++++++++++++++++-
 manuscript/utils.py                           | 102 ++++++--
 static/js/tify-sync.js                        | 151 +++++++-----
 templates/stanzas.html                        |   2 +-
 8 files changed, 756 insertions(+), 98 deletions(-)
 create mode 100644 manuscript/management/commands/link_folio_canvases.py
 create mode 100644 manuscript/migrations/0128_folio_iiif_canvas.py

diff --git a/manuscript/admin.py b/manuscript/admin.py
index ab11857..2f89d12 100644
--- a/manuscript/admin.py
+++ b/manuscript/admin.py
@@ -59,10 +59,28 @@ class StanzaInline(admin.StackedInline):
     )
 
 
+class FolioAdminForm(forms.ModelForm):
+    class Meta:
+        model = Folio
+        fields = "__all__"
+
+    def clean(self):
+        cleaned_data = super().clean()
+        if "canvas_id" in self.changed_data:
+            # the recorded canvas details describe the previously linked
+            # canvas, so drop them when the canvas ID is changed by hand
+            self.instance.canvas_index = None
+            self.instance.canvas_label = None
+            self.instance.image_id = None
+        return cleaned_data
+
+
 class FolioInline(admin.StackedInline):
     model = Folio
+    form = FolioAdminForm
     classes = ("collapse",)
     extra = 1
+    readonly_fields = ("canvas_index", "canvas_label", "image_id")
 
 
 class DetailInline(admin.StackedInline):
@@ -283,20 +301,41 @@ def get_queryset(self, request):
 @admin.register(Folio)
 class FolioAdmin(ImportExportModelAdmin):
     resource_class = FolioResource
+    form = FolioAdminForm
 
-    list_display = ["manuscript", "folio_number", "line_range_display", "stanza_count"]
-    list_filter = ["manuscript"]
+    list_display = [
+        "manuscript",
+        "folio_number",
+        "canvas_label",
+        "line_range_display",
+        "stanza_count",
+    ]
+    list_filter = ["manuscript", ("canvas_id", admin.EmptyFieldListFilter)]
     search_fields = [
         "folio_number",
         "manuscript__siglum",
         "line_code_range_start",
         "line_code_range_end",
+        "canvas_label",
     ]
 
-    readonly_fields = ["stanza_list", "line_range_display", "stanza_count"]
+    readonly_fields = [
+        "stanza_list",
+        "line_range_display",
+        "stanza_count",
+        "canvas_index",
+        "canvas_label",
+        "image_id",
+    ]
 
     fieldsets = (
         ("Folio Information", {"fields": ("manuscript", "folio_number")}),
+        (
+            "IIIF Canvas",
+            {
+                "fields": ("canvas_id", "canvas_label", "canvas_index", "image_id"),
+            },
+        ),
         (
             "Line Range",
             {
diff --git a/manuscript/management/commands/link_folio_canvases.py b/manuscript/management/commands/link_folio_canvases.py
new file mode 100644
index 0000000..2f8ad0f
--- /dev/null
+++ b/manuscript/management/commands/link_folio_canvases.py
@@ -0,0 +1,215 @@
+import re
+from collections import Counter, defaultdict
+
+from django.core.management.base import BaseCommand
+from django.db import transaction
+
+from manuscript.models import SingleManuscript
+from manuscript.utils import fetch_manifest, get_canvases, normalize_folio_label
+
+# folio numbers copied from the viewer's page menu: "<canvas position> : <label>"
+VIEWER_PAGE_REFERENCE = re.compile(r"^\s*(\d+)\s*:\s*(.+?)\s*$")
+# a normalized recto/verso folio number, e.g. "12r" or "iv" (i verso)
+RECTO_VERSO = re.compile(r"(\d+|[ivxlc]+)[rv]")
+
+
+class Command(BaseCommand):
+    help = (
+        "Link folios to canvases in each manuscript's IIIF manifest. A folio is "
+        "linked only when its recto/verso folio number matches exactly one "
+        "canvas label, or when it was copied from the viewer's page menu "
+        '("5 : 1r") and canvas 5 has that label, in which case it is also '
+        "renamed to the label. Everything else is reported so it can be linked "
+        "by hand."
+    )
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "sigla",
+            nargs="*",
+            help="Sigla of manuscripts to process (default: all with a IIIF manifest)",
+        )
+        parser.add_argument(
+            "--overwrite",
+            action="store_true",
+            help="Re-match folios that already have a canvas ID",
+        )
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Report what would be linked without saving",
+        )
+
+    def handle(self, *args, **options):
+        manuscripts = (
+            SingleManuscript.objects.exclude(iiif_url__isnull=True)
+            .exclude(iiif_url="")
+            .order_by("siglum")
+        )
+        if options["sigla"]:
+            manuscripts = manuscripts.filter(siglum__in=options["sigla"])
+            missing = set(options["sigla"]) - set(
+                manuscripts.values_list("siglum", flat=True)
+            )
+            for siglum in sorted(missing):
+                self.stdout.write(
+                    self.style.WARNING(f"{siglum}: not found or has no IIIF manifest")
+                )
+
+        totals = Counter()
+        for manuscript in manuscripts:
+            if not manuscript.folio_set.exists():
+                continue
+            counts = self.link_manuscript(
+                manuscript, options["overwrite"], options["dry_run"]
+            )
+            totals.update(counts)
+
+        prefix = "[dry run] " if options["dry_run"] else ""
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"\n{prefix}Linked {totals['linked']} folios "
+                f"(renamed {totals['renamed']}); "
+                f"{totals['already_linked']} were already linked; "
+                f"{totals['unresolved']} still need to be linked by hand; "
+                f"{totals['needs_folio_number']} linked folios need a correct "
+                "folio number."
+            )
+        )
+
+    def link_manuscript(self, manuscript, overwrite, dry_run):
+        counts = Counter()
+        label = manuscript.siglum or f"Manuscript {manuscript.pk}"
+        try:
+            canvases = get_canvases(fetch_manifest(manuscript.iiif_url))
+        except Exception as e:
+            self.stdout.write(
+                self.style.ERROR(f"{label}: could not load manifest ({e})")
+            )
+            return counts
+
+        canvases_by_id = {canvas["id"]: canvas for canvas in canvases}
+        canvases_by_label = defaultdict(list)
+        for canvas in canvases:
+            canvases_by_label[normalize_folio_label(canvas["label"])].append(canvas)
+
+        folios = list(manuscript.folio_set.all())
+        folio_label_counts = Counter(
+            normalize_folio_label(folio.folio_number) for folio in folios
+        )
+        used_canvas_ids = {
+            folio.canvas_id for folio in folios if folio.canvas_id and not overwrite
+        }
+
+        problems = defaultdict(list)
+        notes = defaultdict(list)
+        with transaction.atomic():
+            for folio in folios:
+                if folio.canvas_id and not overwrite:
+                    counts["already_linked"] += 1
+                    # fill in canvas details for IDs that were entered by hand
+                    canvas = canvases_by_id.get(folio.canvas_id)
+                    if canvas and folio.canvas_index is None:
+                        self.apply_canvas(folio, canvas, dry_run)
+                    continue
+
+                page_reference = VIEWER_PAGE_REFERENCE.match(folio.folio_number or "")
+                if page_reference:
+                    position, page_label = page_reference.groups()
+                    position = int(position)
+                    canvas = (
+                        canvases[position - 1]
+                        if 0 < position <= len(canvases)
+                        else None
+                    )
+                    if not canvas or normalize_folio_label(
+                        canvas["label"]
+                    ) != normalize_folio_label(page_label):
+                        problems[
+                            "viewer page reference does not match the manifest"
+                        ].append(folio.folio_number)
+                    elif canvas["id"] in used_canvas_ids:
+                        problems["canvas already linked to another folio"].append(
+                            folio.folio_number
+                        )
+                    else:
+                        update_fields = []
+                        new_label = normalize_folio_label(page_label)
+                        if (
+                            RECTO_VERSO.fullmatch(new_label)
+                            and not folio_label_counts[new_label]
+                        ):
+                            notes["renamed"].append(
+                                f"{folio.folio_number} → {page_label}"
+                            )
+                            folio.folio_number = page_label
+                            folio_label_counts[new_label] += 1
+                            update_fields.append("folio_number")
+                            counts["renamed"] += 1
+                        else:
+                            notes[
+                                "linked, but the folio number needs correcting"
+                            ].append(folio.folio_number)
+                            counts["needs_folio_number"] += 1
+                        self.apply_canvas(folio, canvas, dry_run, update_fields)
+                        used_canvas_ids.add(canvas["id"])
+                        counts["linked"] += 1
+                    continue
+
+                folio_label = normalize_folio_label(folio.folio_number)
+                matches = canvases_by_label.get(folio_label, [])
+                if not folio_label:
+                    problems["no folio number"].append(f"#{folio.pk}")
+                elif not folio_label.endswith(("r", "v")):
+                    # bare numbers are too easily confused with the image
+                    # sequence numbers some manifests use as labels
+                    problems["not a recto/verso folio number"].append(
+                        folio.folio_number
+                    )
+                elif folio_label_counts[folio_label] > 1:
+                    problems["folio number used more than once"].append(
+                        folio.folio_number
+                    )
+                elif not matches:
+                    problems["no canvas with this label"].append(folio.folio_number)
+                elif len(matches) > 1:
+                    problems["several canvases with this label"].append(
+                        folio.folio_number
+                    )
+                elif matches[0]["id"] in used_canvas_ids:
+                    problems["canvas already linked to another folio"].append(
+                        folio.folio_number
+                    )
+                else:
+                    self.apply_canvas(folio, matches[0], dry_run)
+                    used_canvas_ids.add(matches[0]["id"])
+                    counts["linked"] += 1
+
+        counts["unresolved"] = sum(len(items) for items in problems.values())
+        summary = (
+            f"{label}: linked {counts['linked']}, "
+            f"already linked {counts['already_linked']}, "
+            f"unresolved {counts['unresolved']} "
+            f"(of {len(folios)} folios, {len(canvases)} canvases)"
+        )
+        style = self.style.WARNING if problems else self.style.SUCCESS
+        self.stdout.write(style(summary))
+        for problem, items in [*problems.items(), *notes.items()]:
+            self.stdout.write(f"    {problem}: {', '.join(sorted(set(items)))}")
+        return counts
+
+    def apply_canvas(self, folio, canvas, dry_run, update_fields=()):
+        folio.canvas_id = canvas["id"]
+        folio.canvas_index = canvas["index"]
+        folio.canvas_label = canvas["label"][:255]
+        folio.image_id = canvas["image_id"]
+        if not dry_run:
+            folio.save(
+                update_fields=[
+                    "canvas_id",
+                    "canvas_index",
+                    "canvas_label",
+                    "image_id",
+                    *update_fields,
+                ]
+            )
diff --git a/manuscript/migrations/0128_folio_iiif_canvas.py b/manuscript/migrations/0128_folio_iiif_canvas.py
new file mode 100644
index 0000000..57b9fd1
--- /dev/null
+++ b/manuscript/migrations/0128_folio_iiif_canvas.py
@@ -0,0 +1,65 @@
+# Generated by Django 5.1.15 on 2026-10-20 15:04
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("manuscript", "0127_alter_locationalias_options_and_more"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="folio",
+            name="canvas_id",
+            field=models.CharField(
+                blank=True,
+                help_text="The ID of the canvas in the manuscript's IIIF manifest that shows this folio. This is what links the text to the image viewer.",
+                max_length=1024,
+                null=True,
+                verbose_name="IIIF canvas ID",
+            ),
+        ),
+        migrations.AddField(
+            model_name="folio",
+            name="canvas_index",
+            field=models.PositiveIntegerField(
+                blank=True,
+                help_text="The position of the canvas in the IIIF manifest (starting at 0), recorded when the canvas was linked.",
+                null=True,
+                verbose_name="IIIF canvas position",
+            ),
+        ),
+        migrations.AddField(
+            model_name="folio",
+            name="canvas_label",
+            field=models.CharField(
+                blank=True,
+                help_text="The canvas label in the IIIF manifest, recorded when the canvas was linked. For reference only; it may differ from the folio number.",
+                max_length=255,
+                null=True,
+                verbose_name="IIIF canvas label",
+            ),
+        ),
+        migrations.AddField(
+            model_name="folio",
+            name="image_id",
+            field=models.CharField(
+                blank=True,
+                help_text="The ID of the image on the linked canvas, recorded when the canvas was linked. Used to re-link the folio if the manifest changes.",
+                max_length=1024,
+                null=True,
+                verbose_name="IIIF image ID",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="folio",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("canvas_id__isnull", False)),
+                fields=("manuscript", "canvas_id"),
+                name="unique_folio_canvas_per_manuscript",
+                violation_error_message="Another folio in this manuscript is already linked to this IIIF canvas.",
+            ),
+        ),
+    ]
diff --git a/manuscript/models.py b/manuscript/models.py
index 7795fc3..b680332 100644
--- a/manuscript/models.py
+++ b/manuscript/models.py
@@ -15,8 +15,6 @@
 from django.utils.text import slugify
 from prose.fields import RichTextField
 
-from manuscript.utils import get_canvas_id_for_folio
-
 logger = logging.getLogger(__name__)
 
 
@@ -649,6 +647,33 @@ class Folio(models.Model):
         help_text="Toponyms associated with the folio.",
         verbose_name="Associated toponyms",
     )
+    canvas_id = models.CharField(
+        blank=True,
+        null=True,
+        max_length=1024,
+        verbose_name="IIIF canvas ID",
+        help_text="The ID of the canvas in the manuscript's IIIF manifest that shows this folio. This is what links the text to the image viewer.",
+    )
+    canvas_index = models.PositiveIntegerField(
+        blank=True,
+        null=True,
+        verbose_name="IIIF canvas position",
+        help_text="The position of the canvas in the IIIF manifest (starting at 0), recorded when the canvas was linked.",
+    )
+    canvas_label = models.CharField(
+        blank=True,
+        null=True,
+        max_length=255,
+        verbose_name="IIIF canvas label",
+        help_text="The canvas label in the IIIF manifest, recorded when the canvas was linked. For reference only; it may differ from the folio number.",
+    )
+    image_id = models.CharField(
+        blank=True,
+        null=True,
+        max_length=1024,
+        verbose_name="IIIF image ID",
+        help_text="The ID of the image on the linked canvas, recorded when the canvas was linked. Used to re-link the folio if the manifest changes.",
+    )
 
     def __str__(self) -> str:
         if self.folio_number is not None:
@@ -657,17 +682,18 @@ def __str__(self) -> str:
 
     def get_canvas_id(self):
         """Get the IIIF canvas ID for this folio"""
-        if not self.folio_number:
-            return None
-
-        return get_canvas_id_for_folio(self.folio_number)
-
-    # def get_stanzas(self) -> List[Stanza]:
-    #     """Get all stanzas that appear on this folio in order."""
-    #     return get_stanzas_in_folio(self)
+        return self.canvas_id or None
 
     class Meta:
         ordering = ["folio_number"]
+        constraints = [
+            models.UniqueConstraint(
+                fields=["manuscript", "canvas_id"],
+                condition=Q(canvas_id__isnull=False),
+                name="unique_folio_canvas_per_manuscript",
+                violation_error_message="Another folio in this manuscript is already linked to this IIIF canvas.",
+            )
+        ]
 
 
 class SingleManuscript(models.Model):
diff --git a/manuscript/tests.py b/manuscript/tests.py
index 7ce503c..ec0ce77 100644
--- a/manuscript/tests.py
+++ b/manuscript/tests.py
@@ -1,3 +1,227 @@
-from django.test import TestCase
+from io import StringIO
+from unittest import mock
 
-# Create your tests here.
+from django.core.management import call_command
+from django.db import IntegrityError
+from django.test import SimpleTestCase, TestCase
+
+from manuscript.models import Folio, SingleManuscript
+from manuscript.utils import get_canvases, normalize_folio_label
+
+MANIFEST_URL = "https://example.org/iiif/ms/manifest.json"
+
+
+def v2_canvas(number, label):
+    return {
+        "@id": f"https://example.org/iiif/ms/canvas/p{number:04d}",
+        "label": label,
+        "images": [
+            {
+                "resource": {
+                    "@id": f"https://example.org/image/{number}/full/full/0/default.jpg",
+                    "service": {"@id": f"https://example.org/image/{number}"},
+                }
+            }
+        ],
+    }
+
+
+def v2_manifest(labels):
+    return {
+        "sequences": [
+            {"canvases": [v2_canvas(i + 1, label) for i, label in enumerate(labels)]}
+        ]
+    }
+
+
+class NormalizeFolioLabelTest(SimpleTestCase):
+    def test_equivalent_forms(self):
+        for value in ["12r", "12R", "f. 12r", "fol.12r", "Carta: 12r", "12 recto"]:
+            self.assertEqual(normalize_folio_label(value), "12r", value)
+        self.assertEqual(normalize_folio_label("12 verso"), "12v")
+
+    def test_distinct_forms(self):
+        self.assertEqual(normalize_folio_label("Ir"), "ir")
+        self.assertEqual(normalize_folio_label("piatto.anteriore"), "piattoanteriore")
+        self.assertEqual(normalize_folio_label(None), "")
+
+
+class GetCanvasesTest(SimpleTestCase):
+    def test_v2(self):
+        canvases = get_canvases(v2_manifest(["1r", "1v"]))
+        self.assertEqual(
+            canvases[1],
+            {
+                "index": 1,
+                "id": "https://example.org/iiif/ms/canvas/p0002",
+                "label": "1v",
+                "image_id": "https://example.org/image/2",
+            },
+        )
+
+    def test_v3(self):
+        manifest = {
+            "items": [
+                {
+                    "id": "https://example.org/canvas/1",
+                    "label": {"none": ["57r"]},
+                    "items": [
+                        {
+                            "items": [
+                                {
+                                    "body": {
+                                        "id": "https://example.org/image/1/full/max/0/default.jpg",
+                                        "service": [
+                                            {"id": "https://example.org/image/1"}
+                                        ],
+                                    }
+                                }
+                            ]
+                        }
+                    ],
+                }
+            ]
+        }
+        self.assertEqual(
+            get_canvases(manifest),
+            [
+                {
+                    "index": 0,
+                    "id": "https://example.org/canvas/1",
+                    "label": "57r",
+                    "image_id": "https://example.org/image/1",
+                }
+            ],
+        )
+
+
+class LinkFolioCanvasesTest(TestCase):
+    def setUp(self):
+        self.manuscript = SingleManuscript.objects.create(
+            item_id=1, siglum="Test1", iiif_url=MANIFEST_URL
+        )
+
+    def add_folios(self, *numbers):
+        return [
+            Folio.objects.create(manuscript=self.manuscript, folio_number=number)
+            for number in numbers
+        ]
+
+    def run_command(self, labels, *args):
+        out = StringIO()
+        with mock.patch(
+            "manuscript.management.commands.link_folio_canvases.fetch_manifest",
+            return_value=v2_manifest(labels),
+        ):
+            call_command("link_folio_canvases", *args, stdout=out)
+        return out.getvalue()
+
+    def test_links_unique_matches(self):
+        folio_1r, folio_1v = self.add_folios("1r", "1v")
+        self.run_command(["piatto.anteriore", "Carta: 1r", "Carta: 1v"])
+
+        folio_1r.refresh_from_db()
+        self.assertEqual(folio_1r.canvas_id, "https://example.org/iiif/ms/canvas/p0002")
+        self.assertEqual(folio_1r.canvas_index, 1)
+        self.assertEqual(folio_1r.canvas_label, "Carta: 1r")
+        self.assertEqual(folio_1r.image_id, "https://example.org/image/2")
+        folio_1v.refresh_from_db()
+        self.assertEqual(folio_1v.canvas_index, 2)
+
+    def test_skips_duplicate_canvas_labels(self):
+        (folio,) = self.add_folios("1r")
+        out = self.run_command(["1r", "1v", "1r", "1v"])
+
+        folio.refresh_from_db()
+        self.assertIsNone(folio.canvas_id)
+        self.assertIn("several canvases with this label: 1r", out)
+
+    def test_skips_duplicate_folio_numbers(self):
+        folios = self.add_folios("20r", "20r")
+        out = self.run_command(["20r"])
+
+        for folio in folios:
+            folio.refresh_from_db()
+            self.assertIsNone(folio.canvas_id)
+        self.assertIn("folio number used more than once: 20r", out)
+
+    def test_skips_bare_numbers(self):
+        (folio,) = self.add_folios("2")
+        out = self.run_command(["1", "2", "3"])
+
+        folio.refresh_from_db()
+        self.assertIsNone(folio.canvas_id)
+        self.assertIn("not a recto/verso folio number: 2", out)
+
+    def test_links_and_renames_viewer_page_references(self):
+        (folio,) = self.add_folios("3 : 1v")
+        out = self.run_command(["piatto.anteriore", "1r", "1v"])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, "https://example.org/iiif/ms/canvas/p0003")
+        self.assertEqual(folio.folio_number, "1v")
+        self.assertIn("renamed: 3 : 1v → 1v", out)
+
+    def test_viewer_page_reference_without_folio_label(self):
+        (folio,) = self.add_folios("1 : Front cover")
+        out = self.run_command(["Front cover", "1r"])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_index, 0)
+        self.assertEqual(folio.folio_number, "1 : Front cover")
+        self.assertIn(
+            "linked, but the folio number needs correcting: 1 : Front cover", out
+        )
+
+    def test_viewer_page_reference_not_renamed_onto_existing_folio(self):
+        existing, folio = self.add_folios("1r", "3 : 1r")
+        # existing 1r is ambiguous, so stays unlinked; canvas 3 is still a 1r
+        self.run_command(["1r", "1v", "1r"])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_index, 2)
+        self.assertEqual(folio.folio_number, "3 : 1r")
+        existing.refresh_from_db()
+        self.assertIsNone(existing.canvas_id)
+
+    def test_viewer_page_reference_must_match_manifest(self):
+        (folio,) = self.add_folios("2 : 1r")
+        out = self.run_command(["1r", "1v"])
+
+        folio.refresh_from_db()
+        self.assertIsNone(folio.canvas_id)
+        self.assertEqual(folio.folio_number, "2 : 1r")
+        self.assertIn("viewer page reference does not match the manifest: 2 : 1r", out)
+
+    def test_dry_run_does_not_rename(self):
+        (folio,) = self.add_folios("1 : 1r")
+        self.run_command(["1r"], "--dry-run")
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.folio_number, "1 : 1r")
+        self.assertIsNone(folio.canvas_id)
+
+    def test_keeps_existing_links(self):
+        (folio,) = self.add_folios("1r")
+        folio.canvas_id = "https://example.org/iiif/ms/canvas/p0002"
+        folio.save()
+        self.run_command(["1r", "1v"])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, "https://example.org/iiif/ms/canvas/p0002")
+        # canvas details are filled in for the hand-entered canvas ID
+        self.assertEqual(folio.canvas_label, "1v")
+        self.assertEqual(folio.canvas_index, 1)
+
+    def test_dry_run_does_not_save(self):
+        (folio,) = self.add_folios("1r")
+        self.run_command(["1r"], "--dry-run")
+
+        folio.refresh_from_db()
+        self.assertIsNone(folio.canvas_id)
+
+    def test_canvas_unique_per_manuscript(self):
+        canvas_id = "https://example.org/iiif/ms/canvas/p0001"
+        Folio.objects.create(manuscript=self.manuscript, canvas_id=canvas_id)
+        with self.assertRaises(IntegrityError):
+            Folio.objects.create(manuscript=self.manuscript, canvas_id=canvas_id)
diff --git a/manuscript/utils.py b/manuscript/utils.py
index 0975eb8..3f21fae 100644
--- a/manuscript/utils.py
+++ b/manuscript/utils.py
@@ -1,30 +1,86 @@
-import json
-from datetime import timedelta
-from functools import lru_cache
+import re
 
 import requests
-from django.core.cache import cache
 
+FOLIO_LABEL_PREFIX = re.compile(r"^(?:carta|folio|fol|ff|f|c)\s*[.:]?\s*(?=\d)")
 
-@lru_cache(maxsize=1)
-def get_manifest():
-    """
-    Fetch the IIIF manifest with in-memory caching
-    The lru_cache will keep the manifest in memory for the lifetime of the process
-    """
-    manifest_url = "https://digi.vatlib.it/iiif/MSS_Urb.lat.752/manifest.json"
-    response = requests.get(manifest_url)
+
+def fetch_manifest(manifest_url, timeout=60):
+    """Fetch and parse a IIIF manifest"""
+    response = requests.get(
+        manifest_url, timeout=timeout, headers={"User-Agent": "lasfera"}
+    )
+    response.raise_for_status()
     return response.json()
 
 
-def get_canvas_id_for_folio(folio_number):
-    """Look up the canvas ID for a given folio number (e.g., "1r")"""
-    try:
-        manifest = get_manifest()
-        for canvas in manifest["sequences"][0]["canvases"]:
-            if canvas["label"] == folio_number:
-                return canvas["@id"]
-        return None
-    except Exception as e:
-        print(f"Error fetching canvas ID for folio {folio_number}: {e}")
-        return None
+def _label_to_str(label):
+    """Flatten a IIIF v2 or v3 label into a plain string"""
+    if label is None:
+        return ""
+    if isinstance(label, str):
+        return label
+    if isinstance(label, list):
+        return " ".join(_label_to_str(item) for item in label)
+    if isinstance(label, dict):
+        if "@value" in label:
+            return str(label["@value"])
+        # v3 language map, e.g. {"none": ["1r"]}
+        return " ".join(_label_to_str(values) for values in label.values())
+    return str(label)
+
+
+def _service_id(service):
+    if isinstance(service, list):
+        service = service[0] if service else None
+    if isinstance(service, dict):
+        return service.get("@id") or service.get("id")
+    return None
+
+
+def get_canvases(manifest):
+    """Return the canvases of a IIIF v2 or v3 manifest as a list of dicts
+    with keys: index (0-based), id, label, image_id"""
+    canvases = []
+    if "sequences" in manifest:
+        raw_canvases = manifest["sequences"][0].get("canvases", [])
+    else:
+        raw_canvases = manifest.get("items", [])
+
+    for index, canvas in enumerate(raw_canvases):
+        image_id = None
+        if canvas.get("images"):
+            # v2: canvas.images[].resource
+            resource = canvas["images"][0].get("resource", {})
+            image_id = _service_id(resource.get("service")) or resource.get("@id")
+        elif canvas.get("items"):
+            # v3: canvas.items[] (annotation pages) .items[] (annotations) .body
+            try:
+                body = canvas["items"][0]["items"][0]["body"]
+                if isinstance(body, list):
+                    body = body[0]
+                image_id = _service_id(body.get("service")) or body.get("id")
+            except (IndexError, KeyError, AttributeError):
+                pass
+
+        canvases.append(
+            {
+                "index": index,
+                "id": canvas.get("@id") or canvas.get("id"),
+                "label": _label_to_str(canvas.get("label")).strip(),
+                "image_id": image_id,
+            }
+        )
+    return canvases
+
+
+def normalize_folio_label(label):
+    """Normalize a folio reference or canvas label for comparison,
+    e.g. "Carta: 12 recto", "f. 12r", and "12r" all become "12r"."""
+    if not label:
+        return ""
+    value = label.strip().lower()
+    value = re.sub(r"\brecto\b", "r", value)
+    value = re.sub(r"\bverso\b", "v", value)
+    value = FOLIO_LABEL_PREFIX.sub("", value)
+    return re.sub(r"[\s.]", "", value)
diff --git a/static/js/tify-sync.js b/static/js/tify-sync.js
index 8fad7d9..a7ef7e6 100644
--- a/static/js/tify-sync.js
+++ b/static/js/tify-sync.js
@@ -67,70 +67,98 @@ const TifySync = {
     }, 1000);
   },
   
-  navigateToFolio(folioNumber, retryCount = 0) {
+  navigateToFolio(folioNumber, canvasId = null, retryCount = 0) {
     if (!this.viewerReady && retryCount < 5) {
       console.log(`Viewer not ready for ${folioNumber}, retrying... (${retryCount + 1})`);
-      setTimeout(() => this.navigateToFolio(folioNumber, retryCount + 1), 1000);
+      setTimeout(() => this.navigateToFolio(folioNumber, canvasId, retryCount + 1), 1000);
       return;
     }
 
-    if (!this.viewer || !this.manifestUrl || !folioNumber) {
+    if (!this.viewer || !this.manifestUrl || !(folioNumber || canvasId)) {
       console.log('Cannot navigate: missing required data', {
         hasViewer: !!this.viewer,
         manifestUrl: this.manifestUrl,
-        folioNumber
+        folioNumber,
+        canvasId
       });
       return;
     }
 
     try {
-      console.log('Attempting to navigate to folio:', folioNumber);
-      
-      // Determine page number based on folio - this might require fetching
-      // the manifest data and searching for the folio in labels
-      this.fetchManifestAndNavigate(folioNumber);
+      console.log('Attempting to navigate to folio:', folioNumber, canvasId);
+      this.fetchManifestAndNavigate(folioNumber, canvasId);
     } catch (error) {
       console.error('Error navigating to folio:', error);
     }
   },
-  
-  async fetchManifestAndNavigate(folioNumber) {
+
+  // Canvases from either a IIIF v2 or v3 manifest
+  getCanvases(manifest) {
+    if (manifest.sequences) {
+      return manifest.sequences[0].canvases || [];
+    }
+    return manifest.items || [];
+  },
+
+  // Flatten a IIIF v2 or v3 label into a plain string
+  labelToString(label) {
+    if (!label) return '';
+    if (typeof label === 'string') return label;
+    if (Array.isArray(label)) return label.map(l => this.labelToString(l)).join(' ');
+    if (label['@value']) return label['@value'];
+    return Object.values(label).map(l => this.labelToString(l)).join(' ');
+  },
+
+  findCanvasIndex(canvases, folioNumber, canvasId) {
+    // Folios linked to a canvas are matched by canvas ID
+    if (canvasId) {
+      const index = canvases.findIndex(canvas => (canvas['@id'] || canvas.id) === canvasId);
+      if (index !== -1) {
+        return index;
+      }
+      console.warn('Linked canvas not found in manifest:', canvasId);
+    }
+    if (!folioNumber) {
+      return -1;
+    }
+
+    // Legacy fallback for folios not yet linked to a canvas: match the
+    // folio number against canvas labels and metadata
+    const folioPatterns = [
+      new RegExp(`f.?${folioNumber}[rv]?`, 'i'),  // f12v, f.12v, f12r
+      new RegExp(`${folioNumber}[rv]?`, 'i'),      // 12v, 12r
+      new RegExp(`folio.?${folioNumber}`, 'i')     // folio 12, folio.12
+    ];
+
+    return canvases.findIndex(canvas =>
+      folioPatterns.some(pattern => {
+        const matchesLabel = pattern.test(this.labelToString(canvas.label));
+        const matchesMetadata = canvas.metadata && 
+          canvas.metadata.some(m => pattern.test(this.labelToString(m.value)));
+        
+        if (matchesLabel || matchesMetadata) {
+          console.log('Found match:', {
+            pattern: pattern.toString(),
+            label: canvas.label,
+            metadata: canvas.metadata
+          });
+        }
+        
+        return matchesLabel || matchesMetadata;
+      })
+    );
+  },
+
+  async fetchManifestAndNavigate(folioNumber, canvasId = null) {
     try {
       if (!this.manifestData) {
         const response = await fetch(this.manifestUrl);
         this.manifestData = await response.json();
       }
-      const manifest = this.manifestData;
-
-      // Extract the canvases
-      const canvases = manifest.sequences[0].canvases;
+      const canvases = this.getCanvases(this.manifestData);
       console.log('Found manifest with', canvases.length, 'canvases');
-      
-      // Try different patterns for matching folio numbers
-      const folioPatterns = [
-        new RegExp(`f.?${folioNumber}[rv]?`, 'i'),  // f12v, f.12v, f12r
-        new RegExp(`${folioNumber}[rv]?`, 'i'),      // 12v, 12r
-        new RegExp(`folio.?${folioNumber}`, 'i')     // folio 12, folio.12
-      ];
 
-      // Try to find matching canvas
-      const pageIndex = canvases.findIndex(canvas => 
-        folioPatterns.some(pattern => {
-          const matchesLabel = pattern.test(canvas.label);
-          const matchesMetadata = canvas.metadata && 
-            canvas.metadata.some(m => pattern.test(m.value));
-          
-          if (matchesLabel || matchesMetadata) {
-            console.log('Found match:', {
-              pattern: pattern.toString(),
-              label: canvas.label,
-              metadata: canvas.metadata
-            });
-          }
-          
-          return matchesLabel || matchesMetadata;
-        })
-      );
+      const pageIndex = this.findCanvasIndex(canvases, folioNumber, canvasId);
 
       if (pageIndex !== -1) {
         console.log('Found matching canvas at index:', pageIndex);
@@ -154,7 +182,7 @@ const TifySync = {
           });
         }
       } else {
-        console.log('No matching canvas found for folio:', folioNumber);
+        console.log('No matching canvas found for folio:', folioNumber, canvasId);
       }
     } catch (error) {
       console.error('Error fetching manifest or navigating:', error);
@@ -187,11 +215,12 @@ const TifySync = {
       entries.forEach(entry => {
         const folioElement = entry.target;
         const folioNumber = folioElement.dataset.folioNumber;
+        const canvasId = folioElement.dataset.canvasId || null;
         
         if (entry.isIntersecting) {
           console.log('Folio entered viewport:', folioNumber, 'Intersection ratio:', entry.intersectionRatio);
           folioElement.style.backgroundColor = '#f0f9ff';
-          handleFolioChange(folioNumber);
+          handleFolioChange(folioNumber, canvasId);
         } else {
           folioElement.style.backgroundColor = '';
         }
@@ -237,8 +266,8 @@ document.addEventListener('alpine:init', () => {
         console.log('Tify viewer initialized');
         
         // Set up the observer after Alpine and Tify are initialized
-        TifySync.setupIntersectionObserver((folioNumber) => {
-          this.handleFolioChange(folioNumber);
+        TifySync.setupIntersectionObserver((folioNumber, canvasId) => {
+          this.handleFolioChange(folioNumber, canvasId);
         });
 
         TifySync.viewer.ready.then(() => {
@@ -246,20 +275,21 @@ document.addEventListener('alpine:init', () => {
           const dividers = Array.from(
             document.querySelectorAll('.folio-divider'),
           );
-          let activeFolio = null;
+          let activeDivider = null;
           // get the last divider that is ABOVE the top 15% of screen
           const readingLine = window.innerHeight * 0.15;
           for (let i = 0; i < dividers.length; i++) {
             const rect = dividers[i].getBoundingClientRect();
             if (rect.top <= readingLine) {
-              activeFolio = dividers[i].dataset.folioNumber;
+              activeDivider = dividers[i];
             } else {
               break;
             }
           }
-          if (activeFolio) {
-            console.log('Initial jump to folio:', activeFolio);
-            this.handleFolioChange(activeFolio, true);
+          if (activeDivider) {
+            const { folioNumber, canvasId } = activeDivider.dataset;
+            console.log('Initial jump to folio:', folioNumber);
+            this.handleFolioChange(folioNumber, canvasId || null, true);
           } else {
             console.log(
               'No folio divider found above the current scroll position.',
@@ -269,14 +299,16 @@ document.addEventListener('alpine:init', () => {
       }
     },
 
-    handleFolioChange(folioNumber, force = false) {
-      if (!force && this.currentFolio === folioNumber) {
+    handleFolioChange(folioNumber, canvasId = null, force = false) {
+      // folio numbers are not always unique, so prefer the canvas ID as the key
+      const folioKey = canvasId || folioNumber;
+      if (!force && this.currentFolio === folioKey) {
         return;
       }
-      console.log('Handling folio change:', folioNumber);
-      this.currentFolio = folioNumber;
+      console.log('Handling folio change:', folioNumber, canvasId);
+      this.currentFolio = folioKey;
       if (this.viewerInitialized) {
-        TifySync.navigateToFolio(folioNumber);
+        TifySync.navigateToFolio(folioNumber, canvasId);
       } else {
         console.log('Viewer not yet initialized');
       }
@@ -289,11 +321,12 @@ function navigateToFolio(event, element) {
   event.preventDefault();
   
   // Extract folio number from the data attribute or from parent folio-divider
-  const folioNumber = element.dataset.folio || 
-                      element.closest('.folio-divider')?.dataset.folioNumber;
+  const divider = element.closest('.folio-divider');
+  const folioNumber = element.dataset.folio || divider?.dataset.folioNumber;
+  const canvasId = element.dataset.canvasId || divider?.dataset.canvasId || null;
   
-  if (folioNumber) {
-    console.log('Navigating to folio:', folioNumber);
-    TifySync.navigateToFolio(folioNumber);
+  if (folioNumber || canvasId) {
+    console.log('Navigating to folio:', folioNumber, canvasId);
+    TifySync.navigateToFolio(folioNumber, canvasId);
   }
 }
diff --git a/templates/stanzas.html b/templates/stanzas.html
index adb50e4..dd7ab28 100644
--- a/templates/stanzas.html
+++ b/templates/stanzas.html
@@ -210,7 +210,7 @@ <h2 id="book-{{book_number}}" class="text-xl font-serif font-bold mb-4 scroll-mt
                 <!-- Stanza pairs -->
                 {% for stanza_pair in stanza_pairs %}
                   {% if stanza_pair.new_folio and stanza_pair.current_folio %}
-                    <div class="col-span-2 relative flex items-center my-6 folio-divider" data-folio-number="{{ stanza_pair.current_folio.folio_number }}">
+                    <div class="col-span-2 relative flex items-center my-6 folio-divider" data-folio-number="{{ stanza_pair.current_folio.folio_number }}" data-canvas-id="{{ stanza_pair.current_folio.canvas_id|default_if_none:'' }}">
                       <div class="font-medium text-gray-500 pr-4">
                         Folio {{ stanza_pair.current_folio.folio_number }}
                       </div>

From e59d299866a7121000cc23899fc646d4c7acfad6 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Wed, 21 Oct 2026 10:55:17 -0700
Subject: [PATCH 02/13] Add admin page for linking IIIF canvases by hand

---
 manuscript/admin.py                           | 124 ++++-
 manuscript/canvas_linking.py                  | 169 +++++++
 manuscript/tests.py                           | 190 ++++++++
 static/js/canvas_linking.js                   | 458 ++++++++++++++++++
 .../singlemanuscript/change_form.html         |   8 +
 .../singlemanuscript/link_canvases.html       | 152 ++++++
 6 files changed, 1098 insertions(+), 3 deletions(-)
 create mode 100644 manuscript/canvas_linking.py
 create mode 100644 static/js/canvas_linking.js
 create mode 100644 templates/admin/manuscript/singlemanuscript/change_form.html
 create mode 100644 templates/admin/manuscript/singlemanuscript/link_canvases.html

diff --git a/manuscript/admin.py b/manuscript/admin.py
index 2f89d12..061968c 100644
--- a/manuscript/admin.py
+++ b/manuscript/admin.py
@@ -1,12 +1,19 @@
+import json
+
 from django import forms
-from django.contrib import admin
+from django.contrib import admin, messages
+from django.contrib.admin.utils import unquote
 from django.contrib.contenttypes.admin import GenericTabularInline
+from django.core.exceptions import PermissionDenied, ValidationError
 from django.db.models import Count
-from django.urls import reverse
-from django.utils.html import format_html
+from django.shortcuts import redirect
+from django.template.response import TemplateResponse
+from django.urls import path, reverse
+from django.utils.html import format_html, format_html_join
 from import_export.admin import ImportExportModelAdmin
 
 from common.admin import StripDivMixin
+from manuscript.canvas_linking import clean_canvas_rows, link_canvases
 from manuscript.models import (
     AuthorityFile,
     Codex,
@@ -286,10 +293,121 @@ class SingleManuscriptAdmin(ImportExportModelAdmin):
         "library",
     ]
 
+    change_form_template = "admin/manuscript/singlemanuscript/change_form.html"
+
     @admin.display(boolean=True, description="IIIF Available")
     def has_iiif_url(self, obj):
         return bool(obj.iiif_url)
 
+    def get_urls(self):
+        return [
+            path(
+                "<path:object_id>/canvases/",
+                self.admin_site.admin_view(self.link_canvases_view),
+                name="manuscript_singlemanuscript_canvases",
+            ),
+            *super().get_urls(),
+        ]
+
+    def link_canvases_view(self, request, object_id):
+        """Page for linking the manuscript's folios to its IIIF canvases by hand"""
+        manuscript = self.get_object(request, unquote(object_id))
+        if manuscript is None:
+            return self._get_obj_does_not_exist_redirect(request, self.opts, object_id)
+        if not request.user.has_perm("manuscript.change_folio"):
+            raise PermissionDenied
+
+        change_url = reverse(
+            "admin:manuscript_singlemanuscript_change", args=[manuscript.pk]
+        )
+        if not manuscript.iiif_url:
+            messages.warning(request, "This manuscript has no IIIF manifest URL.")
+            return redirect(change_url)
+
+        can_create = request.user.has_perm("manuscript.add_folio")
+        submitted = None
+        if request.method == "POST":
+            try:
+                raw_rows = json.loads(request.POST.get("rows", ""))
+            except ValueError:
+                raw_rows = None
+            try:
+                rows = clean_canvas_rows(raw_rows)
+                counts, created = link_canvases(manuscript, rows, can_create=can_create)
+            except ValidationError as e:
+                for message in e.messages:
+                    messages.error(request, message)
+                # keep what was entered so it can be corrected
+                if isinstance(raw_rows, list):
+                    submitted = {
+                        str(row.get("id")): str(row.get("folio") or "")
+                        for row in raw_rows
+                        if isinstance(row, dict)
+                    }
+            else:
+                if counts:
+                    messages.success(
+                        request,
+                        f"Saved: linked {counts['linked']}, unlinked "
+                        f"{counts['unlinked']}, and created {counts['created']} "
+                        f"new folio record{'' if counts['created'] == 1 else 's'}.",
+                    )
+                    if created:
+                        messages.warning(
+                            request,
+                            format_html(
+                                "Add a line range to the new folio records so "
+                                "the text can turn to them: {}",
+                                format_html_join(
+                                    ", ",
+                                    '<a href="{}">{}</a>',
+                                    (
+                                        (
+                                            reverse(
+                                                "admin:manuscript_folio_change",
+                                                args=[folio.pk],
+                                            ),
+                                            folio.folio_number,
+                                        )
+                                        for folio in created
+                                    ),
+                                ),
+                            ),
+                        )
+                else:
+                    messages.info(request, "No changes to save.")
+                return redirect(request.path)
+
+        folios = manuscript.folio_set.annotate(
+            toponym_count=Count("locationalias", distinct=True)
+        )
+        context = {
+            **self.admin_site.each_context(request),
+            "opts": self.opts,
+            "title": f"Link IIIF canvases: {manuscript}",
+            "manuscript": manuscript,
+            "change_url": change_url,
+            "can_create": can_create,
+            "folios": [
+                {
+                    "id": folio.pk,
+                    "number": folio.folio_number or "",
+                    "canvas_id": folio.canvas_id,
+                    "line_start": folio.line_code_range_start,
+                    "line_end": folio.line_code_range_end,
+                    "toponyms": folio.toponym_count,
+                    "admin_url": reverse(
+                        "admin:manuscript_folio_change", args=[folio.pk]
+                    ),
+                }
+                for folio in folios
+            ],
+            "submitted": submitted,
+        }
+        return TemplateResponse(
+            request, "admin/manuscript/singlemanuscript/link_canvases.html", context
+        )
+
     class Media:
         js = ("js/text_annotations.js",)
         css = {"all": ("css/text_annotator.css",)}
diff --git a/manuscript/canvas_linking.py b/manuscript/canvas_linking.py
new file mode 100644
index 0000000..92b8176
--- /dev/null
+++ b/manuscript/canvas_linking.py
@@ -0,0 +1,169 @@
+"""Linking a manuscript's folios to the canvases of its IIIF manifest by hand"""
+
+from collections import Counter, defaultdict
+
+from django.core.exceptions import ValidationError
+from django.db import transaction
+
+from manuscript.models import Folio
+from manuscript.utils import normalize_folio_label
+
+FOLIO_NUMBER_MAX_LENGTH = Folio._meta.get_field("folio_number").max_length
+CANVAS_ID_MAX_LENGTH = Folio._meta.get_field("canvas_id").max_length
+
+
+def clean_canvas_rows(rows):
+    """Validate the rows submitted from the canvas linking page. Each row is a
+    canvas from the manifest: id, index, label, image_id, and the folio
+    number entered for it (blank for none)."""
+    if not isinstance(rows, list):
+        raise ValidationError("The submitted images could not be read.")
+
+    cleaned = []
+    for row in rows:
+        try:
+            canvas_id = str(row["id"]).strip()
+            index = int(row["index"])
+            label = str(row.get("label") or "").strip()[:255]
+            image_id = str(row.get("image_id") or "").strip() or None
+            folio_number = str(row.get("folio") or "").strip()
+        except (KeyError, TypeError, ValueError):
+            raise ValidationError("The submitted images could not be read.")
+        if not canvas_id or len(canvas_id) > CANVAS_ID_MAX_LENGTH or index < 0:
+            raise ValidationError("The submitted images could not be read.")
+        if image_id and len(image_id) > CANVAS_ID_MAX_LENGTH:
+            image_id = None
+        if len(folio_number) > FOLIO_NUMBER_MAX_LENGTH:
+            raise ValidationError(
+                f"The folio number entered for image {index + 1} is too long."
+            )
+        cleaned.append(
+            {
+                "id": canvas_id,
+                "index": index,
+                "label": label,
+                "image_id": image_id,
+                "folio": folio_number,
+            }
+        )
+
+    duplicate_ids = [
+        canvas_id
+        for canvas_id, count in Counter(row["id"] for row in cleaned).items()
+        if count > 1
+    ]
+    if duplicate_ids:
+        raise ValidationError("The manifest lists the same image more than once.")
+    return cleaned
+
+
+def link_canvases(manuscript, rows, can_create=True):
+    """Link the manuscript's folios to canvases as entered on the canvas linking
+    page, where rows are cleaned by clean_canvas_rows.
+
+    A folio number is matched to an existing folio of the manuscript (ignoring
+    differences like "f. 12r" and "12r"), or a new folio is created. Folios are
+    never renamed or deleted: a folio whose canvas is cleared or given to
+    another folio is only unlinked, so its toponyms and other data stay intact.
+
+    Returns a Counter of linked, unlinked, and created folios, and a list of
+    the folios created. Raises ValidationError, without saving anything, if
+    the entries conflict."""
+    errors = []
+
+    # folio number entered -> row, checking no folio is entered twice
+    rows_by_folio = {}
+    positions_by_folio = defaultdict(list)
+    for row in rows:
+        if row["folio"]:
+            key = normalize_folio_label(row["folio"]) or row["folio"].lower()
+            rows_by_folio[key] = row
+            positions_by_folio[key].append(row)
+    for key, entered in positions_by_folio.items():
+        if len(entered) > 1:
+            positions = ", ".join(str(row["index"] + 1) for row in entered)
+            errors.append(
+                f'Folio "{entered[0]["folio"]}" is entered for more than one '
+                f"image ({positions}). Each folio can be linked to one image."
+            )
+
+    folios = list(manuscript.folio_set.all())
+    folios_by_key = defaultdict(list)
+    for folio in folios:
+        key = (
+            normalize_folio_label(folio.folio_number)
+            or (folio.folio_number or "").lower()
+        )
+        if key:
+            folios_by_key[key].append(folio)
+
+    targets = {}  # folio number key -> existing folio, or None to create
+    for key, row in rows_by_folio.items():
+        matches = folios_by_key.get(key, [])
+        if len(matches) > 1:
+            numbers = ", ".join(sorted(f'"{f.folio_number}"' for f in matches))
+            errors.append(
+                f'Folio "{row["folio"]}" matches several folio records in this '
+                f"manuscript ({numbers}). Merge or renumber those folio records "
+                "first."
+            )
+        elif matches:
+            targets[key] = matches[0]
+        elif not can_create:
+            errors.append(
+                f'There is no folio record "{row["folio"]}" in this manuscript, '
+                "and you don't have permission to add folio records."
+            )
+        else:
+            targets[key] = None
+
+    if errors:
+        raise ValidationError(errors)
+
+    counts = Counter()
+    created = []
+    submitted_ids = {row["id"] for row in rows}
+    linked_folio_ids = {
+        folio.pk: rows_by_folio[key]["id"]
+        for key, folio in targets.items()
+        if folio is not None
+    }
+    with transaction.atomic():
+        # unlink first, so moving a folio to another canvas can't collide
+        # with the one-folio-per-canvas constraint
+        for folio in folios:
+            if folio.canvas_id not in submitted_ids:
+                continue
+            if linked_folio_ids.get(folio.pk) == folio.canvas_id:
+                continue
+            if folio.pk not in linked_folio_ids:
+                counts["unlinked"] += 1
+            folio.canvas_id = None
+            folio.canvas_index = None
+            folio.canvas_label = None
+            folio.image_id = None
+            folio.save(
+                update_fields=["canvas_id", "canvas_index", "canvas_label", "image_id"]
+            )
+
+        for key, folio in targets.items():
+            row = rows_by_folio[key]
+            if folio is None:
+                folio = Folio(manuscript=manuscript, folio_number=row["folio"])
+                created.append(folio)
+                counts["created"] += 1
+            elif (
+                folio.canvas_id == row["id"]
+                and folio.canvas_index == row["index"]
+                and folio.canvas_label == row["label"]
+                and folio.image_id == row["image_id"]
+            ):
+                continue
+            if folio.canvas_id != row["id"]:
+                counts["linked"] += 1
+            folio.canvas_id = row["id"]
+            folio.canvas_index = row["index"]
+            folio.canvas_label = row["label"]
+            folio.image_id = row["image_id"]
+            folio.save()
+    return counts, created
diff --git a/manuscript/tests.py b/manuscript/tests.py
index ec0ce77..7e9db80 100644
--- a/manuscript/tests.py
+++ b/manuscript/tests.py
@@ -1,14 +1,21 @@
+import json
 from io import StringIO
 from unittest import mock
 
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import Permission
+from django.core.exceptions import ValidationError
 from django.core.management import call_command
 from django.db import IntegrityError
 from django.test import SimpleTestCase, TestCase
+from django.urls import reverse
 
+from manuscript.canvas_linking import clean_canvas_rows, link_canvases
 from manuscript.models import Folio, SingleManuscript
 from manuscript.utils import get_canvases, normalize_folio_label
 
 MANIFEST_URL = "https://example.org/iiif/ms/manifest.json"
+User = get_user_model()
 
 
 def v2_canvas(number, label):
@@ -225,3 +232,186 @@ def test_canvas_unique_per_manuscript(self):
         Folio.objects.create(manuscript=self.manuscript, canvas_id=canvas_id)
         with self.assertRaises(IntegrityError):
             Folio.objects.create(manuscript=self.manuscript, canvas_id=canvas_id)
+
+
+def canvas_row(number, folio="", label=None):
+    return {
+        "id": f"https://example.org/iiif/ms/canvas/p{number:04d}",
+        "index": number - 1,
+        "label": label if label is not None else f"label {number}",
+        "image_id": f"https://example.org/image/{number}",
+        "folio": folio,
+    }
+
+
+class LinkCanvasesTest(TestCase):
+    def setUp(self):
+        self.manuscript = SingleManuscript.objects.create(
+            item_id=1, siglum="Test1", iiif_url=MANIFEST_URL
+        )
+
+    def add_folio(self, number, canvas=None):
+        folio = Folio.objects.create(manuscript=self.manuscript, folio_number=number)
+        if canvas:
+            folio.canvas_id = canvas_row(canvas)["id"]
+            folio.canvas_index = canvas - 1
+            folio.save()
+        return folio
+
+    def link(self, rows, **kwargs):
+        counts, created = link_canvases(
+            self.manuscript, clean_canvas_rows(rows), **kwargs
+        )
+        self.created = created
+        return counts
+
+    def test_links_existing_and_creates_new_folios(self):
+        folio_1r = self.add_folio("1r")
+        counts = self.link([canvas_row(1, "f. 1r"), canvas_row(2, "1v"), canvas_row(3)])
+
+        self.assertEqual(counts, {"linked": 2, "created": 1})
+        self.assertEqual([folio.folio_number for folio in self.created], ["1v"])
+        folio_1r.refresh_from_db()
+        self.assertEqual(folio_1r.folio_number, "1r")
+        self.assertEqual(folio_1r.canvas_id, canvas_row(1)["id"])
+        self.assertEqual(folio_1r.canvas_label, "label 1")
+        self.assertEqual(folio_1r.image_id, "https://example.org/image/1")
+        folio_1v = Folio.objects.get(manuscript=self.manuscript, folio_number="1v")
+        self.assertEqual(folio_1v.canvas_index, 1)
+
+    def test_clearing_unlinks_but_keeps_folio(self):
+        folio = self.add_folio("1r", canvas=1)
+        counts = self.link([canvas_row(1, ""), canvas_row(2)])
+
+        self.assertEqual(counts, {"unlinked": 1})
+        folio.refresh_from_db()
+        self.assertEqual(folio.folio_number, "1r")
+        self.assertIsNone(folio.canvas_id)
+        self.assertIsNone(folio.canvas_index)
+
+    def test_swapping_canvases(self):
+        folio_1r = self.add_folio("1r", canvas=1)
+        folio_1v = self.add_folio("1v", canvas=2)
+        counts = self.link([canvas_row(1, "1v"), canvas_row(2, "1r")])
+
+        self.assertEqual(counts, {"linked": 2})
+        folio_1r.refresh_from_db()
+        folio_1v.refresh_from_db()
+        self.assertEqual(folio_1r.canvas_index, 1)
+        self.assertEqual(folio_1v.canvas_index, 0)
+
+    def test_replacing_a_linked_folio_unlinks_it(self):
+        old = self.add_folio("1 : 1r", canvas=1)
+        new = self.add_folio("1r")
+        counts = self.link([canvas_row(1, "1r")])
+
+        self.assertEqual(counts, {"linked": 1, "unlinked": 1})
+        old.refresh_from_db()
+        new.refresh_from_db()
+        self.assertIsNone(old.canvas_id)
+        self.assertEqual(new.canvas_index, 0)
+
+    def test_no_changes(self):
+        self.add_folio("1r", canvas=1)
+        Folio.objects.filter(folio_number="1r").update(
+            canvas_label="label 1", image_id="https://example.org/image/1"
+        )
+        self.assertEqual(self.link([canvas_row(1, "1r"), canvas_row(2)]), {})
+
+    def test_leaves_links_to_canvases_not_submitted(self):
+        folio = self.add_folio("9r", canvas=9)
+        self.link([canvas_row(1, "1r")])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, canvas_row(9)["id"])
+
+    def test_same_folio_on_two_canvases_is_rejected(self):
+        folio = self.add_folio("1r", canvas=1)
+        with self.assertRaisesMessage(ValidationError, "more than one image (1, 2)"):
+            self.link(
+                [canvas_row(1, "1r"), canvas_row(2, "f. 1r"), canvas_row(3, "2r")]
+            )
+
+        # nothing was saved
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_index, 0)
+        self.assertFalse(Folio.objects.filter(folio_number="2r").exists())
+
+    def test_ambiguous_folio_number_is_rejected(self):
+        self.add_folio("197r")
+        self.add_folio("197r.")
+        with self.assertRaisesMessage(ValidationError, "matches several folio records"):
+            self.link([canvas_row(1, "197r")])
+
+    def test_creating_needs_permission(self):
+        with self.assertRaisesMessage(
+            ValidationError, "permission to add folio records"
+        ):
+            self.link([canvas_row(1, "1r")], can_create=False)
+
+    def test_bad_rows_are_rejected(self):
+        for rows in [None, [{"index": 0}], [canvas_row(1), canvas_row(1)]]:
+            with self.assertRaises(ValidationError):
+                clean_canvas_rows(rows)
+
+
+class LinkCanvasesViewTest(TestCase):
+    def setUp(self):
+        self.manuscript = SingleManuscript.objects.create(
+            item_id=1, siglum="Test1", iiif_url=MANIFEST_URL
+        )
+        self.url = reverse(
+            "admin:manuscript_singlemanuscript_canvases", args=[self.manuscript.pk]
+        )
+        self.user = User.objects.create_superuser("admin", "admin@example.org", "pw")
+        self.client.force_login(self.user)
+
+    def test_page_lists_folios(self):
+        Folio.objects.create(manuscript=self.manuscript, folio_number="1r")
+        response = self.client.get(self.url)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, 'id="canvas-folios"')
+        self.assertContains(response, '"number": "1r"')
+
+    def test_change_form_links_to_page(self):
+        response = self.client.get(
+            reverse(
+                "admin:manuscript_singlemanuscript_change", args=[self.manuscript.pk]
+            )
+        )
+        self.assertContains(response, self.url)
+
+    def test_saving(self):
+        rows = json.dumps([canvas_row(1, "1r"), canvas_row(2)])
+        response = self.client.post(self.url, {"rows": rows})
+
+        self.assertRedirects(response, self.url, fetch_redirect_response=False)
+        folio = Folio.objects.get(manuscript=self.manuscript, folio_number="1r")
+        self.assertEqual(folio.canvas_index, 0)
+
+    def test_saving_lists_new_folios_needing_line_ranges(self):
+        rows = json.dumps([canvas_row(1, "1r"), canvas_row(2)])
+        response = self.client.post(self.url, {"rows": rows}, follow=True)
+
+        folio = Folio.objects.get(manuscript=self.manuscript, folio_number="1r")
+        folio_url = reverse("admin:manuscript_folio_change", args=[folio.pk])
+        self.assertContains(response, "Add a line range to the new folio records")
+        self.assertContains(response, f'<a href="{folio_url}">1r</a>', html=True)
+
+    def test_errors_keep_entries(self):
+        rows = json.dumps([canvas_row(1, "1r"), canvas_row(2, "1r")])
+        response = self.client.post(self.url, {"rows": rows})
+
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "more than one image")
+        self.assertEqual(response.context["submitted"][canvas_row(2)["id"]], "1r")
+        self.assertFalse(Folio.objects.exists())
+
+    def test_needs_folio_permission(self):
+        staff = User.objects.create_user("staff", password="pw", is_staff=True)
+        staff.user_permissions.add(
+            Permission.objects.get(codename="change_singlemanuscript")
+        )
+        self.client.force_login(staff)
+        self.assertEqual(self.client.get(self.url).status_code, 403)
diff --git a/static/js/canvas_linking.js b/static/js/canvas_linking.js
new file mode 100644
index 0000000..c70806f
--- /dev/null
+++ b/static/js/canvas_linking.js
@@ -0,0 +1,458 @@
+// canvas_linking.js - Admin page for linking a manuscript's folios to its IIIF canvases
+(function () {
+  const readJson = (id) => JSON.parse(document.getElementById(id).textContent);
+  const folios = readJson('canvas-folios');
+  const submitted = readJson('canvas-submitted');
+  const manifestUrl = readJson('canvas-manifest-url');
+  const canCreate = readJson('canvas-can-create');
+
+  const form = document.getElementById('canvas-form');
+  const statusEl = document.getElementById('canvas-status');
+  const noticesEl = document.getElementById('canvas-notices');
+  const tbody = document.querySelector('#canvas-table tbody');
+  const summaryEl = document.getElementById('canvas-summary');
+  const filterEl = document.getElementById('canvas-filter');
+  const saveButton = document.getElementById('canvas-save');
+  const fillButton = document.getElementById('canvas-fill');
+  const viewer = document.getElementById('canvas-viewer');
+  const viewerTitle = document.getElementById('canvas-viewer-title');
+  const viewerFrame = viewer.querySelector('.canvas-viewer-image');
+  const viewerImage = viewerFrame.querySelector('img');
+  const viewerFull = document.getElementById('canvas-viewer-full');
+
+  // Same normalization as manuscript.utils.normalize_folio_label, so that
+  // e.g. "Carta: 12 recto", "f. 12r" and "12r" are treated as the same folio
+  const FOLIO_LABEL_PREFIX = /^(?:carta|folio|fol|ff|f|c)\s*[.:]?\s*(?=\d)/;
+  const RECTO_VERSO = /^(\d+|[ivxlc]+)[rv]$/;
+  function normalizeFolioLabel(label) {
+    if (!label) return '';
+    let value = label.trim().toLowerCase();
+    value = value.replace(/\brecto\b/g, 'r').replace(/\bverso\b/g, 'v');
+    value = value.replace(FOLIO_LABEL_PREFIX, '');
+    return value.replace(/[\s.]/g, '');
+  }
+  const folioKey = (number) => normalizeFolioLabel(number) || number.trim().toLowerCase();
+
+  // Flatten a IIIF v2 or v3 label into a plain string
+  function labelToString(label) {
+    if (!label) return '';
+    if (typeof label === 'string') return label;
+    if (Array.isArray(label)) return label.map(labelToString).join(' ');
+    if (label['@value']) return String(label['@value']);
+    return Object.values(label).map(labelToString).join(' ');
+  }
+
+  function serviceId(service) {
+    if (Array.isArray(service)) service = service[0];
+    return service ? service['@id'] || service.id : null;
+  }
+
+  function thumbnailId(thumbnail) {
+    if (Array.isArray(thumbnail)) thumbnail = thumbnail[0];
+    if (!thumbnail) return null;
+    return typeof thumbnail === 'string' ? thumbnail : thumbnail['@id'] || thumbnail.id;
+  }
+
+  // Canvases of a IIIF v2 or v3 manifest, matching manuscript.utils.get_canvases
+  function getCanvases(manifest) {
+    const raw = manifest.sequences ? manifest.sequences[0].canvases || [] : manifest.items || [];
+    return raw.map((canvas, index) => {
+      let resource = null;
+      if (canvas.images && canvas.images.length) {
+        resource = canvas.images[0].resource || null;
+      } else if (canvas.items && canvas.items.length) {
+        try {
+          resource = canvas.items[0].items[0].body;
+          if (Array.isArray(resource)) resource = resource[0];
+        } catch (e) {
+          resource = null;
+        }
+      }
+      const imageService = resource ? serviceId(resource.service) : null;
+      const resourceId = resource ? resource['@id'] || resource.id : null;
+      return {
+        index,
+        id: canvas['@id'] || canvas.id,
+        label: labelToString(canvas.label).trim(),
+        image_id: imageService || resourceId || null,
+        thumbnail: imageService
+          ? `${imageService}/full/!200,200/0/default.jpg`
+          : thumbnailId(canvas.thumbnail) || resourceId,
+        large: imageService ? `${imageService}/full/!1200,1200/0/default.jpg` : resourceId,
+        // some manifests' resource IDs aren't images, so prefer the image service
+        full: imageService ? `${imageService}/full/max/0/default.jpg` : resourceId,
+      };
+    });
+  }
+
+  const foliosByCanvas = new Map();
+  const foliosByKey = new Map();
+  for (const folio of folios) {
+    if (folio.canvas_id) foliosByCanvas.set(folio.canvas_id, folio);
+    if (!folio.number) continue;
+    const key = folioKey(folio.number);
+    if (!foliosByKey.has(key)) foliosByKey.set(key, []);
+    foliosByKey.get(key).push(folio);
+  }
+
+  let rows = [];
+  let canvasPositions = new Map();
+  let dirty = false;
+  let fillNote = '';
+
+  // the text can only turn to folios with both ends of a line range
+  const hasLineRange = (folio) => !!(folio.line_start && folio.line_end);
+
+  function folioDetails(folio) {
+    const details = [];
+    if (folio.line_start) details.push(`lines ${folio.line_start} → ${folio.line_end || 'end'}`);
+    if (folio.toponyms) details.push(`${folio.toponyms} toponym${folio.toponyms === 1 ? '' : 's'}`);
+    return details.join(' · ');
+  }
+
+  function canvasName(canvasId) {
+    return canvasPositions.has(canvasId)
+      ? `image ${canvasPositions.get(canvasId) + 1}`
+      : 'an image no longer in the manifest';
+  }
+
+  function addNote(row, text, kind = '') {
+    const note = document.createElement('span');
+    note.className = `canvas-note ${kind ? 'is-' + kind : ''}`;
+    note.textContent = text;
+    row.notesEl.appendChild(note);
+  }
+
+  // Work out what saving would do for each row, and flag conflicts
+  function update() {
+    const entriesByKey = new Map();
+    for (const row of rows) {
+      const value = row.input.value.trim();
+      if (!value) continue;
+      const key = folioKey(value);
+      if (!entriesByKey.has(key)) entriesByKey.set(key, []);
+      entriesByKey.get(key).push(row);
+    }
+
+    let linked = 0;
+    let changed = 0;
+    let problems = 0;
+    for (const row of rows) {
+      const value = row.input.value.trim();
+      const current = foliosByCanvas.get(row.canvas.id);
+      row.notesEl.replaceChildren();
+      if (row.suggestion) row.suggestion.hidden = !!value;
+      row.isChanged = false;
+      row.hasProblem = false;
+
+      if (!value) {
+        if (current) {
+          row.isChanged = true;
+          addNote(row, `Will unlink folio ${current.number}.`);
+        }
+      } else {
+        const key = folioKey(value);
+        const matches = foliosByKey.get(key) || [];
+        const sameEntry = entriesByKey.get(key).filter((other) => other !== row);
+        if (sameEntry.length) {
+          row.hasProblem = true;
+          const images = sameEntry.map((other) => other.canvas.index + 1).join(', ');
+          addNote(row, `Also entered for image ${images}. Each folio can be linked to one image.`, 'problem');
+        }
+        if (matches.length > 1) {
+          row.hasProblem = true;
+          const numbers = matches.map((folio) => `"${folio.number}"`).join(', ');
+          addNote(row, `Matches several folio records (${numbers}). Merge or renumber those folio records first.`, 'problem');
+        } else if (matches.length === 1) {
+          const folio = matches[0];
+          if (current && current.id === folio.id) {
+            linked += 1;
+            addNote(row, `Linked to folio ${folio.number}.`, 'info');
+          } else {
+            row.isChanged = true;
+            if (folio.canvas_id && folio.canvas_id !== row.canvas.id) {
+              addNote(row, `Will move folio ${folio.number} here from ${canvasName(folio.canvas_id)}.`);
+            } else {
+              addNote(row, `Will link folio ${folio.number}.`);
+            }
+            if (current) addNote(row, `Will unlink folio ${current.number}.`);
+          }
+          const details = folioDetails(folio);
+          if (details) addNote(row, details, 'info');
+          if (!hasLineRange(folio)) {
+            addNote(row, "This folio record has no line range.", 'warning');
+          }
+        } else if (!canCreate) {
+          row.hasProblem = true;
+          addNote(row, `There is no folio record "${value}", and you don't have permission to add folio records.`, 'problem');
+        } else {
+          row.isChanged = true;
+          addNote(row, `Will create a new folio record "${value}".`);
+          addNote(row, "It will need a line range before the text can turn to this image.", 'warning');
+          if (current) addNote(row, `Will unlink folio ${current.number}.`);
+        }
+      }
+
+      if (row.labelCount > 1) {
+        addNote(row, `The manifest label "${row.canvas.label}" appears on ${row.labelCount} images.`, 'info');
+      }
+      row.tr.classList.toggle('is-changed', row.isChanged && !row.hasProblem);
+      row.tr.classList.toggle('has-problem', row.hasProblem);
+      if (row.isChanged) changed += 1;
+      if (row.hasProblem) problems += 1;
+    }
+
+    summaryEl.textContent =
+      `${rows.length} images · ${linked} linked · ${changed} unsaved change${changed === 1 ? '' : 's'}` +
+      (problems ? ` · ${problems} with problems` : '') +
+      fillNote;
+    saveButton.disabled = problems > 0;
+    saveButton.title = problems ? 'Fix the problems shown in red before saving' : '';
+    applyFilter();
+  }
+
+  function applyFilter() {
+    const filter = filterEl.value;
+    for (const row of rows) {
+      const isLinked = !!foliosByCanvas.get(row.canvas.id);
+      row.tr.hidden =
+        (filter === 'linked' && !isLinked) ||
+        (filter === 'unlinked' && isLinked) ||
+        (filter === 'changed' && !row.isChanged) ||
+        (filter === 'problem' && !row.hasProblem);
+    }
+  }
+
+  function buildRow(canvas, labelCounts) {
+    const tr = document.createElement('tr');
+    const current = foliosByCanvas.get(canvas.id);
+
+    const position = document.createElement('td');
+    position.className = 'canvas-position';
+    position.textContent = canvas.index + 1;
+
+    const thumb = document.createElement('td');
+    thumb.className = 'canvas-thumb';
+    if (canvas.thumbnail) {
+      const link = document.createElement('a');
+      link.href = canvas.large || canvas.thumbnail;
+      link.className = 'canvas-thumb-frame is-loading';
+      link.title = 'View larger';
+      const img = document.createElement('img');
+      img.loading = 'lazy';
+      img.alt = `Image ${canvas.index + 1}`;
+      img.addEventListener('load', () => link.classList.remove('is-loading'));
+      img.addEventListener('error', () => {
+        link.classList.remove('is-loading');
+        link.classList.add('is-broken');
+        link.replaceChildren('No image');
+      });
+      img.src = canvas.thumbnail;
+      link.appendChild(img);
+      link.addEventListener('click', (event) => {
+        // open in a new tab as usual with a modifier key or middle click
+        if (event.metaKey || event.ctrlKey || event.shiftKey || link.classList.contains('is-broken')) return;
+        event.preventDefault();
+        openViewer(canvas);
+      });
+      thumb.appendChild(link);
+    }
+
+    const label = document.createElement('td');
+    label.textContent = canvas.label;
+
+    const folioCell = document.createElement('td');
+    folioCell.className = 'canvas-folio';
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.setAttribute('list', 'canvas-folio-numbers');
+    input.setAttribute('aria-label', `Folio number for image ${canvas.index + 1}`);
+    const initial = current ? current.number : '';
+    input.value = submitted && canvas.id in submitted ? submitted[canvas.id] : initial;
+    if (submitted && input.value !== initial) dirty = true;
+    folioCell.appendChild(input);
+
+    // offer the manifest label as the folio number when it looks like one
+    let suggestion = null;
+    if (RECTO_VERSO.test(normalizeFolioLabel(canvas.label))) {
+      suggestion = document.createElement('button');
+      suggestion.type = 'button';
+      suggestion.className = 'canvas-suggestion';
+      suggestion.textContent = `Use ${canvas.label}`;
+      suggestion.title = 'Use the manifest label as the folio number';
+      suggestion.addEventListener('click', () => {
+        input.value = canvas.label;
+        input.dispatchEvent(new Event('input'));
+        input.focus();
+      });
+      folioCell.appendChild(suggestion);
+    }
+    if (current) {
+      const link = document.createElement('a');
+      link.href = current.admin_url;
+      link.textContent = 'Edit folio record';
+      link.style.marginLeft = '0.5em';
+      folioCell.appendChild(link);
+    }
+
+    const notesEl = document.createElement('td');
+
+    tr.append(position, thumb, label, folioCell, notesEl);
+    const row = {
+      canvas,
+      tr,
+      input,
+      suggestion,
+      notesEl,
+      labelCount: labelCounts.get(normalizeFolioLabel(canvas.label)) || 0,
+      isChanged: false,
+      hasProblem: false,
+    };
+    input.addEventListener('input', () => {
+      dirty = true;
+      update();
+    });
+    return row;
+  }
+
+  function showNotices(canvases) {
+    const canvasIds = new Set(canvases.map((canvas) => canvas.id));
+    const notices = [
+      [
+        'Folio records not linked to an image: ',
+        folios.filter((folio) => !folio.canvas_id),
+      ],
+      [
+        "Linked Folio records without a line range: ",
+        folios
+          .filter((folio) => canvasIds.has(folio.canvas_id) && !hasLineRange(folio))
+          .sort((a, b) => canvasPositions.get(a.canvas_id) - canvasPositions.get(b.canvas_id)),
+      ],
+      [
+        'Folio records linked to images no longer in the manifest: ',
+        folios.filter((folio) => folio.canvas_id && !canvasIds.has(folio.canvas_id)),
+      ],
+    ];
+    for (const [text, list] of notices) {
+      if (!list.length) continue;
+      const p = document.createElement('p');
+      p.className = 'canvas-notice';
+      p.append(text);
+      list.forEach((folio, i) => {
+        if (i) p.append(', ');
+        const link = document.createElement('a');
+        link.href = folio.admin_url;
+        link.textContent = folio.number || `(no number, #${folio.id})`;
+        p.appendChild(link);
+      });
+      noticesEl.appendChild(p);
+    }
+  }
+
+  async function load() {
+    let canvases;
+    try {
+      const response = await fetch(manifestUrl);
+      if (!response.ok) throw new Error(`the server responded ${response.status}`);
+      canvases = getCanvases(await response.json());
+    } catch (error) {
+      statusEl.textContent = `Could not load the IIIF manifest (${error.message}).`;
+      statusEl.classList.add('canvas-status-error');
+      return;
+    }
+    if (!canvases.length) {
+      statusEl.textContent = 'The IIIF manifest has no images.';
+      statusEl.classList.add('canvas-status-error');
+      return;
+    }
+
+    canvasPositions = new Map(canvases.map((canvas) => [canvas.id, canvas.index]));
+    const labelCounts = new Map();
+    for (const canvas of canvases) {
+      const key = normalizeFolioLabel(canvas.label);
+      labelCounts.set(key, (labelCounts.get(key) || 0) + 1);
+    }
+    rows = canvases.map((canvas) => buildRow(canvas, labelCounts));
+    tbody.append(...rows.map((row) => row.tr));
+    showNotices(canvases);
+    statusEl.hidden = true;
+    form.hidden = false;
+    update();
+  }
+
+  filterEl.addEventListener('change', applyFilter);
+
+  // Larger view of an image, in a dialog over the page
+  function openViewer(canvas) {
+    const folio = foliosByCanvas.get(canvas.id);
+    viewerTitle.textContent =
+      `Image ${canvas.index + 1}` +
+      (canvas.label ? ` · manifest label "${canvas.label}"` : '') +
+      (folio ? ` · linked to folio ${folio.number}` : '');
+    viewerFrame.classList.add('is-loading');
+    viewerImage.removeAttribute('src');
+    viewerImage.alt = `Image ${canvas.index + 1}`;
+    viewerImage.src = canvas.large || canvas.thumbnail;
+    viewerFull.href = canvas.full || canvas.large || canvas.thumbnail;
+    viewer.showModal();
+  }
+  viewerImage.addEventListener('load', () => viewerFrame.classList.remove('is-loading'));
+  viewerImage.addEventListener('error', () => viewerFrame.classList.remove('is-loading'));
+  document.getElementById('canvas-viewer-close').addEventListener('click', () => viewer.close());
+  // close when clicking the backdrop around the dialog
+  viewer.addEventListener('click', (event) => {
+    if (event.target === viewer) viewer.close();
+  });
+
+  // Same rules as the link_folio_canvases command: fill in an empty image
+  // whose recto/verso label appears once in the manifest and matches exactly
+  // one folio that isn't linked to an image or entered elsewhere
+  fillButton.addEventListener('click', () => {
+    const entered = new Set(
+      rows.map((row) => row.input.value.trim()).filter(Boolean).map(folioKey),
+    );
+    let filled = 0;
+    for (const row of rows) {
+      if (row.input.value.trim() || row.labelCount !== 1) continue;
+      const key = normalizeFolioLabel(row.canvas.label);
+      if (!RECTO_VERSO.test(key) || entered.has(key)) continue;
+      const matches = foliosByKey.get(key) || [];
+      if (matches.length !== 1 || matches[0].canvas_id) continue;
+      row.input.value = matches[0].number;
+      entered.add(key);
+      filled += 1;
+    }
+    if (filled) {
+      dirty = true;
+      filterEl.value = 'changed';
+    }
+    fillNote = ` · filled in ${filled} image${filled === 1 ? '' : 's'}`;
+    update();
+  });
+
+  form.addEventListener('submit', (event) => {
+    if (saveButton.disabled) {
+      event.preventDefault();
+      return;
+    }
+    document.getElementById('canvas-rows').value = JSON.stringify(
+      rows.map((row) => ({
+        id: row.canvas.id,
+        index: row.canvas.index,
+        label: row.canvas.label,
+        image_id: row.canvas.image_id,
+        folio: row.input.value.trim(),
+      })),
+    );
+    dirty = false;
+  });
+
+  window.addEventListener('beforeunload', (event) => {
+    if (dirty && rows.some((row) => row.isChanged)) {
+      event.preventDefault();
+      event.returnValue = '';
+    }
+  });
+
+  load();
+})();
diff --git a/templates/admin/manuscript/singlemanuscript/change_form.html b/templates/admin/manuscript/singlemanuscript/change_form.html
new file mode 100644
index 0000000..7e0be83
--- /dev/null
+++ b/templates/admin/manuscript/singlemanuscript/change_form.html
@@ -0,0 +1,8 @@
+{% extends "admin/import_export/change_form.html" %}
+
+{% block object-tools-items %}
+  {% if original.pk and original.iiif_url %}
+    <li><a href="{% url 'admin:manuscript_singlemanuscript_canvases' original.pk %}">Link IIIF canvases</a></li>
+  {% endif %}
+  {{ block.super }}
+{% endblock %}
diff --git a/templates/admin/manuscript/singlemanuscript/link_canvases.html b/templates/admin/manuscript/singlemanuscript/link_canvases.html
new file mode 100644
index 0000000..da5fc08
--- /dev/null
+++ b/templates/admin/manuscript/singlemanuscript/link_canvases.html
@@ -0,0 +1,152 @@
+{% extends "admin/base_site.html" %}
+{% load static %}
+
+{% block extrastyle %}
+  {{ block.super }}
+  <style>
+    .canvas-help { max-width: 60em; margin-bottom: 1em; }
+    .canvas-toolbar { display: flex; flex-wrap: wrap; gap: 1em; align-items: center; margin: 1em 0; }
+    .canvas-toolbar label { font-weight: normal; }
+    .canvas-notice { margin: 0.5em 0; }
+    .canvas-status-error { color: var(--error-fg, #ba2121); }
+    #canvas-table { width: 100%; }
+    #canvas-table td { vertical-align: middle; }
+    #canvas-table .canvas-position { width: 3em; text-align: right; }
+    #canvas-table .canvas-thumb { width: 110px; }
+    .canvas-thumb-frame { position: relative; display: flex; align-items: center; justify-content: center; width: 100px; height: 100px; cursor: zoom-in; }
+    .canvas-thumb-frame img { max-width: 100px; max-height: 100px; display: block; }
+    .canvas-thumb-frame.is-broken { cursor: default; color: var(--body-quiet-color, #666); font-size: 0.75rem; }
+    .is-loading img { opacity: 0; }
+    .is-loading::after {
+      content: ""; position: absolute; top: 50%; left: 50%; width: 20px; height: 20px; margin: -12px 0 0 -12px;
+      border: 2px solid var(--hairline-color, #ddd); border-top-color: var(--link-fg, #447e9b);
+      border-radius: 50%; animation: canvas-spin 0.8s linear infinite;
+    }
+    @keyframes canvas-spin { to { transform: rotate(360deg); } }
+    #canvas-viewer { padding: 0; border: none; border-radius: 4px; max-width: 92vw; max-height: 92vh; background: var(--body-bg, #fff); color: var(--body-fg, #333); }
+    #canvas-viewer::backdrop { background: rgba(0, 0, 0, 0.6); }
+    #canvas-viewer header { display: flex; justify-content: space-between; align-items: center; gap: 1em; padding: 8px 12px; border-bottom: 1px solid var(--hairline-color, #ddd); }
+    #canvas-viewer .canvas-viewer-image { position: relative; display: flex; align-items: center; justify-content: center; min-width: 300px; min-height: 300px; padding: 8px; }
+    #canvas-viewer .canvas-viewer-image img { display: block; max-width: calc(92vw - 16px); max-height: calc(92vh - 100px); }
+    #canvas-viewer footer { padding: 6px 12px 10px; font-size: 0.8125rem; }
+    #canvas-table .canvas-folio input { width: 9em; }
+    #canvas-table .canvas-suggestion { margin-left: 0.5em; font-size: 0.8125rem; padding: 2px 6px; cursor: pointer; }
+    #canvas-table tr.is-changed td { background: var(--selected-row, #ffc); }
+    #canvas-table tr.has-problem td { background: var(--message-error-bg, #ffefef); }
+    #canvas-table .canvas-note { display: block; }
+    #canvas-table .canvas-note.is-problem { color: var(--error-fg, #ba2121); font-weight: bold; }
+    #canvas-table .canvas-note.is-info { color: var(--body-quiet-color, #666); }
+    #canvas-table .canvas-note.is-warning { color: #9a6700; }
+  </style>
+{% endblock %}
+
+{% block breadcrumbs %}
+  <div class="breadcrumbs">
+    <a href="{% url 'admin:index' %}">Home</a>
+    &rsaquo; <a href="{% url 'admin:app_list' app_label=opts.app_label %}">{{ opts.app_config.verbose_name }}</a>
+    &rsaquo; <a href="{% url 'admin:manuscript_singlemanuscript_changelist' %}">{{ opts.verbose_name_plural|capfirst }}</a>
+    &rsaquo; <a href="{{ change_url }}">{{ manuscript }}</a>
+    &rsaquo; Link IIIF canvases
+  </div>
+{% endblock %}
+
+{% block content %}
+  <div id="content-main">
+    <div class="canvas-help">
+      <p>
+        This page allows you to connect pages from a IIIF manifest to folios in the manuscript, such
+        that the IIIF manifest will automatically change pages as users read the manuscript.
+      </p>
+      <p>
+        How it works:
+        <ul>
+          <li>Each row is one image (canvas) from this manuscript's <a href="{{ manuscript.iiif_url }}" target="_blank" rel="noopener">IIIF manifest</a>.</li>
+          <li>Look at the image, work out which folio of the manuscript it shows, and enter that folio's
+number (for example 12r) to link the image to the text.</li>
+          <li>You can click each image to see it larger.</li>
+          <li>For a quick start, use <strong>Fill in folio numbers from manifest labels</strong>: it copies an
+          image's manifest label into its empty folio number box when the label appears only once in the
+          manifest and matches a Folio record that isn't linked yet. Check the results before saving.</li>
+          <li>Clear a folio number to unlink it.</li>
+          <li>Use the <strong>Show</strong> menu to narrow the list, for example to images not linked yet, your
+          unsaved changes, or rows with problems that need fixing before you can save.</li>
+          <li>Use the Save button at the bottom of the page to save your changes when finished.</li>
+          <li>A Folio record also needs a line range before the text can turn to its image. Add it on the
+          Folio record's own page after saving.</li>
+        </ul>
+        Note that the IIIF institution's own label for each image is shown under "Manifest label" for reference only; it may be wrong or repeated.
+      </p>
+      <p>
+        Note also that this page only handles which Folio record is linked to which image. Folio records are never
+        renamed or deleted here, so their toponyms stay attached; to correct a folio number itself,
+        edit the Folio record.
+        {% if can_create %}Entering a folio number that has no Folio record yet will create a new one on save.{% endif %}
+      </p>
+    </div>
+
+    <p id="canvas-status">Loading the IIIF manifest…</p>
+    <div id="canvas-notices"></div>
+
+    <form id="canvas-form" method="post" hidden>
+      {% csrf_token %}
+      <input type="hidden" name="rows" id="canvas-rows">
+
+      <div class="canvas-toolbar">
+        <label>
+          Show
+          <select id="canvas-filter">
+            <option value="all">all images</option>
+            <option value="linked">linked images</option>
+            <option value="unlinked">images not linked</option>
+            <option value="changed">unsaved changes</option>
+            <option value="problem">problems</option>
+          </select>
+        </label>
+        <button type="button" class="button" id="canvas-fill"
+                title="For each image without a folio number, use its manifest label as the folio number if the label isn't repeated in the manifest and matches exactly one Folio record that isn't linked to an image yet. Nothing is saved until you click Save.">
+          Fill in folio numbers from manifest labels
+        </button>
+        <span id="canvas-summary"></span>
+      </div>
+
+      <div class="module">
+        <table id="canvas-table">
+          <thead>
+            <tr>
+              <th scope="col" class="canvas-position">#</th>
+              <th scope="col">Image</th>
+              <th scope="col">Manifest label</th>
+              <th scope="col">Folio number</th>
+              <th scope="col">Notes</th>
+            </tr>
+          </thead>
+          <tbody></tbody>
+        </table>
+      </div>
+
+      <datalist id="canvas-folio-numbers">
+        {% for folio in folios %}{% if folio.number %}<option value="{{ folio.number }}">{% endif %}{% endfor %}
+      </datalist>
+
+      <div class="submit-row">
+        <input type="submit" value="Save" class="default" id="canvas-save">
+        <a href="{{ change_url }}" class="closelink">Cancel</a>
+      </div>
+    </form>
+  </div>
+
+  <dialog id="canvas-viewer" aria-labelledby="canvas-viewer-title">
+    <header>
+      <strong id="canvas-viewer-title"></strong>
+      <button type="button" class="button" id="canvas-viewer-close">Close</button>
+    </header>
+    <div class="canvas-viewer-image"><img alt=""></div>
+    <footer><a id="canvas-viewer-full" target="_blank" rel="noopener">Open full size in a new tab</a></footer>
+  </dialog>
+
+  {{ folios|json_script:"canvas-folios" }}
+  {{ submitted|json_script:"canvas-submitted" }}
+  {{ manuscript.iiif_url|json_script:"canvas-manifest-url" }}
+  {{ can_create|json_script:"canvas-can-create" }}
+  <script src="{% static 'js/canvas_linking.js' %}"></script>
+{% endblock %}

From ff32452809a552cce8ad649b3c176d79a6b7b19a Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Wed, 21 Oct 2026 11:41:33 -0700
Subject: [PATCH 03/13] Improve folio admin pages and canvas links

---
 manuscript/admin.py                           | 106 +++++++++-
 manuscript/tests.py                           | 184 +++++++++++++++++-
 static/js/canvas_linking.js                   |  20 ++
 .../singlemanuscript/link_canvases.html       |   1 +
 4 files changed, 305 insertions(+), 6 deletions(-)

diff --git a/manuscript/admin.py b/manuscript/admin.py
index 061968c..5b89591 100644
--- a/manuscript/admin.py
+++ b/manuscript/admin.py
@@ -82,12 +82,59 @@ def clean(self):
         return cleaned_data
 
 
-class FolioInline(admin.StackedInline):
+def linked_image_link(folio, thumbnail=False):
+    """Link to a folio's row on the canvas linking page, labelled with the
+    linked image's position and manifest label"""
+    url = reverse(
+        "admin:manuscript_singlemanuscript_canvases", args=[folio.manuscript_id]
+    )
+    if not folio.canvas_id:
+        return format_html('<a href="{}">Not linked</a>', url)
+    position = (
+        f"Image {folio.canvas_index + 1}" if folio.canvas_index is not None else "Image"
+    )
+    label = f" · {folio.canvas_label}" if folio.canvas_label else ""
+    image = ""
+    if thumbnail and folio.image_id:
+        # image_id is usually a IIIF image service; drop the preview if not
+        image = format_html(
+            '<img src="{}/full/!200,200/0/default.jpg" alt="" loading="lazy" '
+            'style="display: block; max-width: 200px; max-height: 200px; '
+            'margin-bottom: 4px;" onerror="this.remove()">',
+            folio.image_id,
+        )
+    # the canvas linking page scrolls to and highlights this folio's row
+    return format_html(
+        '<a href="{}#folio-{}">{}{}{}</a>', url, folio.pk, image, position, label
+    )
+
+
+class FolioInline(admin.TabularInline):
+    """Compact list of a manuscript's folios for editing folio numbers and line
+    ranges. Other details are edited on each folio's own page, and images are
+    linked on the Link IIIF canvases page. Folios aren't added or deleted here:
+    deleting a folio also deletes its toponym aliases."""
+
     model = Folio
-    form = FolioAdminForm
     classes = ("collapse",)
-    extra = 1
-    readonly_fields = ("canvas_index", "canvas_label", "image_id")
+    extra = 0
+    can_delete = False
+    show_change_link = True
+    fields = (
+        "folio_number",
+        "line_code_range_start",
+        "line_code_range_end",
+        "linked_image",
+    )
+    readonly_fields = ("linked_image",)
+    ordering = ("canvas_index", "folio_number")
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+    @admin.display(description="Linked image")
+    def linked_image(self, folio):
+        return linked_image_link(folio)
 
 
 class DetailInline(admin.StackedInline):
@@ -441,9 +488,11 @@ class FolioAdmin(ImportExportModelAdmin):
         "stanza_list",
         "line_range_display",
         "stanza_count",
+        "linked_image",
         "canvas_index",
         "canvas_label",
         "image_id",
+        "toponym_list",
     ]
 
     fieldsets = (
@@ -451,7 +500,8 @@ class FolioAdmin(ImportExportModelAdmin):
         (
             "IIIF Canvas",
             {
-                "fields": ("canvas_id", "canvas_label", "canvas_index", "image_id"),
+                # the linked image shows the canvas position, counting from 1
+                "fields": ("linked_image", "canvas_id", "canvas_label", "image_id"),
             },
         ),
         (
@@ -470,8 +520,54 @@ class FolioAdmin(ImportExportModelAdmin):
                 "fields": ("stanza_count", "stanza_list"),
             },
         ),
+        ("Toponyms", {"fields": ("toponym_list",)}),
+        ("Notes", {"fields": ("folio_includes_map", "folio_notes")}),
     )
 
+    @admin.display(description="Linked image")
+    def linked_image(self, obj):
+        if not obj.pk or not obj.manuscript_id:
+            return "-"
+        return linked_image_link(obj, thumbnail=True)
+
+    @admin.display(description="Toponym aliases on this folio")
+    def toponym_list(self, obj):
+        if not obj.pk:
+            return "-"
+        aliases = obj.locationalias_set.select_related("location").order_by(
+            "placename_alias", "id"
+        )
+        if not aliases:
+            return "None"
+        rows = []
+        for alias in aliases:
+            if alias.location:
+                location = alias.location
+                name = location.name or location.placename_modern or ""
+                toponym = format_html(
+                    '<a href="{}">{}</a> {}',
+                    reverse("admin:manuscript_location_change", args=[location.pk]),
+                    name or location.placename_id,
+                    f"({location.placename_id})" if name else "",
+                )
+            else:
+                toponym = "-"
+            rows.append(
+                (
+                    reverse("admin:manuscript_locationalias_change", args=[alias.pk]),
+                    alias.placename_alias or f"Alias {alias.pk}",
+                    toponym,
+                )
+            )
+        return format_html(
+            '<div style="max-height: 400px; overflow-y: auto;">'
+            '<table style="width: 100%;"><tr><th>Alias</th><th>Toponym</th></tr>'
+            "{}</table></div>",
+            format_html_join(
+                "", '<tr><td><a href="{}">{}</a></td><td>{}</td></tr>', rows
+            ),
+        )
+
     def stanza_count(self, obj):
         return obj.stanzas.count()
 
diff --git a/manuscript/tests.py b/manuscript/tests.py
index 7e9db80..efa85d8 100644
--- a/manuscript/tests.py
+++ b/manuscript/tests.py
@@ -11,7 +11,7 @@
 from django.urls import reverse
 
 from manuscript.canvas_linking import clean_canvas_rows, link_canvases
-from manuscript.models import Folio, SingleManuscript
+from manuscript.models import Folio, Location, LocationAlias, SingleManuscript
 from manuscript.utils import get_canvases, normalize_folio_label
 
 MANIFEST_URL = "https://example.org/iiif/ms/manifest.json"
@@ -382,6 +382,66 @@ def test_change_form_links_to_page(self):
         )
         self.assertContains(response, self.url)
 
+    def test_change_form_lists_folios_compactly(self):
+        folio = Folio.objects.create(
+            manuscript=self.manuscript,
+            folio_number="1r",
+            canvas_id=canvas_row(3)["id"],
+            canvas_index=2,
+            canvas_label="Carta: 1r",
+        )
+        response = self.client.get(
+            reverse(
+                "admin:manuscript_singlemanuscript_change", args=[self.manuscript.pk]
+            )
+        )
+        self.assertContains(response, 'name="folio_set-0-line_code_range_start"')
+        self.assertContains(
+            response, f'{self.url}#folio-{folio.pk}">Image 3 · Carta: 1r'
+        )
+        self.assertContains(
+            response, reverse("admin:manuscript_folio_change", args=[folio.pk])
+        )
+        self.assertNotContains(response, 'name="folio_set-0-canvas_id"')
+        self.assertNotContains(response, 'name="folio_set-0-DELETE"')
+        self.assertNotContains(response, 'name="folio_set-__prefix__-folio_number"')
+
+    def test_folio_page_shows_image_and_toponyms(self):
+        folio = Folio.objects.create(
+            manuscript=self.manuscript,
+            folio_number="1r",
+            canvas_id=canvas_row(3)["id"],
+            canvas_index=2,
+            canvas_label="Carta: 1r",
+            image_id="https://example.org/image/3",
+        )
+        location = Location.objects.create(placename_id="T001", name="Rodi")
+        LocationAlias.objects.create(
+            placename_alias="Rhodes",
+            location=location,
+            manuscript=self.manuscript,
+            folio=folio,
+        )
+        response = self.client.get(
+            reverse("admin:manuscript_folio_change", args=[folio.pk])
+        )
+        self.assertContains(response, f"{self.url}#folio-{folio.pk}")
+        self.assertContains(response, "https://example.org/image/3/full/!200,200/")
+        self.assertContains(response, "Image 3 · Carta: 1r")
+        self.assertContains(response, "Rhodes")
+        self.assertContains(
+            response, reverse("admin:manuscript_location_change", args=[location.pk])
+        )
+        self.assertContains(response, "Rodi</a> (T001)")
+
+    def test_folio_page_edits_notes(self):
+        folio = Folio.objects.create(manuscript=self.manuscript, folio_number="1r")
+        response = self.client.get(
+            reverse("admin:manuscript_folio_change", args=[folio.pk])
+        )
+        self.assertContains(response, 'name="folio_includes_map"')
+        self.assertContains(response, 'name="folio_notes"')
+
     def test_saving(self):
         rows = json.dumps([canvas_row(1, "1r"), canvas_row(2)])
         response = self.client.post(self.url, {"rows": rows})
@@ -415,3 +475,125 @@ def test_needs_folio_permission(self):
         )
         self.client.force_login(staff)
         self.assertEqual(self.client.get(self.url).status_code, 403)
+
+
+def custom_manifest(canvases):
+    """A v2 manifest from (canvas id suffix, label, image id suffix) tuples"""
+    return {
+        "sequences": [
+            {
+                "canvases": [
+                    {
+                        "@id": f"https://example.org/iiif/ms/canvas/{canvas_id}",
+                        "label": label,
+                        "images": [
+                            {
+                                "resource": {
+                                    "service": {
+                                        "@id": f"https://example.org/image/{image}"
+                                    }
+                                }
+                            }
+                        ],
+                    }
+                    for canvas_id, label, image in canvases
+                ]
+            }
+        ]
+    }
+
+
+class VerifyCanvasLinksTest(TestCase):
+    def setUp(self):
+        self.manuscript = SingleManuscript.objects.create(
+            item_id=1, siglum="Test1", iiif_url=MANIFEST_URL
+        )
+
+    def add_folio(self, number, canvas_id, index, label, image):
+        return Folio.objects.create(
+            manuscript=self.manuscript,
+            folio_number=number,
+            canvas_id=f"https://example.org/iiif/ms/canvas/{canvas_id}",
+            canvas_index=index,
+            canvas_label=label,
+            image_id=f"https://example.org/image/{image}",
+        )
+
+    def run_command(self, canvases, *args):
+        out = StringIO()
+        with mock.patch(
+            "manuscript.management.commands.verify_canvas_links.fetch_manifest",
+            return_value=custom_manifest(canvases),
+        ):
+            call_command("verify_canvas_links", *args, stdout=out)
+        return out.getvalue()
+
+    def test_unchanged_links(self):
+        folio = self.add_folio("1r", "a", 0, "1r", "img-a")
+        out = self.run_command([("a", "1r", "img-a")])
+
+        self.assertIn("1 unchanged", out)
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_index, 0)
+
+    def test_moved_and_relabelled_canvas_is_updated(self):
+        folio = self.add_folio("1r", "a", 0, "1r", "img-a")
+        out = self.run_command([("cover", "Cover", "img-c"), ("a", "f. 1r", "img-a")])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_index, 1)
+        self.assertEqual(folio.canvas_label, "f. 1r")
+        self.assertIn("position or label changed: 1r", out)
+
+    def test_relinks_by_image_id(self):
+        folio = self.add_folio("1r", "a", 0, "1r", "img-a")
+        out = self.run_command([("new-b", "1v", "img-b"), ("new-a", "1r", "img-a")])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, "https://example.org/iiif/ms/canvas/new-a")
+        self.assertEqual(folio.canvas_index, 1)
+        self.assertIn("re-linked by image ID: 1r", out)
+
+    def test_relinks_by_position_and_label(self):
+        folio = self.add_folio("1r", "a", 1, "1r", "img-a")
+        self.run_command([("x", "Cover", "img-x"), ("y", "1r", "img-y")])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, "https://example.org/iiif/ms/canvas/y")
+        self.assertEqual(folio.image_id, "https://example.org/image/img-y")
+
+    def test_reports_links_it_cannot_fix(self):
+        folio = self.add_folio("1r", "a", 0, "1r", "img-a")
+        out = self.run_command([("x", "Cover", "img-x")])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, "https://example.org/iiif/ms/canvas/a")
+        self.assertIn("canvas gone, and no replacement found: 1r", out)
+        self.assertIn("1 could not be re-linked", out)
+
+    def test_does_not_take_a_canvas_linked_to_another_folio(self):
+        self.add_folio("1v", "b", 1, "1v", "img-b")
+        folio = self.add_folio("1r", "a", 0, "1r", "img-b")
+        out = self.run_command([("b", "1v", "img-b")])
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, "https://example.org/iiif/ms/canvas/a")
+        self.assertIn("its replacement is linked to another folio: 1r", out)
+
+    def test_dry_run_does_not_save(self):
+        folio = self.add_folio("1r", "a", 0, "1r", "img-a")
+        self.run_command([("new-a", "1r", "img-a")], "--dry-run")
+
+        folio.refresh_from_db()
+        self.assertEqual(folio.canvas_id, "https://example.org/iiif/ms/canvas/a")
+
+    def test_reports_manifests_it_cannot_load(self):
+        self.add_folio("1r", "a", 0, "1r", "img-a")
+        out = StringIO()
+        with mock.patch(
+            "manuscript.management.commands.verify_canvas_links.fetch_manifest",
+            side_effect=Exception("403 Forbidden"),
+        ):
+            call_command("verify_canvas_links", stdout=out)
+        self.assertIn("Test1: could not load manifest (403 Forbidden)", out.getvalue())
+        self.assertIn("1 manifests could not be loaded", out.getvalue())
diff --git a/static/js/canvas_linking.js b/static/js/canvas_linking.js
index c70806f..a412f21 100644
--- a/static/js/canvas_linking.js
+++ b/static/js/canvas_linking.js
@@ -225,6 +225,7 @@
 
   function buildRow(canvas, labelCounts) {
     const tr = document.createElement('tr');
+    tr.id = `image-${canvas.index + 1}`;
     const current = foliosByCanvas.get(canvas.id);
 
     const position = document.createElement('td');
@@ -378,6 +379,25 @@
     statusEl.hidden = true;
     form.hidden = false;
     update();
+    showLinkedRow();
+  }
+
+  // Rows are built after the page loads, so jump to a row named in the URL
+  // here: #folio-<id> for the image linked to that folio record (as linked
+  // from the manuscript's folio list), or #image-<position>
+  function showLinkedRow() {
+    let row = null;
+    const folioMatch = location.hash.match(/^#folio-(\d+)$/);
+    if (folioMatch) {
+      const folio = folios.find((f) => String(f.id) === folioMatch[1]);
+      row = folio && rows.find((r) => r.canvas.id === folio.canvas_id);
+    } else if (/^#image-\d+$/.test(location.hash)) {
+      row = rows.find((r) => `#${r.tr.id}` === location.hash);
+    }
+    if (!row) return;
+    row.tr.classList.add('is-target');
+    row.tr.scrollIntoView({ block: 'center' });
+    row.input.focus({ preventScroll: true });
   }
 
   filterEl.addEventListener('change', applyFilter);
diff --git a/templates/admin/manuscript/singlemanuscript/link_canvases.html b/templates/admin/manuscript/singlemanuscript/link_canvases.html
index da5fc08..2ae23ed 100644
--- a/templates/admin/manuscript/singlemanuscript/link_canvases.html
+++ b/templates/admin/manuscript/singlemanuscript/link_canvases.html
@@ -33,6 +33,7 @@
     #canvas-table .canvas-suggestion { margin-left: 0.5em; font-size: 0.8125rem; padding: 2px 6px; cursor: pointer; }
     #canvas-table tr.is-changed td { background: var(--selected-row, #ffc); }
     #canvas-table tr.has-problem td { background: var(--message-error-bg, #ffefef); }
+    #canvas-table tr.is-target { outline: 2px solid var(--link-fg, #447e9b); outline-offset: -2px; }
     #canvas-table .canvas-note { display: block; }
     #canvas-table .canvas-note.is-problem { color: var(--error-fg, #ba2121); font-weight: bold; }
     #canvas-table .canvas-note.is-info { color: var(--body-quiet-color, #666); }

From 91f8d0d623b2d68afab805344915c71da0acd7ea Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Wed, 21 Oct 2026 11:44:43 -0700
Subject: [PATCH 04/13] Add command to verify IIIF canvas links

---
 .../commands/verify_canvas_links.py           | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 manuscript/management/commands/verify_canvas_links.py

diff --git a/manuscript/management/commands/verify_canvas_links.py b/manuscript/management/commands/verify_canvas_links.py
new file mode 100644
index 0000000..3815a88
--- /dev/null
+++ b/manuscript/management/commands/verify_canvas_links.py
@@ -0,0 +1,168 @@
+from collections import Counter, defaultdict
+
+from django.core.management.base import BaseCommand
+from django.db import transaction
+
+from manuscript.models import SingleManuscript
+from manuscript.utils import fetch_manifest, get_canvases, normalize_folio_label
+
+CANVAS_FIELDS = ["canvas_id", "canvas_index", "canvas_label", "image_id"]
+
+
+class Command(BaseCommand):
+    help = (
+        "Check that each folio's linked IIIF canvas is still in its manuscript's "
+        "manifest. Canvases that moved or were relabelled are updated; folios "
+        "whose canvas is gone are re-linked by image ID, or by position and "
+        "label; anything that can't be re-linked is reported and left as it is. "
+        "Meant to be run regularly, e.g. from a scheduler."
+    )
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "sigla",
+            nargs="*",
+            help="Sigla of manuscripts to check (default: all with linked folios)",
+        )
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Report what would change without saving",
+        )
+
+    def handle(self, *args, **options):
+        manuscripts = (
+            SingleManuscript.objects.exclude(iiif_url__isnull=True)
+            .exclude(iiif_url="")
+            .filter(folio__canvas_id__isnull=False)
+            .distinct()
+            .order_by("siglum")
+        )
+        if options["sigla"]:
+            manuscripts = manuscripts.filter(siglum__in=options["sigla"])
+
+        totals = Counter()
+        for manuscript in manuscripts:
+            totals.update(self.verify_manuscript(manuscript, options["dry_run"]))
+
+        prefix = "[dry run] " if options["dry_run"] else ""
+        summary = (
+            f"\n{prefix}Checked {totals['checked']} linked folios: "
+            f"{totals['ok']} unchanged, {totals['updated']} updated, "
+            f"{totals['relinked']} re-linked, {totals['broken']} could not be "
+            f"re-linked; {totals['unchecked']} manifests could not be loaded."
+        )
+        style = (
+            self.style.WARNING
+            if totals["broken"] or totals["unchecked"]
+            else self.style.SUCCESS
+        )
+        self.stdout.write(style(summary))
+
+    def verify_manuscript(self, manuscript, dry_run):
+        counts = Counter()
+        label = manuscript.siglum or f"Manuscript {manuscript.pk}"
+        try:
+            canvases = get_canvases(fetch_manifest(manuscript.iiif_url))
+        except Exception as e:
+            self.stdout.write(
+                self.style.ERROR(f"{label}: could not load manifest ({e})")
+            )
+            counts["unchecked"] += 1
+            return counts
+
+        canvases_by_id = {canvas["id"]: canvas for canvas in canvases}
+        canvases_by_image = defaultdict(list)
+        for canvas in canvases:
+            if canvas["image_id"]:
+                canvases_by_image[canvas["image_id"]].append(canvas)
+
+        folios = list(manuscript.folio_set.exclude(canvas_id__isnull=True))
+        # canvases held by a valid link, which a re-linked folio can't take
+        used_canvas_ids = {
+            folio.canvas_id for folio in folios if folio.canvas_id in canvases_by_id
+        }
+
+        notes = defaultdict(list)
+        with transaction.atomic():
+            for folio in folios:
+                counts["checked"] += 1
+                canvas = canvases_by_id.get(folio.canvas_id)
+                if canvas:
+                    if self.canvas_changed(folio, canvas):
+                        notes["position or label changed"].append(
+                            self.describe(folio, canvas)
+                        )
+                        self.apply_canvas(folio, canvas, dry_run)
+                        counts["updated"] += 1
+                    else:
+                        counts["ok"] += 1
+                    continue
+
+                canvas, method = self.find_moved_canvas(
+                    folio, canvases, canvases_by_image
+                )
+                if canvas and canvas["id"] not in used_canvas_ids:
+                    notes[f"re-linked by {method}"].append(self.describe(folio, canvas))
+                    self.apply_canvas(folio, canvas, dry_run)
+                    used_canvas_ids.add(canvas["id"])
+                    counts["relinked"] += 1
+                elif canvas:
+                    notes[
+                        "canvas gone, and its replacement is linked to another folio"
+                    ].append(folio.folio_number or f"#{folio.pk}")
+                    counts["broken"] += 1
+                else:
+                    notes["canvas gone, and no replacement found"].append(
+                        folio.folio_number or f"#{folio.pk}"
+                    )
+                    counts["broken"] += 1
+
+        summary = (
+            f"{label}: {counts['checked']} linked folios, {counts['ok']} unchanged, "
+            f"{counts['updated']} updated, {counts['relinked']} re-linked, "
+            f"{counts['broken']} could not be re-linked"
+        )
+        if counts["broken"]:
+            self.stdout.write(self.style.WARNING(summary))
+        elif notes:
+            self.stdout.write(summary)
+        for note, items in notes.items():
+            self.stdout.write(f"    {note}: {', '.join(items)}")
+        return counts
+
+    def find_moved_canvas(self, folio, canvases, canvases_by_image):
+        """Find the canvas a folio's missing canvas has become: the one showing
+        the same image, or else the one at the same position with the same
+        label. Returns (canvas, method) or (None, None)."""
+        matches = canvases_by_image.get(folio.image_id or "", [])
+        if len(matches) == 1:
+            return matches[0], "image ID"
+        index = folio.canvas_index
+        if (
+            index is not None
+            and index < len(canvases)
+            and folio.canvas_label
+            and normalize_folio_label(canvases[index]["label"])
+            == normalize_folio_label(folio.canvas_label)
+        ):
+            return canvases[index], "position and label"
+        return None, None
+
+    def canvas_changed(self, folio, canvas):
+        return (
+            folio.canvas_index != canvas["index"]
+            or (folio.canvas_label or "") != canvas["label"][:255]
+            or (canvas["image_id"] and folio.image_id != canvas["image_id"])
+        )
+
+    def describe(self, folio, canvas):
+        return f"{folio.folio_number or f'#{folio.pk}'} (now image {canvas['index'] + 1}, \"{canvas['label']}\")"
+
+    def apply_canvas(self, folio, canvas, dry_run):
+        folio.canvas_id = canvas["id"]
+        folio.canvas_index = canvas["index"]
+        folio.canvas_label = canvas["label"][:255]
+        folio.image_id = canvas["image_id"] or folio.image_id
+        if not dry_run:
+            folio.save(update_fields=CANVAS_FIELDS)

From 3eef1746902d6b4ab66da5cc400a65411c925b5d Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Wed, 21 Oct 2026 13:50:43 -0700
Subject: [PATCH 05/13] Fix folio dividers placed one stanza late

---
 manuscript/tests.py    | 137 ++++++++++++++++++++++++++++++++++++++++-
 manuscript/views.py    |  66 +++++++++++++-------
 templates/stanzas.html |  18 ++++++
 3 files changed, 197 insertions(+), 24 deletions(-)

diff --git a/manuscript/tests.py b/manuscript/tests.py
index efa85d8..975eb23 100644
--- a/manuscript/tests.py
+++ b/manuscript/tests.py
@@ -11,7 +11,14 @@
 from django.urls import reverse
 
 from manuscript.canvas_linking import clean_canvas_rows, link_canvases
-from manuscript.models import Folio, Location, LocationAlias, SingleManuscript
+from manuscript.models import (
+    Folio,
+    Location,
+    LocationAlias,
+    SingleManuscript,
+    Stanza,
+    StanzaTranslated,
+)
 from manuscript.utils import get_canvases, normalize_folio_label
 
 MANIFEST_URL = "https://example.org/iiif/ms/manifest.json"
@@ -597,3 +604,131 @@ def test_reports_manifests_it_cannot_load(self):
             call_command("verify_canvas_links", stdout=out)
         self.assertIn("Test1: could not load manifest (403 Forbidden)", out.getvalue())
         self.assertIn("1 manifests could not be loaded", out.getvalue())
+
+
+class StanzaFolioDividerTest(TestCase):
+    """Folio dividers on the text page, between stanzas and mid-stanza."""
+
+    def setUp(self):
+        self.manuscript = SingleManuscript.objects.create(item_id=1, siglum="Test1")
+        # Book 1, stanzas 1-4, each with a stanza number (.00) and 8 lines,
+        # translated line by line
+        for stanza in range(1, 5):
+            for line in range(9):
+                code = f"01.{stanza:02d}.{line:02d}"
+                original = Stanza.objects.create(
+                    stanza_line_code_starts=code,
+                    stanza_text=f"Original {code}",
+                    is_rubric=line == 0,
+                )
+                StanzaTranslated.objects.create(
+                    stanza=original,
+                    stanza_line_code_starts=code,
+                    stanza_text=f"Translated {code}",
+                )
+
+    def add_folios(self, *ranges):
+        for number, start, end in ranges:
+            Folio.objects.create(
+                manuscript=self.manuscript,
+                folio_number=number,
+                line_code_range_start=start,
+                line_code_range_end=end,
+                canvas_id=f"https://example.org/iiif/ms/canvas/{number}",
+            )
+
+    def get_page(self):
+        response = self.client.get(
+            reverse("manuscript_stanzas", args=[self.manuscript.siglum])
+        )
+        self.assertEqual(response.status_code, 200)
+        return response
+
+    def stanza_dividers(self, response):
+        return [
+            (
+                group["original"][0]["stanza_line_code_starts"],
+                group["current_folio"].folio_number,
+            )
+            for group in response.context["paired_books"][1]
+            if group.get("new_folio")
+        ]
+
+    def line_breaks(self, response, column="original"):
+        return [
+            (line["stanza_line_code_starts"], line["folio_break"].folio_number)
+            for group in response.context["paired_books"][1]
+            for line in group[column]
+            if line.get("folio_break")
+        ]
+
+    def test_breaks_between_stanzas(self):
+        self.add_folios(("1r", "01.01.00", "01.02.08"), ("1v", "01.03.00", "01.04.08"))
+
+        response = self.get_page()
+
+        self.assertEqual(
+            self.stanza_dividers(response), [("01.01.00", "1r"), ("01.03.00", "1v")]
+        )
+        self.assertEqual(self.line_breaks(response), [])
+        self.assertNotContains(response, "folio-divider-inline")
+
+    def test_break_mid_stanza(self):
+        # Like Vat1, where 240r starts at line 6 of stanza 6
+        self.add_folios(("1r", "01.01.00", "01.02.05"), ("1v", "01.02.06", "01.04.08"))
+
+        response = self.get_page()
+
+        self.assertEqual(self.stanza_dividers(response), [("01.01.00", "1r")])
+        self.assertEqual(self.line_breaks(response), [("01.02.06", "1v")])
+        self.assertEqual(self.line_breaks(response, "translated"), [("01.02.06", "1v")])
+
+        # The marker comes between lines 5 and 6, carrying what tify-sync.js
+        # needs to turn the viewer, in the original column only
+        html = response.content.decode()
+        marker = html.index('data-folio-number="1v"')
+        self.assertLess(html.index("Original 01.02.05"), marker)
+        self.assertLess(marker, html.index("Original 01.02.06"))
+        self.assertContains(
+            response,
+            'class="relative flex items-center my-1 text-sm folio-divider '
+            'folio-divider-inline" data-folio-number="1v" '
+            'data-canvas-id="https://example.org/iiif/ms/canvas/1v"',
+        )
+        self.assertContains(response, 'data-folio-number="1v"', count=1)
+        translated_marker = html.index("Folio 1v", html.index("Translated 01.02.05"))
+        self.assertLess(translated_marker, html.index("Translated 01.02.06"))
+
+    def test_break_at_first_verse_line_is_between_stanzas(self):
+        # The stanza number (.00) falls in the gap before the folio's range
+        self.add_folios(("1r", "01.01.00", "01.02.08"), ("1v", "01.03.01", "01.04.08"))
+
+        response = self.get_page()
+
+        self.assertEqual(
+            self.stanza_dividers(response), [("01.01.00", "1r"), ("01.03.00", "1v")]
+        )
+        self.assertEqual(self.line_breaks(response), [])
+
+    def test_ranges_sharing_a_line(self):
+        # Like Urb1, where each range ends on the line the next one starts on
+        self.add_folios(
+            ("9v", "01.01.01", "01.03.01"),
+            ("10r", "01.03.01", "01.04.08"),
+        )
+
+        response = self.get_page()
+
+        self.assertEqual(
+            self.stanza_dividers(response), [("01.01.00", "9v"), ("01.03.00", "10r")]
+        )
+        self.assertEqual(self.line_breaks(response), [])
+
+    def test_folio_holding_only_the_stanza_number(self):
+        # Like NYPL2, where 1v holds only 01.01.00
+        self.add_folios(("1v", "01.01.00", "01.01.00"), ("2r", "01.01.01", "01.04.08"))
+
+        response = self.get_page()
+
+        self.assertEqual(self.stanza_dividers(response), [("01.01.00", "1v")])
+        self.assertEqual(self.line_breaks(response), [("01.01.01", "2r")])
diff --git a/manuscript/views.py b/manuscript/views.py
index b48a339..89fd5e6 100644
--- a/manuscript/views.py
+++ b/manuscript/views.py
@@ -121,8 +121,13 @@ def manuscript_stanzas(request, siglum):
     line_code_to_folio = {}
 
     if folios.exists():
-        # Try to build a map of line codes to folios
-        for folio in folios:
+        # Try to build a map of line codes to folios. Apply ranges in reading
+        # order so where one folio's range ends on the line the next starts
+        # on, that line goes to the later folio.
+        for folio in sorted(
+            folios,
+            key=lambda f: line_code_to_numeric(f.line_code_range_start) or 0,
+        ):
             if folio.line_code_range_start and folio.line_code_range_end:
                 try:
                     start_code = line_code_to_numeric(folio.line_code_range_start)
@@ -185,29 +190,44 @@ def manuscript_stanzas(request, siglum):
                 "translated": translated_stanza_group,
             }
 
-            # If we have a folio mapping, try to add folio information
+            # If we have a folio mapping, mark where the folio changes. A
+            # change at the stanza's first verse line is shown between stanzas;
+            # a change further in is marked on the line where the folio starts.
             if has_folio_mapping and original_stanzas:
-                first_stanza = original_stanzas[0]
-                if first_stanza["stanza_line_code_starts"]:
-                    try:
-                        stanza_code = line_code_to_numeric(
-                            first_stanza["stanza_line_code_starts"]
-                        )
-                        if stanza_code in line_code_to_folio:
-                            matching_folio = line_code_to_folio[stanza_code]
-
-                            # If this is a new folio, mark it in the stanza group
-                            if current_folio is None or matching_folio != current_folio:
-                                current_folio = matching_folio
-                                stanza_group["new_folio"] = True
-                                stanza_group["current_folio"] = current_folio
-                                logger.info(
-                                    f"New folio for stanza {stanza_number}: {current_folio.folio_number}"
-                                )
-                    except Exception as e:
-                        logger.warning(
-                            f"Error determining folio for stanza {first_stanza.id}: {e}"
+                at_stanza_start = True
+                keep_stanza_divider = False
+                for line in original_stanzas:
+                    line_code = line["stanza_line_code_starts"]
+                    numeric_code = line_code_to_numeric(line_code)
+                    matching_folio = line_code_to_folio.get(numeric_code)
+                    if matching_folio is not None and matching_folio != current_folio:
+                        current_folio = matching_folio
+                        if at_stanza_start and not keep_stanza_divider:
+                            stanza_group["new_folio"] = True
+                            stanza_group["current_folio"] = current_folio
+                            # Only a folio whose range begins at the stanza
+                            # number keeps the divider if another folio starts
+                            # at the first verse line
+                            keep_stanza_divider = numeric_code == line_code_to_numeric(
+                                current_folio.line_code_range_start
+                            )
+                        else:
+                            line["folio_break"] = current_folio
+                            # Mark the same line in the translation so the
+                            # columns stay level
+                            for translated_line in translated_stanza_group:
+                                if (
+                                    translated_line["stanza_line_code_starts"]
+                                    == line_code
+                                ):
+                                    translated_line["folio_break"] = current_folio
+                        logger.info(
+                            f"New folio at line {line_code}: {current_folio.folio_number}"
                         )
+                    # .00 lines are stanza numbers, not manuscript text, so the
+                    # stanza starts at its first verse line
+                    if not line_code.endswith(".00"):
+                        at_stanza_start = False
 
             # Add the stanza group to the book
             paired_books[book_number].append(stanza_group)
diff --git a/templates/stanzas.html b/templates/stanzas.html
index dd7ab28..9a03e8f 100644
--- a/templates/stanzas.html
+++ b/templates/stanzas.html
@@ -221,6 +221,15 @@ <h2 id="book-{{book_number}}" class="text-xl font-serif font-bold mb-4 scroll-mt
                     <!-- Original stanza -->
                     <div class="w-full">
                       {% for stanza in stanza_pair.original %}
+                        {% if stanza.folio_break %}
+                          <!-- Folio changes mid-stanza -->
+                          <div class="relative flex items-center my-1 text-sm folio-divider folio-divider-inline" data-folio-number="{{ stanza.folio_break.folio_number }}" data-canvas-id="{{ stanza.folio_break.canvas_id|default_if_none:'' }}">
+                            <div class="text-gray-500 pr-2">
+                              Folio {{ stanza.folio_break.folio_number }}
+                            </div>
+                            <div class="flex-grow border-t border-dashed border-gray-300"></div>
+                          </div>
+                        {% endif %}
                         <div class="relative">
                           <div class="flex gap-2 items-start">
                             <a class="line-code sr-only target:not-sr-only no-underline scroll-mt-36" 
@@ -245,6 +254,15 @@ <h2 id="book-{{book_number}}" class="text-xl font-serif font-bold mb-4 scroll-mt
                     <!-- Translated stanza -->
                     <div class="w-full">
                       {% for stanza in stanza_pair.translated %}
+                        {% if stanza.folio_break %}
+                          <!-- Matches the mid-stanza folio marker in the original column -->
+                          <div class="relative flex items-center my-1 text-sm" aria-hidden="true">
+                            <div class="text-gray-500 pr-2">
+                              Folio {{ stanza.folio_break.folio_number }}
+                            </div>
+                            <div class="flex-grow border-t border-dashed border-gray-300"></div>
+                          </div>
+                        {% endif %}
                         <div class="relative">
                           <div class="flex gap-2 items-start">
                             <a class="line-code sr-only target:not-sr-only no-underline scroll-mt-36" href="#{{stanza.stanza_line_code_starts}}"

From c4c20702f5e50552ba23320190f13eda770a3124 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Thu, 22 Oct 2026 10:00:35 -0700
Subject: [PATCH 06/13] Show mid-stanza folio breaks across both columns

---
 manuscript/tests.py    |  49 +++++++++++++++----
 manuscript/views.py    |  33 +++++++++----
 templates/stanzas.html | 105 +++++++++++++++++++----------------------
 3 files changed, 115 insertions(+), 72 deletions(-)

diff --git a/manuscript/tests.py b/manuscript/tests.py
index 975eb23..c4c6ad1 100644
--- a/manuscript/tests.py
+++ b/manuscript/tests.py
@@ -673,6 +673,19 @@ def test_breaks_between_stanzas(self):
         self.assertEqual(self.line_breaks(response), [])
         self.assertNotContains(response, "folio-divider-inline")
 
+    def segments(self, response, stanza):
+        """(folio starting the segment, original codes, translated codes) for
+        each segment of a stanza"""
+        group = response.context["paired_books"][1][stanza - 1]
+        return [
+            (
+                segment["folio_break"].folio_number if segment["folio_break"] else None,
+                [line["stanza_line_code_starts"] for line in segment["original"]],
+                [line["stanza_line_code_starts"] for line in segment["translated"]],
+            )
+            for segment in group["segments"]
+        ]
+
     def test_break_mid_stanza(self):
         # Like Vat1, where 240r starts at line 6 of stanza 6
         self.add_folios(("1r", "01.01.00", "01.02.05"), ("1v", "01.02.06", "01.04.08"))
@@ -681,23 +694,43 @@ def test_break_mid_stanza(self):
 
         self.assertEqual(self.stanza_dividers(response), [("01.01.00", "1r")])
         self.assertEqual(self.line_breaks(response), [("01.02.06", "1v")])
-        self.assertEqual(self.line_breaks(response, "translated"), [("01.02.06", "1v")])
+        lines = [f"01.02.{line:02d}" for line in range(9)]
+        self.assertEqual(
+            self.segments(response, 2),
+            [(None, lines[:6], lines[:6]), ("1v", lines[6:], lines[6:])],
+        )
 
-        # The marker comes between lines 5 and 6, carrying what tify-sync.js
-        # needs to turn the viewer, in the original column only
+        # One full-width marker between the two parts of the stanza, carrying
+        # what tify-sync.js needs to turn the viewer
         html = response.content.decode()
         marker = html.index('data-folio-number="1v"')
-        self.assertLess(html.index("Original 01.02.05"), marker)
+        self.assertLess(html.index("Translated 01.02.05"), marker)
         self.assertLess(marker, html.index("Original 01.02.06"))
         self.assertContains(
             response,
-            'class="relative flex items-center my-1 text-sm folio-divider '
+            'class="relative flex items-center my-2 text-sm folio-divider '
             'folio-divider-inline" data-folio-number="1v" '
             'data-canvas-id="https://example.org/iiif/ms/canvas/1v"',
         )
-        self.assertContains(response, 'data-folio-number="1v"', count=1)
-        translated_marker = html.index("Folio 1v", html.index("Translated 01.02.05"))
-        self.assertLess(translated_marker, html.index("Translated 01.02.06"))
+        self.assertContains(response, "Folio 1v", count=1)
+
+    def test_break_mid_stanza_without_matching_translation_line(self):
+        # The translation has no line 01.02.06, so it's split at the next line
+        StanzaTranslated.objects.filter(stanza_line_code_starts="01.02.06").delete()
+        self.add_folios(("1r", "01.01.00", "01.02.05"), ("1v", "01.02.06", "01.04.08"))
+
+        response = self.get_page()
+
+        self.assertEqual(
+            [
+                (folio, translated)
+                for folio, _, translated in self.segments(response, 2)
+            ],
+            [
+                (None, [f"01.02.{line:02d}" for line in range(6)]),
+                ("1v", ["01.02.07", "01.02.08"]),
+            ],
+        )
 
     def test_break_at_first_verse_line_is_between_stanzas(self):
         # The stanza number (.00) falls in the gap before the folio's range
diff --git a/manuscript/views.py b/manuscript/views.py
index 89fd5e6..beafb4e 100644
--- a/manuscript/views.py
+++ b/manuscript/views.py
@@ -53,6 +53,27 @@ def get_annotation_map(model_class, stanzas, ct_id, note_type, manuscript=None):
     return mapping
 
 
+def split_at_folio_breaks(original_lines, translated_lines):
+    """Split a stanza into segments where the folio changes mid-stanza, so each
+    break can be shown across both columns. Each segment has its original and
+    translated lines and the folio starting there (None for the first). The
+    translation is split at the same line code, or the first line after it."""
+    segments = [{"original": [], "translated": [], "folio_break": None}]
+    break_codes = []
+    for line in original_lines:
+        if line.get("folio_break"):
+            segments.append(
+                {"original": [], "translated": [], "folio_break": line["folio_break"]}
+            )
+            break_codes.append(line_code_to_numeric(line["stanza_line_code_starts"]))
+        segments[-1]["original"].append(line)
+    for line in translated_lines:
+        code = line_code_to_numeric(line["stanza_line_code_starts"])
+        index = sum(1 for break_code in break_codes if code and code >= break_code)
+        segments[index]["translated"].append(line)
+    return segments
+
+
 def manuscript_stanzas(request, siglum):
     # Get the requested manuscript
     manuscript = get_object_or_404(SingleManuscript, siglum=siglum)
@@ -213,14 +234,6 @@ def manuscript_stanzas(request, siglum):
                             )
                         else:
                             line["folio_break"] = current_folio
-                            # Mark the same line in the translation so the
-                            # columns stay level
-                            for translated_line in translated_stanza_group:
-                                if (
-                                    translated_line["stanza_line_code_starts"]
-                                    == line_code
-                                ):
-                                    translated_line["folio_break"] = current_folio
                         logger.info(
                             f"New folio at line {line_code}: {current_folio.folio_number}"
                         )
@@ -229,6 +242,10 @@ def manuscript_stanzas(request, siglum):
                     if not line_code.endswith(".00"):
                         at_stanza_start = False
 
+            stanza_group["segments"] = split_at_folio_breaks(
+                original_stanzas, translated_stanza_group or []
+            )
+
             # Add the stanza group to the book
             paired_books[book_number].append(stanza_group)
 
diff --git a/templates/stanzas.html b/templates/stanzas.html
index 9a03e8f..35c7616 100644
--- a/templates/stanzas.html
+++ b/templates/stanzas.html
@@ -217,68 +217,61 @@ <h2 id="book-{{book_number}}" class="text-xl font-serif font-bold mb-4 scroll-mt
                       <div class="flex-grow border-t border-gray-300"></div>
                     </div>
                   {% endif %}
-                  <div class="grid grid-cols-2 gap-8 mb-8">
-                    <!-- Original stanza -->
-                    <div class="w-full">
-                      {% for stanza in stanza_pair.original %}
-                        {% if stanza.folio_break %}
-                          <!-- Folio changes mid-stanza -->
-                          <div class="relative flex items-center my-1 text-sm folio-divider folio-divider-inline" data-folio-number="{{ stanza.folio_break.folio_number }}" data-canvas-id="{{ stanza.folio_break.canvas_id|default_if_none:'' }}">
-                            <div class="text-gray-500 pr-2">
-                              Folio {{ stanza.folio_break.folio_number }}
-                            </div>
-                            <div class="flex-grow border-t border-dashed border-gray-300"></div>
-                          </div>
-                        {% endif %}
-                        <div class="relative">
-                          <div class="flex gap-2 items-start">
-                            <a class="line-code sr-only target:not-sr-only no-underline scroll-mt-36" 
-                                href="{% url 'manuscript_stanzas' default_manuscript.siglum %}#{{stanza.stanza_line_code_starts}}"
-                                id="{{stanza.stanza_line_code_starts}}"
-                                title="Anchor link to line code {{ stanza.stanza_line_code_starts}}"
-                                {% with stanza_folio=stanza.folios.all.0 %}
-                                data-folio="{{ stanza_folio.folio_number }}"
-                                {% endwith %}
-                                onclick="navigateToFolio(event, this)">
-                              <span class="line-text font-serif text-red-700 text-sm">
-                                {{ stanza.stanza_line_code_starts }}
-                              </span>
-                            </a>
-                            <span class="flex-1 pl-4{% if stanza.is_rubric %} text-xl font-bold{% endif %}">
-                              {{ stanza.unescaped_stanza_text|annotate_text:stanza.annotations|safe }}
-                            </span>
-                          </div>
+                  {% for segment in stanza_pair.segments %}
+                    {% if segment.folio_break %}
+                      <!-- Folio changes mid-stanza -->
+                      <div class="relative flex items-center my-2 text-sm folio-divider folio-divider-inline" data-folio-number="{{ segment.folio_break.folio_number }}" data-canvas-id="{{ segment.folio_break.canvas_id|default_if_none:'' }}">
+                        <div class="text-gray-500 pr-4">
+                          Folio {{ segment.folio_break.folio_number }}
                         </div>
-                      {% endfor %}
-                    </div>
-                    <!-- Translated stanza -->
-                    <div class="w-full">
-                      {% for stanza in stanza_pair.translated %}
-                        {% if stanza.folio_break %}
-                          <!-- Matches the mid-stanza folio marker in the original column -->
-                          <div class="relative flex items-center my-1 text-sm" aria-hidden="true">
-                            <div class="text-gray-500 pr-2">
-                              Folio {{ stanza.folio_break.folio_number }}
+                        <div class="flex-grow border-t border-dashed border-gray-300"></div>
+                      </div>
+                    {% endif %}
+                    <div class="grid grid-cols-2 gap-8 {% if forloop.last %}mb-8{% else %}mb-2{% endif %}">
+                      <!-- Original stanza -->
+                      <div class="w-full">
+                        {% for stanza in segment.original %}
+                          <div class="relative">
+                            <div class="flex gap-2 items-start">
+                              <a class="line-code sr-only target:not-sr-only no-underline scroll-mt-36" 
+                                  href="{% url 'manuscript_stanzas' default_manuscript.siglum %}#{{stanza.stanza_line_code_starts}}"
+                                  id="{{stanza.stanza_line_code_starts}}"
+                                  title="Anchor link to line code {{ stanza.stanza_line_code_starts}}"
+                                  {% with stanza_folio=stanza.folios.all.0 %}
+                                  data-folio="{{ stanza_folio.folio_number }}"
+                                  {% endwith %}
+                                  onclick="navigateToFolio(event, this)">
+                                <span class="line-text font-serif text-red-700 text-sm">
+                                  {{ stanza.stanza_line_code_starts }}
+                                </span>
+                              </a>
+                              <span class="flex-1 pl-4{% if stanza.is_rubric %} text-xl font-bold{% endif %}">
+                                {{ stanza.unescaped_stanza_text|annotate_text:stanza.annotations|safe }}
+                              </span>
                             </div>
-                            <div class="flex-grow border-t border-dashed border-gray-300"></div>
                           </div>
-                        {% endif %}
-                        <div class="relative">
-                          <div class="flex gap-2 items-start">
-                            <a class="line-code sr-only target:not-sr-only no-underline scroll-mt-36" href="#{{stanza.stanza_line_code_starts}}"
-                                id="{{stanza.stanza_line_code_starts}}">
-                              <span class="line-text font-serif text-red-700 text-sm">
-                                {{ stanza.stanza_line_code_starts }}
+                        {% endfor %}
+                      </div>
+                      <!-- Translated stanza -->
+                      <div class="w-full">
+                        {% for stanza in segment.translated %}
+                          <div class="relative">
+                            <div class="flex gap-2 items-start">
+                              <a class="line-code sr-only target:not-sr-only no-underline scroll-mt-36" href="#{{stanza.stanza_line_code_starts}}"
+                                  id="{{stanza.stanza_line_code_starts}}">
+                                <span class="line-text font-serif text-red-700 text-sm">
+                                  {{ stanza.stanza_line_code_starts }}
+                                </span>
+                              </a>
+                              <span class="flex-1 pl-4{% if stanza.is_rubric %} text-xl font-bold{% endif %}">
+                                {{ stanza.unescaped_stanza_text|annotate_text:stanza.annotations|safe }}
                               </span>
-                            </a>
-                            <span class="flex-1 pl-4{% if stanza.is_rubric %} text-xl font-bold{% endif %}">
-                              {{ stanza.unescaped_stanza_text|annotate_text:stanza.annotations|safe }}
-                            </span>
+                            </div>
                           </div>
-                        </div>
-                      {% endfor %}
+                        {% endfor %}
+                      </div>
                     </div>
-                  </div>
+                  {% endfor %}
                 {% endfor %}
                 <!-- Book separator -->
                 <div class="flex items-center my-16 py-4">

From cbab030a41afce1c36755ea7a817376cffc55a72 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Thu, 22 Oct 2026 10:12:15 -0700
Subject: [PATCH 07/13] Run unit tests on pull requests

---
 .github/workflows/tests.yml | 66 +++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 .github/workflows/tests.yml

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 0000000..af54570
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,66 @@
+name: "Tests"
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    services:
+      postgres:
+        # matches docker-compose.yml
+        image: postgres:16
+        env:
+          POSTGRES_DB: lasfera
+          POSTGRES_USER: lasfera
+          POSTGRES_PASSWORD: password
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U lasfera"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      DJANGO_READ_DOT_ENV_FILE: "false"
+      DB_HOST: localhost
+      DB_PORT: "5432"
+      DB_NAME: lasfera
+      DB_USER: lasfera
+      DB_PASS: password
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # psycopg2 is built from source and needs the PostgreSQL client headers
+      - name: Install system packages
+        run: sudo apt-get update && sudo apt-get install -y libpq-dev
+
+      # Poetry has to be installed before setup-python can cache its virtualenv
+      - name: Install Poetry
+        run: pipx install poetry==2.2.1
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: poetry
+
+      - name: Install dependencies
+        run: poetry install --no-interaction --no-root
+
+      - name: Check for missing migrations
+        run: poetry run python manage.py makemigrations --check --dry-run
+
+      - name: Run tests
+        run: poetry run python manage.py test --noinput

From 6569d77a1dd1bffc3cea4a2e7fcbeb5ba4ceed17 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Thu, 22 Oct 2026 10:19:09 -0700
Subject: [PATCH 08/13] Run tests on pushes to develop and main

---
 .github/workflows/tests.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index af54570..a8c2a37 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -2,6 +2,11 @@ name: "Tests"
 
 on:
   pull_request:
+  # Heroku's automatic deploys wait for these checks on the merged commit
+  push:
+    branches:
+      - "develop"
+      - "main"
   workflow_dispatch:
 
 permissions:

From f5c7ff5ecc55199d5a7ee7575730db3e4f919732 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Thu, 22 Oct 2026 11:57:03 -0700
Subject: [PATCH 09/13] Add image and variant filters to manuscripts

---
 manuscript/views.py        | 20 +++++++++++++++++---
 templates/manuscripts.html | 25 +++++++++++++++++++++----
 templates/stanzas.html     | 25 ++++++++++++++++++++-----
 3 files changed, 58 insertions(+), 12 deletions(-)

diff --git a/manuscript/views.py b/manuscript/views.py
index beafb4e..c518859 100644
--- a/manuscript/views.py
+++ b/manuscript/views.py
@@ -553,12 +553,18 @@ def manuscripts(request: HttpRequest):
 
     # optimization: use values() and list
     manuscripts = list(
-        SingleManuscript.objects.values("id", "shelfmark", "siglum", "library")
+        SingleManuscript.objects.annotate(
+            has_variants=Exists(
+                TextualVariant.objects.filter(manuscript=OuterRef("pk"))
+            )
+        ).values("id", "shelfmark", "siglum", "library", "iiif_url", "has_variants")
     )
     libraries = Library.objects.values("id", "city", "library")
     library_id_map = {library["id"]: library for library in libraries}
 
     for manuscript in manuscripts:
+        # "with images" means a IIIF manifest is available to view page images
+        manuscript["has_images"] = bool(manuscript["iiif_url"])
         library_id = manuscript["library"]
         library = library_id_map.get(library_id)
         if library:
@@ -576,14 +582,22 @@ def manuscripts(request: HttpRequest):
                 manuscript["shelfmark"] or "no shelfmark",
                 manuscript["siglum"] or "no siglum",
             )
-    sigla = [manuscript["siglum"] for manuscript in manuscripts if manuscript["siglum"]]
+    sigla = [
+        {
+            "siglum": manuscript["siglum"],
+            "has_images": manuscript["has_images"],
+            "has_variants": manuscript["has_variants"],
+        }
+        for manuscript in manuscripts
+        if manuscript["siglum"]
+    ]
 
     return render(
         request,
         "manuscripts.html",
         {
             "manuscripts": sorted(manuscripts, key=lambda m: m["shelfmark_fmt"]),
-            "sigla_index": sorted(sigla),
+            "sigla_index": sorted(sigla, key=lambda s: s["siglum"]),
             "snippet": ManuscriptsIntroduction.objects.first(),
         },
     )
diff --git a/templates/manuscripts.html b/templates/manuscripts.html
index eebe90f..188412d 100644
--- a/templates/manuscripts.html
+++ b/templates/manuscripts.html
@@ -5,7 +5,7 @@
 {% block title %}Manuscript Traditions - La Sfera{% endblock title %}
 
 {% block content %}
-  <div class="mx-auto container pt-3">
+  <div class="mx-auto container pt-3" x-data="{ onlyImages: false, onlyVariants: false }">
     <section class="w-full p-4 my-10">
       <!-- Title -->
       <h3 class="text-4xl mb-8 font-bold" id="top">
@@ -22,13 +22,30 @@ <h3 class="text-4xl mb-8 font-bold" id="top">
           </p>
         {% endif %}
       </div>
+
+      <!-- Filters -->
+      <div class="bg-gray-50 p-4 rounded-lg mb-8 flex flex-wrap gap-x-8 gap-y-2">
+        <span class="font-semibold text-gray-700">Filter:</span>
+        <label class="flex items-center cursor-pointer">
+          <input type="checkbox" x-model="onlyImages"
+            class="h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded cursor-pointer">
+          <span class="ml-2 text-gray-800">Only show manuscripts with images</span>
+        </label>
+        <label class="flex items-center cursor-pointer">
+          <input type="checkbox" x-model="onlyVariants"
+            class="h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded cursor-pointer">
+          <span class="ml-2 text-gray-800">Only show manuscripts with textual variants</span>
+        </label>
+      </div>
+
       <h4 class="text-2xl font-semibold mb-4 text-gray-700">Index of Sigla</h4>
       <div class="bg-gray-50 p-6 rounded-lg mb-10">
         <div class="flex flex-wrap gap-2">
           {% for siglum in sigla_index %}
-            <a href="{% url 'manuscript' siglum %}" 
+            <a href="{% url 'manuscript' siglum.siglum %}"
+              x-show="(!onlyImages || {{ siglum.has_images|yesno:'true,false' }}) && (!onlyVariants || {{ siglum.has_variants|yesno:'true,false' }})"
               class="text-md text-gray-800 px-2 py-1 bg-white border border-gray-300 rounded-md hover:bg-blue-50 hover:border-blue-300 hover:shadow-md hover:text-blue-700 transition-all">
-              {{ siglum }}
+              {{ siglum.siglum }}
             </a>
           {% endfor %}
         </div>
@@ -36,7 +53,7 @@ <h4 class="text-2xl font-semibold mb-4 text-gray-700">Index of Sigla</h4>
       <h4 class="text-2xl font-semibold mb-4 text-gray-700">Index of Manuscripts</h4>
       <ol class="list-decimal">
         {% for manuscript in manuscripts %}
-          <li>
+          <li x-show="(!onlyImages || {{ manuscript.has_images|yesno:'true,false' }}) && (!onlyVariants || {{ manuscript.has_variants|yesno:'true,false' }})">
             {% if manuscript.siglum %}
               <a class="underline hover:no-underline" href="{% url 'manuscript' manuscript.siglum %}">
                 {{ manuscript.shelfmark_fmt|default:manuscript.siglum }}
diff --git a/templates/stanzas.html b/templates/stanzas.html
index 35c7616..69825ba 100644
--- a/templates/stanzas.html
+++ b/templates/stanzas.html
@@ -139,26 +139,41 @@ <h3 class="text-4xl font-bold" id="top">
                   </div>
                 </div>
                 <div class="p-4 bg-white rounded-b-lg">
-                  <div class="grid grid-cols-1 gap-4">
+                  <div class="grid grid-cols-1 gap-4" x-data="{ onlyImages: false, onlyVariants: false }">
 
                     <!-- Manuscript Select -->
                     <div class="w-full">
                       <label for="manuscript-select" class="block text-gray-700 text-sm font-bold mb-2">Select Manuscript:</label>
-                      <select 
-                        id="manuscript-select" 
+                      <select
+                        id="manuscript-select"
                         onchange="window.location.href=`/manuscripts/${this.value}/stanzas/`"
                         class="w-full p-2 border border-gray-300 rounded-md shadow-sm focus:border-blue-500 focus:ring-blue-500">
                         {% for manuscript in manuscripts %}
                             {% if manuscript.iiif_url or manuscript.has_variants %}
                             <option value="{{ manuscript.siglum }}"
-                                    {% if manuscript.siglum == default_manuscript.siglum %}selected{% endif %}>
+                                    {% if manuscript.siglum == default_manuscript.siglum %}selected{% endif %}
+                                    :hidden="(onlyImages && !{{ manuscript.iiif_url|yesno:'true,false' }}) || (onlyVariants && !{{ manuscript.has_variants|yesno:'true,false' }})">
                               {{ manuscript|format_ms }}
                             </option>
                             {% endif %}
                         {% endfor %}
                       </select>
                     </div>
-                    
+
+                    <!-- Manuscript filters -->
+                    <div class="w-full space-y-2">
+                      <label class="flex items-center cursor-pointer">
+                        <input type="checkbox" x-model="onlyImages"
+                          class="h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded cursor-pointer">
+                        <span class="ml-2 pt-1 block text-[1rem]">Only show manuscripts with images</span>
+                      </label>
+                      <label class="flex items-center cursor-pointer">
+                        <input type="checkbox" x-model="onlyVariants"
+                          class="h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded cursor-pointer">
+                        <span class="ml-2 pt-1 block text-[1rem]">Only show manuscripts with textual variants</span>
+                      </label>
+                    </div>
+
                     <!-- Line Code Display -->
                     <div class="w-full">
                       <label for="lineCodeDisplay" class="block text-gray-700 text-sm font-bold mb-2">Line code display:</label>

From 449fc345b372908b52c1d0973bcac3704b2db7f3 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Thu, 22 Oct 2026 11:59:54 -0700
Subject: [PATCH 10/13] Show a banner on the test site

---
 config/context_processors.py             |  5 +++++
 config/settings.py                       |  4 ++++
 config/tests.py                          | 15 +++++++++++++++
 templates/admin/base.html                | 10 ++++++++++
 templates/base.html                      |  1 +
 templates/partials/test_site_banner.html | 10 ++++++++++
 6 files changed, 45 insertions(+)
 create mode 100644 config/tests.py
 create mode 100644 templates/admin/base.html
 create mode 100644 templates/partials/test_site_banner.html

diff --git a/config/context_processors.py b/config/context_processors.py
index 090ede4..727e5a8 100644
--- a/config/context_processors.py
+++ b/config/context_processors.py
@@ -4,3 +4,8 @@
 def carto(request):
     """Expose the CARTO API key to templates for the gazetteer basemaps."""
     return {"CARTO_API_KEY": settings.CARTO_API_KEY}
+
+
+def test_site_banner(request):
+    """Whether to show the test site banner, on the site and in the admin."""
+    return {"TEST_SITE_BANNER": settings.TEST_SITE_BANNER}
diff --git a/config/settings.py b/config/settings.py
index 4a499af..9b9815e 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -40,6 +40,9 @@
 
 # CARTO API key for the gazetteer basemaps (client-exposed)
 CARTO_API_KEY = env("CARTO_API_KEY", default="")
+# Show a banner on every page saying this is a test site whose changes won't
+# carry over to the live site; turn on for staging
+TEST_SITE_BANNER = env.bool("TEST_SITE_BANNER", default=False)
 
 # Application definition
 
@@ -121,6 +124,7 @@
                 "django.contrib.messages.context_processors.messages",
                 "django.template.context_processors.request",
                 "config.context_processors.carto",
+                "config.context_processors.test_site_banner",
             ],
         },
     },
diff --git a/config/tests.py b/config/tests.py
new file mode 100644
index 0000000..ff5ed06
--- /dev/null
+++ b/config/tests.py
@@ -0,0 +1,15 @@
+from django.test import TestCase, override_settings
+from django.urls import reverse
+
+BANNER = "Anything you add or change here may be removed"
+
+
+class TestSiteBannerTest(TestCase):
+    def test_hidden_by_default(self):
+        self.assertNotContains(self.client.get(reverse("dmca")), BANNER)
+        self.assertNotContains(self.client.get(reverse("admin:login")), BANNER)
+
+    @override_settings(TEST_SITE_BANNER=True)
+    def test_shown_on_site_and_admin(self):
+        self.assertContains(self.client.get(reverse("dmca")), BANNER)
+        self.assertContains(self.client.get(reverse("admin:login")), BANNER)
diff --git a/templates/admin/base.html b/templates/admin/base.html
new file mode 100644
index 0000000..63acb12
--- /dev/null
+++ b/templates/admin/base.html
@@ -0,0 +1,10 @@
+{% extends "admin/base.html" %}
+{% comment %}
+  Extends Django's own admin/base.html (the admin theme's base_site.html
+  builds on this) to show the test site banner above the admin header.
+{% endcomment %}
+
+{% block header %}
+  {% include "partials/test_site_banner.html" %}
+  {{ block.super }}
+{% endblock %}
diff --git a/templates/base.html b/templates/base.html
index fc88998..5421afb 100644
--- a/templates/base.html
+++ b/templates/base.html
@@ -105,6 +105,7 @@
     <body class="flex flex-col min-h-screen {% if is_index %}bg-slate-800{% endif %}">
       <div class="min-h-screen bg-white">
 
+        {% include 'partials/test_site_banner.html' %}
 
         {% include 'partials/navigation.html' %}
         <main class="flex-grow {% if is_index %}no-padding{% endif %}">
diff --git a/templates/partials/test_site_banner.html b/templates/partials/test_site_banner.html
new file mode 100644
index 0000000..5822b0d
--- /dev/null
+++ b/templates/partials/test_site_banner.html
@@ -0,0 +1,10 @@
+{% comment %}
+  Shown when the TEST_SITE_BANNER setting is on (e.g. on staging). Styled
+  inline so it looks the same on the site and in the admin.
+{% endcomment %}
+{% if TEST_SITE_BANNER %}
+  <div role="note" style="background: #fef3c7; color: #78350f; border-bottom: 1px solid #f59e0b; padding: 8px 16px; text-align: center; font-size: 0.875rem; line-height: 1.4;">
+    <strong>Test site.</strong>
+    Anything you add or change here may be removed, and won't carry over to the live site.
+  </div>
+{% endif %}

From 653b4cee0ed2697661bab5bbe41338f1ecee8e5c Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Thu, 22 Oct 2026 13:36:08 -0700
Subject: [PATCH 11/13] Improve folio admin UI

---
 manuscript/admin.py                           | 17 +++++++++++++--
 manuscript/tests.py                           | 19 +++++++++++++++++
 static/js/canvas_linking.js                   | 21 ++++++++++++++-----
 .../singlemanuscript/link_canvases.html       |  6 +++---
 4 files changed, 53 insertions(+), 10 deletions(-)

diff --git a/manuscript/admin.py b/manuscript/admin.py
index 5b89591..02de4ed 100644
--- a/manuscript/admin.py
+++ b/manuscript/admin.py
@@ -5,7 +5,8 @@
 from django.contrib.admin.utils import unquote
 from django.contrib.contenttypes.admin import GenericTabularInline
 from django.core.exceptions import PermissionDenied, ValidationError
-from django.db.models import Count
+from django.db.models import Count, Value
+from django.db.models.functions import Concat
 from django.shortcuts import redirect
 from django.template.response import TemplateResponse
 from django.urls import path, reverse
@@ -469,12 +470,14 @@ class FolioAdmin(ImportExportModelAdmin):
     form = FolioAdminForm
 
     list_display = [
-        "manuscript",
+        "folio_display",
         "folio_number",
         "canvas_label",
         "line_range_display",
         "stanza_count",
     ]
+    list_select_related = ["manuscript"]
+    ordering = ["manuscript__siglum", "folio_number"]
     list_filter = ["manuscript", ("canvas_id", admin.EmptyFieldListFilter)]
     search_fields = [
         "folio_number",
@@ -573,7 +576,17 @@ def stanza_count(self, obj):
 
     stanza_count.short_description = "Number of Stanzas"
 
+    @admin.display(
+        description="Folio",
+        ordering=Concat("manuscript__siglum", Value(" "), "folio_number"),
+    )
+    def folio_display(self, obj):
+        manuscript = obj.manuscript or "No manuscript"
+        return f"{manuscript} · {obj.folio_number or '(no folio number)'}"
+
     def line_range_display(self, obj):
+        if not obj.line_code_range_start:
+            return "-"
         end = obj.line_code_range_end or "End"
         return f"{obj.line_code_range_start} → {end}"
 
diff --git a/manuscript/tests.py b/manuscript/tests.py
index c4c6ad1..e5b022b 100644
--- a/manuscript/tests.py
+++ b/manuscript/tests.py
@@ -441,6 +441,25 @@ def test_folio_page_shows_image_and_toponyms(self):
         )
         self.assertContains(response, "Rodi</a> (T001)")
 
+    def test_folio_list_links_by_manuscript_and_folio(self):
+        folio = Folio.objects.create(manuscript=self.manuscript, folio_number="1r")
+        Folio.objects.create(manuscript=self.manuscript)
+        response = self.client.get(reverse("admin:manuscript_folio_changelist"))
+
+        folio_url = reverse("admin:manuscript_folio_change", args=[folio.pk])
+        self.assertContains(
+            response, f'<a href="{folio_url}">Test1 · 1r</a>', html=True
+        )
+        self.assertContains(response, "Test1 · (no folio number)")
+        # sorting by the combined column and by folio number alone both work
+        for column in ["1", "2"]:
+            self.assertEqual(
+                self.client.get(
+                    reverse("admin:manuscript_folio_changelist"), {"o": column}
+                ).status_code,
+                200,
+            )
+
     def test_folio_page_edits_notes(self):
         folio = Folio.objects.create(manuscript=self.manuscript, folio_number="1r")
         response = self.client.get(
diff --git a/static/js/canvas_linking.js b/static/js/canvas_linking.js
index a412f21..649658a 100644
--- a/static/js/canvas_linking.js
+++ b/static/js/canvas_linking.js
@@ -33,6 +33,16 @@
   }
   const folioKey = (number) => normalizeFolioLabel(number) || number.trim().toLowerCase();
 
+  // The folio number in a manifest label in its usual form, e.g. "53r" from
+  // "Carta: 53r" or "53 recto", or null if the label doesn't contain one
+  function folioNumberFromLabel(label) {
+    const match = normalizeFolioLabel(label).match(/^(\d+)([rv])$/);
+    if (match) return `${Number(match[1])}${match[2]}`;
+    // roman-numbered flyleaves, e.g. "Ir", when that's the whole label
+    if (/^[ivxlc]+[rv]$/i.test(label.trim())) return label.trim();
+    return null;
+  }
+
   // Flatten a IIIF v2 or v3 label into a plain string
   function labelToString(label) {
     if (!label) return '';
@@ -273,16 +283,17 @@
     if (submitted && input.value !== initial) dirty = true;
     folioCell.appendChild(input);
 
-    // offer the manifest label as the folio number when it looks like one
+    // offer the folio number in the manifest label, when it has one
     let suggestion = null;
-    if (RECTO_VERSO.test(normalizeFolioLabel(canvas.label))) {
+    const suggestedNumber = folioNumberFromLabel(canvas.label);
+    if (suggestedNumber) {
       suggestion = document.createElement('button');
       suggestion.type = 'button';
       suggestion.className = 'canvas-suggestion';
-      suggestion.textContent = `Use ${canvas.label}`;
-      suggestion.title = 'Use the manifest label as the folio number';
+      suggestion.textContent = `Use ${suggestedNumber}`;
+      suggestion.title = `Use the folio number from the manifest label "${canvas.label}"`;
       suggestion.addEventListener('click', () => {
-        input.value = canvas.label;
+        input.value = suggestedNumber;
         input.dispatchEvent(new Event('input'));
         input.focus();
       });
diff --git a/templates/admin/manuscript/singlemanuscript/link_canvases.html b/templates/admin/manuscript/singlemanuscript/link_canvases.html
index 2ae23ed..c5fa67f 100644
--- a/templates/admin/manuscript/singlemanuscript/link_canvases.html
+++ b/templates/admin/manuscript/singlemanuscript/link_canvases.html
@@ -65,9 +65,9 @@
           <li>Look at the image, work out which folio of the manuscript it shows, and enter that folio's
 number (for example 12r) to link the image to the text.</li>
           <li>You can click each image to see it larger.</li>
-          <li>For a quick start, use <strong>Fill in folio numbers from manifest labels</strong>: it copies an
-          image's manifest label into its empty folio number box when the label appears only once in the
-          manifest and matches a Folio record that isn't linked yet. Check the results before saving.</li>
+          <li>For a quick start, use <strong>Fill in folio numbers from manifest labels</strong>: when an
+          image's manifest label (e.g. "Carta: 53r") appears only once in the manifest and matches a Folio
+          record that isn't linked yet, it fills in that folio's number. Check the results before saving.</li>
           <li>Clear a folio number to unlink it.</li>
           <li>Use the <strong>Show</strong> menu to narrow the list, for example to images not linked yet, your
           unsaved changes, or rows with problems that need fixing before you can save.</li>

From b79a3de2b20865f7cddbd83c5cfef66d441183b6 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Fri, 23 Oct 2026 07:24:53 -0700
Subject: [PATCH 12/13] Open the image viewer on the current folio

---
 static/js/tify-sync.js | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/static/js/tify-sync.js b/static/js/tify-sync.js
index a7ef7e6..46770bc 100644
--- a/static/js/tify-sync.js
+++ b/static/js/tify-sync.js
@@ -26,6 +26,10 @@ const TifySync = {
       }
     }
     
+    // Open the viewer on the reader's current folio rather than on the
+    // manifest's first page
+    const initialPage = this.initialPage();
+
     // Initialize Tify viewer
     this.viewer = new Tify({
       container: `#${containerId}`,
@@ -34,6 +38,7 @@ const TifySync = {
       view: '', // Default to scan view
       optionsResetOnPageChange: ['pan'],
       urlQueryKey: null, // Disable URL parameter changes to avoid conflicts
+      ...(initialPage ? { pages: [initialPage] } : {}),
     });
 
     this.viewer.ready.then(() => {
@@ -50,6 +55,32 @@ const TifySync = {
     return true;
   },
   
+  // The viewer page for the folio the reader is at: the last folio divider
+  // above the lower edge of the band the scroll observer watches (20-40% from
+  // the top of the window). Null if there's none or it has no matching image.
+  initialPage() {
+    if (!this.manifestData) {
+      return null;
+    }
+    const bandBottom = window.innerHeight * 0.4;
+    let divider = null;
+    for (const candidate of document.querySelectorAll('.folio-divider')) {
+      if (candidate.getBoundingClientRect().top > bandBottom) {
+        break;
+      }
+      divider = candidate;
+    }
+    if (!divider) {
+      return null;
+    }
+    const index = this.findCanvasIndex(
+      this.getCanvases(this.manifestData),
+      divider.dataset.folioNumber,
+      divider.dataset.canvasId || null,
+    );
+    return index === -1 ? null : index + 1;
+  },
+
   setupEventListeners() {
     // Listen for custom events from Tify
     // Note: Tify might emit certain events when page changes
@@ -165,6 +196,13 @@ const TifySync = {
         
         // Tify uses 1-based page numbers
         const tifyPageNumber = pageIndex + 1;
+
+        // Don't reopen the page the viewer is already showing
+        const currentPages = this.viewer && this.viewer.options && this.viewer.options.pages;
+        if (currentPages && currentPages.length === 1 && currentPages[0] === tifyPageNumber) {
+          console.log('Viewer is already on page', tifyPageNumber);
+          return;
+        }
         
         // Navigate to the page using Tify's API
         // If Tify provides a direct method to go to a page:

From a9d6ca07386ac33028685f1a7a93f5c18ecb7929 Mon Sep 17 00:00:00 2001
From: Ben Silverman <ben@performantsoftware.com>
Date: Mon, 26 Oct 2026 14:08:39 -0400
Subject: [PATCH 13/13] Add missing migration from main

---
 ...dy_alter_homeintroduction_body_and_more.py | 248 ++++++++++++++++++
 pages/models.py                               |  14 +
 2 files changed, 262 insertions(+)
 create mode 100644 pages/migrations/0012_alter_aboutpage_body_alter_homeintroduction_body_and_more.py

diff --git a/pages/migrations/0012_alter_aboutpage_body_alter_homeintroduction_body_and_more.py b/pages/migrations/0012_alter_aboutpage_body_alter_homeintroduction_body_and_more.py
new file mode 100644
index 0000000..36bad56
--- /dev/null
+++ b/pages/migrations/0012_alter_aboutpage_body_alter_homeintroduction_body_and_more.py
@@ -0,0 +1,248 @@
+# Generated by Django 5.1.15 on 2026-10-26 18:06
+
+import wagtail.fields
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("pages", "0011_alter_aboutpage_body_alter_homeintroduction_body_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="aboutpage",
+            name="body",
+            field=wagtail.fields.StreamField(
+                [
+                    ("paragraph", 0),
+                    ("heading", 1),
+                    ("image", 6),
+                    ("video", 7),
+                    ("quote", 8),
+                    ("accordion", 11),
+                ],
+                blank=True,
+                block_lookup={
+                    0: ("wagtail.blocks.RichTextBlock", (), {"icon": "pilcrow"}),
+                    1: ("wagtail.blocks.CharBlock", (), {"icon": "title"}),
+                    2: (
+                        "wagtail.images.blocks.ImageChooserBlock",
+                        (),
+                        {"required": True},
+                    ),
+                    3: (
+                        "wagtail.blocks.CharBlock",
+                        (),
+                        {
+                            "help_text": "Optional caption for the image",
+                            "required": False,
+                        },
+                    ),
+                    4: (
+                        "wagtail.blocks.CharBlock",
+                        (),
+                        {
+                            "help_text": "Describe the image for screen readers. Defaults to the image title.",
+                            "required": False,
+                        },
+                    ),
+                    5: (
+                        "wagtail.blocks.ChoiceBlock",
+                        [],
+                        {
+                            "choices": [
+                                ("center", "Centered (default size)"),
+                                ("full", "Full width"),
+                                ("left", "Float left (text wraps)"),
+                                ("right", "Float right (text wraps)"),
+                            ],
+                            "required": False,
+                        },
+                    ),
+                    6: (
+                        "wagtail.blocks.StructBlock",
+                        [
+                            [
+                                ("image", 2),
+                                ("caption", 3),
+                                ("alt_text", 4),
+                                ("alignment", 5),
+                            ]
+                        ],
+                        {},
+                    ),
+                    7: (
+                        "wagtail.embeds.blocks.EmbedBlock",
+                        (),
+                        {"icon": "media", "max_height": 400, "max_width": 800},
+                    ),
+                    8: ("wagtail.blocks.BlockQuoteBlock", (), {"icon": "openquote"}),
+                    9: ("wagtail.blocks.CharBlock", (), {"required": True}),
+                    10: ("wagtail.blocks.RichTextBlock", (), {"required": True}),
+                    11: (
+                        "wagtail.blocks.StructBlock",
+                        [[("title", 9), ("content", 10)]],
+                        {},
+                    ),
+                },
+            ),
+        ),
+        migrations.AlterField(
+            model_name="homeintroduction",
+            name="body",
+            field=wagtail.fields.StreamField(
+                [
+                    ("paragraph", 0),
+                    ("heading", 1),
+                    ("image", 6),
+                    ("video", 7),
+                    ("quote", 8),
+                    ("accordion", 11),
+                ],
+                blank=True,
+                block_lookup={
+                    0: ("wagtail.blocks.RichTextBlock", (), {"icon": "pilcrow"}),
+                    1: ("wagtail.blocks.CharBlock", (), {"icon": "title"}),
+                    2: (
+                        "wagtail.images.blocks.ImageChooserBlock",
+                        (),
+                        {"required": True},
+                    ),
+                    3: (
+                        "wagtail.blocks.CharBlock",
+                        (),
+                        {
+                            "help_text": "Optional caption for the image",
+                            "required": False,
+                        },
+                    ),
+                    4: (
+                        "wagtail.blocks.CharBlock",
+                        (),
+                        {
+                            "help_text": "Describe the image for screen readers. Defaults to the image title.",
+                            "required": False,
+                        },
+                    ),
+                    5: (
+                        "wagtail.blocks.ChoiceBlock",
+                        [],
+                        {
+                            "choices": [
+                                ("center", "Centered (default size)"),
+                                ("full", "Full width"),
+                                ("left", "Float left (text wraps)"),
+                                ("right", "Float right (text wraps)"),
+                            ],
+                            "required": False,
+                        },
+                    ),
+                    6: (
+                        "wagtail.blocks.StructBlock",
+                        [
+                            [
+                                ("image", 2),
+                                ("caption", 3),
+                                ("alt_text", 4),
+                                ("alignment", 5),
+                            ]
+                        ],
+                        {},
+                    ),
+                    7: (
+                        "wagtail.embeds.blocks.EmbedBlock",
+                        (),
+                        {"icon": "media", "max_height": 400, "max_width": 800},
+                    ),
+                    8: ("wagtail.blocks.BlockQuoteBlock", (), {"icon": "openquote"}),
+                    9: ("wagtail.blocks.CharBlock", (), {"required": True}),
+                    10: ("wagtail.blocks.RichTextBlock", (), {"required": True}),
+                    11: (
+                        "wagtail.blocks.StructBlock",
+                        [[("title", 9), ("content", 10)]],
+                        {},
+                    ),
+                },
+            ),
+        ),
+        migrations.AlterField(
+            model_name="sitepage",
+            name="body",
+            field=wagtail.fields.StreamField(
+                [
+                    ("paragraph", 0),
+                    ("heading", 1),
+                    ("image", 6),
+                    ("video", 7),
+                    ("quote", 8),
+                    ("accordion", 11),
+                ],
+                blank=True,
+                block_lookup={
+                    0: ("wagtail.blocks.RichTextBlock", (), {"icon": "pilcrow"}),
+                    1: ("wagtail.blocks.CharBlock", (), {"icon": "title"}),
+                    2: (
+                        "wagtail.images.blocks.ImageChooserBlock",
+                        (),
+                        {"required": True},
+                    ),
+                    3: (
+                        "wagtail.blocks.CharBlock",
+                        (),
+                        {
+                            "help_text": "Optional caption for the image",
+                            "required": False,
+                        },
+                    ),
+                    4: (
+                        "wagtail.blocks.CharBlock",
+                        (),
+                        {
+                            "help_text": "Describe the image for screen readers. Defaults to the image title.",
+                            "required": False,
+                        },
+                    ),
+                    5: (
+                        "wagtail.blocks.ChoiceBlock",
+                        [],
+                        {
+                            "choices": [
+                                ("center", "Centered (default size)"),
+                                ("full", "Full width"),
+                                ("left", "Float left (text wraps)"),
+                                ("right", "Float right (text wraps)"),
+                            ],
+                            "required": False,
+                        },
+                    ),
+                    6: (
+                        "wagtail.blocks.StructBlock",
+                        [
+                            [
+                                ("image", 2),
+                                ("caption", 3),
+                                ("alt_text", 4),
+                                ("alignment", 5),
+                            ]
+                        ],
+                        {},
+                    ),
+                    7: (
+                        "wagtail.embeds.blocks.EmbedBlock",
+                        (),
+                        {"icon": "media", "max_height": 400, "max_width": 800},
+                    ),
+                    8: ("wagtail.blocks.BlockQuoteBlock", (), {"icon": "openquote"}),
+                    9: ("wagtail.blocks.CharBlock", (), {"required": True}),
+                    10: ("wagtail.blocks.RichTextBlock", (), {"required": True}),
+                    11: (
+                        "wagtail.blocks.StructBlock",
+                        [[("title", 9), ("content", 10)]],
+                        {},
+                    ),
+                },
+            ),
+        ),
+    ]
diff --git a/pages/models.py b/pages/models.py
index 74b127b..c9512f4 100644
--- a/pages/models.py
+++ b/pages/models.py
@@ -16,6 +16,20 @@ class ImageBlock(blocks.StructBlock):
     caption = blocks.CharBlock(
         required=False, help_text="Optional caption for the image"
     )
+    alt_text = blocks.CharBlock(
+        required=False,
+        help_text="Describe the image for screen readers. Defaults to the image title.",
+    )
+    alignment = blocks.ChoiceBlock(
+        choices=[
+            ("center", "Centered (default size)"),
+            ("full", "Full width"),
+            ("left", "Float left (text wraps)"),
+            ("right", "Float right (text wraps)"),
+        ],
+        default="center",
+        required=False,
+    )
 
     class Meta:
         icon = "image"