@research-copilot/plugin 1.1.16 → 1.1.18

package/dist/skills/paper-poster-html/scripts/poster_check.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""poster_check — unified CLI for HTML academic posters.
+
+Four subcommands:
+
+  measure        Print-emulate HTML in headless Chromium, measure all
+                 ``[data-measure-role]`` elements, report column-bottom
+                 spread and gap to the next horizontal strip. The HARD
+                 alignment gate (spread < 5 px is non-negotiable).
+  preflight      Static HTML scan: LaTeX residue, raw '<' inside
+                 ``$…$`` / ``$$…$$`` / ``\\(…\\)`` / ``\\[…\\]``,
+                 missing local images, missing data-measure-role.
+  polish         Visual-polish warnings on figure sizing, broken
+                 images, typography orphans, and space-between fill.
+                 Soft gate; warns by default. ``--strict`` to fail.
+                 Hard-fails if there's no measurement markup at all.
+  verify-final   Run ``pdfinfo`` on a rendered PDF; check page count,
+                 dimensions match the expected canvas (``--canvas`` or
+                 ``--from-html``), and file size under a limit.
+
+All logic lives in the ``_posterly`` package next to this file. This
+script is a thin argparse dispatcher.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+# Make `_posterly` importable when this file is run directly via
+# `python tools/poster_check.py …`.
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _THIS_DIR not in sys.path:
+    sys.path.insert(0, _THIS_DIR)
+
+from _posterly import canvas as _canvas  # noqa: E402
+from _posterly import measure as _measure  # noqa: E402
+from _posterly import polish as _polish  # noqa: E402
+from _posterly import preflight as _preflight  # noqa: E402
+from _posterly import verify_final as _verify_final  # noqa: E402
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="poster_check",
+        description="Measure / preflight / polish / verify a poster "
+                    "HTML+PDF pair.",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # --- measure --------------------------------------------------------
+    pm = sub.add_parser(
+        "measure",
+        help="alignment + gap gate (print-emulated, HARD gate)",
+    )
+    pm.add_argument("html", help="path to poster.html")
+    pm.add_argument(
+        "--max-spread", type=float, default=5.0,
+        help="hard gate: max column-bottom spread in px "
+             "(default 5.0; aim < 3.0)",
+    )
+    pm.add_argument(
+        "--min-gap", type=float, default=30.0,
+        help="min gap to footer-strip/footer (default 30 px)",
+    )
+    pm.add_argument(
+        "--max-gap", type=float, default=50.0,
+        help="max gap to footer-strip/footer (default 50 px)",
+    )
+    pm.add_argument(
+        "--canvas", type=_canvas.parse_canvas_arg, default=None,
+        help="override canvas (e.g. '60x36in' or 'A0 portrait'); "
+             "by default we parse @page from the HTML",
+    )
+    pm.add_argument(
+        "--allow-empty-column", action="store_true",
+        help="don't fail when a column has no cards "
+             "(fallback to column.bottom; risky)",
+    )
+    pm.add_argument(
+        "--allow-no-footer-gap", action="store_true",
+        help="don't fail when neither footer-strip nor footer exists "
+             "below the content",
+    )
+    pm.add_argument(
+        "--settle-ms", type=int, default=500,
+        help="extra wait after MathJax + fonts.ready settle "
+             "(default 500)",
+    )
+    pm.add_argument(
+        "--mathjax-timeout-ms", type=int, default=15000,
+        help="hard timeout for MathJax typeset (default 15000); "
+             "exceeding it FAILS the gate, not warns",
+    )
+    pm.add_argument(
+        "--min-canvas-fill", type=float, default=0.95,
+        help="hard gate: [data-measure-role='poster'] must fill at "
+             "least this fraction of the print viewport in BOTH "
+             "dimensions (default 0.95). Catches the silent 'forgot "
+             "the print media-query unit override' bug where the "
+             "poster renders at screen scale into a much bigger "
+             "print page.",
+    )
+    pm.add_argument(
+        "--max-canvas-fill", type=float, default=1.01,
+        help="hard gate: poster must NOT exceed this fraction of the "
+             "print viewport (default 1.01; i.e. <=1%% overshoot is "
+             "tolerated for sub-pixel rounding). The symmetric of "
+             "--min-canvas-fill catches the case where a hardcoded "
+             "`width` in px exceeds `@page size`.",
+    )
+    pm.add_argument(
+        "--position-tol-px", type=float, default=2.0,
+        help="hard gate: poster's bbox edges must align with the print "
+             "viewport's origin within this many px (default 2.0). "
+             "Catches `transform: translate*`, mis-positioned absolute "
+             "layout, and stray body margin in print.",
+    )
+    pm.add_argument(
+        "--max-clip-px", type=float, default=2.0,
+        help="hard gate: a card/column/hero whose content is clipped by "
+             "overflow:hidden|clip|scroll|auto by MORE than this many px "
+             "(scrollHeight-clientHeight) FAILS -- clipped content is "
+             "silently lost in print while the box still looks aligned "
+             "(default 2.0; sub-pixel rounding tolerated).",
+    )
+    pm.add_argument(
+        "--max-intercard-gap", type=float,
+        default=_measure.DEFAULT_MAX_INTERCARD_GAP,
+        help="hard gate: max whitespace between consecutive stacked "
+             "cards in a column (default 50 px, same ceiling as the "
+             "footer gap). Catches `justify-content: space-between` "
+             "faking bottom alignment on an under-filled column -- "
+             "spread reads ~0 while a void sits mid-column.",
+    )
+    pm.add_argument(
+        "--min-intercard-gap", type=float,
+        default=_measure.DEFAULT_MIN_INTERCARD_GAP,
+        help="hard gate: min whitespace between consecutive stacked "
+             "cards (default 12 px). Tighter gaps bury the card's drop "
+             "shadow (templates ship `0 2u 6u`) under the next card, "
+             "fusing the stack into one slab. Set 0 to disable for "
+             "shadowless themes.",
+    )
+    pm.add_argument(
+        "--json-out", default=None,
+        help="dump raw measurement to JSON",
+    )
+    pm.set_defaults(func=_measure.cmd_measure)
+
+    # --- preflight ------------------------------------------------------
+    pp = sub.add_parser(
+        "preflight",
+        help="static HTML lint (LaTeX residue, math, images, roles)",
+    )
+    pp.add_argument("html", help="path to poster.html")
+    pp.set_defaults(func=_preflight.cmd_preflight)
+
+    # --- polish ---------------------------------------------------------
+    ppl = sub.add_parser(
+        "polish",
+        help="visual-polish warnings (figure size, orphans, "
+             "space-between, flex/<br>)",
+    )
+    ppl.add_argument("html", help="path to poster.html")
+    ppl.add_argument(
+        "--canvas", type=_canvas.parse_canvas_arg, default=None,
+        help="override canvas (default: parse @page from HTML)",
+    )
+    ppl.add_argument(
+        "--settle-ms", type=int, default=500,
+        help="extra wait after layout settles (default 500)",
+    )
+    ppl.add_argument(
+        "--mathjax-timeout-ms", type=int, default=15000,
+        help="hard timeout for MathJax typeset (default 15000)",
+    )
+    ppl.add_argument(
+        "--wide-min-ratio", type=float, default=0.65,
+        help="wide figures (AR>1.3) must occupy >= this fraction of "
+             "card width (default 0.65)",
+    )
+    ppl.add_argument(
+        "--tall-max-ratio", type=float, default=0.70,
+        help="tall figures (AR<0.8) above this fraction trigger a "
+             "text-right recommendation (default 0.70)",
+    )
+    ppl.add_argument(
+        "--square-min-ratio", type=float, default=0.55,
+        help="square figures (0.8<=AR<=1.3) must occupy >= this "
+             "fraction (default 0.55)",
+    )
+    ppl.add_argument(
+        "--max-space-between-fill", type=float, default=0.05,
+        help="warn if a space-between column has an inter-card gap "
+             "exceeding this fraction of column height (default 0.05)",
+    )
+    ppl.add_argument(
+        "--max-card-trailing", type=float, default=0.10,
+        help="warn (CARD/TRAILING) if a card leaves more than this "
+             "fraction of its height blank below the last line "
+             "(default 0.10); catches a flex-stretched card padded "
+             "with whitespace to fake a full page",
+    )
+    ppl.add_argument(
+        "--strict", action="store_true",
+        help="exit non-zero when any warning is emitted",
+    )
+    ppl.set_defaults(func=_polish.cmd_polish)
+
+    # --- verify-final ---------------------------------------------------
+    pv = sub.add_parser(
+        "verify-final",
+        help="run pdfinfo + size/dimension/page checks on PDF",
+    )
+    pv.add_argument("pdf", help="path to poster.pdf")
+    pv.add_argument(
+        "--canvas", type=_canvas.parse_canvas_arg, default=None,
+        help="expected canvas (e.g. '60x36in' or 'A0 portrait'); "
+             "either this or --from-html is required",
+    )
+    pv.add_argument(
+        "--from-html", default=None,
+        help="read expected canvas from `@page { size }` in this "
+             "HTML; mutually exclusive with --canvas",
+    )
+    pv.add_argument(
+        "--dim-tol-in", type=float, default=0.05,
+        help="dimension tolerance in inches (default 0.05)",
+    )
+    pv.add_argument(
+        "--max-size-mb", type=float, default=20.0,
+        help="max file size in MB (default 20)",
+    )
+    pv.add_argument(
+        "--allow-rotated", action="store_true",
+        help="accept swapped W/H even when PDF declares no page "
+             "rotation (most posters should NOT need this)",
+    )
+    pv.set_defaults(func=_verify_final.cmd_verify_final)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/skills/paper-poster-html/scripts/preprocess_figures.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""preprocess_figures -- clean up extracted crops before they go on a poster.
+
+A bbox crop off a PDF page (see ``extract_pdf_figures.py crop``) almost
+always carries a band of near-white page margin: the bbox is read off a
+coordinate grid by eye, so it's deliberately generous. Those margins make
+the figure render small inside its card and trip the asset_check
+"natural >= 1.5x rendered" resolution gate for the WRONG reason (the real
+pixels are fine; they're just padded with whitespace). This script:
+
+  * autocrops the near-white border (PIL ImageChops.difference against a
+    white backdrop, configurable threshold), leaving ``--pad`` px of
+    breathing room so nothing touches the card edge;
+  * reports each image's natural pixel size;
+  * warns when an image is below ``--min-px`` (low-res crops upscale ugly
+    on a printed A0); and
+  * keeps FIGURE_MANIFEST.json honest -- when a crop is modified, its
+    ``natural_px`` and ``sha256`` in the manifest are updated to match,
+    so the sha chain asset_check relies on stays valid.
+
+PIL is imported lazily so ``--help`` works without it and a missing dep
+yields a readable install hint instead of an import traceback.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _THIS_DIR not in sys.path:
+    sys.path.insert(0, _THIS_DIR)
+
+from _posterly.textutil import ascii_safe  # noqa: E402
+
+# Near-white threshold: pixels at/above this in all channels count as
+# "blank margin". 248 (of 255) keeps faint antialiased plot edges while
+# trimming JPEG-ish off-white page background.
+DEFAULT_WHITE_THRESHOLD = 248
+
+
+def _eprint(*args: object, **kw: object) -> None:
+    print(*args, file=sys.stderr, **kw)  # type: ignore[arg-type]
+
+
+def _load_pil():
+    """Import PIL pieces or exit(2) with an actionable message."""
+    try:
+        from PIL import Image, ImageChops  # type: ignore
+        return Image, ImageChops
+    except ImportError:
+        _eprint(
+            "ERROR: Pillow (PIL) not installed -- required for "
+            "preprocess_figures. Install with:\n"
+            "  python -m pip install pillow"
+        )
+        raise SystemExit(2)
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _autocrop_box(img, ImageChops, threshold: int):
+    """Return the bbox of the non-white content, or None if all-white.
+
+    We build a white backdrop the same size, take the absolute per-pixel
+    difference, then threshold to a 1-bit mask whose ``getbbox`` is the
+    tight content box. Using difference-vs-white (rather than scanning for
+    exact 255) tolerates the slightly-off-white background of rasterised
+    PDF pages.
+    """
+    rgb = img.convert("RGB")
+    bg = rgb.point(lambda _p: 255)            # solid white, same size/mode
+    diff = ImageChops.difference(rgb, bg)
+    # Map "close to white" (diff small) -> 0, content -> 255.
+    cutoff = 255 - threshold                   # e.g. threshold 248 -> 7
+    mask = diff.convert("L").point(
+        lambda p: 255 if p > cutoff else 0)
+    return mask.getbbox()
+
+
+def _apply_pad(box, pad: int, size):
+    """Expand a (l,t,r,b) box by ``pad`` px, clamped to image size."""
+    w, h = size
+    l, t, r, b = box
+    return (max(0, l - pad), max(0, t - pad),
+            min(w, r + pad), min(h, b + pad))
+
+
+def _load_manifest(path: Path) -> dict | None:
+    if not path.exists():
+        _eprint(f"WARN: manifest not found, skipping sync: "
+                f"{ascii_safe(path)}")
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        _eprint(f"ERROR: manifest unreadable: {ascii_safe(exc)}")
+        raise SystemExit(1)
+
+
+def _sync_manifest_entry(manifest: dict, manifest_path: Path,
+                         img_path: Path, natural_px, sha: str) -> bool:
+    """Update natural_px + sha256 for the manifest entry whose 'file'
+    resolves to this image. Match by resolved absolute path so a relative
+    manifest 'file' (assets/paper_figures/x.png) still matches an image
+    given by any path spelling. Returns True if an entry was updated.
+    """
+    target = img_path.resolve()
+    updated = False
+    for fig in manifest.get("figures", []):
+        fpath = (manifest_path.parent / fig.get("file", "")).resolve()
+        if fpath == target:
+            fig["natural_px"] = [natural_px[0], natural_px[1]]
+            fig["sha256"] = sha
+            updated = True
+    return updated
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="preprocess_figures",
+        description="Autocrop near-white margins, report natural size, "
+                    "warn on low-res, and sync FIGURE_MANIFEST.json.",
+    )
+    p.add_argument("images", nargs="+", metavar="IMG",
+                   help="one or more image files to process in place")
+    p.add_argument("--autocrop", action="store_true",
+                   help="trim near-white border (default: report only)")
+    p.add_argument("--pad", type=int, default=6,
+                   help="px of padding kept around content after autocrop "
+                        "(default 6)")
+    p.add_argument("--threshold", type=int, default=DEFAULT_WHITE_THRESHOLD,
+                   help="near-white cutoff 0-255; pixels brighter than this "
+                        f"are margin (default {DEFAULT_WHITE_THRESHOLD})")
+    p.add_argument("--min-px", type=int, nargs=2, metavar=("W", "H"),
+                   default=None,
+                   help="warn if natural size is below W x H px "
+                        "(e.g. --min-px 1200 700)")
+    p.add_argument("--manifest", default=None,
+                   help="FIGURE_MANIFEST.json to keep in sync after edits")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    Image, ImageChops = _load_pil()
+
+    manifest_path = Path(args.manifest).resolve() if args.manifest else None
+    manifest = _load_manifest(manifest_path) if manifest_path else None
+    manifest_dirty = False
+
+    any_warn = False
+    any_missing = False
+    for img_arg in args.images:
+        img_path = Path(img_arg)
+        if not img_path.exists():
+            _eprint(f"ERROR: image not found: {ascii_safe(img_path)}")
+            any_missing = True
+            continue
+        try:
+            img = Image.open(img_path)
+            img.load()
+        except Exception as exc:
+            _eprint(f"ERROR: cannot open {ascii_safe(img_path)}: "
+                    f"{ascii_safe(exc)}")
+            any_missing = True
+            continue
+
+        before = img.size
+        changed = False
+
+        if args.autocrop:
+            box = _autocrop_box(img, ImageChops, args.threshold)
+            if box is None:
+                _eprint(f"[preprocess] WARN: {ascii_safe(img_path.name)} "
+                        f"is all near-white; skipping autocrop.")
+            else:
+                box = _apply_pad(box, args.pad, img.size)
+                if box != (0, 0, img.width, img.height):
+                    img = img.crop(box)
+                    img.save(img_path)
+                    changed = True
+
+        natural = img.size
+        crop_note = (f"  (autocropped from {before[0]}x{before[1]})"
+                     if changed else "")
+        print(f"[preprocess] {ascii_safe(img_path.name)}: "
+              f"{natural[0]}x{natural[1]}px{crop_note}")
+
+        # Low-res warning -- a printed A0 poster magnifies every missing pixel.
+        if args.min_px is not None:
+            mw, mh = args.min_px
+            if natural[0] < mw or natural[1] < mh:
+                _eprint(f"[preprocess] WARN: {ascii_safe(img_path.name)} "
+                        f"{natural[0]}x{natural[1]}px is below "
+                        f"--min-px {mw}x{mh}; may upscale poorly in print.")
+                any_warn = True
+
+        # Manifest sync: refresh natural_px + sha256 for the matching entry.
+        # We re-hash whenever a manifest is supplied (even without a crop)
+        # so a manifest can be reconciled to images edited out-of-band.
+        if manifest is not None:
+            sha = _sha256_file(img_path)
+            if _sync_manifest_entry(manifest, manifest_path, img_path,
+                                    natural, sha):
+                manifest_dirty = True
+            else:
+                _eprint(f"[preprocess] note: no manifest entry references "
+                        f"{ascii_safe(img_path.name)}; not synced.")
+
+    if manifest is not None and manifest_dirty:
+        manifest_path.write_text(
+            json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+        print(f"[preprocess] manifest synced: {ascii_safe(manifest_path)}")
+
+    if any_missing:
+        return 2
+    if any_warn:
+        # Low-res is a WARN, not a hard fail -- the asset gate decides
+        # severity. Return 0 so a pipeline keeps going but the WARN lines
+        # are visible on stderr.
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())