Normalize Birch page shell during finalization

research/app_artifacts.py

@@ -23,6 +23,12 @@ MARKER_STYLE_RE = re.compile(
     rf"<style\b[^>]*>\s*{re.escape(MARKER)}\s*</style>",
     re.I | re.S,
 )
+PAGE_RE = re.compile(
+    r'<main\b[^>]*\bclass=["\'][^"\']*\bpage\b[^"\']*["\']',
+    re.I,
+)
+MAIN_CLASS_RE = re.compile(r'(<main\b[^>]*\bclass=["\'])([^"\']*)', re.I)
+MAIN_RE = re.compile(r"<main\b", re.I)
 
 
 def finalize_bucket_html(
@@ -62,7 +68,7 @@ def finalize_bucket_html(
             return _artifact_urls(username, job.id)
 
         css = _birch_css_path(home).read_text()
-        finalized = _inject_birch_css(html, css)
+        finalized = _ensure_page_shell(_inject_birch_css(html, css))
         _validate_html(finalized)
         api.batch_bucket_files(
             bucket_id,
@@ -110,6 +116,17 @@ def _inject_birch_css(html: str, css: str) -> str:
     return html.replace(MARKER, css.strip())
 
 
+def _ensure_page_shell(html: str) -> str:
+    """Add Birch's required `.page` class to the first main element."""
+    if PAGE_RE.search(html):
+        return html
+    if MAIN_CLASS_RE.search(html):
+        return MAIN_CLASS_RE.sub(r"\1page \2", html, count=1)
+    if MAIN_RE.search(html):
+        return MAIN_RE.sub('<main class="page"', html, count=1)
+    return html
+
+
 def _download_first(
     api: Any,
     bucket_id: str,
@@ -155,6 +172,8 @@ def _validate_html(html: str) -> None:
         raise ValueError("HTML artifact has no doctype")
     if not STYLE_RE.search(html):
         raise ValueError("HTML artifact has no embedded Birch stylesheet")
+    if not PAGE_RE.search(html):
+        raise ValueError("HTML artifact has no Birch page shell")
     if "</html>" not in html.lower():
         raise ValueError("HTML artifact is incomplete")