@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/paper-poster-html/scripts/_posterly/render.py

@@ -0,0 +1,215 @@
+"""Shared Playwright launch + page-settle helpers.
+
+Used by ``measure``, ``polish``, and ``render_preview``. Centralises:
+
+1. Print-emulated Chromium context at the correct viewport.
+2. MathJax detection + bounded typeset wait (so a stuck CDN can't
+   hang the script forever).
+3. ``document.fonts.ready`` + two RAFs + a fixed settle ms — so
+   the layout is locked before any geometry is read.
+4. A sanity check that catches the "page has ``$…$`` TeX in body text
+   but no rendered ``<mjx-container>``" case — MathJax never ran
+   (CDN blocked, script error, …). Measurement / polish must NOT
+   silently pass against a raw-TeX layout.
+
+The ``settle_page`` helper returns a :class:`SettleResult` with the raw
+status flags. ``measure``/``polish`` treat MathJax issues as hard fails;
+``render_preview`` warns and continues (rendering raw-TeX is at least
+visible to the user, whereas a silent measure PASS isn't).
+"""
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .textutil import ascii_safe
+
+
+def _eprint(*args: Any, **kw: Any) -> None:
+    print(*args, file=sys.stderr, **kw)
+
+
+@dataclass
+class SettleResult:
+    mathjax_intended: bool
+    """The page intended to load MathJax — either a ``<script src=…mathjax…>``
+    tag is present or ``window.MathJax`` config was set. Used to gate the
+    ``tex_without_mathjax`` failure: a poster that documents TeX syntax in
+    prose without ever loading MathJax is a perfectly valid use case and
+    must NOT trip the sanity check."""
+
+    has_mathjax: bool
+    """``window.MathJax.startup.promise`` was defined at settle time
+    (MathJax actually initialized)."""
+
+    mathjax_status: str
+    """One of ``'ok'``, ``'timeout'``, ``'error'``, ``'not-needed'``."""
+
+    mathjax_error: str | None
+    """Exception message if ``mathjax_status == 'error'``, else None."""
+
+    tex_without_mathjax: bool
+    """Body innerText has TeX delimiters but no ``<mjx-container>`` rendered.
+    Only counted as a failure when ``mathjax_intended`` is True (otherwise
+    the ``$…$`` is most likely prose, not math)."""
+
+
+def open_print_emulated_page(p, viewport_px: tuple[int, int]):
+    """Launch headless Chromium, open a context+page at the viewport,
+    emulate print media. Returns ``(browser, ctx, page)``.
+
+    Print emulation is set BEFORE navigation by the caller (via
+    ``page.emulate_media``), so MathJax typesets against ``@media print``
+    layout from the start. Without that, the screen-mode ``--u`` value
+    leaks in and measurement is unreliable.
+    """
+    w, h = viewport_px
+    browser = p.chromium.launch()
+    ctx = browser.new_context(viewport={"width": w, "height": h})
+    page = ctx.new_page()
+    page.emulate_media(media="print")
+    page.set_viewport_size({"width": w, "height": h})
+    return browser, ctx, page
+
+
+def settle_page(
+    page,
+    *,
+    mathjax_timeout_ms: int = 15000,
+    settle_ms: int = 500,
+) -> SettleResult:
+    """Wait for MathJax, fonts, two RAFs, and an extra fixed ms.
+
+    Returns a :class:`SettleResult` rather than raising — the caller
+    decides whether each flag is a hard fail or a soft warning.
+    Idempotent on math-free pages: detection is synchronous and the
+    typeset wait is skipped when MathJax wasn't loaded.
+    """
+    # 1a) Did the page INTEND to load MathJax? A <script src="…mathjax…">
+    #     tag OR a window.MathJax config object counts. Used to decide
+    #     whether stray `$…$` in body text is "math that failed to render"
+    #     (intended) vs "prose that happens to mention TeX" (not intended).
+    try:
+        mathjax_intended = bool(page.evaluate(
+            "() => !!(document.querySelector('script[src*=\"mathjax\" i]') "
+            "|| (window.MathJax && Object.keys(window.MathJax).length > 0))"
+        ))
+    except Exception:
+        mathjax_intended = False
+
+    # 1b) Did MathJax actually initialise?
+    try:
+        has_mj = bool(page.evaluate(
+            "() => !!(window.MathJax && window.MathJax.startup "
+            "&& window.MathJax.startup.promise)"
+        ))
+    except Exception:
+        has_mj = False
+
+    mj_status = "not-needed"
+    mj_error: str | None = None
+
+    # 2) If present, bound the typeset wait with Promise.race so a
+    #    stuck MathJax can't hang us.
+    if has_mj:
+        mj_js = (
+            f"() => Promise.race(["
+            f"  MathJax.startup.promise"
+            f"    .then(() => (MathJax.typesetPromise"
+            f"      ? MathJax.typesetPromise() : null))"
+            f"    .then(() => 'ok'),"
+            f"  new Promise(r => setTimeout("
+            f"    () => r('timeout'), {mathjax_timeout_ms}))"
+            f"])"
+        )
+        try:
+            mj_status = page.evaluate(mj_js) or "timeout"
+        except Exception as e:
+            mj_status = "error"
+            mj_error = str(e)
+
+    # 3) Fonts (best-effort) + two RAFs + fixed settle ms.
+    try:
+        page.evaluate(
+            "() => document.fonts && document.fonts.ready "
+            "? document.fonts.ready : null"
+        )
+    except Exception:
+        pass
+    page.evaluate(
+        "() => new Promise(r => "
+        "requestAnimationFrame(() => requestAnimationFrame(r)))"
+    )
+    page.wait_for_timeout(settle_ms)
+
+    # 4) Sanity check for the silent-fail case: page has TeX in body
+    #    text but no rendered mjx-container. Covers all four delimiter
+    #    pairs the templates configure (`$...$`, `$$...$$`, `\(...\)`,
+    #    `\[...\]`). No length bound — earlier `{1,1500}` regex limits
+    #    were Codex-flagged for letting long raw-TeX paste slip past.
+    #    `[^$\n]+` (inline) and `[\s\S]+?` (display, non-greedy) avoid
+    #    catastrophic backtracking even on multi-paragraph segments.
+    try:
+        sanity = page.evaluate(
+            "() => {"
+            "  const has_mjx = "
+            "    document.querySelectorAll('mjx-container').length > 0;"
+            "  const txt = document.body && document.body.innerText || '';"
+            "  const has_dollar  = /\\$[^$\\n]+\\$/.test(txt);"
+            "  const has_ddollar = /\\$\\$[\\s\\S]+?\\$\\$/.test(txt);"
+            "  const has_paren   = /\\\\\\([\\s\\S]+?\\\\\\)/.test(txt);"
+            "  const has_brack   = /\\\\\\[[\\s\\S]+?\\\\\\]/.test(txt);"
+            "  return {has_mjx, has_tex: has_dollar || has_ddollar "
+            "                          || has_paren  || has_brack};"
+            "}"
+        )
+        tex_without_mathjax = bool(
+            sanity.get("has_tex") and not sanity.get("has_mjx")
+        )
+    except Exception:
+        tex_without_mathjax = False
+
+    return SettleResult(
+        mathjax_intended=mathjax_intended,
+        has_mathjax=has_mj,
+        mathjax_status=mj_status,
+        mathjax_error=mj_error,
+        tex_without_mathjax=tex_without_mathjax,
+    )
+
+
+def hard_fail_on_settle_problems(
+    result: SettleResult,
+    *,
+    mathjax_timeout_ms: int,
+) -> str | None:
+    """Return a one-line failure message if ``measure`` / ``polish``
+    must hard-fail given a settle result, else None.
+
+    Centralised so the two strict gates agree on what counts as a fail.
+    """
+    if result.mathjax_status == "error":
+        return (
+            f"MathJax typeset error: {ascii_safe(result.mathjax_error)}. "
+            f"Refusing to measure a broken-script page."
+        )
+    if result.mathjax_status == "timeout":
+        return (
+            f"MathJax typeset did not finish within "
+            f"{mathjax_timeout_ms} ms. Refusing to measure a "
+            f"partially typeset poster."
+        )
+    # Only fail when MathJax was INTENDED to load (script tag or config
+    # present) but didn't render anything. A poster that documents TeX
+    # syntax in prose without ever loading MathJax is a valid use case.
+    if result.mathjax_intended and result.tex_without_mathjax:
+        return (
+            "page intended to load MathJax (script/config present) "
+            "but no rendered <mjx-container> was found despite TeX "
+            "delimiters in body text. MathJax likely failed to load "
+            "(CDN block? script error?). Refusing to measure raw-TeX "
+            "layout."
+        )
+    return None

