Headless draft preview: snapshot + token endpoint on the CMS

FrontendPageMixin disabled preview entirely (no Django templates), so
editors had no way to see a draft before publishing. Re-enable it
headlessly on content pages: serve_preview serializes the draft exactly
as the content API would (same _serialize_page, portal-tag injection
included), parks it in a PreviewSnapshot row, and redirects the editor's
preview iframe/tab to the frontend. The unguessable uuid pk is the whole
authorization for GET /api/content/preview/<token> — 1h TTL, pruned on
write. Index pages stay non-previewable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: nofurtherinformation

cms/content/api.py

@@ -28,7 +28,7 @@
 from django.conf import settings
 from django.views.decorators.http import require_GET
 
-from content.models import PlacePage, StaticPage, TagPage
+from content.models import PlacePage, PreviewSnapshot, StaticPage, TagPage
 from core.api import _json, pagination
 
 CONTENT_TYPE_PAGES = {
@@ -127,6 +127,19 @@ def content_detail(request, content_type, slug):
     )
 
 
+@require_GET
+def content_preview(request, token):
+    """GET /api/content/preview/<token>
+
+    Draft snapshot minted by the editor's Preview button
+    (ContentPageBase.serve_preview). Token-gated: the unguessable uuid with a
+    short TTL is the whole authorization, so no auth header is required."""
+    snapshot = PreviewSnapshot.fresh().filter(token=token).first()
+    if snapshot is None:
+        return _json({"detail": "Preview expired or not found"}, status=404)
+    return _json(snapshot.data)
+
+
 @require_GET
 def content_list(request, content_type):
     """GET /api/content/<type>/list?language=xx&offset=n&limit=n

cms/content/migrations/0004_previewsnapshot.py

@@ -0,0 +1,28 @@
+import uuid
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("content", "0003_import_legacy_content"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="PreviewSnapshot",
+            fields=[
+                (
+                    "token",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("data", models.JSONField()),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+            ],
+        ),
+    ]

cms/content/models.py

@@ -19,10 +19,15 @@
 no extra join table, and the slugs are not translatable content.
 """
 
+import uuid
+from datetime import timedelta
+
 from django.conf import settings
 from django.contrib.postgres.fields import ArrayField
 from django.core.exceptions import ValidationError
 from django.db import DatabaseError, models, transaction
+from django.shortcuts import redirect
+from django.utils import timezone
 from wagtail.admin.panels import FieldPanel
 from wagtail.fields import StreamField
 from wagtail.models import Page
@@ -39,7 +44,8 @@ class FrontendPageMixin:
 
     - ``preview_modes = []`` disables the editor Preview panel and the "View
       draft" button; there is no Django template, so previewing raised
