@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/skills/pdf/scripts/render.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""Render an office file (or PDF) to page/slide PNGs so you can LOOK at the result.
+
+Usage:
+  python3 render.py FILE [--outdir DIR] [--dpi 110] [--pages 1-3] [--pdf-only]
+
+FILE may be .docx/.doc/.pptx/.ppt/.xlsx/.xls/.odt/.odp/.ods/.rtf/.csv or .pdf.
+Office files are converted to PDF with LibreOffice (soffice) in an isolated,
+throw-away user profile (so a running LibreOffice or a stale lock never hangs
+the conversion), then split into PNGs with pdftoppm, or pypdfium2 if poppler
+is missing.
+
+Prints JSON:
+  {"rendered": true, "pdf": "DIR/name.pdf", "pages": N, "files": ["DIR/name-01.png", ...]}
+  {"rendered": false, "missing": [...], "install": "..."}   (exit 0, nothing rendered)
+Exit 1 only when a tool was present but the conversion itself failed.
+
+This file is shared verbatim by the docx, pptx, xlsx and pdf skills.
+"""
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+
+OFFICE_EXT = {".docx", ".doc", ".dotx", ".pptx", ".ppt", ".potx", ".xlsx", ".xlsm", ".xls",
+              ".odt", ".odp", ".ods", ".rtf", ".csv"}
+
+
+def find_soffice() -> str | None:
+    override = os.environ.get("SOFFICE")
+    if override is not None:  # explicit path, or "" to mean "no LibreOffice"
+        return override if override and os.path.exists(override) else None
+    for name in ("soffice", "libreoffice"):
+        p = shutil.which(name)
+        if p:
+            return p
+    for p in ("/Applications/LibreOffice.app/Contents/MacOS/soffice",
+              r"C:\Program Files\LibreOffice\program\soffice.exe",
+              r"C:\Program Files (x86)\LibreOffice\program\soffice.exe",
+              "/usr/lib/libreoffice/program/soffice", "/opt/libreoffice/program/soffice"):
+        if os.path.exists(p):
+            return p
+    return None
+
+
+def install_hint(missing: list[str]) -> str:
+    sysname = platform.system()
+    tips = []
+    if "soffice" in missing:
+        tips.append({"Darwin": "brew install --cask libreoffice (or download from libreoffice.org)",
+                     "Linux": "sudo apt-get install -y libreoffice-core libreoffice-writer libreoffice-calc libreoffice-impress",
+                     "Windows": "winget install TheDocumentFoundation.LibreOffice"}.get(sysname, "install LibreOffice"))
+    if "pdftoppm" in missing:
+        tips.append({"Darwin": "brew install poppler", "Linux": "sudo apt-get install -y poppler-utils",
+                     "Windows": "pip install pypdfium2"}.get(sysname, "pip install pypdfium2"))
+    return "; ".join(tips)
+
+
+# Windows/Office CJK font names -> fonts that actually exist on this machine, so the
+# preview shows real glyphs with similar metrics instead of empty boxes. Only the
+# throw-away LibreOffice profile used for rendering is changed; the document is not.
+CJK_SUBSTITUTES = {
+    "Darwin": {
+        "SimSun": "Songti SC", "宋体": "Songti SC", "NSimSun": "Songti SC", "SimSun-ExtB": "Songti SC",
+        "SimHei": "Heiti SC", "黑体": "Heiti SC", "Microsoft YaHei": "Hiragino Sans GB",
+        "微软雅黑": "Hiragino Sans GB", "Microsoft JhengHei": "Heiti TC", "PMingLiU": "Songti TC",
+        "FangSong": "STFangsong", "FangSong_GB2312": "STFangsong", "仿宋": "STFangsong", "仿宋_GB2312": "STFangsong",
+        "KaiTi": "Kaiti SC", "KaiTi_GB2312": "Kaiti SC", "楷体": "Kaiti SC", "楷体_GB2312": "Kaiti SC",
+        "DengXian": "Hiragino Sans GB", "等线": "Hiragino Sans GB",
+        "FZXiaoBiaoSong-B05S": "Songti SC", "方正小标宋简体": "Songti SC",
+    },
+    "Linux": {k: v for k, v in (
+        ("SimSun", "Noto Serif CJK SC"), ("宋体", "Noto Serif CJK SC"), ("NSimSun", "Noto Serif CJK SC"),
+        ("SimHei", "Noto Sans CJK SC"), ("黑体", "Noto Sans CJK SC"), ("Microsoft YaHei", "Noto Sans CJK SC"),
+        ("微软雅黑", "Noto Sans CJK SC"), ("FangSong", "Noto Serif CJK SC"), ("FangSong_GB2312", "Noto Serif CJK SC"),
+        ("KaiTi", "Noto Serif CJK SC"), ("KaiTi_GB2312", "Noto Serif CJK SC"), ("DengXian", "Noto Sans CJK SC"),
+        ("FZXiaoBiaoSong-B05S", "Noto Serif CJK SC"))},
+}
+
+
+SYSTEM_CJK_FONT_FILES = [
+    # LibreOffice on macOS does not see these system fonts; link them into the profile so CJK renders.
+    "/System/Library/Fonts/Hiragino Sans GB.ttc", "/System/Library/Fonts/STHeiti Medium.ttc",
+    "/System/Library/Fonts/STHeiti Light.ttc", "/System/Library/Fonts/Supplemental/Songti.ttc",
+    "/System/Library/Fonts/PingFang.ttc", "/System/Library/Fonts/Supplemental/Kaiti.ttc",
+    "/System/Library/Fonts/Supplemental/STFangsong.ttf", "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",
+]
+
+
+def write_profile(prof: str) -> None:
+    fonts_dir = os.path.join(prof, "user", "fonts")
+    os.makedirs(fonts_dir, exist_ok=True)
+    for f in SYSTEM_CJK_FONT_FILES:
+        if os.path.exists(f):
+            try:
+                os.symlink(f, os.path.join(fonts_dir, os.path.basename(f)))
+            except OSError:
+                shutil.copy(f, fonts_dir)
+    pairs = CJK_SUBSTITUTES.get(platform.system())
+    if not pairs:
+        return  # Windows has the real fonts
+    from xml.sax.saxutils import quoteattr
+    nodes = "".join(
+        f'<item oor:path="/org.openoffice.VCL/FontSubstitutions"><node oor:name={quoteattr("p" + str(i))} oor:op="replace">'
+        f'<prop oor:name="ReplaceFont"><value>{src}</value></prop>'
+        f'<prop oor:name="SubstituteFont"><value>{dst}</value></prop>'
+        f'<prop oor:name="Always"><value>true</value></prop>'
+        f'<prop oor:name="OnScreenOnly"><value>false</value></prop></node></item>'
+        for i, (src, dst) in enumerate(pairs.items()))
+    nodes += ('<item oor:path="/org.openoffice.VCL"><prop oor:name="FontSubstitutionsEnabled" oor:op="fuse">'
+              '<value>true</value></prop></item>'
+              '<item oor:path="/org.openoffice.Office.Common/Font/Substitution"><prop oor:name="Replacement" oor:op="fuse">'
+              '<value>true</value></prop></item>'
+              '<item oor:path="/org.openoffice.Office.Common/Font/Substitution"><prop oor:name="FontPairs" oor:op="fuse">'
+              '<value>' + "".join(
+                  f'<it><prop oor:name="Always"><value>true</value></prop>'
+                  f'<prop oor:name="OnScreenOnly"><value>false</value></prop>'
+                  f'<prop oor:name="ReplaceFont"><value>{s}</value></prop>'
+                  f'<prop oor:name="SubstituteFont"><value>{d}</value></prop></it>'
+                  for s, d in pairs.items()) + '</value></prop></item>')
+    os.makedirs(os.path.join(prof, "user"), exist_ok=True)
+    with open(os.path.join(prof, "user", "registrymodifications.xcu"), "w", encoding="utf-8") as f:
+        f.write('<?xml version="1.0" encoding="UTF-8"?>\n<oor:items xmlns:oor="http://openoffice.org/2001/registry" '
+                'xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">'
+                + nodes + '</oor:items>\n')
+
+
+def to_pdf(src: str, outdir: str, timeout: int) -> str:
+    soffice = find_soffice()
+    if not soffice:
+        raise LookupError("soffice")
+    with tempfile.TemporaryDirectory(prefix="lo-profile-") as prof:
+        write_profile(prof)
+        profile_url = "file:///" + prof.replace("\\", "/").lstrip("/")
+        cmd = [soffice, f"-env:UserInstallation={profile_url}", "--headless", "--norestore",
+               "--nolockcheck", "--convert-to", "pdf", "--outdir", outdir, src]
+        proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8",
+                              errors="replace", timeout=timeout, check=False)
+    pdf = os.path.join(outdir, os.path.splitext(os.path.basename(src))[0] + ".pdf")
+    if proc.returncode != 0 or not os.path.exists(pdf):
+        raise RuntimeError(f"soffice conversion failed (rc={proc.returncode}): {proc.stderr.strip() or proc.stdout.strip()}")
+    return pdf
+
+
+def parse_pages(spec: str | None, n: int) -> list[int]:
+    if not spec:
+        return list(range(1, n + 1))
+    out: list[int] = []
+    for part in spec.split(","):
+        a, _, b = part.partition("-")
+        lo, hi = int(a), int(b or a)
+        out += [p for p in range(lo, hi + 1) if 1 <= p <= n]
+    return out
+
+
+def pdf_pages(pdf: str) -> int:
+    try:
+        from pypdf import PdfReader
+        return len(PdfReader(pdf).pages)
+    except Exception:
+        info = shutil.which("pdfinfo")
+        if info:
+            r = subprocess.run([info, pdf], capture_output=True, text=True, check=False)
+            for line in r.stdout.splitlines():
+                if line.startswith("Pages:"):
+                    return int(line.split()[1])
+    return 0
+
+
+def rasterize(pdf: str, outdir: str, stem: str, dpi: int, pages: list[int]) -> list[str]:
+    width = max(2, len(str(max(pages) if pages else 1)))
+    files = []
+    tool = shutil.which("pdftoppm")
+    if tool:
+        for p in pages:
+            prefix = os.path.join(outdir, f"{stem}-{p:0{width}d}")
+            subprocess.run([tool, "-png", "-r", str(dpi), "-f", str(p), "-l", str(p), "-singlefile", pdf, prefix],
+                           check=True, capture_output=True)
+            files.append(prefix + ".png")
+        return files
+    import pypdfium2 as pdfium  # raises ImportError -> reported as missing
+    doc = pdfium.PdfDocument(pdf)
+    for p in pages:
+        img = doc[p - 1].render(scale=dpi / 72).to_pil()
+        path = os.path.join(outdir, f"{stem}-{p:0{width}d}.png")
+        img.save(path)
+        files.append(path)
+    return files
+
+
+def main(argv=None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0],
+                                 epilog=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("file")
+    ap.add_argument("--outdir", default=None, help="default: <file dir>/render")
+    ap.add_argument("--dpi", type=int, default=110)
+    ap.add_argument("--pages", default=None, help="e.g. 1-3,7 (default: all)")
+    ap.add_argument("--pdf-only", action="store_true", help="convert to PDF, skip PNGs")
+    ap.add_argument("--timeout", type=int, default=240)
+    a = ap.parse_args(argv)
+
+    src = os.path.abspath(a.file)
+    outdir = os.path.abspath(a.outdir or os.path.join(os.path.dirname(src), "render"))
+    os.makedirs(outdir, exist_ok=True)
+    stem = os.path.splitext(os.path.basename(src))[0]
+    ext = os.path.splitext(src)[1].lower()
+    missing: list[str] = []
+    try:
+        if ext == ".pdf":
+            pdf = src
+        elif ext in OFFICE_EXT:
+            pdf = to_pdf(src, outdir, a.timeout)
+        else:
+            print(json.dumps({"rendered": False, "error": f"unsupported file type {ext}"}))
+            return 1
+    except LookupError:
+        missing.append("soffice")
+    except (RuntimeError, subprocess.TimeoutExpired) as e:
+        print(json.dumps({"rendered": False, "error": str(e)}, ensure_ascii=False))
+        return 1
+    if missing:
+        print(json.dumps({"rendered": False, "missing": missing, "install": install_hint(missing)}, ensure_ascii=False))
+        return 0
+    n = pdf_pages(pdf)
+    if a.pdf_only:
+        print(json.dumps({"rendered": True, "pdf": pdf, "pages": n, "files": []}, ensure_ascii=False))
+        return 0
+    try:
+        for old in glob.glob(os.path.join(outdir, f"{stem}-*.png")):
+            os.remove(old)
+        files = rasterize(pdf, outdir, stem, a.dpi, parse_pages(a.pages, n))
+    except ImportError:
+        print(json.dumps({"rendered": False, "pdf": pdf, "missing": ["pdftoppm"],
+                          "install": install_hint(["pdftoppm"])}, ensure_ascii=False))
+        return 0
+    print(json.dumps({"rendered": True, "pdf": pdf, "pages": n, "files": files}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pdf/tests/test_pdf_skill.py

@@ -0,0 +1,415 @@
+"""End-to-end tests for the pdf skill helper scripts. No network required."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS = Path(__file__).resolve().parent.parent / "scripts"
+
+
+def run(script: str, *args: str, expect: int = 0) -> subprocess.CompletedProcess:
+    env = dict(os.environ, LC_ALL="C", LANG="C", PYTHONIOENCODING="utf-8")
+    proc = subprocess.run(
+        [sys.executable, str(SCRIPTS / script), *args],
+        capture_output=True, text=True, encoding="utf-8", env=env,
+        check=False,
+    )
+    assert proc.returncode == expect, f"{script} {args}: rc={proc.returncode}\n{proc.stderr}"
+    return proc
+
+
+@pytest.fixture(scope="module")
+def workdir(tmp_path_factory) -> Path:
+    return tmp_path_factory.mktemp("pdfwork")
+
+
+@pytest.fixture(scope="module")
+def sample_image(workdir: Path) -> Path:
+    from PIL import Image
+    img_path = workdir / "sample.png"
+    img = Image.new("RGB", (120, 80), (30, 120, 200))
+    img.save(img_path)
+    return img_path
+
+
+@pytest.fixture(scope="module")
+def report_pdf(workdir: Path, sample_image: Path) -> Path:
+    spec = {
+        "title": "Quarterly Example Report",
+        "author": "example-author",
+        "elements": [
+            {"type": "heading", "text": "Quarterly Example Report", "level": 1},
+            {"type": "paragraph", "text": "This is the introduction paragraph with a marker UNIQUEMARK42."},
+            {"type": "table", "rows": [["Region", "Units"], ["North", "1250"], ["South", "980"]], "header": True},
+            {"type": "image", "path": str(sample_image), "width": 200},
+            {"type": "pagebreak"},
+            {"type": "heading", "text": "Appendix", "level": 2},
+            {"type": "paragraph", "text": "Second page content."},
+        ],
+    }
+    spec_path = workdir / "spec.json"
+    spec_path.write_text(json.dumps(spec), encoding="utf-8")
+    out = workdir / "report.pdf"
+    run("pdf_create.py", str(spec_path), "-o", str(out))
+    assert out.exists() and out.stat().st_size > 500
+    return out
+
+
+def test_create_and_meta(report_pdf: Path):
+    meta = json.loads(run("pdf_read.py", str(report_pdf), "--meta").stdout)
+    assert meta["page_count"] == 2
+    assert meta["encrypted"] is False
+    assert meta["likely_scanned_pages"] == []
+    assert "Quarterly Example Report" in meta["metadata"].get("Title", "")
+
+
+def test_extract_text(report_pdf: Path):
+    data = json.loads(run("pdf_read.py", str(report_pdf), "--text").stdout)
+    assert data["page_count"] == 2
+    assert "UNIQUEMARK42" in data["pages"][0]
+    assert "Appendix" in data["pages"][1]
+    assert "Page 1" in data["pages"][0]  # page number footer
+
+
+def test_extract_tables(report_pdf: Path, workdir: Path):
+    csv_dir = workdir / "csvs"
+    data = json.loads(run("pdf_read.py", str(report_pdf), "--tables",
+                          "--csv-dir", str(csv_dir)).stdout)
+    assert data["table_count"] >= 1
+    rows = data["tables"][0]["rows"]
+    assert rows[0] == ["Region", "Units"]
+    assert ["North", "1250"] in rows
+    csv_files = list(csv_dir.glob("*.csv"))
+    assert csv_files and "Region" in csv_files[0].read_text(encoding="utf-8")
+
+
+@pytest.fixture(scope="module")
+def form_pdf(workdir: Path) -> Path:
+    from reportlab.lib.pagesizes import A4
+    from reportlab.pdfgen import canvas
+    out = workdir / "form.pdf"
+    c = canvas.Canvas(str(out), pagesize=A4)
+    form = c.acroForm
+    c.drawString(72, 760, "Example Form")
+    form.textfield(name="surname", x=72, y=700, width=300, height=20, value="")
+    form.checkbox(name="agree", x=72, y=660, buttonStyle="check")
+    form.radio(name="color", value="red", x=72, y=620, selected=False)
+    form.radio(name="color", value="blue", x=110, y=620, selected=True)
+    form.choice(name="size", x=72, y=580, width=120, height=20,
+                options=["small", "large"], value="small")
+    c.save()
+    return out
+
+
+def test_form_fill_unicode_roundtrip(form_pdf: Path, workdir: Path):
+    surname = "Фамилия — ‘test’"
+    values = {"surname": surname, "agree": True, "color": "/red", "size": "large"}
+    fields_json = workdir / "values.json"
+    fields_json.write_text(json.dumps(values, ensure_ascii=False), encoding="utf-8")
+    filled = workdir / "filled.pdf"
+    run("pdf_fill_form.py", str(form_pdf), "--fields-json", str(fields_json),
+        "-o", str(filled))
+    data = json.loads(run("pdf_read.py", str(filled), "--fields").stdout)
+    fields = data["fields"]
+    assert fields["surname"]["value"] == surname
+    assert fields["agree"]["value"] in ("/Yes", "/On", "True", "/1")
+    assert fields["color"]["value"] == "/red"
+    assert fields["size"]["value"] == "large"
+
+
+def test_merge_split_rotate(report_pdf: Path, workdir: Path):
+    merged = workdir / "merged.pdf"
+    out = json.loads(run("pdf_merge.py", str(report_pdf), str(report_pdf),
+                         "-o", str(merged), "--bookmarks").stdout)
+    assert out["page_count"] == 4
+
+    part = workdir / "part.pdf"
+    out = json.loads(run("pdf_split.py", str(merged), "--pages", "2-3",
+                         "--rotate", "90", "-o", str(part)).stdout)
+    assert out["page_count"] == 2
+    meta = json.loads(run("pdf_read.py", str(part), "--meta").stdout)
+    assert meta["page_count"] == 2
+    assert all(p["rotation"] % 360 == 90 for p in meta["pages"])
+
+
+def test_watermark(report_pdf: Path, workdir: Path):
+    # Build the stamp at mid-page so its text does not overlap existing
+    # headings (overlapping glyphs confuse text extraction).
+    from reportlab.lib.pagesizes import A4
+    from reportlab.pdfgen import canvas
+    stamp = workdir / "stamp.pdf"
+    c = canvas.Canvas(str(stamp), pagesize=A4)
+    c.setFont("Helvetica", 40)
+    c.drawString(200, 400, "DRAFT")
+    c.save()
+    stamped = workdir / "stamped.pdf"
+    run("pdf_watermark.py", str(report_pdf), "--stamp", str(stamp), "-o", str(stamped))
+    data = json.loads(run("pdf_read.py", str(stamped), "--text").stdout)
+    assert all("DRAFT" in page for page in data["pages"])
+
+
+def test_encrypt_decrypt_roundtrip(report_pdf: Path, workdir: Path):
+    enc = workdir / "enc.pdf"
+    run("pdf_secure.py", str(report_pdf), "--encrypt", "-o", str(enc),
+        "--user-password", "your-password")
+    meta = json.loads(run("pdf_read.py", str(enc), "--meta").stdout)
+    assert meta["encrypted"] is True
+
+    dec = workdir / "dec.pdf"
+    run("pdf_secure.py", str(enc), "--decrypt", "-o", str(dec),
+        "--password", "your-password")
+    data = json.loads(run("pdf_read.py", str(dec), "--text").stdout)
+    assert "UNIQUEMARK42" in data["pages"][0]
+
+
+def test_compress(report_pdf: Path, workdir: Path):
+    out = workdir / "compressed.pdf"
+    run("pdf_split.py", str(report_pdf), "--pages", "1-2", "--compress", "-o", str(out))
+    data = json.loads(run("pdf_read.py", str(out), "--text").stdout)
+    assert "UNIQUEMARK42" in data["pages"][0]
+
+
+# ---------------------------------------------------------------- form creation
+
+FORM_SPEC = {
+    "title": "Example Intake Form",
+    "page_size": "A4",
+    "fields": [
+        {"name": "surname", "type": "text", "page": 1, "label": "Surname",
+         "label_box": [72, 700, 150, 714], "entry_box": [160, 696, 400, 716]},
+        {"name": "agree", "type": "checkbox", "page": 1, "label": "I agree",
+         "label_box": [72, 660, 150, 674], "entry_box": [160, 658, 176, 674]},
+        {"name": "color", "type": "radio", "page": 1, "label": "Color",
+         "label_box": [72, 620, 150, 634], "entry_box": [160, 616, 400, 636],
+         "options": ["red", "blue"], "value": "blue"},
+        {"name": "size", "type": "dropdown", "page": 1, "label": "Size",
+         "label_box": [72, 580, 150, 594], "entry_box": [160, 576, 300, 596],
+         "options": ["small", "large"], "value": "small"},
+    ],
+}
+
+
+@pytest.fixture(scope="module")
+def built_form(workdir: Path) -> Path:
+    spec_path = workdir / "formspec.json"
+    spec_path.write_text(json.dumps(FORM_SPEC), encoding="utf-8")
+    out = workdir / "built_form.pdf"
+    result = json.loads(run("pdf_make_form.py", str(spec_path), "-o", str(out)).stdout)
+    assert len(result["fields"]) == 4
+    return out
+
+
+def test_make_form_lists_all_fields(built_form: Path):
+    data = json.loads(run("pdf_read.py", str(built_form), "--fields").stdout)
+    fields = data["fields"]
+    assert set(fields) == {"surname", "agree", "color", "size"}
+    assert fields["surname"]["type"] == "text"
+    assert fields["agree"]["options"] == ["/Off", "/Yes"]
+    assert fields["color"]["value"] == "/blue"  # pre-selected radio
+    assert set(fields["size"]["options"]) == {"small", "large"}
+    # label text is drawn on the page, not just stored in the widget
+    text = json.loads(run("pdf_read.py", str(built_form), "--text").stdout)
+    assert "Surname" in text["pages"][0] and "Size" in text["pages"][0]
+
+
+def test_make_form_fill_roundtrip(built_form: Path, workdir: Path):
+    values = {"surname": "Smith", "agree": True, "color": "/red", "size": "large"}
+    vals = workdir / "builtvals.json"
+    vals.write_text(json.dumps(values), encoding="utf-8")
+    filled = workdir / "built_filled.pdf"
+    run("pdf_fill_form.py", str(built_form), "--fields-json", str(vals), "-o", str(filled))
+    fields = json.loads(run("pdf_read.py", str(filled), "--fields").stdout)["fields"]
+    assert fields["surname"]["value"] == "Smith"
+    assert fields["agree"]["value"] == "/Yes"
+    assert fields["color"]["value"] == "/red"
+    assert fields["size"]["value"] == "large"
+
+
+# ------------------------------------------------------------- layout validation
+
+def test_form_layout_valid_spec(workdir: Path):
+    spec_path = workdir / "layout_ok.json"
+    spec_path.write_text(json.dumps(FORM_SPEC), encoding="utf-8")
+    report = json.loads(run("pdf_form_layout.py", str(spec_path)).stdout)
+    assert report["ok"] is True
+    assert report["errors"] == 0
+    assert all(f["ok"] for f in report["fields"])
+
+
+def test_form_layout_detects_problems(workdir: Path):
+    bad = {
+        "page_size": "A4",
+        "fields": [
+            # out of bounds (x1 beyond A4 width)
+            {"name": "wide", "type": "text", "page": 1, "label": "Wide",
+             "label_box": [10, 700, 60, 714], "entry_box": [70, 696, 900, 716]},
+            # two overlapping entry boxes
+            {"name": "one", "type": "text", "page": 1, "label": "One",
+             "label_box": [10, 600, 60, 614], "entry_box": [70, 596, 300, 616]},
+            {"name": "two", "type": "text", "page": 1, "label": "Two",
+             "label_box": [10, 560, 60, 574], "entry_box": [200, 600, 400, 620]},
+            # label far away from its entry
+            {"name": "lost", "type": "text", "page": 1, "label": "Lost",
+             "label_box": [10, 100, 60, 114], "entry_box": [400, 500, 500, 520]},
+            # too small
+            {"name": "tiny", "type": "text", "page": 1,
+             "entry_box": [10, 50, 14, 54]},
+        ],
+    }
+    spec_path = workdir / "layout_bad.json"
+    spec_path.write_text(json.dumps(bad), encoding="utf-8")
+    proc = run("pdf_form_layout.py", str(spec_path), expect=1)
+    report = json.loads(proc.stdout)
+    assert report["ok"] is False
+    by_name = {f["name"]: f for f in report["fields"]}
+    assert any("bounds" in p for p in by_name["wide"]["problems"])
+    assert any("overlaps field" in p for p in by_name["two"]["problems"])
+    assert any("from its entry" in p for p in by_name["lost"]["problems"])
+    assert any("minimum size" in p for p in by_name["tiny"]["problems"])
+    assert by_name["one"]["ok"]  # first of the overlapping pair reports clean
+
+
+# ------------------------------------------------- rasterization (overlay, pages)
+
+def _raster_available() -> bool:
+    import shutil
+    try:
+        import pypdfium2
+        return True
+    except ImportError:
+        return shutil.which("pdftoppm") is not None
+
+
+def test_form_layout_overlay(built_form: Path, workdir: Path):
+    spec_path = workdir / "formspec.json"
+    out_png = workdir / "overlay.png"
+    report = json.loads(run("pdf_form_layout.py", str(spec_path), "--pdf", str(built_form),
+                            "--render-overlay", str(out_png)).stdout)
+    overlay = report["overlay"]
+    if _raster_available():
+        assert overlay["rendered"] is True
+        assert out_png.exists() and out_png.stat().st_size > 1000
+        from PIL import Image
+        with Image.open(out_png) as img:
+            assert img.width > 100 and img.height > 100
+    else:
+        assert overlay["rendered"] is False
+        assert overlay["missing"]  # install hints present
+
+
+def test_form_layout_overlay_blank_page(workdir: Path):
+    # No --pdf: overlay is drawn on a blank page, PIL-only, always renders.
+    spec_path = workdir / "formspec.json"
+    out_png = workdir / "overlay_blank.png"
+    report = json.loads(run("pdf_form_layout.py", str(spec_path),
+                            "--render-overlay", str(out_png)).stdout)
+    assert report["overlay"]["rendered"] is True
+    assert out_png.exists()
+
+
+def test_page_image_export(report_pdf: Path, workdir: Path):
+    out_dir = workdir / "pageimgs"
+    result = json.loads(run("pdf_page_image.py", str(report_pdf), "--pages", "1-2",
+                            "--dpi", "72", "--out-dir", str(out_dir)).stdout)
+    if _raster_available():
+        assert result["rendered"] is True
+        assert len(result["files"]) == 2
+        from PIL import Image
+        with Image.open(result["files"][0]) as img:
+            # A4 at 72 dpi is ~595x842 px
+            assert 500 < img.width < 700
+    else:
+        assert result["rendered"] is False
+        assert result["missing"]
+
+
+def test_page_image_bad_range(report_pdf: Path, workdir: Path):
+    if not _raster_available():
+        pytest.skip("no rasterizer available")
+    run("pdf_page_image.py", str(report_pdf), "--pages", "9",
+        "--out-dir", str(workdir / "nope"), expect=4)
+
+
+# --------------------------------------------------------------------- stamping
+
+def test_stamp_text(report_pdf: Path, workdir: Path):
+    out = workdir / "stamp_text.pdf"
+    run("pdf_stamp.py", str(report_pdf), "-o", str(out),
+        "--text", "STAMPMARK77", "--x", "150", "--y", "500",
+        "--font-size", "30", "--color", "#cc0000", "--pages", "1")
+    data = json.loads(run("pdf_read.py", str(out), "--text").stdout)
+    assert "STAMPMARK77" in data["pages"][0]
+    assert "STAMPMARK77" not in data["pages"][1]  # only page 1 stamped
+
+
+def test_stamp_text_rotated_opacity(report_pdf: Path, workdir: Path):
+    out = workdir / "stamp_rot.pdf"
+    run("pdf_stamp.py", str(report_pdf), "-o", str(out),
+        "--text", "DRAFT", "--x", "150", "--y", "400", "--font-size", "60",
+        "--rotation", "45", "--opacity", "0.3")
+    # Rotated glyphs confuse pdfplumber's line grouping; verify via pypdf.
+    from pypdf import PdfReader
+    text = PdfReader(str(out)).pages[0].extract_text()
+    assert "DRAFT" in text
+
+
+def test_stamp_image(report_pdf: Path, sample_image: Path, workdir: Path):
+    out = workdir / "stamp_img.pdf"
+    run("pdf_stamp.py", str(report_pdf), "-o", str(out),
+        "--image", str(sample_image), "--x", "400", "--y", "60",
+        "--width", "100", "--pages", "2")
+    from pypdf import PdfReader
+    before = PdfReader(str(report_pdf))
+    after = PdfReader(str(out))
+
+    def image_xobjects(page):
+        res = page.get("/Resources", {})
+        xo = res.get("/XObject")
+        if xo is None:
+            return 0
+        return sum(1 for k in xo if xo[k].get("/Subtype") == "/Image")
+
+    assert image_xobjects(after.pages[1]) > image_xobjects(before.pages[1])
+    assert image_xobjects(after.pages[0]) == image_xobjects(before.pages[0])
+
+
+# --------------------------------------------------------- metadata + attachments
+
+def test_meta_set_and_clear(report_pdf: Path, workdir: Path):
+    out = workdir / "meta_set.pdf"
+    run("pdf_meta.py", str(report_pdf), "--set-meta", "-o", str(out),
+        "--title", "Retitled Example", "--author", "example-author",
+        "--subject", "Testing", "--keywords", "alpha, beta")
+    meta = json.loads(run("pdf_read.py", str(out), "--meta").stdout)["metadata"]
+    assert meta["Title"] == "Retitled Example"
+    assert meta["Author"] == "example-author"
+    assert meta["Subject"] == "Testing"
+    assert meta["Keywords"] == "alpha, beta"
+
+    cleared = workdir / "meta_clear.pdf"
+    run("pdf_meta.py", str(out), "--clear-meta", "-o", str(cleared))
+    meta = json.loads(run("pdf_read.py", str(cleared), "--meta").stdout)["metadata"]
+    assert "Title" not in meta or meta.get("Title") in ("", None)
+
+
+def test_attachments_roundtrip(report_pdf: Path, workdir: Path):
+    payload = workdir / "payload.txt"
+    payload.write_text("attachment payload UNIQUEATTACH99\n", encoding="utf-8")
+    with_att = workdir / "with_att.pdf"
+    run("pdf_meta.py", str(report_pdf), "--attach", str(payload), "-o", str(with_att))
+
+    listing = json.loads(run("pdf_meta.py", str(with_att), "--list-attachments").stdout)
+    assert listing["attachment_count"] == 1
+    assert listing["attachments"] == ["payload.txt"]
+
+    ext_dir = workdir / "extracted"
+    result = json.loads(run("pdf_meta.py", str(with_att),
+                            "--extract-attachments", str(ext_dir)).stdout)
+    assert len(result["extracted"]) == 1
+    extracted = Path(result["extracted"][0])
+    assert "UNIQUEATTACH99" in extracted.read_text(encoding="utf-8")