predictygraph 0.1.0__tar.gz → 0.2.1__tar.gz

{predictygraph-0.1.0 → predictygraph-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: predictygraph
-Version: 0.1.0
+Version: 0.2.1
 Summary: Predictable graphs: a readable, CSS-styled diagram DSL with per-group layouts, rendered to SVG/APNG
 Author-Email: Reza Jelveh <git@jelveh.me>
 License: GPL-3.0-or-later
@@ -32,6 +32,7 @@ uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg
 uv run pdg diagram.pdg --css theme.css -o out.svg
 uv run pdg diagram.pdg -o out.png                    # animated PNG (APNG)
 uv run pdg diagram.pdg --check                       # validate only
+uv run pdg diagram.pdg -o d.png --width 1000 --colors 64   # small PNG for chat
 uv run pdg diagram.pdg --target web                  # size labels to fit any browser font
 ```
 

{predictygraph-0.1.0 → predictygraph-0.2.1}/README.md

@@ -18,6 +18,7 @@ uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg
 uv run pdg diagram.pdg --css theme.css -o out.svg
 uv run pdg diagram.pdg -o out.png                    # animated PNG (APNG)
 uv run pdg diagram.pdg --check                       # validate only
+uv run pdg diagram.pdg -o d.png --width 1000 --colors 64   # small PNG for chat
 uv run pdg diagram.pdg --target web                  # size labels to fit any browser font
 ```
 

{predictygraph-0.1.0 → predictygraph-0.2.1}/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
 ]
 requires-python = ">=3.11"
 readme = "README.md"
-version = "0.1.0"
+version = "0.2.1"
 
 [project.license]
 text = "GPL-3.0-or-later"

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/cli.py

@@ -31,7 +31,9 @@ def main(
     at: float | None = typer.Option(None, "--at", help="SVG frozen at this time (seconds)"),
     fps: int = typer.Option(20, "--fps", help="APNG frames per second"),
     seconds: float | None = typer.Option(None, "--seconds", help="APNG length (default: one full loop)"),
-    scale: float = typer.Option(2.0, "--scale", help="APNG pixel scale"),
+    scale: float = typer.Option(2.0, "--scale", help="PNG pixel scale"),
+    width: int | None = typer.Option(None, "--width", help="PNG width in pixels (overrides --scale)"),
+    colors: int | None = typer.Option(None, "--colors", help="PNG palette size, 2-256 (smaller files)"),
     allow_outside: bool = typer.Option(False, "--allow-outside",
                                        help="Let image= and css \"...\" read files outside the input's directory"),
 ) -> None:
