feat: overlay-based header+label on content pages only (pypdf merge)

- Render base PDF with no header/label via Playwright
- Build single-page overlay PDF with header image + label
- Stamp overlay onto content pages (skip cover/toc + final image pages)
- Header flush at top edge, label at right edge (1.65cm x 23.42cm)
- Pages 1-2: clean (no header, no label)
- Final image pages: clean (no header, no label)
- Added pypdf>=4.0.0 dependency

app/services/pdf_renderer.py

@@ -63,6 +63,12 @@ async def render_pdf_from_html(
 ) -> bytes:
     """Render HTML string to PDF bytes using Playwright Chromium.
 
+    Generates a base PDF (content only, no decorative header/label),
+    then creates a one-page overlay with the header image and right-side
+    label, and stamps the overlay onto content pages (page 3 → last
+    content page) using pypdf.  Pages 1-2 (cover/TOC) and trailing
+    full-page image pages get no overlay.
+
     Args:
         html_content: Complete HTML document string.
         format: Page format (default A4).
@@ -96,91 +102,59 @@ async def render_pdf_from_html(
             file_url = Path(tmp_path).as_uri()
             await page.goto(file_url, wait_until="networkidle", timeout=wait_timeout)
 
-            # Wait for fonts to be fully loaded
-            await page.evaluate("""
-                () => document.fonts.ready
-            """)
-
-            # Wait for all images to complete loading
+            # Wait for fonts and images to be fully loaded
+            await page.evaluate("() => document.fonts.ready")
             await page.evaluate("""
                 () => {
                     const images = Array.from(document.querySelectorAll('img'));
                     return Promise.all(images.map(img => {
                         if (img.complete) return Promise.resolve();
-                        return new Promise((resolve) => {
-                            img.addEventListener('load', resolve);
-                            img.addEventListener('error', resolve);
+                        return new Promise(r => {
+                            img.addEventListener('load', r);
+                            img.addEventListener('error', r);
                         });
                     }));
                 }
             """)
-
-            # Small delay for final layout settle
             await page.wait_for_timeout(500)
 
-            # Debug: verify label element presence
-            label_info = await page.evaluate("""
-                () => {
-                    const el = document.querySelector('.hb-right-label');
-                    if (!el) return 'NO .hb-right-label element found';
-                    const img = el.querySelector('img');
-                    const src = img ? img.src.substring(0, 80) : 'NO img';
-                    const loaded = img ? img.complete : false;
-                    const natW = img ? img.naturalWidth : 0;
-                    const natH = img ? img.naturalHeight : 0;
-                    return `label OK: loaded=${loaded}, natural=${natW}x${natH}, src=${src}...`;
-                }
-            """)
-            logger.info("Label check: %s", label_info)
-
-            # Extract header image src from DOM for Playwright header_template
+            # ── Collect info from DOM before hiding elements ──
             header_src = await page.evaluate("""
                 () => {
                     const img = document.querySelector('.page-header img');
                     return img ? img.src : '';
                 }
             """)
-
-            # Build header template — image scales to fit the top margin zone.
-            # Playwright margin.top = 2.54cm; header image fills that entire zone.
-            if header_src:
-                header_tpl = (
-                    '<div style="width:100%;height:100%;margin:0;padding:0;overflow:hidden;">'
-                    f'<img src="{header_src}" '
-                    'style="display:block;width:100%;height:100%;margin:0;padding:0;object-fit:fill;" />'
-                    '</div>'
-                )
-            else:
-                header_tpl = '<span></span>'
-
-            # Hide in-page header and footer divs before PDF generation.
-            # .hb-right-label stays visible (position:fixed, repeats every page).
-            await page.evaluate("""
+            label_src = await page.evaluate("""
                 () => {
-                    document.querySelectorAll('.page-header, .page-footer')
-                        .forEach(el => el.style.display = 'none');
+                    const img = document.querySelector('.hb-right-label img');
+                    return img ? img.src : '';
                 }
             """)
+            num_bottom_pages = await page.evaluate("""
+                () => document.querySelectorAll('.fullpage-img-wrap').length
+            """)
+            # Cover page count: cover + TOC image (each is a .cover-page)
+            num_cover_pages = await page.evaluate("""
+                () => document.querySelectorAll('.cover-page').length
+            """)
+
+            logger.info(
+                "Overlay info: header=%s, label=%s, covers=%d, bottoms=%d",
+                bool(header_src), bool(label_src),
+                num_cover_pages, num_bottom_pages,
+            )
 
-            # Hide the label on cover and fullpage image pages.
-            # These pages expand to fill the full page so the label
-            # should not be visible on them.
+            # ── Hide header, footer, and label from the base PDF ──
             await page.evaluate("""
                 () => {
-                    document.querySelectorAll('.cover-page, .fullpage-img-wrap').forEach(el => {
-                        const overlay = document.createElement('div');
-                        overlay.style.cssText = 'position:absolute;top:0;right:0;width:2cm;height:100%;background:#fff;z-index:20;';
-                        el.style.position = 'relative';
-                        el.appendChild(overlay);
-                    });
+                    document.querySelectorAll('.page-header, .page-footer, .hb-right-label')
+                        .forEach(el => el.style.display = 'none');
                 }
             """)
 
-            # NON-NEGOTIABLE: 2.54 cm margins on all four sides.
-            # Header: rendered by header_template inside the top margin zone.
-            # Footer: page number rendered by footer_template in the bottom margin.
-            # Content: sits inside the margin box — no CSS padding needed.
-            pdf_bytes = await page.pdf(
+            # ── Render BASE PDF (no header, no label) ──
+            base_pdf = await page.pdf(
                 format=format,
                 print_background=print_background,
                 prefer_css_page_size=prefer_css_page_size,
@@ -191,7 +165,7 @@ async def render_pdf_from_html(
                     "left": "2.54cm",
                 },
                 display_header_footer=True,
-                header_template=header_tpl,
+                header_template='<span></span>',
                 footer_template=(
                     '<div style="width:100%;text-align:center;font-size:10px;'
                     'font-family:Century Gothic,Segoe UI,sans-serif;color:#333;'
@@ -199,12 +173,132 @@ async def render_pdf_from_html(
                     '<span class="pageNumber"></span></div>'
                 ),
             )
-
-            logger.info("PDF rendered via Playwright, size=%d bytes", len(pdf_bytes))
-            return pdf_bytes
+            logger.info("Base PDF rendered, size=%d bytes", len(base_pdf))
 
         finally:
             os.unlink(tmp_path)
 
+        # ── Build overlay (header + label) and stamp onto content pages ──
+        if not header_src and not label_src:
+            logger.info("No header or label to overlay, returning base PDF")
+            return base_pdf
+
+        overlay_pdf = await _build_overlay_pdf(
+            page, header_src, label_src, format, wait_timeout
+        )
+
+        merged = _stamp_overlay(
+            base_pdf, overlay_pdf,
+            skip_front=num_cover_pages,
+            skip_back=num_bottom_pages,
+        )
+        logger.info("Final PDF with overlay, size=%d bytes", len(merged))
+        return merged
+
     finally:
         await context.close()
+
+
+async def _build_overlay_pdf(
+    page, header_src: str, label_src: str,
+    format: str, timeout: int,
+) -> bytes:
+    """Render a single-page transparent overlay PDF with header + label."""
+    parts = []
+    if header_src:
+        parts.append(
+            f'<div style="position:fixed;top:0;left:0;width:100%;height:2.54cm;'
+            f'margin:0;padding:0;overflow:hidden;z-index:1;">'
+            f'<img src="{header_src}" style="display:block;width:100%;'
+            f'height:100%;object-fit:fill;margin:0;padding:0;" /></div>'
+        )
+    if label_src:
+        parts.append(
+            f'<div style="position:fixed;top:0;right:0;width:1.65cm;'
+            f'height:23.42cm;z-index:2;overflow:hidden;">'
+            f'<img src="{label_src}" style="display:block;width:100%;'
+            f'height:100%;object-fit:fill;" /></div>'
+        )
+
+    overlay_html = (
+        '<!doctype html><html><head><meta charset="utf-8">'
+        '<style>'
+        '@page{size:A4;margin:0}'
+        'html,body{margin:0;padding:0;background:transparent}'
+        '</style></head><body>'
+        + '\n'.join(parts)
+        + '<div style="height:297mm;width:210mm;"></div>'
+        '</body></html>'
+    )
+
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".html", delete=False, encoding="utf-8",
+    ) as tmp:
+        tmp.write(overlay_html)
+        tmp_path = tmp.name
+
+    try:
+        await page.goto(
+            Path(tmp_path).as_uri(),
+            wait_until="networkidle",
+            timeout=timeout,
+        )
+        await page.evaluate("() => document.fonts.ready")
+        await page.evaluate("""
+            () => {
+                const images = Array.from(document.querySelectorAll('img'));
+                return Promise.all(images.map(img => {
+                    if (img.complete) return Promise.resolve();
+                    return new Promise(r => {
+                        img.addEventListener('load', r);
+                        img.addEventListener('error', r);
+                    });
+                }));
+            }
+        """)
+        await page.wait_for_timeout(300)
+
+        overlay_bytes = await page.pdf(
+            format=format,
+            print_background=True,
+            prefer_css_page_size=True,
+            margin={"top": "0", "right": "0", "bottom": "0", "left": "0"},
+            display_header_footer=False,
+        )
+        logger.info("Overlay PDF rendered, size=%d bytes", len(overlay_bytes))
+        return overlay_bytes
+    finally:
+        os.unlink(tmp_path)
+
+
+def _stamp_overlay(
+    base_pdf: bytes,
+    overlay_pdf: bytes,
+    skip_front: int = 2,
+    skip_back: int = 4,
+) -> bytes:
+    """Merge overlay onto content pages of the base PDF.
+
+    Pages 0..(skip_front-1) and (total-skip_back)..(total-1) are left
+    untouched.  All other pages get the overlay stamped on top.
+    """
+    import io
+    from pypdf import PdfReader, PdfWriter
+
+    base = PdfReader(io.BytesIO(base_pdf))
+    overlay_reader = PdfReader(io.BytesIO(overlay_pdf))
+    overlay_page = overlay_reader.pages[0]
+    writer = PdfWriter()
+
+    total = len(base.pages)
+    first_content = skip_front            # e.g. page index 2
+    last_content = total - skip_back - 1  # e.g. total-5
+
+    for i, pg in enumerate(base.pages):
+        if first_content <= i <= last_content:
+            pg.merge_page(overlay_page)
+        writer.add_page(pg)
+
+    buf = io.BytesIO()
+    writer.write(buf)
+    return buf.getvalue()

app/static/css/print.css

@@ -65,7 +65,7 @@ body {
     width: 100%;
     max-width: 100%;
     margin: 0;
-    padding: 0 1.85cm 0 0;
+    padding: 0;
     position: relative;
     z-index: 1;
     overflow: visible;
@@ -90,28 +90,23 @@ body {
 
 /* ------------------------------
    DECORATIVE RIGHT-SIDE LABEL
-   position:fixed repeats on every printed page.
-   Placed at right:0 inside the content area.
-   page-content gets padding-right to prevent overlap.
-   Original: 43.28cm × 3.31cm → scaled 54% × 50%
-   = 23.42cm × 1.65cm
+   Hidden in the base HTML. Rendered as a PDF overlay
+   by pdf_renderer.py onto content pages only.
+   Kept here so the <img> loads for src extraction.
+   Original: 43.28cm × 3.31cm → 54% × 50% = 23.42cm × 1.65cm
    ------------------------------ */
 .hb-right-label {
-    position: fixed;
-    top: 0;
-    right: 0;
-    width: 1.65cm;
-    height: 23.42cm;
-    z-index: 10;
-    pointer-events: none;
+    position: absolute;
+    top: -9999px;
+    left: -9999px;
+    width: 1px;
+    height: 1px;
     overflow: hidden;
+    pointer-events: none;
 }
 
 .hb-right-label img {
     display: block;
-    width: 100%;
-    height: 100%;
-    object-fit: fill;
 }
 
 /* ------------------------------

requirements.txt

@@ -6,4 +6,5 @@ httpx>=0.27.0
 jinja2>=3.1.0
 markupsafe>=2.1.0
 playwright>=1.40.0
+pypdf>=4.0.0
 python-dotenv>=1.0.0