-      TemplateDoesNotExist 500s.
+      TemplateDoesNotExist 500s. ContentPageBase re-enables it headlessly
+      via snapshot + frontend redirect (serve_preview below).
     - URL generation is redirected at the single choke point Wagtail
       documents for custom routing, ``get_url_parts``, so every derived link
       ("View live" in the editor header/listings/flash messages, usage
@@ -77,12 +83,56 @@ def url(self):
         return self.get_url()
 
 
+class PreviewSnapshot(models.Model):
+    """A draft page serialized exactly as the content API would serve it,
+    parked for the frontend preview route. The row IS the capability: the
+    unguessable pk is the whole grant (short TTL, pruned on write), so the
+    fetch endpoint needs no auth."""
+
+    TTL = timedelta(hours=1)
+
+    token = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    data = models.JSONField()
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    @classmethod
+    def fresh(cls):
+        return cls.objects.filter(created_at__gte=timezone.now() - cls.TTL)
+
+    @classmethod
+    def prune(cls):
+        cls.objects.filter(created_at__lt=timezone.now() - cls.TTL).delete()
+
+
 class ContentPageBase(FrontendPageMixin, Page):
     """Shared shape of tag/place pages: subtitle + StreamField body."""
 
     subtitle = models.CharField(max_length=255, blank=True, default="")
     body = StreamField(ContentStreamBlock(), blank=True)
 
+    # Content type key in the public API (content/api.py CONTENT_TYPE_PAGES).
+    api_content_type: str
+
+    # Re-enable the Preview panel / "View draft" button the mixin disables:
+    # previews are headless too — serve_preview parks a serialized snapshot
+    # and hands the editor's iframe/tab to the frontend, which fetches it
+    # back by token (GET /api/content/preview/<token>).
+    preview_modes = [("frontend", "Preview on site")]
+
+    def serve_preview(self, request, mode_name):
+        # Local import: content.api imports these models.
+        from content.api import _serialize_page
+
+        PreviewSnapshot.prune()
+        snapshot = PreviewSnapshot.objects.create(
+            data={
+                "content": _serialize_page(self, self.api_content_type),
+                "available_languages": [self.locale.language_code],
+                "type": self.api_content_type,
+            }
+        )
+        return redirect(f"{settings.FRONTEND_URL}/preview/{snapshot.token}")
+
     content_panels = Page.content_panels + [
         FieldPanel("subtitle"),
         FieldPanel("body"),
@@ -154,6 +204,7 @@ class StaticPage(ContentPageBase):
     /api/content/static/slug/<slug>; a hardcoded Next.js route with the same
     path takes precedence, so pages can migrate into the CMS one at a time."""
 
+    api_content_type = "static"
     parent_page_types = ["content.StaticIndexPage"]
     subpage_types: list[str] = []
 
@@ -174,6 +225,7 @@ class TagPage(ContentPageBase):
         help_text="Slug of the Districtr map module this tag page features.",
     )
 
+    api_content_type = "tags"
     parent_page_types = ["content.TagsIndexPage"]
     subpage_types: list[str] = []
 
@@ -230,6 +282,7 @@ class PlacePage(ContentPageBase):
         help_text="Slugs of the Districtr map modules this place page features.",
     )
 
+    api_content_type = "places"
     parent_page_types = ["content.PlacesIndexPage"]
     subpage_types: list[str] = []
 

cms/content/tests.py

@@ -20,13 +20,15 @@
 from django.core.management import call_command as django_call_command
 from django.core.management.base import CommandError
 from django.db import connection
-from django.test import SimpleTestCase, TestCase, override_settings
+from django.test import RequestFactory, SimpleTestCase, TestCase, override_settings
+from django.utils import timezone
 from wagtail.models import GroupPagePermission, Locale, Page, Revision, Site
 from wagtail.permission_policies.pages import PagePermissionPolicy
 
 from content.models import (
     PlacePage,
     PlacesIndexPage,
+    PreviewSnapshot,
     StaticIndexPage,
     StaticPage,
     TagPage,
@@ -623,22 +625,22 @@ def test_index_page_urls(self):
         # No frontend listing for static pages: not routable, no "View live".
         self.assertIsNone(self.static_index.url)
 
-    def test_preview_disabled(self):
+    def test_index_preview_disabled(self):
         # No Wagtail template exists; previewing raised TemplateDoesNotExist.
-        for page in (
-            self.tag,
-            self.place,
-            self.static,
-            self.tags_index,
-            self.places_index,
-            self.static_index,
-        ):
+        # Content pages preview headlessly instead (PreviewTests); index
+        # pages have nothing to preview.
+        for page in (self.tags_index, self.places_index, self.static_index):
             self.assertEqual(page.preview_modes, [])
             self.assertFalse(page.is_previewable())
 
+    def test_content_pages_are_previewable(self):
+        for page in (self.tag, self.place, self.static):
+            self.assertTrue(page.is_previewable())
+
     def test_admin_editor_shows_frontend_live_url(self):
         # The page editor (where Preview/"View live" 500'd) renders, offers
-        # no preview panel, and links "View live" at the frontend URL.
+        # the headless preview panel, and links "View live" at the frontend
+        # URL.
         self.tag.save_revision(clean=False).publish()
         get_user_model().objects.create_superuser(
             username="root@districtr.org",
@@ -652,7 +654,7 @@ def test_admin_editor_shows_frontend_live_url(self):
         self.assertEqual(response.status_code, 200)
         html = response.content.decode()
         self.assertIn("https://beta.districtr.org/portal/fair-maps", html)
-        self.assertNotIn('data-side-panel-toggle="preview"', html)
+        self.assertIn('data-side-panel-toggle="preview"', html)
 
 
 # ---------------------------------------------------------------------------
@@ -1175,3 +1177,49 @@ def test_json_report(self):
         )
         self.assertTrue(entry["text_ok"])
         self.assertEqual(entry["docs"]["published"]["output_blocks"]["plan_gallery"], 1)
+
+
+@override_settings(FRONTEND_URL="https://beta.districtr.org")
+class PreviewTests(TestCase):
+    """Headless preview: serve_preview parks a serialized snapshot and
+    redirects to the frontend, which fetches it back by token."""
+
+    @classmethod
+    def setUpTestData(cls):
+        en = Locale.objects.get(language_code="en")
+        static_index = StaticIndexPage.objects.get(locale=en)
+        cls.draft = StaticPage(title="Draft About", slug="about-draft", live=False)
+        static_index.add_child(instance=cls.draft)
+
+    def test_serve_preview_snapshots_and_redirects(self):
+        response = self.draft.serve_preview(RequestFactory().get("/"), "frontend")
+        self.assertEqual(response.status_code, 302)
+        prefix = "https://beta.districtr.org/preview/"
+        self.assertTrue(response["Location"].startswith(prefix))
+
+        token = response["Location"].removeprefix(prefix)
+        snapshot = PreviewSnapshot.objects.get(token=token)
+        self.assertEqual(snapshot.data["type"], "static")
+        self.assertEqual(snapshot.data["content"]["title"], "Draft About")
+        self.assertEqual(snapshot.data["available_languages"], ["en"])
+
+    def test_preview_endpoint_serves_fresh_and_404s_expired(self):
+        response = self.draft.serve_preview(RequestFactory().get("/"), "frontend")
+        token = response["Location"].rsplit("/", 1)[-1]
+        url = f"/api/content/preview/{token}"
+
+        payload = self.client.get(url).json()
+        self.assertEqual(payload["content"]["slug"], "about-draft")
+
+        PreviewSnapshot.objects.filter(token=token).update(
+            created_at=timezone.now() - PreviewSnapshot.TTL * 2
+        )
+        self.assertEqual(self.client.get(url).status_code, 404)
+
+    def test_prune_on_mint_drops_stale_snapshots(self):
+        stale = PreviewSnapshot.objects.create(data={})
+        PreviewSnapshot.objects.filter(token=stale.token).update(
+            created_at=timezone.now() - PreviewSnapshot.TTL * 2
+        )
+        self.draft.serve_preview(RequestFactory().get("/"), "frontend")
+        self.assertFalse(PreviewSnapshot.objects.filter(token=stale.token).exists())

cms/content/urls.py

@@ -5,6 +5,7 @@
 app_name = "content"
 
 urlpatterns = [
+    path("preview/<uuid:token>", api.content_preview, name="preview"),
     path("<str:content_type>/slug/<slug:slug>", api.content_detail, name="detail"),
     path("<str:content_type>/list", api.content_list, name="list"),
 ]