@@ -52,7 +54,7 @@ def main(
             typer.echo(f"{src}: ok")
             return
         if dest.suffix.lower() in (".png", ".apng"):
-            write_apng(scene, dest, fps, scale, seconds)
+            write_apng(scene, dest, fps, scale, seconds, width, static, colors)
         else:
             t = at if at is not None else (0.0 if static else None)
             dest.write_text(write_svg(scene, t), encoding="utf-8")

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/default.css

@@ -14,3 +14,10 @@ group { fill: #f3f4f6; stroke: #9ca3af; stroke-width: 1; border-radius: 10px;
         padding: 14px; color: #374151; font-size: 12px; font-weight: bold;
         label-position: top; }
 edge  { stroke: #4b5563; stroke-width: 1.5; color: #374151; font-size: 11px; }
+
+/* Text parts: `sub=` lines, step badges, figure caption, legend box. */
+sub     { color: #6b7280; font-size: 0.85em; }
+group sub { font-weight: normal; }
+step    { fill: #374151; color: #ffffff; font-size: 11px; font-weight: bold; }
+caption { color: #6b7280; font-size: 12px; font-style: italic; text-align: center; }
+legend  { fill: #ffffff; stroke: #d1d5db; color: #374151; font-size: 11px; }

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/layout.py

@@ -14,13 +14,27 @@ from .text import load_image, measure
 
 
 # ---------------------------------------------------------------- sizing
+BOLD = ("bold", "bolder", "600", "700", "800", "900")
+SUB_GAP = 3.0  # px between a label and its `sub=` lines
+
+
+def text_block(text: str | None, st: dict, default_fs: float) -> tuple[float, float, list[str]]:
+    if not text:
+        return 0.0, 0.0, []
+    fs = px(st.get("font-size"), default_fs)
+    return measure(text, st.get("font-family", "sans-serif"), fs, st.get("font-weight", "normal") in BOLD)
+
+
 def size_node(n: Node, doc: Document) -> None:
     st = n.style
-    fs = px(st.get("font-size"), 14)
-    bold = st.get("font-weight", "normal") in ("bold", "600", "700", "800", "900")
     label = n.label if n.label is not None else n.id
-    n.text_w, n.text_h, n.text_lines = measure(label, st.get("font-family", "sans-serif"), fs, bold) if label else (0.0, 0.0, [])
+    n.text_w, n.text_h, n.text_lines = text_block(label, st, 14)
+    sw, sh, n.sub_lines = text_block(n.attrs.get("sub"), n.sub_style or st, 12)
+    n.sub_h = sh + SUB_GAP if n.sub_lines else 0.0
+    n.text_w, n.text_h = max(n.text_w, sw), n.text_h + n.sub_h  # text_h covers label + sub
     pt, pr, pb, pl = box4(st.get("padding"), 8)
+    pl += accent_width(st, "left")
+    pr += accent_width(st, "right")
     shape = n.attrs.get("shape")
     if "image" in n.attrs:
         img = load_image(n.attrs["image"], doc.base_dir, doc.allow_outside)
@@ -71,6 +85,14 @@ def size_node(n: Node, doc: Document) -> None:
 
 
 # ---------------------------------------------------------------- helpers
+def accent_width(st: dict, side: str) -> float:
+    """Room an `accent-bar` takes on `side` (it sits inside the box, before the padding)."""
+    spec = st.get("accent-bar")
+    if not spec or spec.strip() == "none" or st.get("accent-side", "left") != side:
+        return 0.0
+    return px(st["accent-bar"].split()[0], 4)
+
+
 def direct_child(item: Item, g: Group) -> Item | None:
     """Ancestor-or-self of `item` that is a direct child of g."""
     cur = item
@@ -116,6 +138,14 @@ class LineLayout(Layout):
         cross = max((k.h if horizontal else k.w) for k in self.kids)
         pos = 0.0
         for k in self.kids:
+            if align == "stretch":  # every child as wide (column) / tall (row) as the widest
+                if horizontal:
+                    k.h = cross
+                else:
+                    grow = cross - k.w
+                    k.w = cross
+                    if isinstance(k, Group) and opt(k, "justify", "start") == "center":
+                        k.ox += grow / 2  # content stays left unless the tier asks to centre it
             size_c = k.h if horizontal else k.w
             off = {"start": 0, "end": cross - size_c}.get(align, (cross - size_c) / 2)
             if horizontal:
@@ -485,13 +515,15 @@ def layout_group(g: Group, doc: Document) -> None:
     else:
         lay = LAYOUTS[g.attrs["layout"]](g, doc)
         cw, ch = lay.run()
-    g.label_h = 0.0
+    g.label_h = g.title_h = 0.0
     lw = 0.0
     if g.label and g.kind == "group":
-        fs = px(g.style.get("font-size"), 12)
-        lw, g.label_h, _ = measure(g.label, g.style.get("font-family", "sans-serif"), fs,
-                                   g.style.get("font-weight", "normal") in ("bold", "700"))
-        g.label_h += 6
+        lw, g.title_h, _ = text_block(g.label, g.style, 12)
+        sw, sh, _ = text_block(g.attrs.get("sub"), g.sub_style or g.style, 11)
+        lw = max(lw, sw)
+        g.label_h = g.title_h + (sh + SUB_GAP if sh else 0.0) + 6
+        if g.style.get("title-fill") not in (None, "none") and g.style.get("label-position", "top") != "bottom":
+            g.label_h += 6
     inner_w = max(cw, lw) + getattr(g, "extra_w", 0.0)  # extra_w: room requested for the title
     top = g.style.get("label-position", "top") != "bottom"
     g.ox = pl + (inner_w - cw) / 2

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/model.py

@@ -16,6 +16,7 @@ class Item:
     attrs: dict[str, str] = field(default_factory=dict)
     parent: "Group | None" = None
     style: dict[str, str] = field(default_factory=dict)
+    sub_style: dict[str, str] = field(default_factory=dict)  # `sub=` text (CSS `sub` selector)
     # layout results (relative to parent content origin, then absolute)
     w: float = 0.0
     h: float = 0.0
@@ -48,6 +49,8 @@ class Node(Item):
     text_lines: list[str] = field(default_factory=list)
     text_w: float = 0.0
     text_h: float = 0.0
+    sub_lines: list[str] = field(default_factory=list)  # secondary text under the label
+    sub_h: float = 0.0
 
 
 @dataclass
@@ -59,6 +62,8 @@ class Group(Item):
     ox: float = 0.0
     oy: float = 0.0
     label_h: float = 0.0
+    title_h: float = 0.0  # label only; label_h also counts the subtitle
+    part_styles: dict[str, dict[str, str]] = field(default_factory=dict)  # root: caption, legend
 
 
 @dataclass
@@ -73,6 +78,7 @@ class Edge:
     scope: Group | None = None
     style: dict[str, str] = field(default_factory=dict)
     label_style: dict[str, str] = field(default_factory=dict)
+    step_style: dict[str, str] = field(default_factory=dict)
     index: int = 0
     waypoints: list[tuple[float, float]] = field(default_factory=list)
     wp_owner: Group | None = None
@@ -89,6 +95,8 @@ class Document:
     items: dict[str, Item] = field(default_factory=dict)
     base_dir: str = "."
     allow_outside: bool = False  # let image=/css "..." read files outside base_dir
+    legend: list[Node] = field(default_factory=list)  # `legend .cls "text"` entries (not laid out)
+    legend_title: str | None = None
 
     def walk(self, g: Group | None = None):
         g = g or self.root

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/parser.py

@@ -11,6 +11,8 @@ from pathlib import Path
 from .model import Document, Edge, Group, Node
 from .safe import MAX_EDGES, safe_path
 
+MAX_LEGEND = 64
+
 
 class PdgSyntaxError(ValueError):
     def __init__(self, msg: str, line: int):
@@ -189,6 +191,19 @@ class Parser:
             if classes:
                 d["__classes__"] = " ".join(classes)
             return
+        if head == "legend" and (len(toks) == 1 or toks[1][0] in ("string", "cls")):
+            if self.scope is not self.root:
+                raise PdgSyntaxError("'legend' only allowed at top level", lineno)
+            label, classes, attrs = self._tail(toks, 1, lineno)
+            if not classes:  # `legend "Key"` names the box
+                self.doc.legend_title = label
+                return
+            if len(self.doc.legend) >= MAX_LEGEND:
+                raise PdgSyntaxError(f"too many legend entries (limit {MAX_LEGEND})", lineno)
+            entry = Node(id=f"pdg-legend-{len(self.doc.legend)}", label=label or " ".join(classes),
+                         classes=list(classes), attrs=attrs, parent=self.root)
+            self.doc.legend.append(entry)
+            return
         if head == "group" and len(toks) >= 2 and toks[1][0] == "ident":
             if toks[-1] != ("punct", "{"):
                 raise PdgSyntaxError("group needs '{'", lineno)

predictygraph-0.2.1/src/predictygraph/render/apng.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""PNG / APNG writer: Scene IR -> PNG (one frame) or animated PNG (frames sampled from
+the animation tracks).
+
+Size controls: `scale` (pixel scale) or `width` (target pixel width, overrides scale);
+`still` forces one frame; `colors` quantises to a palette (much smaller files for flat
+diagram colours). A scene without animation is always written as a single frame.
+"""
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+from ..anim import loop_length
+from ..ir import Scene
+from .svg import write_svg
+
+MAX_PIXELS = 8000  # longest side; keeps a typo in --width/--scale from eating memory
+
+
+class ApngWriter:
+    def __init__(self, scene: Scene, fps: int = 20, scale: float = 2.0, seconds: float | None = None,
+                 width: int | None = None, still: bool = False, colors: int | None = None):
+        self.scene, self.fps = scene, fps
+        if width:
+            scale = width / max(scene.width, 1.0)
+        longest = max(scene.width, scene.height, 1.0)
+        self.scale = max(0.05, min(scale, MAX_PIXELS / longest))
+        durs = scene.durations()
+        self.still = still or not durs
+        self.seconds = seconds or (loop_length(durs) if durs else 1.0)
+        self.colors = max(2, min(int(colors), 256)) if colors else None
+
+    def _raster(self, svg: str):
+        try:
+            import cairosvg
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError("PNG export needs cairosvg: install predictygraph[apng]") from exc
+        from PIL import Image
+        png = cairosvg.svg2png(bytestring=svg.encode(), scale=self.scale)
+        return Image.open(io.BytesIO(png)).convert("RGBA")
+
+    def frames(self):
+        n = 1 if self.still else max(1, round(self.seconds * self.fps))
+        return [self._raster(write_svg(self.scene, i / self.fps)) for i in range(n)]
+
+    def _flatten(self, im):
+        """Opaque RGB (diagrams have a background) and, with `colors`, a palette image."""
+        from PIL import Image
+        bg = Image.new("RGBA", im.size, self.scene.background or "#ffffff")
+        rgb = Image.alpha_composite(bg, im).convert("RGB")
+        if self.colors:
+            return rgb.quantize(self.colors, method=Image.Quantize.MEDIANCUT, dither=Image.Dither.NONE)
+        return rgb
+
+    def save(self, out: Path) -> Path:
+        frames = [self._flatten(f) for f in self.frames()]
+        if len(frames) == 1:
+            frames[0].save(out, format="PNG", optimize=True)
+        else:
+            frames[0].save(out, format="PNG", save_all=True, append_images=frames[1:],
+                           duration=round(1000 / self.fps), loop=0, disposal=1, blend=0,
+                           default_image=False, optimize=True)
+        return out
+
+
+def write_apng(scene: Scene, out: Path, fps: int = 20, scale: float = 2.0, seconds: float | None = None,
+               width: int | None = None, still: bool = False, colors: int | None = None) -> Path:
+    return ApngWriter(scene, fps, scale, seconds, width, still, colors).save(out)

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/route.py

@@ -20,6 +20,7 @@ from .style import px
 LANE = 9.0    # distance between parallel lanes
 CLEAR = 12.0  # min distance between a horizontal run and the boxes above/below it
 RECT_SHAPES = {"box", "square", "round", "pill", "cylinder", "note", "image", "none"}
+ROUND_SHAPES = {"circle", "ellipse", "diamond"}
 
 
 def lca(a, b, root):
@@ -62,6 +63,23 @@ def port(n, side):
             "left": (n.ax, n.cy), "right": (n.ax + n.w, n.cy)}[side]
 
 
+def on_outline(n, p, vert):
+    """Move a port that was shifted along a side back onto the node's outline.
+    Boxes are flat, so only circles, ellipses and diamonds need it: the point slides
+    along the flow axis until it touches the curve (or slanted edge)."""
+    shape = n.attrs.get("shape", "box")
+    if isinstance(n, Group) or shape not in ROUND_SHAPES:
+        return p
+    hw, hh = n.w / 2, n.h / 2
+    if vert:
+        u = min(abs(p[0] - n.cx) / hw, 1.0)
+        reach = hh * (math.sqrt(1 - u * u) if shape != "diamond" else 1 - u)
+        return p[0], n.cy + math.copysign(reach, p[1] - n.cy)
+    u = min(abs(p[1] - n.cy) / hh, 1.0)
+    reach = hw * (math.sqrt(1 - u * u) if shape != "diamond" else 1 - u)
+    return n.cx + math.copysign(reach, p[0] - n.cx), p[1]
+
+
 @dataclass
 class Diagonal:
     """When may a bend/ortho jog be a slant instead of a right-angle step?"""
@@ -166,42 +184,48 @@ class Router:
 
     # ------------------------------------------------------------ passes
     def _parallel_offsets(self):
+        """Edges between the same two nodes get side-by-side lanes. The offset is in
+        absolute coordinates, so an edge and its reverse simply take different lanes."""
         pairs: dict[tuple[str, str], list[Edge]] = {}
         for e in self.doc.edges:
             pairs.setdefault(tuple(sorted((e.src, e.dst))), []).append(e)
         for es in pairs.values():
             n = len(es)
             for i, e in enumerate(es):
-                k = (i - (n - 1) / 2) * 12
-                # opposite-direction edges get mirrored sign so they stay apart
-                self.offset[e.id] = k if e.src <= e.dst else -k
+                self.offset[e.id] = (i - (n - 1) / 2) * 12
 
     def _spread_ports(self):
         """Several curved/bent edges on one side of a node: spread them symmetrically
-        around the side's middle (ordered by where they go)."""
+        around the side's middle, ordered by where they go, so they don't cross.
+        Parallel edges (same two nodes) take part too, which keeps them apart and in
+        the same order at both ends."""
         sides: dict[tuple[str, str], list] = {}
-        for e in self.doc.edges:
-            if e.attrs.get("exit") or e.attrs.get("enter") or self.offset.get(e.id):
-                continue
-            pts, axis = self.geometry(e)
-            if axis not in ("v", "h"):
-                continue
-            a, b = self.doc.items[e.src], self.doc.items[e.dst]
-            if flow_dir(lca(a, b, self.doc.root)) == "auto" or e.style.get("route", "curve") in ("straight", "ortho"):
-                continue  # ortho fan-in/out merges into a bus instead
-            i = 0 if axis == "v" else 1
-            for end, node, here, there in ((0, a, pts[0], pts[1] if len(pts) > 2 else pts[-1]),
-                                           (1, b, pts[-1], pts[-2] if len(pts) > 2 else pts[0])):
-                side = ("bottom" if there[1] > here[1] else "top") if axis == "v" else \
-                       ("right" if there[0] > here[0] else "left")
-                sides.setdefault((node.id, side), []).append((there[i], e.id, end))
+        saved, self.offset = self.offset, {}  # order by the unshifted geometry
+        try:
+            for e in self.doc.edges:
+                if e.attrs.get("exit") or e.attrs.get("enter"):
+                    continue
+                pts, axis = self.geometry(e)
+                if axis not in ("v", "h"):
+                    continue
+                a, b = self.doc.items[e.src], self.doc.items[e.dst]
+                if flow_dir(lca(a, b, self.doc.root)) == "auto" or e.style.get("route", "curve") in ("straight", "ortho"):
+                    continue  # ortho fan-in/out merges into a bus instead
+                i = 0 if axis == "v" else 1
+                for end, node, here, there in ((0, a, pts[0], pts[1] if len(pts) > 2 else pts[-1]),
+                                               (1, b, pts[-1], pts[-2] if len(pts) > 2 else pts[0])):
+                    side = ("bottom" if there[1] > here[1] else "top") if axis == "v" else \
+                           ("right" if there[0] > here[0] else "left")
+                    sides.setdefault((node.id, side), []).append((there[i], e.id, end))
+        finally:
+            self.offset = saved
         for (nid, side), lst in sides.items():
             if len(lst) < 2:
                 continue
             n = self.doc.items[nid]
-            if n.attrs.get("shape", "box") in ("diamond", "circle", "ellipse") and not isinstance(n, Group):
-                continue
             span = n.w if side in ("top", "bottom") else n.h
+            if n.attrs.get("shape", "box") in ROUND_SHAPES and not isinstance(n, Group):
+                span *= 0.6  # stay on the part of the outline that faces the side
             step = min(18.0, (span - 12) / (len(lst) - 1)) if span > 12 else 0.0
             lst.sort()
             for k, (_, eid, end) in enumerate(lst):
@@ -341,6 +365,19 @@ class Router:
         if da.id in ri and db.id in ri and abs(ri[da.id] - ri[db.id]) == 1:
             self.gapkey[e.id] = (owner.id, min(ri[da.id], ri[db.id]))
 
+    def span_items(self, a, b):
+        """Leaf nodes overlapping the band between a and b (both axes), plus a and b:
+        the things a same-side C-shaped edge must go around."""
+        x0, x1 = min(a.ax, b.ax), max(a.ax + a.w, b.ax + b.w)
+        y0, y1 = min(a.ay, b.ay), max(a.ay + a.h, b.ay + b.h)
+        out = [a, b]
+        for it in self.doc.walk():
+            if isinstance(it, Group) or it in (a, b):
+                continue
+            if it.ay < y1 and it.ay + it.h > y0 and it.ax < x1 and it.ax + it.w > x0:
+                out.append(it)
+        return out
+
     def geometry(self, e: Edge):
         """-> (points, axis). axis: v | h (flow axis), L (explicit L port) or free."""
         a, b = self.doc.items[e.src], self.doc.items[e.dst]
@@ -359,6 +396,17 @@ class Router:
             if v0 != v1:  # L-shape: one corner
                 corner = (p0[0], p1[1]) if v0 else (p1[0], p0[1])
                 return [p0, corner, p1], "L"
+            if ex == en and not wps:  # same side: C-shape around everything in between
+                gap = px(e.style.get("stub"), 24) if e.style.get("stub") else 24.0
+                if ex in ("left", "right"):
+                    lo = min(it.ax for it in self.span_items(a, b)) if ex == "left" else None
+                    hi = max(it.ax + it.w for it in self.span_items(a, b)) if ex == "right" else None
+                    x = lo - gap if ex == "left" else hi + gap
+                    return [p0, (x, p0[1]), (x, p1[1]), p1], "L"
+                lo = min(it.ay for it in self.span_items(a, b)) if ex == "top" else None
+                hi = max(it.ay + it.h for it in self.span_items(a, b)) if ex == "bottom" else None
+                y = lo - gap if ex == "top" else hi + gap
+                return [p0, (p0[0], y), (p1[0], y), p1], "L"
             return [p0] + wps + [p1], ("v" if v0 else "h")
         if d in ("TB", "BT", "LR", "RL") and route != "straight":
             vert = d in ("TB", "BT")
@@ -371,18 +419,21 @@ class Router:
             elif not wps:
                 self._record_channel(e, owner, da, db, vert)
             p0, p1 = self._ports(a, b, vert)
+            spread = (e.id, 0) in self.port_shift or (e.id, 1) in self.port_shift
             s0, s1 = self.port_shift.get((e.id, 0), 0.0), self.port_shift.get((e.id, 1), 0.0)
             if vert:
                 p0, p1 = (p0[0] + s0, p0[1]), (p1[0] + s1, p1[1])
             else:
                 p0, p1 = (p0[0], p0[1] + s0), (p1[0], p1[1] + s1)
-            if s0 or s1:
+            if spread:
+                p0, p1 = on_outline(a, p0, vert), on_outline(b, p1, vert)
                 return [p0] + wps + [p1], ("v" if vert else "h")
             if off:
                 if vert:
                     p0, p1 = (p0[0] + off, p0[1]), (p1[0] + off, p1[1])
                 else:
                     p0, p1 = (p0[0], p0[1] + off), (p1[0], p1[1] + off)
+                p0, p1 = on_outline(a, p0, vert), on_outline(b, p1, vert)
             # boxes overlap on the cross axis: one straight line, no jog / double trace
             boxy = all(x.attrs.get("shape", "box") in RECT_SHAPES or isinstance(x, Group) for x in (a, b))
             if not wps and not off and boxy:

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/scene.py

@@ -16,6 +16,7 @@ import math
 
 from .anim import BORDER_MODES, Track, border_tracks, dash_len, flow_tracks, seconds
 from .ir import Elem, Scene
+from .layout import SUB_GAP, accent_width
 from .model import Document, Edge, Group, Node
 from .route import Diagonal, Router, flow_dir, lca
 from .style import box4, px
@@ -45,7 +46,53 @@ class SceneBuilder:
         layers = [groups_layer, edges_layer, nodes_layer]
         if self.title_layer.children:
             layers.append(self.title_layer)
-        return Scene(root.w, root.h, root.style.get("background"), layers)
+        w, h = root.w, root.h
+        legend, lw, lh = self.legend(h)
+        if legend:
+            layers.append(legend)
+            w, h = max(w, lw), h + lh
+        cap = root.attrs.get("caption")
+        if cap:
+            st = root.part_styles.get("caption") or root.style
+            fs = px(st.get("font-size"), 12)
+            cw, ch, lines = measure(cap, st.get("font-family", "sans-serif"), fs)
+            w = max(w, cw + 28)
+            align = st.get("text-align", "center")
+            x, anchor = {"left": (14, "start"), "right": (w - 14, "end")}.get(align, (w / 2, "middle"))
+            layers.append(Elem("group", cls="pdg-caption", children=self.text(lines, x, h, fs, st, anchor)))
+            h += ch + 14
+        return Scene(w, h, root.style.get("background"), layers)
+
+    def legend(self, top: float) -> tuple[Elem | None, float, float]:
+        """`legend .cls "text"` entries: a key box under the diagram, swatches styled like nodes."""
+        entries = self.doc.legend
+        if not entries:
+            return None, 0.0, 0.0
+        st = self.doc.root.part_styles.get("legend") or {}
+        fs = px(st.get("font-size"), 11)
+        fam = st.get("font-family", self.doc.root.style.get("font-family", "sans-serif"))
+        sw, gap, pad = 14.0, 16.0, 10.0
+        title = self.doc.legend_title
+        tw, th, _ = measure(title, fam, fs, True) if title else (0.0, 0.0, [])
+        x = pad + (tw + gap if title else 0.0)
+        kids, row_h = [], max(sw, fs * 1.25)
+        y0 = top + pad
+        if title:
+            kids += self.text([title], 14 + pad, y0 + (row_h - fs * 1.25) / 2, fs, {**st, "font-weight": "bold"}, "start")
+        for n in entries:
+            ew, _, _ = measure(n.label, fam, fs)
+            ns = n.style
+            r = min(px(ns.get("border-radius"), 3), 4)
+            kids.append(Elem("rect", cls=" ".join(["pdg-legend-swatch"] + n.classes),
+                             geom={"x": 14 + x, "y": y0 + (row_h - sw) / 2, "w": sw, "h": sw, "rx": r},
+                             paint={"fill": ns.get("fill", "#ffffff"), "stroke": ns.get("stroke", "#9ca3af"),
+                                    "stroke-width": 1.2}))
+            kids += self.text([n.label], 14 + x + sw + 6, y0 + (row_h - fs * 1.25) / 2, fs, st, "start")
+            x += sw + 6 + ew + gap
+        bw, bh = x - gap + pad, row_h + 2 * pad
+        box = Elem("rect", cls="pdg-legend-box", geom={"x": 14, "y": top, "w": bw, "h": bh, "rx": 6},
+                   paint={"fill": st.get("fill", "#ffffff"), "stroke": st.get("stroke", "#d1d5db"), "stroke-width": 1})
+        return Elem("group", cls="pdg-legend", children=[box] + kids), bw + 28, bh + 14
 
     # ------------------------------------------------------------ text
     @staticmethod
@@ -113,6 +160,7 @@ class SceneBuilder:
         st = n.style
         shape = n.attrs.get("shape", "box")
         out = Elem("group", id=n.id, cls=" ".join(["pdg-node"] + n.classes), children=self.shape(n, shape, st))
+        out.children += self.accent(n, st)
         fs = px(st.get("font-size"), 14)
         if n.image:
             img = n.image
@@ -130,17 +178,45 @@ class SceneBuilder:
     def _node_text(self, n, st, fs):
         align = st.get("text-align", "center")
         pt, pr, pb, pl = box4(st.get("padding"), 8)
+        pl += accent_width(st, "left")
+        pr += accent_width(st, "right")
         top = n.cy - n.text_h / 2
-        if align == "left":
-            return self.text(n.text_lines, n.ax + pl, top, fs, st, "start")
-        if align == "right":
-            return self.text(n.text_lines, n.ax + n.w - pr, top, fs, st, "end")
-        return self.text(n.text_lines, n.cx, top, fs, st)
+        x, anchor = {"left": (n.ax + pl, "start"), "right": (n.ax + n.w - pr, "end")}.get(align, (n.cx, "middle"))
+        out = self.text(n.text_lines, x, top, fs, st, anchor)
+        if n.sub_lines:
+            sst = n.sub_style or st
+            sfs = px(sst.get("font-size"), 12)
+            stop = top + n.text_h - n.sub_h + SUB_GAP
+            out += self.text(n.sub_lines, x, stop, sfs, sst, anchor)
+        return out
+
+    def accent(self, it, st) -> list[Elem]:
+        """`accent-bar: 4px #22c55e` draws a strip inside the box edge (`accent-side`)."""
+        spec = st.get("accent-bar")
+        if not spec or spec.strip() == "none":
+            return []
+        parts = spec.split()
+        bw = px(parts[0], 4)
+        color = parts[1] if len(parts) > 1 else st.get("stroke", "#22c55e")
+        side = st.get("accent-side", "left")
+        x = it.ax if side == "left" else it.ax + it.w - bw
+        r = min(px(st.get("border-radius"), 6), bw)
+        return [Elem("rect", cls="pdg-accent", geom={"x": x, "y": it.ay, "w": bw, "h": it.h, "rx": r},
+                     paint={"fill": color})]
 
     def group(self, g: Group) -> Elem:
         st = g.style
         out = Elem("group", id=g.id, cls=" ".join(["pdg-group"] + g.classes),
                    children=self.shape(g, g.attrs.get("shape", "box"), st))
+        out.children += self.accent(g, st)
+        if g.label and st.get("title-fill") not in (None, "none") and st.get("label-position", "top") != "bottom":
+            pt = box4(st.get("padding"), 14)[0]
+            bh = pt + g.label_h - 3
+            r = px(st.get("border-radius"), 8)
+            out.children.append(Elem("path", cls="pdg-title-band", paint={"fill": st["title-fill"]}, geom={"segs": [
+                ("M", g.ax, g.ay + bh), ("L", g.ax, g.ay + r), ("A", r, r, 0, 0, 1, g.ax + r, g.ay),
+                ("L", g.ax + g.w - r, g.ay), ("A", r, r, 0, 0, 1, g.ax + g.w, g.ay + r),
+                ("L", g.ax + g.w, g.ay + bh), ("Z",)]}))
         if g.label:
             fs = px(st.get("font-size"), 12)
             pt, pr, pb, pl = box4(st.get("padding"), 14)
@@ -152,6 +228,10 @@ class SceneBuilder:
             x0 = self._title_x(g, st, tw, pl, pr, top, th)
             box = (x0 - TITLE_PAD, top - 2, x0 + tw + TITLE_PAD, top + th + 2)
             texts = self.text(lines, x0, top, fs, st, "start")
+            if g.attrs.get("sub") and not bottom:
+                sst = g.sub_style or st
+                texts += self.text(g.attrs["sub"].split("\n"), x0, top + g.title_h + SUB_GAP,
+                                   px(sst.get("font-size"), 11), sst, "start")
             xs = self._crossings(box[1], box[3], box[0], box[2])
             if xs:
                 # ask the pipeline for a wider group: children are centred, so widening
@@ -288,9 +368,37 @@ class SceneBuilder:
             out.children.append(self.head(kind, tip, dvec, hl, color, width,
                                           self.doc.root.style.get("background", "#ffffff")))
         if e.label:
-            out.children += self.edge_label(e, self.edge_polys[e.id])
+            lab = self.edge_label(e, self.edge_polys[e.id])
+            out.children += lab
+        if e.attrs.get("step"):
+            box = lab[0].geom if e.label else None
+            out.children += self.step_badge(e, self.edge_polys[e.id], box)
         return out
 
+    def step_badge(self, e, poly, label_box=None) -> list[Elem]:
+        """Numbered circle on the edge, a third of the way along its path. With a label the
+        badge sits just left of the label box, so neither covers the other."""
+        st = e.step_style or e.style
+        fs = px(st.get("font-size"), 11)
+        txt = e.attrs["step"][:3]
+        w, h, _ = measure(txt, st.get("font-family", "sans-serif"), fs, True)
+        r = max(w, h) / 2 + 3
+        lens = [math.dist(a, b) for a, b in zip(poly, poly[1:])]
+        goal, acc = sum(lens) / 3, 0.0
+        cx, cy = poly[0]
+        for (a, b), l in zip(zip(poly, poly[1:]), lens):
+            if acc + l >= goal and l:
+                t = (goal - acc) / l
+                cx, cy = a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t
+                break
+            acc += l
+        if label_box:
+            cx, cy = label_box["x"] - r - 3, label_box["y"] + label_box["h"] / 2
+        circ = Elem("circle", cls="pdg-step", geom={"cx": cx, "cy": cy, "r": r},
+                    paint={"fill": st.get("fill", "#374151"), "stroke": self.doc.root.style.get("background", "#ffffff"),
+                           "stroke-width": 1.5})
+        return [circ] + self.text([txt], cx, cy - fs * 1.25 / 2, fs, {**st, "font-weight": st.get("font-weight", "bold")})
+
     @staticmethod
     def head(kind, tip, d, hl, color, width, bg="#ffffff") -> Elem:
         """Arrowhead as plain geometry: tip sits exactly on the target outline.

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/style.py

@@ -134,18 +134,46 @@ class StyleSheet:
 
 
 BOX_KEYS = ("fill", "stroke", "color", "font-size", "stroke-width", "border-radius", "font-weight",
-            "stroke-dasharray", "padding", "border", "border-speed")
+            "stroke-dasharray", "padding", "border", "border-speed", "accent-bar", "accent-side", "title-fill")
 EDGE_KEYS = ("arrow", "head", "head-start", "head-size", "route", "radius", "stub", "flow", "flow-speed",
              "diagonal", "diagonal-angle")
 INHERITED_EDGE_KEYS = tuple(k for k in EDGE_KEYS if k not in ("flow", "head-start"))
+TEXT_KEYS = ("font-family", "font-size", "color", "font-weight", "font-style", "text-align")
 
 
 @dataclass
-class _Label:
-    """Pseudo item so `label` / `edge.x label` selectors match an edge's label."""
+class _Part:
+    """Pseudo item so `label`, `sub`, `step`, `caption`, `legend` selectors match a piece
+    of text that belongs to an item (an edge label, a node subtitle, a step badge, ...)."""
+    kind: str
     classes: list
     id: str = ""
-    kind: str = "label"
+
+
+def part_style(sheet: "StyleSheet", kind: str, owner, anc: list, inherit: dict) -> dict[str, str]:
+    """Style for a text part: inherits text keys from its owner, then CSS for `kind`.
+    Subtitles drop the owner's weight: a bold title should not make the second line bold.
+    `em`/`%` font sizes are relative to the owner's size."""
+    base = {k: inherit[k] for k in TEXT_KEYS if k in inherit and not (kind == "sub" and k == "font-weight")}
+    st = sheet.resolve_vars({**base, **sheet.compute(_Part(kind, list(owner.classes)), [owner] + anc)})
+    fs = st.get("font-size", "").strip()
+    if fs.endswith("em"):
+        st["font-size"] = f"{px(inherit.get('font-size'), 14) * number(fs[:-2], 1, 0.1, 10):.2f}px"
+    elif fs.endswith("%"):
+        st["font-size"] = f"{px(inherit.get('font-size'), 14) * number(fs[:-1], 100, 10, 1000) / 100:.2f}px"
+    return st
+
+
+def number_steps(doc: Document) -> None:
+    """`graph steps=auto`: number every edge without its own `step=` in file order."""
+    if doc.root.attrs.get("steps") != "auto":
+        return
+    n = 0
+    for e in doc.edges:
+        if "step" in e.attrs:
+            continue
+        n += 1
+        e.attrs["step"] = str(n)
 
 
 def apply_styles(doc: Document, target: str | None = None) -> None:
@@ -154,15 +182,19 @@ def apply_styles(doc: Document, target: str | None = None) -> None:
     for css, _ in doc.stylesheets:
         sheet.add(css)
     root = doc.root
+    number_steps(doc)
     root.style = sheet.resolve_vars(sheet.compute(root, []))
+    root.part_styles = {k: part_style(sheet, k, root, [], root.style) for k in ("caption", "legend")}
 
-    for item in doc.walk():
+    for item in [*doc.walk(), *doc.legend]:
         anc = item.ancestors()  # nearest first; root last
         parent = item.parent.style if item.parent else root.style
         st = {k: parent[k] for k in ("font-family",) if k in parent}
         st.update(sheet.compute(item, anc))
         st.update({k: v for k, v in item.attrs.items() if k in BOX_KEYS})
         item.style = sheet.resolve_vars(st)
+        if "sub" in item.attrs:
+            item.sub_style = part_style(sheet, "sub", item, anc, item.style)
     ge = root.attrs
     for e in doc.edges:
         anc = [a for a in (([e.scope] + e.scope.ancestors()) if e.scope is not root else [root]) if a is not None]
@@ -181,9 +213,9 @@ def apply_styles(doc: Document, target: str | None = None) -> None:
             elif k in EDGE_KEYS or k in ("stroke", "color", "stroke-dasharray", "font-size"):
                 st[k] = v
         e.style = sheet.resolve_vars(st)
-        lab = sheet.compute(_Label(e.classes), [e] + anc)
-        e.label_style = sheet.resolve_vars({**{k: e.style[k] for k in ("font-family", "font-size", "color")
-                                               if k in e.style}, **lab})
+        e.label_style = part_style(sheet, "label", e, anc, e.style)
+        if "step" in e.attrs:
+            e.step_style = part_style(sheet, "step", e, anc, e.style)
 
 
 def px(v: str | None, default: float = 0.0) -> float:

{predictygraph-0.1.0 → predictygraph-0.2.1}/src/predictygraph/theme.py

@@ -56,6 +56,8 @@ def load_theme(name: str, base_dir: str = ".", _seen=()) -> dict:
         parent = load_theme(data["extends"], str(path.parent), _seen + (name,))
         for sect in ("palette", "roles", "shape"):
             parent.setdefault(sect, {}).update(data.get(sect, {}))
+        if "css" in data:  # extra rules stack: parent's first, then the child's
+            parent["css"] = parent.get("css", "") + "\n" + data["css"]
         parent["name"] = data.get("name", name)
         parent["dark"] = data.get("dark", parent.get("dark", False))
         data = parent
@@ -104,4 +106,6 @@ def theme_css(name: str, base_dir: str = ".") -> str:
     lines.append("node.solid { fill: var(--fg); stroke: var(--fg); color: var(--bg); }")
     if "edge-width" in shape:
         lines.append(f"edge {{ stroke-width: {shape['edge-width']}; }}")
+    if t.get("css"):  # free-form rules after the generated ones; var(--hue) works here
+        lines.append(t["css"])
     return "\n".join(lines) + "\n"

predictygraph-0.2.1/src/predictygraph/themes/hami.toml

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# The look of the HAMi documentation diagrams: soft blue panels with a header band,
+# white rounded boxes with a bold title and a grey second line (`sub=`), HAMi green
+# for highlighted components (accent bar on the left), numbered steps.
+schema = 1
+name = "hami"
+dark = false
+
+# extra rules after the generated palette CSS (must sit before the first [table])
+css = """
+graph { font-family: "Source Sans 3", "Source Sans Pro", Arial, Helvetica, "Liberation Sans", sans-serif; }
+node  { font-weight: 600; padding: 10px 14px; }
+sub   { color: var(--muted); font-size: 0.85em; }
+group { title-fill: #dbeafe; stroke: #bfdbfe; font-size: 13px; }
+group.green { title-fill: #dcfce7; stroke: #bbf7d0; fill: #f0fdf4; }
+node.green  { fill: #ffffff; stroke: var(--green); accent-bar: 4px var(--green); }
+node.blue   { fill: #ffffff; stroke: var(--blue); accent-bar: 4px var(--blue); }
+step  { fill: var(--green); color: #ffffff; }
+legend { stroke: var(--border); color: var(--fg); }
+caption { color: var(--muted); }
+"""
+
+[palette]
+bg = "#ffffff"
+bg-alt = "#f1f5f9"
+surface = "#ffffff"
+fg = "#1e293b"
+muted = "#64748b"
+border = "#cbd5e1"
+red = "#dc2626"
+orange = "#ea580c"
+yellow = "#ca8a04"
+green = "#16a34a"
+cyan = "#0891b2"
+blue = "#2563eb"
+purple = "#7c3aed"
+
+[roles]
+group-fill = "bg-alt"
+group-text = "fg"
+edge = "muted"
+
+[shape]
+radius = 10

predictygraph-0.2.1/tests/test_annotations.py

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Subtitles, step badges, legend, caption, accent bars and header bands."""
+from predictygraph import build_scene
+from predictygraph.parser import parse
+
+
+def scene(src):
+    doc = parse(src)
+    return doc, build_scene(doc)
+
+
+def classes(sc):
+    out, stack = [], list(sc.layers)
+    while stack:
+        e = stack.pop()
+        out.append(e.cls or "")
+        stack += e.children
+    return " ".join(out)
+
+
+def texts(sc):
+    out, stack = [], list(sc.layers)
+    while stack:
+        e = stack.pop()
+        if e.kind == "text":
+            out.append(e.geom["text"])
+        stack += e.children
+    return out
+
+
+def test_sub_adds_height_and_is_drawn():
+    plain, _ = scene('a "Title"\n')
+    doc, sc = scene('a "Title" sub="second line"\n')
+    assert doc.items["a"].h > plain.items["a"].h
+    assert "second line" in texts(sc)
+
+
+def test_sub_is_not_bold_and_smaller():
+    doc, _ = scene('css { node { font-weight: bold; font-size: 20px; } }\na "T" sub="s"\n')
+    st = doc.items["a"].sub_style
+    assert "font-weight" not in st or st["font-weight"] == "normal"
+    assert float(st["font-size"].rstrip("px")) < 20
+
+
+def test_group_sub_drawn_under_title():
+    doc, sc = scene('group g "Panel" sub="what it does" {\n a\n}\n')
+    assert "what it does" in texts(sc)
+    assert doc.items["g"].label_h > doc.items["g"].title_h
+
+
+def test_steps_auto_and_explicit():
+    doc, sc = scene("graph steps=auto\na -> b\nb -> c step=9\nc -> d\n")
+    assert [e.attrs["step"] for e in doc.edges] == ["1", "9", "2"]
+    assert classes(sc).count("pdg-step") == 3
+
+
+def test_legend_and_caption_grow_canvas():
+    _, base = scene("a -> b\n")
+    _, sc = scene('graph caption="Figure 1"\na -> b\nlegend "Key"\nlegend .green "HAMi"\n')
+    assert sc.height > base.height
+    assert {"Key", "HAMi", "Figure 1"} <= set(texts(sc))
+    assert "pdg-legend-box" in classes(sc)
+
+
+def test_accent_bar_widens_node_and_draws():
+    plain, _ = scene('a "a longer label"\n')
+    doc, sc = scene('css { node { accent-bar: 5px #0f0; } }\na "a longer label"\n')
+    assert doc.items["a"].w == plain.items["a"].w + 5
+    assert "pdg-accent" in classes(sc)
+
+
+def test_title_fill_band():
+    _, sc = scene('css { group { title-fill: #dbeafe; } }\ngroup g "G" {\n a\n}\n')
+    assert "pdg-title-band" in classes(sc)

predictygraph-0.2.1/tests/test_routing.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Routing regressions: edges between the same nodes, and edges fanning out of a
+round node, must stay apart and must not cross."""
+from predictygraph import _style, parse
+from predictygraph.layout import layout
+from predictygraph.route import Router
+
+STATES = """graph dir=LR
+default node shape=circle
+idle "Idle"
+running "Running"
+error "Error"
+done "Done"
+idle -> running "Start"
+running -> error "Fail"
+running -> done "OK"
+error -> running "Retry"
+done -> idle "Reset"
+"""
+
+
+def _ends():
+    doc = _style(parse(STATES), None, None, None)
+    layout(doc)
+    r = Router(doc).route()
+    ends = {}
+    for e in doc.edges:
+        pts, _ = r.geometry(e)
+        ends[(e.src, e.dst)] = (pts[0], pts[-1])
+    return ends
+
+
+def test_edge_and_its_reverse_do_not_overlap():
+    ends = _ends()
+    fail = ends[("running", "error")]
+    retry = ends[("error", "running")]
+    # Fail leaves Running at p0, Retry arrives at Running at p1 (and vice versa at Error)
+    assert abs(fail[0][1] - retry[1][1]) >= 8, "Fail and Retry share a port on Running"
+    assert abs(fail[1][1] - retry[0][1]) >= 8, "Fail and Retry share a port on Error"
+
+
+def test_edges_leaving_one_side_keep_their_order():
+    ends = _ends()
+    # on Running's right side: Fail (to Error, top) above Retry above OK (to Done, bottom)
+    ys = [ends[("running", "error")][0][1], ends[("error", "running")][1][1], ends[("running", "done")][0][1]]
+    assert ys == sorted(ys), f"edges cross on Running's right side: {ys}"
+
+
+def test_shifted_ports_sit_on_the_circle():
+    doc = _style(parse(STATES), None, None, None)
+    layout(doc)
+    r = Router(doc).route()
+    for e in doc.edges:
+        pts, _ = r.geometry(e)
+        for n, p in ((doc.items[e.src], pts[0]), (doc.items[e.dst], pts[-1])):
+            d = ((p[0] - n.cx) / (n.w / 2)) ** 2 + ((p[1] - n.cy) / (n.h / 2)) ** 2
+            assert abs(d - 1) < 0.02, f"{e.src}->{e.dst} end is off the outline of {n.id}"

predictygraph-0.2.1/tests/test_stack.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""align=stretch tiers, same-side C-shaped edges, theme css."""
+from predictygraph import build_scene
+from predictygraph.parser import parse
+from predictygraph.theme import theme_css
+
+
+def test_stretch_makes_tiers_equal_width():
+    doc = parse("graph layout=column align=stretch\ngroup a {\n x\n}\ngroup b {\n p\n q\n r\n}\n")
+    build_scene(doc)
+    assert doc.items["a"].w == doc.items["b"].w
+
+
+def test_same_side_edge_goes_around_boxes_between():
+    src = ("graph layout=column\nlong \"a fairly wide box\"\nmid \"an even wider box in the middle\"\n"
+           "low \"low\"\nlong -> low exit=left enter=left route=ortho\n")
+    doc = parse(src)
+    build_scene(doc)
+    from predictygraph.route import Router
+    pts, _ = Router(doc).geometry(doc.edges[0])
+    assert min(x for x, _ in pts) < doc.items["mid"].ax
+
+
+def test_hami_theme_has_extra_css():
+    css = theme_css("hami")
+    assert "accent-bar" in css and "title-fill" in css
+
+
+def test_png_width_colors_and_single_frame(tmp_path):
+    import pytest
+    pytest.importorskip("cairosvg")  # optional extra: predictygraph[apng]
+    pytest.importorskip("PIL")
+    from PIL import Image
+    from predictygraph.render.apng import write_apng
+    sc = build_scene(parse('a "x"\nb "y"\na -> b\n'))
+    out = write_apng(sc, tmp_path / "d.png", width=300, colors=16)
+    im = Image.open(out)
+    assert im.size[0] == 300 and getattr(im, "n_frames", 1) == 1 and im.mode == "P"

predictygraph-0.1.0/src/predictygraph/render/apng.py

@@ -1,43 +0,0 @@
-# SPDX-FileCopyrightText: 2026 The predictygraph Authors
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-"""APNG writer: Scene IR -> animated PNG (frames sampled from the animation tracks)."""
-from __future__ import annotations
-
-import io
-from pathlib import Path
-
-from ..anim import loop_length
-from ..ir import Scene
-from .svg import write_svg
-
-
-class ApngWriter:
-    def __init__(self, scene: Scene, fps: int = 20, scale: float = 2.0, seconds: float | None = None):
-        self.scene, self.fps, self.scale = scene, fps, scale
-        durs = scene.durations()
-        self.seconds = seconds or (loop_length(durs) if durs else 1.0)
-
-    def _raster(self, svg: str):
-        try:
-            import cairosvg
-        except ImportError as exc:  # pragma: no cover
-            raise RuntimeError("APNG export needs cairosvg: install predictygraph[apng]") from exc
-        from PIL import Image
-        png = cairosvg.svg2png(bytestring=svg.encode(), scale=self.scale)
-        return Image.open(io.BytesIO(png)).convert("RGBA")
-
-    def frames(self):
-        n = max(1, round(self.seconds * self.fps))
-        return [self._raster(write_svg(self.scene, i / self.fps)) for i in range(n)]
-
-    def save(self, out: Path) -> Path:
-        frames = self.frames()
-        frames[0].save(out, format="PNG", save_all=True, append_images=frames[1:],
-                       duration=round(1000 / self.fps), loop=0, disposal=1, blend=0, default_image=False)
-        return out
-
-
-def write_apng(scene: Scene, out: Path, fps: int = 20, scale: float = 2.0, seconds: float | None = None) -> Path:
-    return ApngWriter(scene, fps, scale, seconds).save(out)