package/dist/skills/paper-poster-html/scripts/_posterly/textutil.py

@@ -0,0 +1,16 @@
+"""Make a string safe to print to a terminal / CI log / pasted issue.
+
+Runtime output is otherwise all-ASCII (rounds 7-9), but USER-derived
+fragments -- orphan text, an image src, a MathJax error, raw pdfinfo
+output -- can re-inject Unicode that source-level grep can't catch.
+Escape it at the output boundary so terminal output never mojibakes.
+"""
+from __future__ import annotations
+
+
+def ascii_safe(s: object) -> str:
+    r"""Backslash-escape any non-ASCII char.
+
+    ``ascii_safe("1.18-1.30× ↑")`` -> ``"1.18-1.30\\xd7 \\u2191"``.
+    """
+    return str(s).encode("ascii", "backslashreplace").decode("ascii")

package/dist/skills/paper-poster-html/scripts/_posterly/verify_final.py

@@ -0,0 +1,171 @@
+"""Final-PDF sanity check via ``pdfinfo``.
+
+Checks the rendered PDF is exactly what was asked for:
+
+  - **page count == 1** (a multi-page export almost always means the
+    canvas size and ``@page { size }`` disagreed)
+  - **dimensions match the expected canvas** within ±0.05 in
+    (default; ``--dim-tol-in`` to tune)
+  - **file size <= --max-size-mb** (overlarge PDFs often mean an
+    accidentally embedded raw image or 600 dpi figure)
+
+The expected canvas can come from:
+
+  - ``--canvas '<W>x<H><unit>'`` (e.g. ``60x36in`` / ``A0 portrait``)
+  - ``--from-html poster.html`` (parses the same ``@page`` rule the
+    HTML uses, so the verification can't drift from the source)
+
+Exactly one of those must be supplied — no hardcoded landscape default.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import canvas as _canvas
+from .textutil import ascii_safe
+
+
+def _eprint(*args: Any, **kw: Any) -> None:
+    print(*args, file=sys.stderr, **kw)
+
+
+def cmd_verify_final(args: argparse.Namespace) -> int:
+    pdf = Path(args.pdf).resolve()
+    if not pdf.exists():
+        _eprint(f"ERROR: PDF not found: {ascii_safe(pdf)}")
+        return 2
+
+    # Resolve expected canvas.
+    if args.canvas is None and args.from_html is None:
+        _eprint(
+            "ERROR: verify-final needs either `--canvas <W>x<H><unit>` "
+            "(e.g. '60x36in' or 'A0 portrait') or `--from-html "
+            "<poster.html>` so the expected size can't be wrong by "
+            "default."
+        )
+        return 2
+    if args.canvas is not None and args.from_html is not None:
+        _eprint(
+            "ERROR: --canvas and --from-html are mutually exclusive; "
+            "pick one."
+        )
+        return 2
+    if args.canvas is not None:
+        exp_w, exp_h = args.canvas
+        src = "--canvas"
+    else:
+        html_path = Path(args.from_html).resolve()
+        if not html_path.exists():
+            _eprint(f"ERROR: --from-html path not found: {ascii_safe(html_path)}")
+            return 2
+        parsed = _canvas.read_canvas_from_html(html_path)
+        if parsed is None:
+            _eprint(
+                f"ERROR: no `@page {{ size }}` found in "
+                f"{ascii_safe(html_path)}. Fall back to --canvas."
+            )
+            return 2
+        exp_w, exp_h = parsed
+        src = f"--from-html ({ascii_safe(html_path.name)})"
+
+    # Preserve user PATH (Homebrew/conda/etc.) but force C locale so
+    # pdfinfo number formatting is consistent across systems.
+    env = os.environ.copy()
+    env["LC_ALL"] = "C"
+    env["LANG"] = "C"
+    try:
+        out = subprocess.check_output(
+            ["pdfinfo", str(pdf)],
+            text=True, stderr=subprocess.STDOUT, env=env,
+        )
+    except FileNotFoundError:
+        _eprint(
+            "ERROR: pdfinfo not installed. Install poppler:\n"
+            "  Linux:   apt install poppler-utils  "
+            "(or `dnf install poppler-utils`)\n"
+            "  macOS:   brew install poppler\n"
+            "  Windows: choco install poppler  (or download from "
+            "poppler-windows)"
+        )
+        return 2
+    except subprocess.CalledProcessError as e:
+        _eprint(f"ERROR: pdfinfo failed: {ascii_safe(e.output)}")
+        return 2
+
+    info: dict[str, str] = {}
+    for line in out.splitlines():
+        if ":" in line:
+            k, v = line.split(":", 1)
+            info[k.strip()] = v.strip()
+
+    pages = int(info.get("Pages", "0"))
+    page_size = info.get("Page size", "")
+    page_rot = int(info.get("Page rot", "0") or "0")
+    file_size_b = pdf.stat().st_size
+    file_size_mb = file_size_b / (1024 * 1024)
+
+    print(f"[verify-final] {ascii_safe(pdf)}")
+    print(f"  expected canvas = {exp_w:.2f}in x {exp_h:.2f}in  "
+          f"(from {src})")
+    print(f"  pages           = {pages}")
+    print(f"  page size       = {ascii_safe(page_size)}")
+    print(f"  page rot        = {page_rot}")
+    print(f"  file size       = {file_size_mb:.2f} MB")
+
+    problems: list[str] = []
+
+    if pages != 1:
+        problems.append(f"page count = {pages}, expected 1")
+
+    # pdfinfo's Page size is in points (1pt = 1/72 in).
+    m = re.search(r"([\d.]+)\s*x\s*([\d.]+)\s*pts", page_size)
+    if not m:
+        problems.append(
+            f"could not parse pdfinfo `Page size`: {ascii_safe(page_size)!r}"
+        )
+    else:
+        w_in = float(m.group(1)) / 72.0
+        h_in = float(m.group(2)) / 72.0
+        print(f"  -> {w_in:.2f}in x {h_in:.2f}in")
+        tol = args.dim_tol_in
+        direct_ok = (
+            abs(w_in - exp_w) <= tol and abs(h_in - exp_h) <= tol
+        )
+        swap_ok = (
+            abs(w_in - exp_h) <= tol and abs(h_in - exp_w) <= tol
+        )
+        allow_swap = args.allow_rotated or page_rot in (90, 270)
+        if direct_ok:
+            pass
+        elif swap_ok and allow_swap:
+            print(
+                f"  (swapped dimensions accepted -- page rot = "
+                f"{page_rot}deg"
+                + (" + --allow-rotated" if args.allow_rotated else "")
+                + ")"
+            )
+        else:
+            problems.append(
+                f"dimensions {w_in:.2f}x{h_in:.2f}in "
+                f"do not match canvas {exp_w}x{exp_h}in "
+                f"(tol +/-{tol}in, page rot {page_rot}deg)"
+            )
+
+    if file_size_mb > args.max_size_mb:
+        problems.append(
+            f"file {file_size_mb:.2f} MB > limit "
+            f"{args.max_size_mb} MB"
+        )
+
+    for p in problems:
+        _eprint(f"  FAIL: {p}")
+    if problems:
+        return 1
+    print("[verify-final] PASS")
+    return 0