@nomad-e/bluma-cli 0.1.58 → 0.1.59

package/dist/config/skills/pdf/scripts/create_report.py

@@ -3,287 +3,685 @@
 Professional PDF Report Generator — BluMa Template
 
 Usage:
+  Demo (sample content):
     python create_report.py [--title TITLE] [--subtitle SUBTITLE] [--output FILE]
 
-Generates a professional report PDF with cover page, table of contents,
-styled sections, tables, and callout boxes.
+  Production (your content, same visual system):
+    python create_report.py --from-json report.json --output .bluma/artifacts/relatorio.pdf
+
+JSON schema (UTF-8 file):
+{
+  "title": "Relatório",
+  "subtitle": "Subtítulo opcional",
+  "author": "Equipe / Cliente (opcional)",
+  "page_break_per_section": true,
+  "sections": [
+    {
+      "num": 1,
+      "title": "Introdução",
+      "blocks": [
+        { "type": "paragraph", "text": "Texto com quebras\\nlinha." },
+        { "type": "callout", "title": "Destaque", "text": "...", "variant": "info" },
+        { "type": "bullets", "items": ["Item A", "Item B"] },
+        { "type": "table", "headers": ["Col1", "Col2"], "rows": [["a", "b"]], "col_widths": null }
+      ]
+    }
+  ]
+}
+
+variant for callout: "info" | "warning"
+Text in JSON is escaped for XML/HTML safety; use plain text, not ReportLab tags.
+
+Editorial guidance for agents (structure, copy, restraint): see pdf/SKILL.md
+section "JSON quality — make the PDF look designed".
 """
 
+from __future__ import annotations
+
 import argparse
+import json
+import sys
 from datetime import date
+from pathlib import Path
+from typing import Any
+from xml.sax.saxutils import escape
 
 from reportlab.lib.pagesizes import A4
 from reportlab.lib.units import cm
 from reportlab.lib.colors import HexColor
 from reportlab.lib.styles import ParagraphStyle
-from reportlab.lib.enums import TA_CENTER, TA_JUSTIFY, TA_LEFT
+from reportlab.lib.enums import TA_CENTER, TA_JUSTIFY
 from reportlab.platypus import (
-    SimpleDocTemplate, Paragraph, Spacer, PageBreak,
-    Table, TableStyle, HRFlowable,
+    SimpleDocTemplate,
+    Paragraph,
+    Spacer,
+    PageBreak,
+    Table,
+    TableStyle,
+    HRFlowable,
 )
 
 
 # ── Color Palette ──────────────────────────────────────────────
 
 COLORS = {
-    'primary':    HexColor('#1B2A4A'),
-    'secondary':  HexColor('#2C5F8A'),
-    'accent':     HexColor('#E67E22'),
-    'text':       HexColor('#2D3436'),
-    'text_light': HexColor('#636E72'),
-    'bg_light':   HexColor('#F8F9FA'),
-    'bg_accent':  HexColor('#EBF5FB'),
-    'border':     HexColor('#BDC3C7'),
-    'white':      HexColor('#FFFFFF'),
+    "primary": HexColor("#0F172A"),  # slate-900 — mais editorial que navy genérico
+    "secondary": HexColor("#334155"),  # slate-700
+    "accent": HexColor("#C2410C"),  # laranja queimado — menos “banner de site”
+    "muted": HexColor("#64748B"),
+    "text": HexColor("#1E293B"),
+    "text_light": HexColor("#64748B"),
+    "bg_light": HexColor("#F1F5F9"),
+    "bg_accent": HexColor("#E0F2FE"),
+    "border": HexColor("#CBD5E1"),
+    "white": HexColor("#FFFFFF"),
 }
 
 # ── Typography ─────────────────────────────────────────────────
 
-FONT = 'Helvetica'
-FONT_B = 'Helvetica-Bold'
-FONT_I = 'Helvetica-Oblique'
+FONT = "Helvetica"
+FONT_B = "Helvetica-Bold"
+FONT_I = "Helvetica-Oblique"
 
 PAGE_W, PAGE_H = A4
 M = 2.5 * cm
 CW = PAGE_W - 2 * M
 
 S = {
-    'title': ParagraphStyle('T', fontName=FONT_B, fontSize=28, leading=34,
-                            textColor=COLORS['primary'], alignment=TA_CENTER, spaceAfter=6),
-    'subtitle': ParagraphStyle('ST', fontName=FONT, fontSize=14, leading=18,
-                               textColor=COLORS['secondary'], alignment=TA_CENTER, spaceAfter=30),
-    'h1': ParagraphStyle('H1', fontName=FONT_B, fontSize=20, leading=26,
-                         textColor=COLORS['primary'], spaceBefore=28, spaceAfter=12),
-    'h2': ParagraphStyle('H2', fontName=FONT_B, fontSize=15, leading=20,
-                         textColor=COLORS['secondary'], spaceBefore=20, spaceAfter=8),
-    'body': ParagraphStyle('B', fontName=FONT, fontSize=10.5, leading=15,
-                           textColor=COLORS['text'], alignment=TA_JUSTIFY,
-                           spaceBefore=2, spaceAfter=8),
-    'bullet': ParagraphStyle('BL', fontName=FONT, fontSize=10.5, leading=15,
-                             textColor=COLORS['text'], leftIndent=24, bulletIndent=12,
-                             spaceBefore=2, spaceAfter=4),
-    'meta': ParagraphStyle('M', fontName=FONT, fontSize=11,
-                           textColor=COLORS['text_light'], alignment=TA_CENTER, spaceAfter=4),
-    'date': ParagraphStyle('D', fontName=FONT, fontSize=10,
-                           textColor=COLORS['secondary'], alignment=TA_CENTER),
-    'toc': ParagraphStyle('TOC', fontName=FONT, fontSize=11, leading=20,
-                          textColor=COLORS['text']),
-    'toc_b': ParagraphStyle('TOCB', fontName=FONT_B, fontSize=11, leading=20,
-                            textColor=COLORS['primary']),
+    "title": ParagraphStyle(
+        "T",
+        fontName=FONT_B,
+        fontSize=26,
+        leading=31,
+        textColor=COLORS["primary"],
+        alignment=TA_CENTER,
+        spaceAfter=8,
+    ),
+    "subtitle": ParagraphStyle(
+        "ST",
+        fontName=FONT,
+        fontSize=13,
+        leading=17,
+        textColor=COLORS["secondary"],
+        alignment=TA_CENTER,
+        spaceAfter=6,
+    ),
+    "h1": ParagraphStyle(
+        "H1",
+        fontName=FONT_B,
+        fontSize=18,
+        leading=24,
+        textColor=COLORS["primary"],
+        spaceBefore=22,
+        spaceAfter=10,
+    ),
+    # Cabeçalho de capítulo (sem spaceBefore — evita “buraco” dentro da tabela)
+    "h1_sec": ParagraphStyle(
+        "H1Sec",
+        fontName=FONT_B,
+        fontSize=17,
+        leading=22,
+        textColor=COLORS["primary"],
+        spaceBefore=0,
+        spaceAfter=0,
+    ),
+    "h2": ParagraphStyle(
+        "H2",
+        fontName=FONT_B,
+        fontSize=13,
+        leading=18,
+        textColor=COLORS["secondary"],
+        spaceBefore=16,
+        spaceAfter=6,
+    ),
+    "body": ParagraphStyle(
+        "B",
+        fontName=FONT,
+        fontSize=10.5,
+        leading=15,
+        textColor=COLORS["text"],
+        alignment=TA_JUSTIFY,
+        spaceBefore=2,
+        spaceAfter=8,
+    ),
+    "bullet": ParagraphStyle(
+        "BL",
+        fontName=FONT,
+        fontSize=10.5,
+        leading=15,
+        textColor=COLORS["text"],
+        leftIndent=18,
+        bulletIndent=8,
+        spaceBefore=1,
+        spaceAfter=3,
+    ),
+    "meta": ParagraphStyle(
+        "M",
+        fontName=FONT,
+        fontSize=10,
+        textColor=COLORS["text_light"],
+        alignment=TA_CENTER,
+        spaceAfter=4,
+    ),
+    "date": ParagraphStyle(
+        "D",
+        fontName=FONT,
+        fontSize=9.5,
+        textColor=COLORS["muted"],
+        alignment=TA_CENTER,
+    ),
+    "toc": ParagraphStyle(
+        "TOC",
+        fontName=FONT,
+        fontSize=10.5,
+        leading=18,
+        textColor=COLORS["text"],
+    ),
+    "toc_b": ParagraphStyle(
+        "TOCB",
+        fontName=FONT_B,
+        fontSize=10.5,
+        leading=18,
+        textColor=COLORS["primary"],
+    ),
 }
 
 
-# ── Components ─────────────────────────────────────────────────
-
-def cover(story, title, subtitle=None, author=None):
-    story.append(Spacer(1, 6 * cm))
-    story.append(Paragraph(title, S['title']))
-    story.append(Spacer(1, 0.5 * cm))
-    story.append(HRFlowable(width='40%', thickness=2, color=COLORS['accent'],
-                             spaceAfter=20, spaceBefore=10))
+def _ptext(s: str) -> str:
+    """Plain text → safe Paragraph markup (preserva quebras como <br/>)."""
+    if s is None:
+        return ""
+    return escape(str(s)).replace("\n", "<br/>")
+
+
+def _cover_title_paragraph(title: str) -> Paragraph:
+    """Título da capa: tamanho adaptável + quebra em duas linhas equilibradas."""
+    raw = (title or "").strip()
+    if not raw:
+        return Paragraph("", S["title"])
+    if "\n" in raw:
+        return Paragraph(_ptext(raw), S["title"])
+    n = len(raw)
+    if n > 56:
+        fs, ld = 17, 21
+    elif n > 42:
+        fs, ld = 20, 25
+    else:
+        fs, ld = 26, 31
+    sty = ParagraphStyle(
+        "TCoverDyn",
+        fontName=FONT_B,
+        fontSize=fs,
+        leading=ld,
+        textColor=COLORS["primary"],
+        alignment=TA_CENTER,
+        spaceAfter=8,
+    )
+    # Duas linhas com comprimento o mais equilibrado possível (evita órfãos)
+    if n > 28 and " " in raw:
+        words = raw.split()
+        if len(words) >= 2:
+            best_cut, best_diff = 1, 10**9
+            for cut in range(1, len(words)):
+                a = len(" ".join(words[:cut]))
+                b = len(" ".join(words[cut:]))
+                diff = abs(a - b)
+                if diff < best_diff:
+                    best_diff = diff
+                    best_cut = cut
+            last_w = words[best_cut]
+            if best_cut > 1 and len(words[best_cut:]) == 1 and len(last_w) <= 10:
+                best_cut -= 1
+            if 1 <= best_cut < len(words):
+                line1 = " ".join(words[:best_cut])
+                line2 = " ".join(words[best_cut:])
+                markup = _ptext(line1) + "<br/>" + _ptext(line2)
+                return Paragraph(markup, sty)
+    return Paragraph(_ptext(raw), sty)
+
+
+def _normalize_col_widths(
+    widths: list[float] | None, ncols: int
+) -> list[float]:
+    if not widths or len(widths) != ncols:
+        return [CW / ncols] * ncols
+    s = sum(float(w) for w in widths)
+    if s <= 0:
+        return [CW / ncols] * ncols
+    scale = CW / s
+    return [float(w) * scale for w in widths]
+
+
+# ── Cover (story + canvas) ─────────────────────────────────────
+
+
+def cover_story(story: list, title: str, subtitle: str | None, author: str | None) -> None:
+    story.append(Spacer(1, 5.5 * cm))
+    story.append(_cover_title_paragraph(title))
     if subtitle:
-        story.append(Paragraph(subtitle, S['subtitle']))
-    story.append(Spacer(1, 3 * cm))
+        story.append(Paragraph(_ptext(subtitle), S["subtitle"]))
+    story.append(Spacer(1, 0.4 * cm))
+    story.append(
+        HRFlowable(
+            width="32%",
+            thickness=1.5,
+            color=COLORS["accent"],
+            spaceAfter=22,
+            spaceBefore=6,
+        )
+    )
+    story.append(Spacer(1, 2.8 * cm))
     if author:
-        story.append(Paragraph(author, S['meta']))
-    story.append(Paragraph(date.today().strftime('%B %Y'), S['date']))
+        story.append(Paragraph(_ptext(author), S["meta"]))
+    story.append(Paragraph(_ptext(date.today().strftime("%d %B %Y")), S["date"]))
     story.append(PageBreak())
 
 
-def toc(story, sections):
-    story.append(Paragraph("Table of Contents", S['h1']))
-    story.append(Spacer(1, 0.5 * cm))
+def draw_cover_canvas(canvas_obj, doc) -> None:
+    """Barra lateral de marca + filete superior — só na capa (texto segue no fluxo)."""
+    canvas_obj.saveState()
+    canvas_obj.setFillColor(COLORS["primary"])
+    canvas_obj.rect(0, 0, 0.55 * cm, PAGE_H, fill=1, stroke=0)
+    canvas_obj.setStrokeColor(COLORS["accent"])
+    canvas_obj.setLineWidth(2.5)
+    canvas_obj.line(M, PAGE_H - M, PAGE_W - M, PAGE_H - M)
+    canvas_obj.restoreState()
+
+
+# ── TOC & body ─────────────────────────────────────────────────
+
+
+def toc(story: list, sections: list[dict[str, Any]]) -> None:
+    story.append(Paragraph("Sumário", S["h1"]))
+    story.append(Spacer(1, 0.35 * cm))
     for sec in sections:
-        style = S['toc_b'] if sec.get('level', 1) == 1 else S['toc']
-        indent = '' if sec.get('level', 1) == 1 else '&nbsp;&nbsp;&nbsp;&nbsp;'
+        style = S["toc_b"] if sec.get("level", 1) == 1 else S["toc"]
+        indent = "" if sec.get("level", 1) == 1 else "&nbsp;&nbsp;&nbsp;&nbsp;"
+        num = sec.get("num", "")
+        title = sec["title"]
+        if sec.get("level", 1) == 1 and num != "":
+            left = f"{indent}{num}. {title}"
+        else:
+            left = f"{indent}{title}"
         row = Table(
-            [[Paragraph(f"{indent}{sec['num']}. {sec['title']}" if sec.get('level', 1) == 1
-                        else f"{indent}{sec['title']}", style),
-              Paragraph(str(sec.get('page', '')), style)]],
-            colWidths=[CW - 40, 40],
+            [
+                [
+                    Paragraph(left, style),
+                    Paragraph(str(sec.get("page", "")), style),
+                ]
+            ],
+            colWidths=[CW - 36, 36],
+        )
+        row.setStyle(
+            TableStyle(
+                [
+                    ("ALIGN", (1, 0), (1, 0), "RIGHT"),
+                    ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+                    ("LINEBELOW", (0, 0), (-1, -1), 0.35, COLORS["border"]),
+                    ("TOPPADDING", (0, 0), (-1, -1), 5),
+                    ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                ]
+            )
         )
-        row.setStyle(TableStyle([
-            ('ALIGN', (1, 0), (1, 0), 'RIGHT'),
-            ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
-            ('LINEBELOW', (0, 0), (-1, -1), 0.5, COLORS['bg_light']),
-            ('TOPPADDING', (0, 0), (-1, -1), 4),
-            ('BOTTOMPADDING', (0, 0), (-1, -1), 4),
-        ]))
         story.append(row)
     story.append(PageBreak())
 
 
-def section(story, num, title):
+def section(story: list, num: int | str, title: str) -> None:
     header = Table(
-        [[Paragraph(f"{num}.", ParagraphStyle('SN', fontName=FONT_B, fontSize=20,
-                                              textColor=COLORS['accent'])),
-          Paragraph(title, S['h1'])]],
-        colWidths=[35, CW - 35],
+        [
+            [
+                Paragraph(
+                    f"{num}.",
+                    ParagraphStyle(
+                        "SN",
+                        fontName=FONT_B,
+                        fontSize=18,
+                        textColor=COLORS["accent"],
+                    ),
+                ),
+                Paragraph(_ptext(title), S["h1_sec"]),
+            ]
+        ],
+        colWidths=[32, CW - 32],
+    )
+    header.setStyle(
+        TableStyle(
+            [
+                ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                ("TOPPADDING", (0, 0), (-1, -1), 0),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 0),
+            ]
+        )
     )
-    header.setStyle(TableStyle([
-        ('VALIGN', (0, 0), (-1, -1), 'TOP'),
-        ('TOPPADDING', (0, 0), (-1, -1), 0),
-        ('BOTTOMPADDING', (0, 0), (-1, -1), 0),
-    ]))
     story.append(header)
-    story.append(HRFlowable(width='100%', thickness=1, color=COLORS['secondary'],
-                             spaceAfter=12))
+    story.append(
+        HRFlowable(
+            width="100%",
+            thickness=0.75,
+            color=COLORS["border"],
+            spaceAfter=12,
+        )
+    )
 
 
-def callout(story, title, text, box_type='info'):
-    bg = COLORS['bg_accent'] if box_type == 'info' else COLORS['bg_light']
-    border = COLORS['secondary'] if box_type == 'info' else COLORS['accent']
+def callout(story: list, title: str, text: str, box_type: str = "info") -> None:
+    box_type = box_type if box_type in ("info", "warning") else "info"
+    bg = COLORS["bg_accent"] if box_type == "info" else COLORS["bg_light"]
+    border = COLORS["secondary"] if box_type == "info" else COLORS["accent"]
+    label = "Informação" if box_type == "info" else "Atenção"
     content = [
-        [Paragraph(f"<b>{title}</b>",
-                   ParagraphStyle('CT', fontName=FONT_B, fontSize=10,
-                                  textColor=COLORS['primary'], spaceAfter=4))],
-        [Paragraph(text, ParagraphStyle('CB', fontName=FONT, fontSize=9.5,
-                                        leading=14, textColor=COLORS['text']))],
+        [
+            Paragraph(
+                f"<b>{_ptext(label)} — {_ptext(title)}</b>",
+                ParagraphStyle(
+                    "CT",
+                    fontName=FONT_B,
+                    fontSize=9.5,
+                    textColor=COLORS["primary"],
+                    spaceAfter=4,
+                ),
+            )
+        ],
+        [
+            Paragraph(
+                _ptext(text),
+                ParagraphStyle(
+                    "CB",
+                    fontName=FONT,
+                    fontSize=9.5,
+                    leading=14,
+                    textColor=COLORS["text"],
+                ),
+            )
+        ],
     ]
     t = Table(content, colWidths=[CW - 20])
-    t.setStyle(TableStyle([
-        ('BACKGROUND', (0, 0), (-1, -1), bg),
-        ('BOX', (0, 0), (-1, -1), 1.5, border),
-        ('LEFTPADDING', (0, 0), (-1, -1), 14),
-        ('RIGHTPADDING', (0, 0), (-1, -1), 14),
-        ('TOPPADDING', (0, 0), (0, 0), 10),
-        ('BOTTOMPADDING', (-1, -1), (-1, -1), 10),
-    ]))
-    story.append(Spacer(1, 8))
+    t.setStyle(
+        TableStyle(
+            [
+                ("BACKGROUND", (0, 0), (-1, -1), bg),
+                ("BOX", (0, 0), (-1, -1), 0.85, border),
+                ("LEFTPADDING", (0, 0), (-1, -1), 12),
+                ("RIGHTPADDING", (0, 0), (-1, -1), 12),
+                ("TOPPADDING", (0, 0), (0, 0), 9),
+                ("BOTTOMPADDING", (-1, -1), (-1, -1), 9),
+            ]
+        )
+    )
+    story.append(Spacer(1, 6))
     story.append(t)
-    story.append(Spacer(1, 8))
-
-
-def pro_table(story, headers, rows, col_widths=None):
-    data = [headers] + rows
-    if not col_widths:
-        col_widths = [CW / len(headers)] * len(headers)
+    story.append(Spacer(1, 6))
+
+
+def pro_table(
+    story: list,
+    headers: list[str],
+    rows: list[list[str]],
+    col_widths: list[float] | None = None,
+) -> None:
+    h_esc = [_ptext(h) for h in headers]
+    data = [h_esc] + [[_ptext(c) for c in row] for row in rows]
+    col_widths = _normalize_col_widths(col_widths, len(headers))
     t = Table(data, colWidths=col_widths, repeatRows=1)
-    t.setStyle(TableStyle([
-        ('BACKGROUND', (0, 0), (-1, 0), COLORS['primary']),
-        ('TEXTCOLOR', (0, 0), (-1, 0), COLORS['white']),
-        ('FONTNAME', (0, 0), (-1, 0), FONT_B),
-        ('FONTSIZE', (0, 0), (-1, 0), 10),
-        ('BOTTOMPADDING', (0, 0), (-1, 0), 10),
-        ('TOPPADDING', (0, 0), (-1, 0), 10),
-        ('FONTNAME', (0, 1), (-1, -1), FONT),
-        ('FONTSIZE', (0, 1), (-1, -1), 9.5),
-        ('TEXTCOLOR', (0, 1), (-1, -1), COLORS['text']),
-        ('TOPPADDING', (0, 1), (-1, -1), 7),
-        ('BOTTOMPADDING', (0, 1), (-1, -1), 7),
-        *[('BACKGROUND', (0, i), (-1, i), COLORS['bg_light'])
-          for i in range(1, len(data), 2)],
-        ('LINEBELOW', (0, 0), (-1, 0), 1.5, COLORS['secondary']),
-        ('LINEBELOW', (0, 1), (-1, -2), 0.5, COLORS['border']),
-        ('LINEBELOW', (0, -1), (-1, -1), 1, COLORS['secondary']),
-        ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
-        ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
-        ('LEFTPADDING', (0, 0), (-1, -1), 10),
-        ('RIGHTPADDING', (0, 0), (-1, -1), 10),
-    ]))
+    t.setStyle(
+        TableStyle(
+            [
+                ("BACKGROUND", (0, 0), (-1, 0), COLORS["primary"]),
+                ("TEXTCOLOR", (0, 0), (-1, 0), COLORS["white"]),
+                ("FONTNAME", (0, 0), (-1, 0), FONT_B),
+                ("FONTSIZE", (0, 0), (-1, 0), 9.5),
+                ("BOTTOMPADDING", (0, 0), (-1, 0), 9),
+                ("TOPPADDING", (0, 0), (-1, 0), 9),
+                ("FONTNAME", (0, 1), (-1, -1), FONT),
+                ("FONTSIZE", (0, 1), (-1, -1), 9),
+                ("TEXTCOLOR", (0, 1), (-1, -1), COLORS["text"]),
+                ("TOPPADDING", (0, 1), (-1, -1), 6),
+                ("BOTTOMPADDING", (0, 1), (-1, -1), 6),
+                *[
+                    ("BACKGROUND", (0, i), (-1, i), COLORS["bg_light"])
+                    for i in range(1, len(data), 2)
+                ],
+                ("LINEBELOW", (0, 0), (-1, 0), 1, COLORS["accent"]),
+                ("LINEBELOW", (0, 1), (-1, -2), 0.25, COLORS["border"]),
+                ("LINEBELOW", (0, -1), (-1, -1), 0.75, COLORS["secondary"]),
+                ("ALIGN", (0, 0), (-1, -1), "LEFT"),
+                ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+                ("LEFTPADDING", (0, 0), (-1, -1), 9),
+                ("RIGHTPADDING", (0, 0), (-1, -1), 9),
+            ]
+        )
+    )
+    story.append(Spacer(1, 4))
     story.append(t)
-    story.append(Spacer(1, 12))
+    story.append(Spacer(1, 10))
 
 
-def header_footer(canvas_obj, doc):
+def header_footer(canvas_obj, doc) -> None:
     canvas_obj.saveState()
-    y_h = PAGE_H - 1.5 * cm
-    canvas_obj.setStrokeColor(COLORS['secondary'])
-    canvas_obj.setLineWidth(1.5)
+    y_h = PAGE_H - 1.35 * cm
+    canvas_obj.setStrokeColor(COLORS["border"])
+    canvas_obj.setLineWidth(0.6)
     canvas_obj.line(M, y_h, PAGE_W - M, y_h)
     canvas_obj.setFont(FONT, 8)
-    canvas_obj.setFillColor(COLORS['text_light'])
-    canvas_obj.drawString(M, y_h + 4, doc.title or '')
-
-    y_f = 1.2 * cm
-    canvas_obj.setStrokeColor(COLORS['border'])
-    canvas_obj.setLineWidth(0.5)
-    canvas_obj.line(M, y_f + 8, PAGE_W - M, y_f + 8)
-    canvas_obj.drawCentredString(PAGE_W / 2, y_f, f"Page {doc.page}")
+    canvas_obj.setFillColor(COLORS["text_light"])
+    title = (doc.title or "")[:90]
+    canvas_obj.drawString(M, y_h + 3, title)
+
+    y_f = 1.05 * cm
+    canvas_obj.setStrokeColor(COLORS["border"])
+    canvas_obj.setLineWidth(0.35)
+    canvas_obj.line(M, y_f + 10, PAGE_W - M, y_f + 10)
+    canvas_obj.setFont(FONT, 8)
+    canvas_obj.setFillColor(COLORS["muted"])
+    canvas_obj.drawCentredString(PAGE_W / 2, y_f, f"Página {doc.page}")
     canvas_obj.restoreState()
 
 
-# ── Main ───────────────────────────────────────────────────────
+def on_first_page(canvas_obj, doc) -> None:
+    draw_cover_canvas(canvas_obj, doc)
+
+
+def on_later_pages(canvas_obj, doc) -> None:
+    header_footer(canvas_obj, doc)
 
-def main():
-    parser = argparse.ArgumentParser(description='Generate professional PDF report')
-    parser.add_argument('--title', default='Sample Report')
-    parser.add_argument('--subtitle', default='A Professional Document')
-    parser.add_argument('--output', default='report.pdf')
-    args = parser.parse_args()
+
+# ── JSON-driven build ──────────────────────────────────────────
+
+
+def build_from_json(data: dict[str, Any], output_path: str) -> None:
+    title = data.get("title") or "Relatório"
+    subtitle = data.get("subtitle")
+    author = data.get("author")
+    # True = cada capítulo em página nova (relatório executivo); False = fluxo contínuo
+    page_per_section = data.get("page_break_per_section", True)
+    if not isinstance(page_per_section, bool):
+        page_per_section = bool(page_per_section)
+
+    sections = data.get("sections") or []
+    if not isinstance(sections, list):
+        raise ValueError('"sections" must be a list')
+
+    toc_rows: list[dict[str, Any]] = []
+    for i, sec in enumerate(sections, start=1):
+        if not isinstance(sec, dict):
+            continue
+        num = sec.get("num", i)
+        toc_rows.append({"num": num, "title": sec.get("title", f"Seção {i}"), "level": 1, "page": ""})
 
     doc = SimpleDocTemplate(
-        args.output, pagesize=A4,
-        leftMargin=M, rightMargin=M, topMargin=M, bottomMargin=M,
-        title=args.title, author='BluMa',
+        output_path,
+        pagesize=A4,
+        leftMargin=M,
+        rightMargin=M,
+        topMargin=M,
+        bottomMargin=M,
+        title=title,
+        author="BluMa",
     )
 
-    story = []
-
-    cover(story, args.title, args.subtitle, "Generated by BluMa")
-
-    toc(story, [
-        {'num': 1, 'title': 'Introduction', 'level': 1, 'page': 3},
-        {'num': 2, 'title': 'Key Findings', 'level': 1, 'page': 4},
-        {'num': 3, 'title': 'Conclusion', 'level': 1, 'page': 5},
-    ])
-
-    section(story, 1, "Introduction")
-    story.append(Paragraph(
-        "This document demonstrates the professional PDF generation capabilities "
-        "of BluMa. Every element — from typography to color palette — follows a "
-        "consistent design system that ensures readability and visual appeal.",
-        S['body'],
-    ))
-    story.append(Paragraph(
-        "The design system uses a navy and steel blue palette with warm orange "
-        "accents, Helvetica typography with a clear hierarchy, and generous "
-        "whitespace for a clean, modern look.",
-        S['body'],
-    ))
-
-    callout(story, "Key Insight",
-            "Professional documents communicate credibility before the reader "
-            "processes a single word. Design is the first impression.")
-
-    section(story, 2, "Key Findings")
-    story.append(Paragraph("Analysis results are summarized in the table below:", S['body']))
-    pro_table(story,
-              ['Metric', 'Q1 2026', 'Q2 2026', 'Change'],
-              [
-                  ['Revenue', '$1.2M', '$1.5M', '+25%'],
-                  ['Active Users', '45,000', '58,000', '+29%'],
-                  ['Retention', '82%', '87%', '+5pp'],
-                  ['NPS Score', '42', '56', '+14'],
-              ])
-    story.append(Paragraph(
-        "All metrics show significant improvement quarter-over-quarter, "
-        "driven primarily by the new onboarding flow and retention campaigns.",
-        S['body'],
-    ))
-
-    story.append(Paragraph("Key highlights:", S['body']))
+    story: list = []
+    cover_story(story, title, subtitle, author)
+    toc(story, toc_rows)
+
+    first_section = True
+    for sec in sections:
+        if not isinstance(sec, dict):
+            continue
+        num = sec.get("num", 0)
+        sec_title = sec.get("title", "")
+        if page_per_section and not first_section:
+            story.append(PageBreak())
+        first_section = False
+
+        blocks = [b for b in (sec.get("blocks") or []) if isinstance(b, dict)]
+        section(story, num, sec_title)
+        for block in blocks:
+            btype = block.get("type")
+            if btype == "paragraph":
+                story.append(Paragraph(_ptext(block.get("text", "")), S["body"]))
+            elif btype == "h2":
+                story.append(Paragraph(_ptext(block.get("text", "")), S["h2"]))
+            elif btype == "callout":
+                callout(
+                    story,
+                    block.get("title", ""),
+                    block.get("text", ""),
+                    block.get("variant", "info"),
+                )
+            elif btype == "bullets":
+                for item in block.get("items") or []:
+                    story.append(Paragraph(f"&bull;&nbsp; {_ptext(item)}", S["bullet"]))
+            elif btype == "table":
+                headers = block.get("headers") or []
+                rows = block.get("rows") or []
+                cw = block.get("col_widths")
+                pro_table(story, list(headers), [list(r) for r in rows], cw)
+            elif btype == "spacer":
+                story.append(Spacer(1, float(block.get("pt", 12))))
+
+        story.append(Spacer(1, 14))
+
+    doc.build(story, onFirstPage=on_first_page, onLaterPages=on_later_pages)
+    print(f"Report generated: {output_path}", file=sys.stderr)
+
+
+def demo_report(args: argparse.Namespace) -> None:
+    doc = SimpleDocTemplate(
+        args.output,
+        pagesize=A4,
+        leftMargin=M,
+        rightMargin=M,
+        topMargin=M,
+        bottomMargin=M,
+        title=args.title,
+        author="BluMa",
+    )
+
+    story: list = []
+    cover_story(story, args.title, args.subtitle, "Gerado por BluMa")
+
+    toc(
+        story,
+        [
+            {"num": 1, "title": "Introdução", "level": 1, "page": ""},
+            {"num": 2, "title": "Achados", "level": 1, "page": ""},
+            {"num": 3, "title": "Conclusão", "level": 1, "page": ""},
+        ],
+    )
+
+    section(story, 1, "Introdução")
+    story.append(
+        Paragraph(
+            _ptext(
+                "Este modelo define tipografia, margens, tabelas e caixas de destaque "
+                "para que o PDF pareça um relatório corporativo, não um print de terminal."
+            ),
+            S["body"],
+        )
+    )
+    story.append(
+        Paragraph(
+            _ptext(
+                "Paleta slate + laranja queimado, hierarquia clara e espaço em branco "
+                "intencional reduzem a sensação de documento “gerado por script”."
+            ),
+            S["body"],
+        )
+    )
+    callout(
+        story,
+        "Leitura rápida",
+        "Use o modo --from-json para manter este visual com o seu conteúdo, "
+        "sem reimplementar estilos no improviso.",
+        "info",
+    )
+
+    story.append(PageBreak())
+    section(story, 2, "Achados")
+    story.append(Paragraph(_ptext("Resumo numérico:"), S["body"]))
+    pro_table(
+        story,
+        ["Métrica", "Q1 2026", "Q2 2026", "Var."],
+        [
+            ["Receita", "R$ 1,2M", "R$ 1,5M", "+25%"],
+            ["Usuários ativos", "45.000", "58.000", "+29%"],
+            ["Retenção", "82%", "87%", "+5pp"],
+        ],
+    )
+    story.append(Paragraph(_ptext("Destaques:"), S["body"]))
     for item in [
-        "Revenue growth exceeded targets by 10 percentage points",
-        "User retention improved across all cohorts",
-        "NPS score moved from 'good' to 'excellent' territory",
+        "Crescimento acima da meta em onboarding",
+        "Retenção estável em todas as coortes",
+        "NPS em faixa “excelente”",
     ]:
-        story.append(Paragraph(f"•  {item}", S['bullet']))
+        story.append(Paragraph(f"&bull;&nbsp; {_ptext(item)}", S["bullet"]))
+    callout(
+        story,
+        "Metodologia",
+        "Comparativos homólogos, ajustados por sazonalidade quando aplicável.",
+        "warning",
+    )
 
-    callout(story, "Note", "Growth rates are compared to the same period in the "
-            "prior fiscal year, adjusted for seasonality.", box_type='warning')
+    story.append(PageBreak())
+    section(story, 3, "Conclusão")
+    story.append(
+        Paragraph(
+            _ptext(
+                "Recomenda-se manter as iniciativas em curso e acompanhar CAC com "
+                "corte mensal nos canais de aquisição."
+            ),
+            S["body"],
+        )
+    )
+
+    doc.build(story, onFirstPage=on_first_page, onLaterPages=on_later_pages)
+    print(f"Report generated: {args.output}", file=sys.stderr)
 
-    section(story, 3, "Conclusion")
-    story.append(Paragraph(
-        "The data confirms that the strategic initiatives launched in Q4 2025 "
-        "are delivering measurable results. We recommend continuing the current "
-        "trajectory while monitoring customer acquisition costs closely.",
-        S['body'],
-    ))
 
-    doc.build(story, onFirstPage=lambda c, d: None, onLaterPages=header_footer)
-    print(f"Report generated: {args.output}")
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate professional PDF report (BluMa)")
+    parser.add_argument("--title", default="Relatório")
+    parser.add_argument("--subtitle", default="Documento executivo")
+    parser.add_argument("--output", default="report.pdf")
+    parser.add_argument(
+        "--from-json",
+        dest="from_json",
+        metavar="FILE",
+        help="Build from structured JSON (recommended for real deliverables)",
+    )
+    args = parser.parse_args()
+
+    if args.from_json:
+        path = Path(args.from_json)
+        if not path.is_file():
+            print(f"File not found: {path}", file=sys.stderr)
+            sys.exit(1)
+        data = json.loads(path.read_text(encoding="utf-8"))
+        build_from_json(data, args.output)
+    else:
+        demo_report(args)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()