Return papercraft pages as PNG pictures as well as SVG files

QA: the A4 SVGs came back with mime_type None, so chat embeds, <img> and
fetchers refused them and they were download-only. Each page is now also
drawn with matplotlib (same pieces, labels, folds and tabs, 150 dpi) and
returned as a gallery of PNGs; the SVGs stay for printing in mm. The UI
panel shows the PNG pages instead of an inline SVG preview.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

SPEC.md

@@ -111,7 +111,7 @@ Verbs: `sat/stood/lay/rested` → `on` (ground implied), `shone/glowed` → `lig
 | `translate_to_scene` | sentence, primitives, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
 | `refine_scene` | ledger, changes, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
 | `simplify_item` | ledger, item id, html, rings, samples → report, rung PNGs, rung GLBs, mini HTML file, mini HTML text |
-| `papercraft_rings` | ledger, item id, rings, samples, height_cm → pieces report, one SVG per A4 page (mm) |
+| `papercraft_rings` | ledger, item id, rings, samples, height_cm → pieces report, PNG per A4 page (to look at), SVG per A4 page (mm, to print) |
 
 `check_words` also returns `maps_to` per noun (the asset it would get), so a word
 that exists but maps to the wrong thing shows up before submitting.
@@ -147,7 +147,9 @@ Cut solid lines, fold dashed lines. The report lists, per piece, `glues_to` (the
 carries) and `receives_from` (pieces whose tabs land on it), so a tabless piece such as
 the top cap still shows its joint.
 
-Output is A4 pages (190 × 277 mm inside 10 mm margins). Each piece is turned to its
+Output is A4 pages (190 × 277 mm inside 10 mm margins), each as a 150 dpi PNG (chats,
+`<img>` and fetchers show PNGs; SVG files come back without a MIME type) and as an SVG
+in millimetres for printing. Each piece is turned to its
 narrowest orientation and shelf-packed; strips longer than a page are split like curled
 ones. With `height_cm` blank the model is the tallest whose every piece fits a page,
 which is set by band width and cap size, not strip length. The report gives

app.py

@@ -230,7 +230,7 @@ def simplify_item(ledger_json: str, item_id: str, html: str = "url", rings: str
 
 
 def papercraft_rings(ledger_json: str, item_id: str, rings: str = "8", samples: str = "16",
-                     height_cm: str = "") -> tuple[str, list]:
+                     height_cm: str = "") -> tuple[str, list, list]:
     """Make a printable papercraft net of one object from its rings rung, on A4 pages (see simplify_item).
 
     Every band between two rings unrolls exactly into one paper strip; bands that would
@@ -247,7 +247,8 @@ def papercraft_rings(ledger_json: str, item_id: str, rings: str = "8", samples:
             piece still fits one A4 page. The report gives that A4 limit either way.
 
     Returns:
-        (report JSON string with the pieces, pages and what glues to what, one SVG file per A4 page in mm).
+        (report JSON string with the pieces, pages and what glues to what, one PNG picture per A4
+        page at 150 dpi to look at, one SVG file per A4 page in mm to print).
     """
     try:
         ledger = _json(ledger_json, "ledger_json")
@@ -271,20 +272,22 @@ def papercraft_rings(ledger_json: str, item_id: str, rings: str = "8", samples:
         pieces, scale = papercraft.net(profile, n, h or a4_cm)
         work, slug = tempfile.mkdtemp(prefix="vli_paper_"), re.sub(r"\W+", "_", item["word"])
         sheets = papercraft.pages(pieces)
-        files, page_report = [], []
+        files, pictures, page_report = [], [], []
         for k, placed in enumerate(sheets, 1):
-            text, size = papercraft.svg(placed, f"{item['word']}: {len(profile)} rings x {n}, page {k}/{len(sheets)}")
+            title = f"{item['word']}: {len(profile)} rings x {n}, page {k}/{len(sheets)}"
+            text, size = papercraft.svg(placed, title)
             path = os.path.join(work, f"{slug}_net_p{k}.svg")
             with open(path, "w", encoding="utf-8") as f:
                 f.write(text)
             files.append(path)
+            pictures.append((papercraft.png(placed, title, os.path.join(work, f"{slug}_net_p{k}.png")), f"page {k}"))
             page_report.append({"page": k, "size_mm": size, "pieces": [pc["name"] for pc, _ in placed]})
         report = {"item": item_id, "word": item["word"], "rings": len(profile), "samples": n,
                   "model_height_cm": round((profile[-1]["y"] - profile[0]["y"]) * scale / 10, 1),
                   "real_height_cm": round(real_cm, 1), "max_height_cm_for_a4": round(a4_cm, 1),
                   "fits_a4": bool(h is None or h <= a4_cm), "pages": page_report,
                   "pieces": [{"name": name, **j} for name, j in papercraft.joins(pieces).items()]}
-        return json.dumps(report, indent=1), files
+        return json.dumps(report, indent=1), pictures, files
     except Exception as e:
         _fail(e)
 
@@ -324,17 +327,6 @@ def _use_primitive(primitives_json, word, shape):
     return json.dumps(prims)
 
 
-def _svg_preview(files):
-    """Show the SVG pages side by side, scaled to the panel."""
-    pages = []
-    for path in files or []:
-        with open(path, encoding="utf-8") as f:
-            text = f.read()
-        pages.append(text.replace("<svg ", '<svg style="width:100%;height:auto;border:1px solid #ccc" ', 1))
-    cells = "".join(f'<div style="flex:1 1 260px;max-width:420px">{p}</div>' for p in pages)
-    return f'<div style="display:flex;flex-wrap:wrap;gap:8px">{cells}</div>' if pages else ""
-
-
 def _html_preview(path):
     """Live preview (sandboxed iframe) of the mini HTML file."""
     if not path:
@@ -405,8 +397,8 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
     with gr.Accordion("Papercraft net (rings)", open=False):
         paper_height = gr.Textbox(label="Model height in cm (blank = largest that fits A4)", value="")
         paper = gr.Button("Make net")
-        paper_preview = gr.HTML()
-        paper_file = gr.File(label="A4 pages (.svg, mm)", file_count="multiple")
+        paper_pages = gr.Gallery(label="A4 pages", columns=3)
+        paper_file = gr.File(label="A4 pages to print (.svg, mm)", file_count="multiple")
         paper_report = gr.Code(label="Pieces", language="json")
 
     gr.on([sentence.change, primitives.change], check_words, [sentence, primitives], words,
@@ -424,7 +416,7 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
                [ladder_report, ladder_pics, ladder_files, ladder_file, ladder_html], api_name="simplify_item") \
         .then(_html_preview, ladder_file, ladder_preview, api_visibility="private")
     paper.click(papercraft_rings, [ledger, item_id, ring_count, ring_samples, paper_height],
-                [paper_report, paper_file], api_name="papercraft_rings")         .then(_svg_preview, paper_file, paper_preview, api_visibility="private")
+                [paper_report, paper_pages, paper_file], api_name="papercraft_rings")
 
 if __name__ == "__main__":
     demo.launch(mcp_server=True)

vli/papercraft.py

@@ -20,6 +20,7 @@ MARGIN_MM = 10.0
 HEADER_MM = 8.0
 STRIP_MAX_MM = PAGE_MM[1] - HEADER_MM - 2 * TAB_MM  # longer strips are split
 MIN_CAP_MM = 4.0
+LEGEND = "cut solid, fold dashed, glue tabs to the named piece"
 MIN_TAB_MM = 2.0
 LABEL_TAB_MM = 8.0
 
@@ -212,9 +213,7 @@ def pages(pieces):
 
 def svg(placed, title):
     """One A4 page (millimetres, 10 mm margins) of placed pieces."""
-    pts_all = np.concatenate([_points(pc) + off for pc, off in placed])
-    width = max(PAGE_MM[0], float(pts_all[:, 0].max())) + 2 * MARGIN_MM
-    height = max(PAGE_MM[1], float(pts_all[:, 1].max())) + 2 * MARGIN_MM
+    width, height = _page_size(placed)
 
     def pts(poly, off):
         return " ".join(f"{p[0] + off[0] + MARGIN_MM:.1f},{p[1] + off[1] + MARGIN_MM:.1f}" for p in poly)
@@ -225,8 +224,7 @@ def svg(placed, title):
     out = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{width:.0f}mm" height="{height:.0f}mm" '
            f'viewBox="0 0 {width:.1f} {height:.1f}" font-family="sans-serif">',
            '<rect width="100%" height="100%" fill="#fff"/>',
-           f'<text x="{MARGIN_MM}" y="{MARGIN_MM + 4}" font-size="4">{_esc(title)}: cut solid, fold dashed, '
-           f'glue tabs to the named piece</text>']
+           f'<text x="{MARGIN_MM}" y="{MARGIN_MM + 4}" font-size="4">{_esc(title)}: {LEGEND}</text>']
     for pc, off in placed:
         for t in pc["tabs"]:
             out.append(f'<polygon points="{pts(t["poly"], off)}" fill="#eee" stroke="#000" stroke-width="0.2"/>')
@@ -247,6 +245,44 @@ def svg(placed, title):
     return "\n".join(out), (round(width), round(height))
 
 
+def _page_size(placed):
+    pts_all = np.concatenate([_points(pc) + off for pc, off in placed])
+    return (max(PAGE_MM[0], float(pts_all[:, 0].max())) + 2 * MARGIN_MM,
+            max(PAGE_MM[1], float(pts_all[:, 1].max())) + 2 * MARGIN_MM)
+
+
+def png(placed, title, path, dpi=150):
+    """The same page as svg(), rasterised: chats, <img> tags and fetchers show PNGs, not SVG files."""
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    from matplotlib.patches import Polygon
+
+    width, height = _page_size(placed)
+    fig = plt.figure(figsize=(width / 25.4, height / 25.4), dpi=dpi)
+    ax = fig.add_axes([0, 0, 1, 1])
+    ax.set_xlim(0, width)
+    ax.set_ylim(height, 0)
+    ax.axis("off")
+    pt = 72 / 25.4  # points per mm
+    m = np.array([MARGIN_MM, MARGIN_MM])
+    ax.text(MARGIN_MM, MARGIN_MM + 4, f"{title}: {LEGEND}", fontsize=4 * pt, va="baseline")
+    for pc, off in placed:
+        o = off + m
+        for t in pc["tabs"]:
+            ax.add_patch(Polygon(np.array(t["poly"]) + o, facecolor="#eee", edgecolor="k", linewidth=0.2 * pt))
+            if t["show"]:
+                ax.text(*(t["at"] + o), t["label"], fontsize=2 * pt, ha="center", va="center")
+        ax.add_patch(Polygon(np.array(pc["outline"]) + o, facecolor="#fff", edgecolor="k", linewidth=0.3 * pt))
+        for p, q in pc["folds"]:
+            ax.plot([p[0] + o[0], q[0] + o[0]], [p[1] + o[1], q[1] + o[1]], color="#888",
+                    linewidth=0.2 * pt, linestyle=(0, (1.5 / 0.2, 1 / 0.2)))
+        ax.text(*(np.mean(pc["outline"], axis=0) + o), pc["name"], fontsize=4 * pt, ha="center", va="center")
+    fig.savefig(path, facecolor="white")
+    plt.close(fig)
+    return path
+
+
 def joins(pieces):
     """Both sides of every joint. Tabs sit on one side only (the last band carries the
     tabs for the top cap), so a piece lists the tabs it carries and the pieces whose