diff --git a/docs/MCP.md b/docs/MCP.md
index 5a5c0db..7a67883 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -214,7 +214,7 @@ Export tools write artifact files with a 24-hour TTL; in-app chat renders downlo
### Export and deliverables
-`export_audit_report`, `export_compare_csv`, `export_list_as_csv`, `export_sitemap_xml`, `validate_rich_results`, `compose_custom_report`, `export_custom_report`, `list_export_formats`
+`export_audit_report`, `export_compare_csv`, `export_list_as_csv`, `export_sitemap_xml`, `validate_rich_results`, `list_export_formats`
Full audit exports use the same generators as the Export view. PDF export requires `reportlab`.
diff --git a/src/website_profiling/llm/agent.py b/src/website_profiling/llm/agent.py
index 40418c6..985abdb 100644
--- a/src/website_profiling/llm/agent.py
+++ b/src/website_profiling/llm/agent.py
@@ -79,7 +79,6 @@ def _max_tool_rounds(cfg: dict[str, str]) -> int:
- Full audit PDF/HTML/CSV/JSON: export_audit_report with format pdf|html|csv|json
- Compare issue diff CSV: export_compare_csv with baseline_report_id
- Export a list as CSV: export_list_as_csv with tool_name and tool_args (e.g. list_broken_links)
-- Custom client report: compose_custom_report with title and sections (executive_summary, category_scores, tool, notes), then export_custom_report format=pdf or html
- After export tools succeed, tell the user their download is ready; the UI renders file buttons automatically
Visualization playbook (chat UI renders charts and tables from tool JSON automatically):
diff --git a/src/website_profiling/reporting/pdf/__init__.py b/src/website_profiling/reporting/pdf/__init__.py
new file mode 100644
index 0000000..c2aabc1
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/__init__.py
@@ -0,0 +1,15 @@
+"""PDF document model and export pipeline."""
+from __future__ import annotations
+
+from .builder import build_pdf_document
+from .document import PdfDocument
+from .options import PdfBuildOptions, PdfLimits
+from .render import render_pdf_document
+
+__all__ = [
+ "build_pdf_document",
+ "render_pdf_document",
+ "PdfDocument",
+ "PdfBuildOptions",
+ "PdfLimits",
+]
diff --git a/src/website_profiling/reporting/pdf/adapters/__init__.py b/src/website_profiling/reporting/pdf/adapters/__init__.py
new file mode 100644
index 0000000..50c1f7d
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/adapters/__init__.py
@@ -0,0 +1,29 @@
+"""Section adapter registry.
+
+Each adapter maps a section key to a function that accepts the raw payload
+dict + PdfBuildOptions and returns a list of PdfSection objects. Adapters
+that find no relevant data return an empty list.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from ..document import PdfSection
+from ..options import PdfBuildOptions
+
+SectionAdapterFn = Callable[[dict[str, Any], PdfBuildOptions], list[PdfSection]]
+
+# Populated by each sub-module at import time
+SECTION_ADAPTERS: dict[str, SectionAdapterFn] = {}
+
+
+def register(key: str) -> Callable[[SectionAdapterFn], SectionAdapterFn]:
+ """Decorator: @register("lighthouse") marks a function as a section adapter."""
+ def _wrap(fn: SectionAdapterFn) -> SectionAdapterFn:
+ SECTION_ADAPTERS[key] = fn
+ return fn
+ return _wrap
+
+
+# Import adapters so they self-register
+from . import core, findings, appendix # noqa: E402, F401
diff --git a/src/website_profiling/reporting/pdf/adapters/appendix.py b/src/website_profiling/reporting/pdf/adapters/appendix.py
new file mode 100644
index 0000000..16329ff
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/adapters/appendix.py
@@ -0,0 +1,68 @@
+"""Appendix adapter — crawled URL sample and data-source glossary."""
+from __future__ import annotations
+
+from typing import Any
+
+from ....tools.export_audit_data import _GLOSSARY_ROWS
+from ..document import (
+ KeyValueBlock,
+ PdfSection,
+ PdfTruncation,
+ SpacerBlock,
+ UrlListBlock,
+)
+from ..options import PdfBuildOptions
+from . import register
+
+
+@register("appendix")
+def adapt_appendix(payload: dict[str, Any], opts: PdfBuildOptions) -> list[PdfSection]:
+ if not opts.include_appendix:
+ return []
+
+ sections: list[PdfSection] = []
+
+ # --- Crawled URLs sample ---
+ links = [l for l in (payload.get("links") or []) if isinstance(l, dict)]
+ if links:
+ limit = opts.limits.urls_sample
+ sample = links[:limit]
+ rows = [
+ {
+ "url": str(lnk.get("url") or ""),
+ "status": str(lnk.get("status") or ""),
+ "title": str(lnk.get("title") or "").strip(),
+ }
+ for lnk in sample
+ ]
+ has_titles = any(r["title"] for r in rows)
+ trunc = PdfTruncation(shown=len(rows), total=len(links)) if len(links) > limit else None
+ sections.append(PdfSection(
+ id="appendix.urls",
+ section_key="links",
+ title="Crawled URLs (sample)",
+ priority=80,
+ page_break_before=False,
+ blocks=[
+ UrlListBlock(
+ id="appendix.url_list",
+ rows=rows,
+ show_title=has_titles,
+ truncation=trunc,
+ ),
+ SpacerBlock(id="appendix.url_spacer", height_pt=6),
+ ],
+ ))
+
+ # --- Glossary ---
+ if opts.include_glossary:
+ gloss_rows = [(term, desc) for term, desc in _GLOSSARY_ROWS]
+ sections.append(PdfSection(
+ id="appendix.glossary",
+ section_key="core",
+ title="Data source glossary",
+ priority=90,
+ blocks=[KeyValueBlock(id="appendix.glossary_kv", rows=gloss_rows, layout="glossary")],
+ ))
+
+ return sections
diff --git a/src/website_profiling/reporting/pdf/adapters/core.py b/src/website_profiling/reporting/pdf/adapters/core.py
new file mode 100644
index 0000000..27bef7e
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/adapters/core.py
@@ -0,0 +1,38 @@
+"""Core adapter — audit-details section (category scores live on cover)."""
+from __future__ import annotations
+
+from typing import Any
+
+from ....tools.export_audit_data import _format_report_date, _summary_lines
+from ..document import KeyValueBlock, PdfSection, SpacerBlock
+from ..options import PdfBuildOptions
+from . import register
+
+
+@register("core")
+def adapt_core(payload: dict[str, Any], opts: PdfBuildOptions) -> list[PdfSection]:
+ sections: list[PdfSection] = []
+
+ # Category scores are rendered on the cover page — not duplicated here.
+
+ # --- Audit details section ---
+ summary_rows = _summary_lines(payload)
+ if summary_rows:
+ formatted_rows: list[tuple[str, str]] = []
+ for key, val in summary_rows:
+ if key == "Report generated":
+ formatted_rows.append((key, _format_report_date(val)))
+ else:
+ formatted_rows.append((key, val))
+ sections.append(PdfSection(
+ id="core.audit_details",
+ section_key="core",
+ title="Audit details",
+ priority=70,
+ blocks=[
+ KeyValueBlock(id="core.audit_kv", rows=formatted_rows, layout="audit"),
+ SpacerBlock(id="core.audit_spacer", height_pt=6),
+ ],
+ ))
+
+ return sections
diff --git a/src/website_profiling/reporting/pdf/adapters/findings.py b/src/website_profiling/reporting/pdf/adapters/findings.py
new file mode 100644
index 0000000..ebc18e8
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/adapters/findings.py
@@ -0,0 +1,54 @@
+"""Findings adapter — normalizes and groups all audit issues."""
+from __future__ import annotations
+
+from typing import Any
+
+from ....tools.export_audit_data import _issues_rows, _priority_sort_key
+from ..document import PdfSection, PdfTruncation
+from ..normalize import group_issues_for_pdf, normalize_issue_for_pdf
+from ..options import PdfBuildOptions
+from . import register
+
+
+@register("findings")
+def adapt_findings(payload: dict[str, Any], opts: PdfBuildOptions) -> list[PdfSection]:
+ raw_rows = _issues_rows(payload)
+ if not raw_rows:
+ return []
+
+ raw_rows = sorted(raw_rows, key=_priority_sort_key)
+ total = len(raw_rows)
+ capped = raw_rows[: opts.limits.issues_total]
+
+ pdf_issues = [
+ normalize_issue_for_pdf(row, include_recommendation=opts.include_recommendations)
+ for row in capped
+ ]
+
+ groups = group_issues_for_pdf(
+ pdf_issues,
+ issues_per_group=opts.limits.issues_per_group,
+ issues_total=opts.limits.issues_total,
+ )
+
+ if not groups:
+ return []
+
+ section_trunc: PdfTruncation | None = None
+ if total > opts.limits.issues_total:
+ section_trunc = PdfTruncation(
+ shown=opts.limits.issues_total,
+ total=total,
+ reason="limit",
+ continue_in=["CSV", "workbook"],
+ )
+
+ return [PdfSection(
+ id="findings",
+ section_key="findings",
+ title="Findings",
+ priority=20,
+ page_break_before=False,
+ blocks=list(groups), # type: ignore[arg-type]
+ truncation=section_trunc,
+ )]
diff --git a/src/website_profiling/reporting/pdf/builder.py b/src/website_profiling/reporting/pdf/builder.py
new file mode 100644
index 0000000..8f2d30b
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/builder.py
@@ -0,0 +1,178 @@
+"""build_pdf_document — assembles a PdfDocument from a raw report payload."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from ...tools.export_audit_data import (
+ _executive_export_data,
+ _executive_source_label,
+ _format_report_date,
+ _issue_priority_counts,
+ _issues_rows,
+ _overall_score,
+ _priority_sort_key,
+ _score_band,
+)
+from .document import (
+ SCHEMA_VERSION,
+ PdfCoverBlock,
+ PdfDocument,
+ PdfFooterBlock,
+ PdfIssue,
+ PdfMeta,
+ PdfScoreHero,
+ ScoreCard,
+ ScoreCardsBlock,
+ StatChip,
+ StatGridBlock,
+)
+from .normalize import normalize_issue_for_pdf
+from .options import PdfBuildOptions
+from .adapters import SECTION_ADAPTERS
+
+
+def _build_meta(
+ payload: dict[str, Any],
+ opts: PdfBuildOptions,
+ exported_at: str,
+ all_issue_counts: dict[str, int],
+ overall: Optional[int],
+ included_sections: list[str],
+) -> PdfMeta:
+ site = str(payload.get("site_name") or "Site Audit")
+ generated_raw = str(payload.get("report_generated_at") or "")
+ generated = _format_report_date(generated_raw)
+ meta_block = payload.get("report_meta") or {}
+ data_sources: list[str] = []
+ if isinstance(meta_block, dict):
+ data_sources = [str(s) for s in (meta_block.get("data_sources") or [])]
+ report_title = str(payload.get("report_title") or "Technical SEO Audit Report")
+ return PdfMeta(
+ report_id=opts.report_id,
+ property=site,
+ report_title=report_title,
+ generated_at=generated,
+ exported_at=exported_at,
+ data_sources=data_sources,
+ health_score=overall,
+ issue_counts=all_issue_counts,
+ included_sections=included_sections,
+ )
+
+
+def _build_cover(
+ payload: dict[str, Any],
+ opts: PdfBuildOptions,
+ overall: Optional[int],
+ all_issue_counts: dict[str, int],
+) -> PdfCoverBlock:
+ site = str(payload.get("site_name") or "Site Audit")
+ report_title = str(payload.get("report_title") or "Technical SEO Audit Report")
+
+ score_txt, band = _score_band(float(overall) if overall is not None else None)
+ hero = PdfScoreHero(score=score_txt, band=band, label="Overall health score") # type: ignore[arg-type]
+
+ priority_chips = [
+ StatChip(label="Critical", value=str(all_issue_counts["critical"]), tone="critical"),
+ StatChip(label="High", value=str(all_issue_counts["high"]), tone="high"),
+ StatChip(label="Medium", value=str(all_issue_counts["medium"]), tone="medium"),
+ StatChip(label="Low", value=str(all_issue_counts["low"]), tone="low"),
+ ]
+ priority_strip = StatGridBlock(id="cover.priority_strip", chips=priority_chips, columns=4)
+
+ categories = payload.get("categories") or []
+ score_cards: list[ScoreCard] = []
+ for cat in categories:
+ if not isinstance(cat, dict):
+ continue
+ from ...reporting.terminology import category_display_name
+ name = category_display_name(str(cat.get("name") or "Category"))
+ raw = cat.get("score")
+ sv: float | None = None
+ if raw is not None:
+ try:
+ sv = float(raw)
+ except (TypeError, ValueError):
+ pass
+ stxt, sband = _score_band(sv)
+ issue_n = len(cat.get("issues") or [])
+ score_cards.append(ScoreCard(name=name, score=stxt, issue_count=issue_n, tone=sband)) # type: ignore[arg-type]
+ cat_scores_block = ScoreCardsBlock(id="cover.category_scores", cards=score_cards)
+
+ # Executive summary
+ exec_data = _executive_export_data(payload)
+ exec_summary = exec_data.get("summary") or None
+ exec_source = _executive_source_label(exec_data.get("source") or "") if exec_data.get("source") else None
+ priorities_list: list[str] = exec_data.get("priorities") or []
+
+ # Top issues for cover — one row per distinct headline; prefer rows with a URL
+ all_rows = sorted(_issues_rows(payload), key=_priority_sort_key)
+ top_limit = opts.limits.top_issues_cover
+ headline_order: list[str] = []
+ by_headline: dict[str, PdfIssue] = {}
+ for row in all_rows:
+ issue = normalize_issue_for_pdf(row, include_recommendation=False)
+ if issue.headline not in by_headline:
+ headline_order.append(issue.headline)
+ by_headline[issue.headline] = issue
+ elif not by_headline[issue.headline].url and issue.url:
+ by_headline[issue.headline] = issue
+ top_issues = [by_headline[h] for h in headline_order[:top_limit]]
+
+ return PdfCoverBlock(
+ headline=f"Site Audit — {site}",
+ subtitle=report_title,
+ hero=hero,
+ priority_strip=priority_strip,
+ category_scores=cat_scores_block,
+ executive_summary=exec_summary,
+ executive_source=exec_source,
+ priorities_list=priorities_list[:8],
+ top_issues=top_issues,
+ )
+
+
+def build_pdf_document(
+ payload: dict[str, Any],
+ opts: Optional[PdfBuildOptions] = None,
+) -> PdfDocument:
+ """Transform a raw ReportPayload dict into a PdfDocument ready for rendering."""
+ if opts is None:
+ opts = PdfBuildOptions()
+
+ exported_at = datetime.now(timezone.utc).strftime("%d %B %Y, %H:%M UTC")
+ overall = _overall_score(payload)
+ all_issues = _issues_rows(payload)
+ all_issue_counts = _issue_priority_counts(all_issues)
+
+ effective_sections = opts.effective_sections()
+
+ # Run each requested adapter
+ sections: list = []
+ for key in effective_sections:
+ adapter = SECTION_ADAPTERS.get(key)
+ if adapter is None:
+ continue
+ result = adapter(payload, opts)
+ sections.extend(result)
+
+ # Sort sections by priority
+ sections.sort(key=lambda s: s.priority)
+
+ meta = _build_meta(
+ payload, opts, exported_at, all_issue_counts, overall,
+ included_sections=effective_sections,
+ )
+ cover = _build_cover(payload, opts, overall, all_issue_counts)
+ footer = PdfFooterBlock(exported_at=exported_at)
+
+ return PdfDocument(
+ schema_version=SCHEMA_VERSION,
+ document_kind="audit",
+ meta=meta,
+ cover=cover,
+ sections=sections,
+ footer=footer,
+ appendix=None, # appendix content is included as PdfSections in sections list
+ )
diff --git a/src/website_profiling/reporting/pdf/document.py b/src/website_profiling/reporting/pdf/document.py
new file mode 100644
index 0000000..94e9aa4
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/document.py
@@ -0,0 +1,322 @@
+"""PdfDocument v1 — versioned, block-based document model.
+
+All types are JSON-serializable dataclasses. The renderer consumes these;
+no ReportLab types appear here.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+SCHEMA_VERSION = "1.0"
+
+# ---------------------------------------------------------------------------
+# Primitive / shared
+# ---------------------------------------------------------------------------
+
+PriorityTone = Literal["critical", "high", "medium", "low", "neutral", "good", "fair", "poor"]
+DocumentKind = Literal["audit", "compare"]
+
+
+@dataclass
+class PdfTruncation:
+ shown: int
+ total: int
+ reason: Literal["limit", "page_budget", "empty"] = "limit"
+ continue_in: list[str] = field(default_factory=lambda: ["CSV", "workbook"])
+
+
+# ---------------------------------------------------------------------------
+# Block types — renderer handles each `type` discriminator
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HeadingBlock:
+ type: str = field(default="heading", init=False)
+ id: str = ""
+ text: str = ""
+ level: int = 2 # 2 = section heading, 3 = sub-heading
+ visible: bool = True
+
+
+@dataclass
+class ParagraphBlock:
+ type: str = field(default="paragraph", init=False)
+ id: str = ""
+ text: str = ""
+ italic: bool = False
+ visible: bool = True
+
+
+@dataclass
+class CalloutBlock:
+ type: str = field(default="callout", init=False)
+ id: str = ""
+ text: str = ""
+ severity: Literal["info", "warn", "critical"] = "info"
+ visible: bool = True
+
+
+@dataclass
+class SpacerBlock:
+ type: str = field(default="spacer", init=False)
+ id: str = ""
+ height_pt: float = 8.0
+ visible: bool = True
+
+
+@dataclass
+class KpiItem:
+ label: str
+ value: str
+ delta: Optional[str] = None
+ tone: PriorityTone = "neutral"
+ help: Optional[str] = None
+
+
+@dataclass
+class KpiRowBlock:
+ type: str = field(default="kpi_row", init=False)
+ id: str = ""
+ items: list[KpiItem] = field(default_factory=list)
+ visible: bool = True
+
+
+@dataclass
+class StatChip:
+ label: str
+ value: str
+ tone: PriorityTone = "neutral"
+
+
+@dataclass
+class StatGridBlock:
+ type: str = field(default="stat_grid", init=False)
+ id: str = ""
+ chips: list[StatChip] = field(default_factory=list)
+ columns: int = 4
+ visible: bool = True
+
+
+@dataclass
+class KeyValueBlock:
+ type: str = field(default="key_value", init=False)
+ id: str = ""
+ rows: list[tuple[str, str]] = field(default_factory=list)
+ layout: Literal["default", "audit", "glossary"] = "default"
+ visible: bool = True
+
+
+@dataclass
+class ScoreCard:
+ name: str
+ score: Optional[str] # formatted string, e.g. "87" or "—"
+ issue_count: int = 0
+ tone: Literal["score-good", "score-fair", "score-poor", "score-na"] = "score-na"
+
+
+@dataclass
+class ScoreCardsBlock:
+ type: str = field(default="score_cards", init=False)
+ id: str = ""
+ cards: list[ScoreCard] = field(default_factory=list)
+ visible: bool = True
+
+
+@dataclass
+class TableColumn:
+ key: str
+ label: str
+ width: Literal["narrow", "medium", "wide", "url"] = "medium"
+ align: Literal["left", "center", "right"] = "left"
+
+
+@dataclass
+class MetricTableBlock:
+ type: str = field(default="metric_table", init=False)
+ id: str = ""
+ columns: list[TableColumn] = field(default_factory=list)
+ rows: list[dict[str, str]] = field(default_factory=list)
+ repeat_header: bool = True
+ truncation: Optional[PdfTruncation] = None
+ visible: bool = True
+
+
+@dataclass
+class UrlListBlock:
+ type: str = field(default="url_list", init=False)
+ id: str = ""
+ rows: list[dict[str, str]] = field(default_factory=list) # keys: url, status, title
+ show_title: bool = True
+ truncation: Optional[PdfTruncation] = None
+ visible: bool = True
+
+
+# ---------------------------------------------------------------------------
+# Issue blocks — primary findings format
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PdfIssueMetrics:
+ gsc_clicks: Optional[int] = None
+ gsc_impressions: Optional[int] = None
+ ga4_sessions: Optional[int] = None
+ impact_score: Optional[float] = None
+ lh_audit_id: Optional[str] = None
+
+
+@dataclass
+class PdfIssue:
+ id: str
+ priority: str
+ category: str
+ headline: str # ≤ 80 chars, no embedded URL duplication
+ url: Optional[str] = None
+ path: Optional[str] = None # display-only short path
+ detail: Optional[str] = None
+ recommendation: Optional[str] = None
+ metrics: Optional[PdfIssueMetrics] = None
+ tags: list[str] = field(default_factory=list)
+ related_urls: list[str] = field(default_factory=list) # collapsed duplicates
+
+
+@dataclass
+class IssueGroupBlock:
+ type: str = field(default="issue_group", init=False)
+ id: str = ""
+ title: str = ""
+ group_label: str = "" # e.g. "Critical — 1 issue"
+ issues: list[PdfIssue] = field(default_factory=list)
+ render_as: Literal["list", "compact_table"] = "list"
+ truncation: Optional[PdfTruncation] = None
+ visible: bool = True
+
+
+@dataclass
+class IssueTableBlock:
+ """Fallback tabular rendering for dense medium/low groups."""
+ type: str = field(default="issue_table", init=False)
+ id: str = ""
+ title: str = ""
+ issues: list[PdfIssue] = field(default_factory=list)
+ truncation: Optional[PdfTruncation] = None
+ visible: bool = True
+
+
+@dataclass
+class MarkdownBlock:
+ type: str = field(default="markdown", init=False)
+ id: str = ""
+ text: str = ""
+ visible: bool = True
+
+
+# Union type for IDE / type-checkers
+PdfBlock = (
+ HeadingBlock
+ | ParagraphBlock
+ | CalloutBlock
+ | SpacerBlock
+ | KpiRowBlock
+ | StatGridBlock
+ | KeyValueBlock
+ | ScoreCardsBlock
+ | MetricTableBlock
+ | UrlListBlock
+ | IssueGroupBlock
+ | IssueTableBlock
+ | MarkdownBlock
+)
+
+# ---------------------------------------------------------------------------
+# Cover
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PdfScoreHero:
+ score: Optional[str]
+ band: Literal["score-good", "score-fair", "score-poor", "score-na"]
+ label: str # e.g. "Overall health score"
+
+
+@dataclass
+class PdfCoverBlock:
+ headline: str
+ subtitle: str
+ hero: PdfScoreHero
+ priority_strip: StatGridBlock
+ category_scores: ScoreCardsBlock
+ executive_summary: Optional[str] = None # prose paragraph
+ executive_source: Optional[str] = None
+ priorities_list: list[str] = field(default_factory=list)
+ top_issues: list[PdfIssue] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Section
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PdfSection:
+ id: str
+ section_key: str
+ title: str
+ priority: int = 50 # lower = earlier in document
+ page_break_before: bool = False
+ keep_with_next_blocks: int = 1
+ source_label: Optional[str] = None
+ provenance: Optional[str] = None
+ blocks: list[Any] = field(default_factory=list) # list[PdfBlock]
+ truncation: Optional[PdfTruncation] = None
+
+
+# ---------------------------------------------------------------------------
+# Appendix
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PdfAppendix:
+ url_sample: Optional[UrlListBlock] = None
+ audit_details: Optional[KeyValueBlock] = None
+ glossary: Optional[KeyValueBlock] = None
+
+
+# ---------------------------------------------------------------------------
+# Meta / Footer
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PdfMeta:
+ report_id: Optional[int]
+ property: str
+ report_title: str
+ generated_at: str # formatted for display
+ exported_at: str
+ data_sources: list[str]
+ health_score: Optional[int]
+ issue_counts: dict[str, int] # {critical, high, medium, low}
+ truncation_summary: list[str] = field(default_factory=list)
+ included_sections: list[str] = field(default_factory=list)
+ locale: str = "en"
+
+
+@dataclass
+class PdfFooterBlock:
+ confidential_note: str = "Confidential — prepared for client review."
+ generator: str = "Site Audit"
+ exported_at: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Root document
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PdfDocument:
+ schema_version: str
+ document_kind: DocumentKind
+ meta: PdfMeta
+ cover: PdfCoverBlock
+ sections: list[PdfSection]
+ footer: PdfFooterBlock
+ appendix: Optional[PdfAppendix] = None
diff --git a/src/website_profiling/reporting/pdf/normalize.py b/src/website_profiling/reporting/pdf/normalize.py
new file mode 100644
index 0000000..94cc4c7
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/normalize.py
@@ -0,0 +1,354 @@
+"""Issue normalization and grouping for PDF output.
+
+Transforms raw ``_issues_rows`` dicts (which mirror the DB payload) into
+``PdfIssue`` objects suited for print layout:
+- Strips duplicated URLs from headlines
+- Expands Lighthouse audit-id abbreviations into human labels
+- Groups by priority → category for use by IssueGroupBlock
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+from .document import IssueGroupBlock, PdfIssue, PdfIssueMetrics, PdfTruncation
+
+# ---------------------------------------------------------------------------
+# Lighthouse audit-id → human label registry
+# ---------------------------------------------------------------------------
+
+_LH_AUDIT_LABELS: dict[str, str] = {
+ "cache-insight": "Serve assets with efficient cache policy",
+ "color-contrast": "Background and foreground colors lack sufficient contrast",
+ "unused-css-rules": "Remove unused CSS",
+ "errors-in-console": "Browser errors logged to the console",
+ "label-content-name-mismatch": "Button/link label does not match accessible name",
+ "network-dependency-tree-insight": "Minimize critical request chain depth",
+ "render-blocking-insight": "Eliminate render-blocking resources",
+ "unused-javascript": "Remove unused JavaScript",
+ "uses-optimized-images": "Efficiently encode images",
+ "uses-responsive-images": "Properly size images",
+ "uses-webp-images": "Serve images in next-gen formats",
+ "largest-contentful-paint-element": "Largest Contentful Paint element",
+ "total-blocking-time": "Total Blocking Time",
+ "cumulative-layout-shift": "Cumulative Layout Shift",
+ "first-contentful-paint": "First Contentful Paint",
+ "speed-index": "Speed Index",
+ "interactive": "Time to Interactive",
+ "server-response-time": "Reduce initial server response time",
+ "dom-size": "Avoid an excessive DOM size",
+ "long-tasks": "Avoid long main-thread tasks",
+ "layout-shifts": "Avoid large layout shifts",
+ "image-alt": "Image elements do not have alt attributes",
+ "link-name": "Links do not have a discernible name",
+ "button-name": "Buttons do not have an accessible name",
+ "duplicate-id-active": "Document has active focus elements with duplicate ID",
+ "heading-order": "Heading elements are not in a sequentially-descending order",
+ "meta-description": "Document does not have a meta description",
+ "document-title": "Document does not have a element",
+ "hreflang": "Document does not have a valid hreflang",
+ "canonical": "Page is not canonical",
+ "robots-txt": "Robots.txt is not valid",
+ "tap-targets": "Touch targets are not sized appropriately",
+}
+
+_URL_IN_MSG_PATTERN = re.compile(
+ r"(https?://\S+|(?:^|[\s:])(/\S+))", re.IGNORECASE
+)
+
+# Colon at end of a known-bad audit id: "cache-insight:" → strip colon
+_AUDIT_ID_TRAILING_COLON = re.compile(r"^([\w-]+):$")
+
+
+def _lh_label(audit_id: str) -> str:
+ """Return a human-readable label for a Lighthouse audit id."""
+ clean = audit_id.rstrip(":").strip().lower()
+ return _LH_AUDIT_LABELS.get(clean, clean.replace("-", " ").title())
+
+
+def _strip_url_from_headline(message: str, url: str) -> str:
+ """Remove URL from message text when it duplicates the dedicated url field."""
+ if not url or not message:
+ return message
+
+ # Direct inclusion: "Issue text: https://example.com/path"
+ stripped = message.replace(url, "").strip().rstrip(":").strip()
+ if stripped and stripped != message:
+ return stripped
+
+ # URL with trailing slash variant
+ url_slash = url.rstrip("/") + "/"
+ stripped2 = message.replace(url_slash, "").strip().rstrip(":").strip()
+ if stripped2 and stripped2 != message:
+ return stripped2
+
+ return message
+
+
+def _extract_path(url: str) -> Optional[str]:
+ """Return just the path component of a URL for compact display."""
+ if not url:
+ return None
+ try:
+ parsed = urlparse(url)
+ return parsed.path or None
+ except Exception:
+ return None
+
+
+def _is_lighthouse_row(message: str, tags: list[str]) -> tuple[bool, str]:
+ """Detect Lighthouse issue rows and return (is_lh, audit_id)."""
+ # Pattern: "audit-id:" alone or at start of message
+ m = _AUDIT_ID_TRAILING_COLON.match(message.strip())
+ if m:
+ return True, m.group(1)
+ # Tag-based
+ if "lighthouse" in tags:
+ return True, ""
+ return False, ""
+
+
+def _issue_id(row: dict[str, Any]) -> str:
+ key = f"{row.get('category','')}\x00{row.get('priority','')}\x00{row.get('message','')}\x00{row.get('url','')}"
+ return hashlib.md5(key.encode()).hexdigest()[:12]
+
+
+def _shorten_headline(headline: str, raw_message: str, url: str) -> str:
+ """Apply common headline cleanups after URL strip / lighthouse expansion."""
+ lower = headline.lower()
+ lower_raw = raw_message.lower()
+
+ if "url in sitemap but not crawled" in lower:
+ return "In sitemap, not crawled"
+
+ if lower_raw.startswith("redirect:"):
+ m = re.match(r"redirect:\s*(\d{3})\s*to\b", lower_raw)
+ if m:
+ return f"{m.group(1)} redirect"
+
+ if lower.startswith("lighthouse:"):
+ return headline.split(":", 1)[-1].strip()
+
+ if lower.startswith("axe:"):
+ body = headline.split(":", 1)[-1].strip()
+ if len(body) > 90:
+ dot = body.find(". ")
+ if dot > 0:
+ body = body[: dot + 1]
+ else:
+ body = body[:87].rsplit(" ", 1)[0] + "…"
+ return body
+
+ if len(headline) > 100:
+ return headline[:97].rsplit(" ", 1)[0] + "…"
+
+ return headline
+
+
+_GENERIC_CWV_REC = "See Performance (Core Web Vitals) in this audit, or re-run Lighthouse from Run audit."
+
+
+def _normalize_recommendation(rec: Optional[str]) -> Optional[str]:
+ if not rec:
+ return None
+ if rec.strip() == _GENERIC_CWV_REC:
+ return "Review Lighthouse audit details for this page."
+ return rec.strip()
+
+
+def collapse_duplicate_issues(issues: list[PdfIssue]) -> list[PdfIssue]:
+ """Merge rows that share the same headline + recommendation into one card with URL list."""
+ buckets: dict[tuple[str, str], list[PdfIssue]] = {}
+ order: list[tuple[str, str]] = []
+ for iss in issues:
+ key = (iss.headline, iss.recommendation or "")
+ if key not in buckets:
+ order.append(key)
+ buckets[key] = []
+ buckets[key].append(iss)
+
+ collapsed: list[PdfIssue] = []
+ for key in order:
+ group = buckets[key]
+ first = group[0]
+ urls: list[str] = []
+ for item in group:
+ if item.url and item.url not in urls:
+ urls.append(item.url)
+ if len(urls) <= 1:
+ collapsed.append(first)
+ continue
+ headline = first.headline
+ if len(urls) > 1 and not headline.endswith(")"):
+ headline = f"{headline} ({len(urls)} URLs)"
+ collapsed.append(PdfIssue(
+ id=first.id,
+ priority=first.priority,
+ category=first.category,
+ headline=headline,
+ url=None,
+ path=first.path,
+ detail=first.detail,
+ recommendation=first.recommendation,
+ metrics=first.metrics,
+ tags=first.tags,
+ related_urls=urls,
+ ))
+ return collapsed
+
+
+def normalize_issue_for_pdf(
+ row: dict[str, Any],
+ include_recommendation: bool = True,
+) -> PdfIssue:
+ """Convert a raw issues_row dict → PdfIssue for print layout."""
+ priority = str(row.get("priority") or "").lower()
+ category = str(row.get("category") or "")
+ raw_message = str(row.get("message") or "").strip()
+ url = str(row.get("url") or "").strip()
+ recommendation = _normalize_recommendation(
+ str(row.get("recommendation") or "").strip() if include_recommendation else None
+ )
+
+ # Detect Lighthouse rows (audit-id only, no human label)
+ is_lh, audit_id = _is_lighthouse_row(raw_message, [])
+ if is_lh and audit_id:
+ headline = _lh_label(audit_id)
+ else:
+ headline = _strip_url_from_headline(raw_message, url)
+
+ headline = _shorten_headline(headline, raw_message, url)
+
+ tags: list[str] = []
+ lower_msg = raw_message.lower()
+ if "sitemap" in lower_msg:
+ tags.append("sitemap")
+ if is_lh or "lighthouse" in lower_msg:
+ tags.append("lighthouse")
+ if "axe" in lower_msg or "wcag" in lower_msg or "contrast" in lower_msg:
+ tags.append("axe")
+ if "redirect" in lower_msg:
+ tags.append("redirect")
+ if "canonical" in lower_msg:
+ tags.append("canonical")
+ if "security" in category.lower():
+ tags.append("security")
+
+ # Metrics from issue dict (ReportIssue fields)
+ gsc_clicks = row.get("gsc_clicks")
+ gsc_imp = row.get("gsc_impressions")
+ impact = row.get("impact_score")
+ lh_id = audit_id if is_lh else row.get("lh_audit_id")
+ metrics = None
+ if any(v is not None for v in (gsc_clicks, gsc_imp, impact, lh_id)):
+ metrics = PdfIssueMetrics(
+ gsc_clicks=int(gsc_clicks) if gsc_clicks is not None else None,
+ gsc_impressions=int(gsc_imp) if gsc_imp is not None else None,
+ impact_score=float(impact) if impact is not None else None,
+ lh_audit_id=str(lh_id) if lh_id else None,
+ )
+
+ return PdfIssue(
+ id=_issue_id(row),
+ priority=priority,
+ category=category,
+ headline=headline,
+ url=url or None,
+ path=_extract_path(url),
+ detail=None,
+ recommendation=recommendation or None,
+ metrics=metrics,
+ tags=tags,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Grouping
+# ---------------------------------------------------------------------------
+
+_PRIORITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+_PRIORITY_LABELS = {
+ "critical": "Critical",
+ "high": "High",
+ "medium": "Medium",
+ "low": "Low",
+}
+
+# Above this count per priority, sub-group by category
+_SUBGROUP_THRESHOLD = 8
+
+# Always use stacked list layout — tables only for cover top-issues / URL inventory
+_COMPACT_TABLE_THRESHOLD = 999
+
+
+def group_issues_for_pdf(
+ issues: list[PdfIssue],
+ issues_per_group: int = 25,
+ issues_total: int = 120,
+) -> list[IssueGroupBlock]:
+ """Group PdfIssue list by priority → category, returning IssueGroupBlock list."""
+ # Sort and cap total
+ sorted_issues = sorted(issues, key=lambda i: (_PRIORITY_ORDER.get(i.priority, 9), i.category))
+ if len(sorted_issues) > issues_total:
+ sorted_issues = sorted_issues[:issues_total]
+
+ # Bucket by priority
+ by_priority: dict[str, list[PdfIssue]] = {}
+ for iss in sorted_issues:
+ by_priority.setdefault(iss.priority, []).append(iss)
+
+ groups: list[IssueGroupBlock] = []
+
+ for pri in ("critical", "high", "medium", "low"):
+ pri_issues = by_priority.get(pri, [])
+ if not pri_issues:
+ continue
+
+ pri_label = _PRIORITY_LABELS.get(pri, pri.title())
+ total_in_pri = len(pri_issues)
+
+ if total_in_pri <= _SUBGROUP_THRESHOLD:
+ # Single group for this priority
+ shown = collapse_duplicate_issues(pri_issues[:issues_per_group])
+ trunc = (
+ PdfTruncation(shown=len(shown), total=total_in_pri)
+ if total_in_pri > len(shown)
+ else None
+ )
+ render_as = "compact_table" if len(shown) >= _COMPACT_TABLE_THRESHOLD else "list"
+ groups.append(IssueGroupBlock(
+ id=f"findings.{pri}",
+ title=f"{pri_label} findings",
+ group_label=f"{pri_label} — {total_in_pri} issue{'s' if total_in_pri != 1 else ''}",
+ issues=shown,
+ render_as=render_as,
+ truncation=trunc,
+ ))
+ else:
+ # Sub-group by category
+ by_cat: dict[str, list[PdfIssue]] = {}
+ for iss in pri_issues:
+ by_cat.setdefault(iss.category, []).append(iss)
+
+ for cat, cat_issues in sorted(by_cat.items()):
+ cat_total = len(cat_issues)
+ shown = collapse_duplicate_issues(cat_issues[:issues_per_group])
+ trunc = (
+ PdfTruncation(shown=len(shown), total=cat_total)
+ if cat_total > len(shown)
+ else None
+ )
+ render_as = "compact_table" if len(shown) >= _COMPACT_TABLE_THRESHOLD else "list"
+ cat_id = cat.lower().replace(" ", "_").replace("&", "and")
+ groups.append(IssueGroupBlock(
+ id=f"findings.{pri}.{cat_id}",
+ title=f"{pri_label} — {cat}",
+ group_label=f"{pri_label} — {cat}: {cat_total} issue{'s' if cat_total != 1 else ''}",
+ issues=shown,
+ render_as=render_as,
+ truncation=trunc,
+ ))
+
+ return groups
diff --git a/src/website_profiling/reporting/pdf/options.py b/src/website_profiling/reporting/pdf/options.py
new file mode 100644
index 0000000..678a446
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/options.py
@@ -0,0 +1,43 @@
+"""PdfBuildOptions, PdfLimits, and document profiles."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+Profile = Literal["executive", "standard", "full"]
+
+# Sections for each profile; None in sections means "use profile default"
+_PROFILE_SECTIONS: dict[str, list[str]] = {
+ "executive": ["core"],
+ "standard": ["core", "findings", "appendix"],
+ "full": ["core", "findings", "lighthouse", "security", "traffic", "keywords",
+ "indexation", "content", "links", "appendix"],
+}
+
+
+@dataclass
+class PdfLimits:
+ issues_total: int = 120
+ issues_per_group: int = 25
+ top_issues_cover: int = 6
+ urls_sample: int = 20
+ metric_table_rows: int = 15
+ gsc_queries: int = 10
+ keyword_rows: int = 15
+ diagnostic_items: int = 20
+
+
+@dataclass
+class PdfBuildOptions:
+ profile: Profile = "standard"
+ sections: Optional[list[str]] = None # None → derive from profile
+ limits: PdfLimits = field(default_factory=PdfLimits)
+ include_appendix: bool = True
+ include_recommendations: bool = True
+ include_glossary: bool = True
+ report_id: Optional[int] = None
+
+ def effective_sections(self) -> list[str]:
+ if self.sections is not None:
+ return self.sections
+ return _PROFILE_SECTIONS.get(self.profile, _PROFILE_SECTIONS["standard"])
diff --git a/src/website_profiling/reporting/pdf/render/__init__.py b/src/website_profiling/reporting/pdf/render/__init__.py
new file mode 100644
index 0000000..fc2a79a
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/render/__init__.py
@@ -0,0 +1,7 @@
+"""PDF/HTML renderers."""
+from __future__ import annotations
+
+from .html import render_html_document
+from .reportlab import render_pdf_document
+
+__all__ = ["render_pdf_document", "render_html_document"]
diff --git a/src/website_profiling/reporting/pdf/render/html.py b/src/website_profiling/reporting/pdf/render/html.py
new file mode 100644
index 0000000..ee1eda8
--- /dev/null
+++ b/src/website_profiling/reporting/pdf/render/html.py
@@ -0,0 +1,774 @@
+"""HTML renderer — converts PdfDocument → preview/print HTML matching the PDF layout."""
+from __future__ import annotations
+
+import html
+import re
+from typing import Any
+
+from ..document import (
+ CalloutBlock,
+ HeadingBlock,
+ IssueGroupBlock,
+ IssueTableBlock,
+ KeyValueBlock,
+ KpiRowBlock,
+ MarkdownBlock,
+ MetricTableBlock,
+ ParagraphBlock,
+ PdfCoverBlock,
+ PdfDocument,
+ PdfIssue,
+ PdfSection,
+ ScoreCardsBlock,
+ SpacerBlock,
+ StatGridBlock,
+ UrlListBlock,
+)
+from . import styles as S
+
+
+def html_styles() -> str:
+ """CSS shared by standard export preview HTML."""
+ return """
+ :root {
+ --ink: #0f172a;
+ --muted: #64748b;
+ --line: #e2e8f0;
+ --surface: #ffffff;
+ --surface-muted: #f8fafc;
+ --header-bg: #f1f5f9;
+ --brand-accent: #2563eb;
+ --good: #059669;
+ --good-bg: #ecfdf5;
+ --fair: #d97706;
+ --fair-bg: #fffbeb;
+ --poor: #dc2626;
+ --poor-bg: #fef2f2;
+ --critical-fg: #991b1b;
+ --critical-bg: #fee2e2;
+ --high-fg: #c2410c;
+ --high-bg: #ffedd5;
+ --medium-fg: #a16207;
+ --medium-bg: #fef3c7;
+ --low-fg: #475569;
+ --low-bg: #f1f5f9;
+ }
+ * { box-sizing: border-box; }
+ body {
+ margin: 0;
+ background: #eef2f7;
+ color: var(--ink);
+ font: 400 14px/1.45 "Segoe UI", system-ui, -apple-system, sans-serif;
+ }
+ .report {
+ max-width: 816px;
+ margin: 0 auto;
+ background: var(--surface);
+ box-shadow: 0 1px 3px rgba(15, 23, 42, 0.08);
+ }
+ .cover {
+ padding: 1.75rem 1.85rem 1.25rem;
+ background: var(--surface);
+ }
+ .cover-head {
+ display: flex;
+ justify-content: space-between;
+ align-items: flex-start;
+ gap: 1rem;
+ margin-bottom: 0.35rem;
+ }
+ .cover-head h1 {
+ margin: 0;
+ font-size: 1.35rem;
+ font-weight: 700;
+ line-height: 1.25;
+ }
+ .cover-subtitle {
+ margin: 0.25rem 0 0;
+ color: var(--muted);
+ font-size: 0.92rem;
+ }
+ .hero-score {
+ text-align: center;
+ min-width: 4.5rem;
+ }
+ .hero-score .score {
+ display: block;
+ font-size: 2rem;
+ font-weight: 700;
+ line-height: 1;
+ }
+ .hero-score .suffix {
+ display: block;
+ margin-top: 0.15rem;
+ font-size: 0.72rem;
+ color: var(--muted);
+ }
+ .hero-score.score-good .score { color: var(--good); }
+ .hero-score.score-fair .score { color: var(--fair); }
+ .hero-score.score-poor .score { color: var(--poor); }
+ .hero-score.score-na .score { color: var(--muted); }
+ .cover-meta-line {
+ margin: 0.5rem 0 1rem;
+ color: var(--muted);
+ font-size: 0.82rem;
+ }
+ .section-title {
+ margin: 1.1rem 0 0.35rem;
+ font-size: 0.82rem;
+ font-weight: 700;
+ color: var(--ink);
+ }
+ .section-rule {
+ border: none;
+ border-top: 1px solid var(--line);
+ margin: 0 0 0.65rem;
+ }
+ .section-lead {
+ margin: 0 0 0.65rem;
+ color: var(--muted);
+ font-size: 0.78rem;
+ }
+ .grid-table {
+ width: 100%;
+ border-collapse: collapse;
+ table-layout: fixed;
+ margin-bottom: 0.85rem;
+ font-size: 0.82rem;
+ }
+ .grid-table th,
+ .grid-table td {
+ border: 1px solid var(--line);
+ padding: 0.65rem 0.5rem;
+ text-align: center;
+ vertical-align: middle;
+ }
+ .stat-grid td.stat-critical { background: var(--critical-bg); color: var(--critical-fg); }
+ .stat-grid td.stat-high { background: var(--high-bg); color: var(--high-fg); }
+ .stat-grid td.stat-medium { background: var(--medium-bg); color: var(--medium-fg); }
+ .stat-grid td.stat-low { background: var(--low-bg); color: var(--low-fg); }
+ .stat-grid .stat-value {
+ display: block;
+ font-size: 1.15rem;
+ font-weight: 700;
+ line-height: 1.1;
+ }
+ .stat-grid .stat-label {
+ display: block;
+ margin-top: 0.2rem;
+ font-size: 0.72rem;
+ color: var(--muted);
+ }
+ .score-grid .score-value {
+ display: block;
+ font-size: 0.95rem;
+ font-weight: 700;
+ line-height: 1.1;
+ }
+ .score-grid .score-name {
+ display: block;
+ margin-top: 0.25rem;
+ font-size: 0.72rem;
+ font-weight: 600;
+ line-height: 1.25;
+ }
+ .score-grid .score-meta {
+ display: block;
+ margin-top: 0.15rem;
+ font-size: 0.68rem;
+ color: var(--muted);
+ }
+ .score-grid td { background: var(--surface-muted); }
+ .score-grid .score-good .score-value { color: var(--good); }
+ .score-grid .score-fair .score-value { color: var(--fair); }
+ .score-grid .score-poor .score-value { color: var(--poor); }
+ .score-grid .score-na .score-value { color: var(--muted); }
+ .exec-panel {
+ border: 1px solid var(--line);
+ border-left: 3px solid var(--brand-accent);
+ background: var(--surface-muted);
+ padding: 0.85rem 1rem;
+ margin-bottom: 1rem;
+ border-radius: 0 4px 4px 0;
+ }
+ .exec-source {
+ margin: 0 0 0.45rem;
+ font-size: 0.68rem;
+ font-weight: 700;
+ color: var(--brand-accent);
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ }
+ .exec-body { margin: 0; font-size: 0.88rem; line-height: 1.5; }
+ .exec-subhead {
+ margin: 0.65rem 0 0.35rem;
+ font-size: 0.72rem;
+ font-weight: 700;
+ color: var(--muted);
+ }
+ .exec-priorities {
+ margin: 0;
+ padding-left: 1.1rem;
+ font-size: 0.82rem;
+ line-height: 1.45;
+ }
+ .data-table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: 0.82rem;
+ border: 1px solid var(--line);
+ margin-bottom: 0.85rem;
+ }
+ .data-table th,
+ .data-table td {
+ padding: 0.55rem 0.65rem;
+ text-align: left;
+ vertical-align: middle;
+ border-bottom: 1px solid var(--line);
+ }
+ .data-table thead th {
+ background: var(--header-bg);
+ font-size: 0.72rem;
+ font-weight: 700;
+ color: var(--muted);
+ }
+ .data-table tbody tr:nth-child(even) td { background: var(--surface-muted); }
+ .data-table tbody tr:last-child td { border-bottom: none; }
+ .data-table .col-status { text-align: center; width: 4.5rem; }
+ .data-table .col-priority { text-align: center; width: 5rem; }
+ .kv-audit th {
+ width: 23%;
+ font-weight: 700;
+ vertical-align: top;
+ }
+ .kv-glossary th {
+ width: 21%;
+ font-weight: 700;
+ vertical-align: top;
+ background: var(--header-bg);
+ }
+ .kv-glossary td { line-height: 1.45; }
+ .link { color: var(--brand-accent); word-break: break-all; }
+ .site-wide { color: var(--muted); font-style: italic; font-size: 0.78rem; }
+ .badge {
+ display: inline-block;
+ padding: 0.15rem 0.45rem;
+ border-radius: 3px;
+ font-size: 0.65rem;
+ font-weight: 700;
+ text-transform: uppercase;
+ letter-spacing: 0.03em;
+ border: 1px solid transparent;
+ }
+ .badge-critical { background: var(--critical-bg); color: var(--critical-fg); border-color: var(--critical-fg); }
+ .badge-high { background: var(--high-bg); color: var(--high-fg); border-color: var(--high-fg); }
+ .badge-medium { background: var(--medium-bg); color: var(--medium-fg); border-color: var(--medium-fg); }
+ .badge-low { background: var(--low-bg); color: var(--low-fg); border-color: var(--low-fg); }
+ .status-200 { background: var(--good-bg); color: var(--good); border-color: var(--good); }
+ .status-3xx { background: var(--fair-bg); color: var(--fair); border-color: var(--fair); }
+ .status-4xx, .status-5xx { background: var(--poor-bg); color: var(--poor); border-color: var(--poor); }
+ .status-other { background: var(--surface-muted); color: var(--muted); border-color: var(--line); }
+ .content { padding: 0 1.85rem 1.5rem; }
+ .doc-section { margin-bottom: 1.35rem; }
+ .doc-section > h2 {
+ margin: 0 0 0.35rem;
+ font-size: 0.82rem;
+ font-weight: 700;
+ }
+ .doc-section .source-label {
+ margin: 0 0 0.5rem;
+ font-size: 0.78rem;
+ color: var(--muted);
+ }
+ .group-label {
+ margin: 0.65rem 0 0.35rem;
+ font-size: 0.78rem;
+ font-weight: 700;
+ }
+ .issue-card {
+ border-left: 3px solid var(--line);
+ background: var(--surface-muted);
+ padding: 0.45rem 0.65rem;
+ margin-bottom: 0.45rem;
+ font-size: 0.82rem;
+ }
+ .issue-card.priority-critical { border-color: var(--critical-fg); background: var(--critical-bg); }
+ .issue-card.priority-high { border-color: var(--high-fg); background: var(--high-bg); }
+ .issue-card.priority-medium { border-color: var(--medium-fg); background: var(--medium-bg); }
+ .issue-card.priority-low { border-color: var(--low-fg); background: var(--low-bg); }
+ .issue-headline { margin: 0; font-weight: 700; line-height: 1.35; }
+ .issue-url {
+ margin: 0.2rem 0 0;
+ font-size: 0.76rem;
+ color: var(--brand-accent);
+ word-break: break-all;
+ }
+ .issue-rec {
+ margin: 0.25rem 0 0;
+ font-size: 0.76rem;
+ color: var(--muted);
+ font-style: italic;
+ }
+ .issue-url-list {
+ margin: 0.25rem 0 0;
+ padding-left: 1rem;
+ font-size: 0.76rem;
+ color: var(--brand-accent);
+ }
+ .muted-note {
+ margin: 0.35rem 0 0;
+ font-size: 0.76rem;
+ color: var(--muted);
+ }
+ .page-break {
+ break-before: page;
+ page-break-before: always;
+ height: 0;
+ margin: 0;
+ border-top: 1px dashed var(--line);
+ }
+ .report-footer {
+ border-top: 1px solid var(--line);
+ padding: 0.85rem 1.85rem 1.25rem;
+ color: var(--muted);
+ font-size: 0.72rem;
+ line-height: 1.45;
+ }
+ .content {
+ padding: 0 1.85rem 1.5rem;
+ }
+ .custom-section {
+ margin-bottom: 1.35rem;
+ }
+ .custom-section > h2 {
+ margin: 0 0 0.35rem;
+ font-size: 0.82rem;
+ font-weight: 700;
+ }
+ .callout {
+ border: 1px solid var(--line);
+ border-left: 3px solid var(--brand-accent);
+ background: var(--surface-muted);
+ padding: 0.85rem 1rem;
+ border-radius: 0 4px 4px 0;
+ margin: 0.5rem 0;
+ }
+ p.muted, .muted {
+ color: var(--muted);
+ font-size: 0.82rem;
+ margin: 0.35rem 0 0.65rem;
+ }
+ .url, td.url {
+ color: var(--brand-accent);
+ word-break: break-all;
+ font-size: 0.76rem;
+ }
+ table.data, .table-wrap table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: 0.82rem;
+ border: 1px solid var(--line);
+ margin: 0.5rem 0 0.85rem;
+ }
+ table.data th, table.data td,
+ .table-wrap table th, .table-wrap table td {
+ padding: 0.55rem 0.65rem;
+ text-align: left;
+ vertical-align: top;
+ border-bottom: 1px solid var(--line);
+ }
+ table.data thead th, .table-wrap table thead th {
+ background: var(--header-bg);
+ font-size: 0.72rem;
+ font-weight: 700;
+ color: var(--muted);
+ }
+ .category-cards {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.75rem;
+ margin: 0.65rem 0;
+ }
+ article.score-card {
+ flex: 1 1 140px;
+ max-width: 180px;
+ border: 1px solid var(--line);
+ border-radius: 4px;
+ padding: 0.75rem;
+ background: var(--surface-muted);
+ text-align: center;
+ }
+ article.score-card .score-value {
+ font-size: 1.1rem;
+ font-weight: 700;
+ }
+ article.score-card .score-name {
+ margin-top: 0.35rem;
+ font-size: 0.72rem;
+ font-weight: 600;
+ }
+ article.score-card .score-meta {
+ margin-top: 0.2rem;
+ font-size: 0.68rem;
+ color: var(--muted);
+ }
+ article.score-card.score-good .score-value { color: var(--good); }
+ article.score-card.score-fair .score-value { color: var(--fair); }
+ article.score-card.score-poor .score-value { color: var(--poor); }
+ article.score-card.score-na .score-value { color: var(--muted); }
+ .notes, .json-preview {
+ line-height: 1.5;
+ font-size: 0.82rem;
+ }
+ .json-preview {
+ overflow-x: auto;
+ background: var(--surface-muted);
+ padding: 0.75rem;
+ border: 1px solid var(--line);
+ border-radius: 4px;
+ }
+ @media print {
+ body { background: #fff; }
+ .report { max-width: none; box-shadow: none; }
+ .cover, .content, .report-footer { padding-left: 0.65in; padding-right: 0.65in; }
+ .page-break { border: none; }
+ }
+"""
+
+
+def _esc(text: Any) -> str:
+ return html.escape(str(text) if text is not None else "")
+
+
+def _priority_badge(priority: str) -> str:
+ key = priority.lower()
+ cls = f"badge badge-{key}" if key in {"critical", "high", "medium", "low"} else "badge badge-low"
+ return f'<span class="{cls}">{_esc(priority)}</span>'
+
+
+def _status_badge(code: str) -> str:
+ c = str(code or "").strip()
+ if c == "200":
+ cls = "badge status-200"
+ elif c.startswith("3"):
+ cls = "badge status-3xx"
+ elif c and c[0] in "45":
+ cls = "badge status-4xx" if c.startswith("4") else "badge status-5xx"
+ else:
+ cls = "badge status-other"
+ return f'<span class="{cls}">{_esc(c or "—")}</span>'
+
+
+def _issue_location(issue: PdfIssue) -> str:
+ if issue.path:
+ return f'<span class="link">{_esc(issue.path)}</span>'
+ if issue.url:
+ return f'<span class="link">{_esc(issue.url)}</span>'
+ return '<span class="site-wide">Site-wide</span>'
+
+
+def _section_heading(title: str) -> str:
+ return f'<h3 class="section-title">{_esc(title)}</h3><hr class="section-rule"/>'
+
+
+def _render_stat_grid(block: StatGridBlock) -> str:
+ if not block.chips:
+ return ""
+ cells = []
+ for chip in block.chips:
+ tone = chip.tone if chip.tone in {"critical", "high", "medium", "low"} else "low"
+ cells.append(
+ f'<td class="stat-{tone}">'
+ f'<span class="stat-value">{_esc(chip.value)}</span>'
+ f'<span class="stat-label">{_esc(chip.label)}</span>'
+ f"</td>"
+ )
+ while len(cells) < block.columns:
+ cells.append("<td></td>")
+ return f'<table class="grid-table stat-grid"><tr>{"".join(cells)}</tr></table>'
+
+
+def _render_score_cards(block: ScoreCardsBlock) -> str:
+ if not block.cards:
+ return ""
+ cols = S.GRID_COLS
+ rows_html: list[str] = []
+ row: list[str] = []
+ for card in block.cards:
+ issue_label = f"{card.issue_count} issue{'s' if card.issue_count != 1 else ''}"
+ row.append(
+ f'<td class="{_esc(card.tone)}">'
+ f'<span class="score-value">{_esc(card.score or "—")}</span>'
+ f'<span class="score-name">{_esc(card.name)}</span>'
+ f'<span class="score-meta">{issue_label}</span>'
+ f"</td>"
+ )
+ if len(row) == cols:
+ rows_html.append(f"<tr>{''.join(row)}</tr>")
+ row = []
+ if row:
+ while len(row) < cols:
+ row.append("<td></td>")
+ rows_html.append(f"<tr>{''.join(row)}</tr>")
+ return f'<table class="grid-table score-grid">{"".join(rows_html)}</table>'
+
+
+def _render_executive_panel(cover: PdfCoverBlock) -> str:
+ if not (cover.executive_summary or cover.priorities_list):
+ return ""
+ parts = ['<div class="exec-panel">']
+ if cover.executive_source:
+ parts.append(f'<p class="exec-source">Source · {_esc(cover.executive_source)}</p>')
+ if cover.executive_summary:
+ parts.append(f'<p class="exec-body">{_esc(cover.executive_summary)}</p>')
+ if cover.priorities_list:
+ parts.append('<p class="exec-subhead">Recommended priorities</p>')
+ parts.append('<ol class="exec-priorities">')
+ for pri in cover.priorities_list[:6]:
+ parts.append(f"<li>{_esc(pri)}</li>")
+ parts.append("</ol>")
+ parts.append("</div>")
+ return "".join(parts)
+
+
+def _render_top_issues(issues: list[PdfIssue]) -> str:
+ if not issues:
+ return ""
+ rows = "".join(
+ f"<tr>"
+ f'<td class="col-priority">{_priority_badge(iss.priority)}</td>'
+ f"<td>{_esc(iss.headline)}</td>"
+ f"<td>{_issue_location(iss)}</td>"
+ f"</tr>"
+ for iss in issues
+ )
+ return (
+ f"{_section_heading('Top traffic-impacting issues')}"
+ f'<p class="section-lead">Ranked by severity and traffic impact — address critical and high items first.</p>'
+ f'<table class="data-table top-issues">'
+ f"<thead><tr><th class=\"col-priority\">Priority</th><th>Issue</th><th>Location</th></tr></thead>"
+ f"<tbody>{rows}</tbody></table>"
+ )
+
+
+def _render_cover(cover: PdfCoverBlock, meta) -> str:
+ counts = meta.issue_counts
+ total = sum(counts.values())
+ meta_line = (
+ f"Report generated {meta.generated_at} · {total} findings "
+ f"(Critical {counts.get('critical', 0)}, High {counts.get('high', 0)}, "
+ f"Medium {counts.get('medium', 0)}, Low {counts.get('low', 0)})"
+ )
+ hero = cover.hero
+ exec_html = ""
+ if cover.executive_summary or cover.priorities_list:
+ exec_html = _section_heading("Executive summary") + _render_executive_panel(cover)
+ top_html = _render_top_issues(cover.top_issues)
+
+ cat_html = ""
+ if cover.category_scores.cards:
+ cat_html = _section_heading("Category scores") + _render_score_cards(cover.category_scores)
+
+ return f"""
+ <header class="cover">
+ <div class="cover-head">
+ <div>
+ <h1>{_esc(cover.headline)}</h1>
+ <p class="cover-subtitle">{_esc(cover.subtitle)}</p>
+ </div>
+ <div class="hero-score {_esc(hero.band)}">
+ <span class="score">{_esc(hero.score or "—")}</span>
+ <span class="suffix">/100</span>
+ </div>
+ </div>
+ <p class="cover-meta-line">{_esc(meta_line)}</p>
+ {_render_stat_grid(cover.priority_strip)}
+ {cat_html}
+ {exec_html}
+ {top_html}
+ </header>"""
+
+
+def _render_issue(issue: PdfIssue) -> str:
+ pri = issue.priority.lower()
+ cls = f"issue-card priority-{pri}" if pri in {"critical", "high", "medium", "low"} else "issue-card"
+ parts = [f'<div class="{cls}">', f'<p class="issue-headline">{_esc(issue.headline)}</p>']
+ if issue.related_urls:
+ items = "".join(f"<li>{_esc(u)}</li>" for u in issue.related_urls[:10])
+ extra = len(issue.related_urls) - 10
+ if extra > 0:
+ items += f'<li class="muted-note">… and {extra} more (see CSV export)</li>'
+ parts.append(f'<ul class="issue-url-list">{items}</ul>')
+ elif issue.url:
+ parts.append(f'<p class="issue-url">{_esc(issue.url)}</p>')
+ if issue.recommendation:
+ parts.append(f'<p class="issue-rec">Fix: {_esc(issue.recommendation)}</p>')
+ parts.append("</div>")
+ return "".join(parts)
+
+
+def _render_issue_group(block: IssueGroupBlock) -> str:
+ parts = [f'<p class="group-label">{_esc(block.group_label)}</p>']
+ if block.render_as == "compact_table":
+ rows = "".join(
+ f"<tr><td>{_esc(iss.headline)}</td>"
+ f'<td class="link">{_esc(iss.url or "")}</td></tr>'
+ for iss in block.issues
+ )
+ parts.append(
+ f'<table class="data-table"><thead><tr><th>Issue</th><th>URL</th></tr></thead>'
+ f"<tbody>{rows}</tbody></table>"
+ )
+ else:
+ for iss in block.issues:
+ parts.append(_render_issue(iss))
+ if block.truncation:
+ t = block.truncation
+ parts.append(
+ f'<p class="muted-note">Showing {t.shown} of {t.total}. '
+ f"Full list in {', '.join(t.continue_in)}.</p>"
+ )
+ return "".join(parts)
+
+
+def _render_key_value(block: KeyValueBlock) -> str:
+ if not block.rows:
+ return ""
+ layout = getattr(block, "layout", "default") or "default"
+ if layout == "audit":
+ table_cls = "data-table kv-audit"
+ elif layout == "glossary":
+ table_cls = "data-table kv-glossary"
+ else:
+ table_cls = "data-table kv-audit"
+ rows = "".join(
+ f"<tr><th>{_esc(k)}</th><td>{_esc(v)}</td></tr>" for k, v in block.rows
+ )
+ return f'<table class="{table_cls}"><tbody>{rows}</tbody></table>'
+
+
+def _render_url_list(block: UrlListBlock) -> str:
+ if not block.rows:
+ return ""
+ show_title = getattr(block, "show_title", True)
+ head = "<th>URL</th><th class=\"col-status\">Status</th>"
+ if show_title:
+ head += "<th>Title</th>"
+ body_rows: list[str] = []
+ for row in block.rows:
+ url = str(row.get("url") or "")
+ status = str(row.get("status") or "")
+ cells = (
+ f'<td class="link">{_esc(url)}</td>'
+ f'<td class="col-status">{_status_badge(status)}</td>'
+ )
+ if show_title:
+ title = str(row.get("title") or "").strip()
+ title_cell = _esc(title) if title else '<span class="site-wide">—</span>'
+ cells += f"<td>{title_cell}</td>"
+ body_rows.append(f"<tr>{cells}</tr>")
+ note = ""
+ if block.truncation:
+ t = block.truncation
+ note = (
+ f'<p class="muted-note">Showing {t.shown} of {t.total} URLs. '
+ f"Export CSV/workbook for full inventory.</p>"
+ )
+ return (
+ f'<table class="data-table url-list"><thead><tr>{head}</tr></thead>'
+ f'<tbody>{"".join(body_rows)}</tbody></table>{note}'
+ )
+
+
+def _render_block(block: Any) -> str:
+ if not getattr(block, "visible", True):
+ return ""
+ btype = getattr(block, "type", None)
+ if btype == "issue_group":
+ return _render_issue_group(block)
+ if btype == "key_value":
+ return _render_key_value(block)
+ if btype == "url_list":
+ return _render_url_list(block)
+ if btype == "issue_table":
+ rows = "".join(
+ f"<tr><td>{_esc(iss.headline)}</td><td class=\"link\">{_esc(iss.url or '')}</td></tr>"
+ for iss in block.issues
+ )
+ title = f"<p class=\"group-label\">{_esc(block.title)}</p>" if block.title else ""
+ return (
+ f"{title}<table class=\"data-table\"><thead><tr><th>Issue</th><th>URL</th></tr></thead>"
+ f"<tbody>{rows}</tbody></table>"
+ )
+ if btype == "paragraph":
+ return f"<p>{_esc(block.text)}</p>"
+ if btype == "heading":
+ tag = "h3" if block.level >= 3 else "h2"
+ return f"<{tag}>{_esc(block.text)}</{tag}>"
+ if btype == "callout":
+ return f'<div class="exec-panel"><p class="exec-body">{_esc(block.text)}</p></div>'
+ if btype == "markdown":
+ text = re.sub(r"<[^>]+>", " ", block.text)
+ return f"<p>{_esc(text)}</p>"
+ if btype == "metric_table":
+ cols = block.columns
+ if not cols:
+ return ""
+ head = "".join(f"<th>{_esc(c.label)}</th>" for c in cols)
+ body = ""
+ for row in block.rows:
+ body += "<tr>" + "".join(
+ f'<td>{_esc(row.get(c.key, ""))}</td>' for c in cols
+ ) + "</tr>"
+ return f'<table class="data-table"><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table>'
+ if btype in {"spacer", "kpi_row", "stat_grid", "score_cards"}:
+ return ""
+ return ""
+
+
+def _render_section(section: PdfSection) -> str:
+ parts = [f'<section class="doc-section" id="{_esc(section.id)}">']
+ parts.append(f"<h2>{_esc(section.title)}</h2><hr class=\"section-rule\"/>")
+ if section.source_label:
+ parts.append(f'<p class="source-label">Source: {_esc(section.source_label)}</p>')
+ for block in section.blocks:
+ parts.append(_render_block(block))
+ if section.truncation:
+ t = section.truncation
+ parts.append(
+ f'<p class="muted-note">Showing {t.shown} of {t.total} issues. '
+ f"Export CSV or workbook for full data.</p>"
+ )
+ parts.append("</section>")
+ return "".join(parts)
+
+
+def render_html_document(doc: PdfDocument) -> str:
+ """Render a PdfDocument as HTML matching the PDF export layout."""
+ cover_html = _render_cover(doc.cover, doc.meta)
+ sections_html = "".join(_render_section(s) for s in doc.sections)
+ footer = doc.footer
+ footer_text = (
+ f"{footer.confidential_note} "
+ f"Generated by {footer.generator} · {footer.exported_at}"
+ )
+ title = _esc(doc.cover.headline)
+ return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>{title}
+
+
+
+
+{cover_html}
+
+
+{sections_html}
+
+
+
+
+