predictygraph 0.2.2__tar.gz → 0.2.4__tar.gz

{predictygraph-0.2.2 → predictygraph-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: predictygraph
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -27,16 +27,40 @@ Editor support: [tree-sitter-pdg](https://github.com/predictygraph/tree-sitter-p
 Rendered examples and the gallery: [predictygraph.github.io](https://predictygraph.github.io/). This repo keeps
 only `.pdg` sources; images live in the docs repo (git-lfs).
 
+## Install
+
+```bash
+uv tool install "predictygraph[apng]"    # or: pipx install "predictygraph[apng]"
+```
+
+`[apng]` adds PNG output. `pdg` is the short alias of the `predictygraph` command.
+
+## Use
+
 ```bash
-uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg (not committed)
-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
+pdg examples/annotations.pdg                     # -> examples/annotations.svg (not committed)
+pdg diagram.pdg --css theme.css -o out.svg
+pdg diagram.pdg -o out.png                       # PNG (animated if the diagram moves)
+pdg diagram.pdg --check                          # validate only
+pdg diagram.pdg -o d.png --width 1000 --colors 64   # small PNG for chat
+pdg diagram.pdg --target web                     # size labels to fit any browser font
 ```
 
-`pdg` is the short alias of the `predictygraph` command.
+From a checkout, prefix these with `uv run`. Start with
+[examples/annotations.pdg](examples/annotations.pdg): one small diagram that uses every
+annotation feature, with a comment for each.
+
+## Agent skill
+
+[skills/predictygraph](skills/predictygraph) teaches an AI agent to write, render and
+check `.pdg` diagrams.
+
+```bash
+# Hermes Agent
+hermes skills install https://raw.githubusercontent.com/predictygraph/predictygraph/master/skills/predictygraph/SKILL.md
+# Claude Code and other agents that read SKILL.md folders: copy the folder
+cp -r skills/predictygraph ~/.claude/skills/
+```
 
 ## Credits
 

{predictygraph-0.2.2 → predictygraph-0.2.4}/README.md

@@ -13,16 +13,40 @@ Editor support: [tree-sitter-pdg](https://github.com/predictygraph/tree-sitter-p
 Rendered examples and the gallery: [predictygraph.github.io](https://predictygraph.github.io/). This repo keeps
 only `.pdg` sources; images live in the docs repo (git-lfs).
 
+## Install
+
+```bash
+uv tool install "predictygraph[apng]"    # or: pipx install "predictygraph[apng]"
+```
+
+`[apng]` adds PNG output. `pdg` is the short alias of the `predictygraph` command.
+
+## Use
+
 ```bash
-uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg (not committed)
-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
+pdg examples/annotations.pdg                     # -> examples/annotations.svg (not committed)
+pdg diagram.pdg --css theme.css -o out.svg
+pdg diagram.pdg -o out.png                       # PNG (animated if the diagram moves)
+pdg diagram.pdg --check                          # validate only
+pdg diagram.pdg -o d.png --width 1000 --colors 64   # small PNG for chat
+pdg diagram.pdg --target web                     # size labels to fit any browser font
 ```
 
-`pdg` is the short alias of the `predictygraph` command.
+From a checkout, prefix these with `uv run`. Start with
+[examples/annotations.pdg](examples/annotations.pdg): one small diagram that uses every
+annotation feature, with a comment for each.
+
+## Agent skill
+
+[skills/predictygraph](skills/predictygraph) teaches an AI agent to write, render and
+check `.pdg` diagrams.
+
+```bash
+# Hermes Agent
+hermes skills install https://raw.githubusercontent.com/predictygraph/predictygraph/master/skills/predictygraph/SKILL.md
+# Claude Code and other agents that read SKILL.md folders: copy the folder
+cp -r skills/predictygraph ~/.claude/skills/
+```
 
 ## Credits
 

{predictygraph-0.2.2 → predictygraph-0.2.4}/pyproject.toml

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

{predictygraph-0.2.2 → predictygraph-0.2.4}/src/predictygraph/layout.py

@@ -160,6 +160,9 @@ class LineLayout(Layout):
             if j != i + 1:
                 continue
             w, _, _ = text_block(e.label, e.label_style or e.style, 11, bold=False)
+            if e.attrs.get("step"):  # the step badge sits just left of the label
+                bw, bh, _ = text_block(e.attrs["step"][:3], e.step_style or e.style, 11, bold=True)
+                w += max(bw, bh) + 12
             need[i] = max(need.get(i, 0.0), w + 34)
         return need
 
@@ -555,6 +558,43 @@ def absolutize(g: Group, ox: float, oy: float) -> None:
             absolutize(c, c.ax, c.ay)
 
 
+def shift(item: Item, dx: float) -> None:
+    """Move an item sideways by dx after absolutize: its own x (relative to its parent)
+    and the absolute position of it and everything inside it."""
+    item.x += dx
+
+    def move(i: Item) -> None:
+        i.ax += dx
+        if isinstance(i, Group):
+            for c in i.children:
+                move(c)
+    move(item)
+
+
+def align_x(doc: Document) -> None:
+    """`align-x=ID`: centre an item horizontally on another item, e.g. line up a box with
+    the one it calls in the panel below. Siblings on the side it moves towards travel with
+    it, so every gap (and the edge labels in it) keeps its width; the whole block stays
+    inside the parent's content box, so no group is resized and nothing overlaps."""
+    for item in list(doc.walk()):
+        ref = doc.items.get(item.attrs.get("align-x", ""))
+        p = item.parent
+        if ref is None or ref is item or p is None:
+            continue
+        pr = box4(p.style.get("padding"), 14)[1]
+        lo_edge, hi_edge = p.ax + p.ox, p.ax + p.w - pr
+        dx = ref.cx - item.cx
+        if dx > 0:  # item and everything right of it move right, up to the right edge
+            block = [s for s in p.children if s is item or s.ax >= item.ax + item.w - 1e-6]
+            dx = min(dx, hi_edge - max(s.ax + s.w for s in block))
+        else:       # item and everything left of it move left, down to the left edge
+            block = [s for s in p.children if s is item or s.ax + s.w <= item.ax + 1e-6]
+            dx = max(dx, lo_edge - min(s.ax for s in block))
+        if abs(dx) > 0.01:
+            for s in block:
+                shift(s, dx)
+
+
 def layout(doc: Document) -> None:
     root = doc.root
     for e in doc.edges:  # layout may run again after the router widens gaps
@@ -562,6 +602,7 @@ def layout(doc: Document) -> None:
             e.waypoints, e.wp_owner = [], None
     layout_group(root, doc)
     absolutize(root, 0, 0)
+    align_x(doc)
     # translate virtual waypoints into absolute coords and attach to edges
     for g in [root] + [i for i in doc.walk() if isinstance(i, Group)]:
         lay = getattr(g, "layout_obj", None)

{predictygraph-0.2.2 → predictygraph-0.2.4}/src/predictygraph/scene.py

@@ -38,6 +38,43 @@ def point_along(poly: list[tuple[float, float]], frac: float) -> tuple[float, fl
     return poly[-1]
 
 
+def corner_radius(st: dict, shape: str, w: float, h: float) -> float:
+    """The corner radius a box shape is drawn with (shared by the box and its accent bar)."""
+    if shape == "pill":
+        return h / 2
+    r = px(st.get("border-radius"), 0)
+    return max(r, 10) if shape == "round" else r
+
+
+def accent_segs(x: float, y: float, w: float, h: float, bw: float, r: float, side: str) -> list:
+    """Path for a `bw`-wide strip down one side of an (x, y, w, h) box with corner radius r.
+    The outer edge follows the box's corner arcs and the inner edge is straight, so the
+    strip stays inside the rounded outline. Drawn for the left side, mirrored for right."""
+    bw, r = min(bw, w / 2), min(r, h / 2)
+    if r <= 0:
+        pts = [(0, 0), (bw, 0), (bw, h), (0, h)]
+        segs = [("M", *pts[0])] + [("L", *p) for p in pts[1:]]
+    elif bw < r:  # inner edge cuts the corner arc at height dy below the top
+        dy = r - math.sqrt(r * r - (r - bw) ** 2)
+        segs = [("M", 0, r), ("A", r, r, 0, 0, 1, bw, dy), ("L", bw, h - dy),
+                ("A", r, r, 0, 0, 1, 0, h - r)]
+    else:  # strip wider than the radius: full corner arc, then straight along top/bottom
+        segs = [("M", 0, r), ("A", r, r, 0, 0, 1, r, 0), ("L", bw, 0), ("L", bw, h), ("L", r, h),
+                ("A", r, r, 0, 0, 1, 0, h - r)]
+    segs.append(("Z",))
+    flip = side != "left"
+
+    def place(s):
+        if s[0] == "A":  # (A, rx, ry, rot, large, sweep, px, py): mirroring flips the sweep
+            _, rx, ry, rot, large, sweep, px_, py_ = s
+            return ("A", rx, ry, rot, large, 1 - sweep if flip else sweep,
+                    x + (w - px_ if flip else px_), y + py_)
+        if s[0] == "Z":
+            return s
+        return (s[0], x + (w - s[1] if flip else s[1]), y + s[2])
+    return [place(s) for s in segs]
+
+
 class SceneBuilder:
     def __init__(self, doc: Document, router: Router):
         self.doc, self.router = doc, router
@@ -177,11 +214,7 @@ class SceneBuilder:
             paint["opacity"] = st["opacity"]
         if st.get("shadow") == "soft":
             paint["filter"] = "shadow"
-        r = px(st.get("border-radius"), 0)
-        if shape == "round":
-            r = max(r, 10)
-        if shape == "pill":
-            r = h / 2
+        r = corner_radius(st, shape, w, h)
         if shape in ("box", "round", "pill", "note", "square"):
             el = Elem("rect", geom={"x": x, "y": y, "w": w, "h": h, "rx": r}, paint=paint)
         elif shape in ("circle", "ellipse"):
@@ -249,14 +282,14 @@ class SceneBuilder:
         return out
 
     def accent(self, it, st) -> list[Elem]:
-        """`accent-bar: 4px #22c55e` draws a strip inside the box edge (`accent-side`)."""
+        """`accent-bar: 4px #22c55e`: a strip along one side (`accent-side`), clipped to the
+        box's own rounded corners so it never pokes outside them."""
         a = accent(st)
         if not a:
             return []
         bw, color, side = a
-        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},
+        r = min(corner_radius(st, it.attrs.get("shape", "box"), it.w, it.h), it.h / 2)
+        return [Elem("path", cls="pdg-accent", geom={"segs": accent_segs(it.ax, it.ay, it.w, it.h, bw, r, side)},
                      paint={"fill": color or st.get("stroke", "#22c55e")})]
 
     def group(self, g: Group) -> Elem:
@@ -278,7 +311,7 @@ class SceneBuilder:
     def _title_band(self, g: Group, st: dict) -> Elem:
         """`title-fill`: a band behind the title, rounded like the group's top corners."""
         bh = box4(st.get("padding"), 14)[0] + g.label_h - 3
-        r = px(st.get("border-radius"), 8)
+        r = min(corner_radius(st, g.attrs.get("shape", "box"), g.w, g.h), bh)
         return 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),

predictygraph-0.2.4/tests/test_stack.py

@@ -0,0 +1,98 @@
+# 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"
+
+
+def test_align_x_lines_up_across_panels():
+    src = ('graph layout=column align=stretch\n'
+           'group top layout=row gap=20 {\n a "left box"\n b "short"\n}\n'
+           'group bottom layout=row gap=200 {\n c "c"\n d "a much wider box here"\n}\n')
+    plain = parse(src)
+    build_scene(plain)
+    doc = parse(src.replace('b "short"', 'b "short" align-x=d'))
+    build_scene(doc)
+    assert abs(doc.items["b"].cx - doc.items["d"].cx) < 0.5
+    assert abs(plain.items["b"].cx - plain.items["d"].cx) > 1  # it really moved
+
+
+def test_align_x_stays_inside_its_panel():
+    src = ('graph layout=column\n'
+           'group top layout=row gap=20 {\n a "left box"\n b "short" align-x=d\n}\n'
+           'group bottom layout=row gap=400 {\n c "c"\n d "far right"\n}\n')
+    doc = parse(src)
+    build_scene(doc)
+    b, top = doc.items["b"], doc.items["top"]
+    assert b.ax + b.w <= top.ax + top.w
+
+
+def test_align_x_never_overlaps_a_sibling():
+    src = ('graph layout=column\n'
+           'group top layout=row gap=10 {\n a "aaaaaaaa" align-x=z\n b "bbbbbbbb"\n}\n'
+           'group bottom layout=row {\n y "y"\n z "z"\n}\n')
+    doc = parse(src)
+    build_scene(doc)
+    a, b = doc.items["a"], doc.items["b"]
+    assert a.ax + a.w <= b.ax
+
+
+def test_accent_bar_stays_inside_rounded_corners():
+    from predictygraph.scene import accent_segs
+    segs = accent_segs(0, 0, 100, 40, 4, 10, "left")
+    xs = [s[-2] for s in segs if s[0] != "Z"]
+    ys = [s[-1] for s in segs if s[0] != "Z"]
+    assert min(xs) >= 0 and max(xs) <= 4
+    assert min(ys) > 0 and max(ys) < 40  # starts below the top edge: it follows the arc
+    right = accent_segs(0, 0, 100, 40, 4, 10, "right")
+    assert min(s[-2] for s in right if s[0] != "Z") >= 96
+
+
+def test_align_x_keeps_gaps_by_moving_neighbours():
+    src = ('graph layout=column align=stretch\n'
+           'group top layout=row gap=300 {\n p "p"\n q "q"\n}\n'
+           'group bottom layout=row gap=30 {\n a "aaaa" align-x=q\n b "bbbb"\n}\n'
+           'a -> b "a fairly long label"\n')
+    plain = parse(src.replace(" align-x=q", ""))
+    build_scene(plain)
+    doc = parse(src)
+    build_scene(doc)
+    gap = lambda d: d.items["b"].ax - (d.items["a"].ax + d.items["a"].w)
+    assert abs(gap(doc) - gap(plain)) < 0.01  # b moved with a: the label still fits
+    assert doc.items["a"].ax > plain.items["a"].ax

predictygraph-0.2.2/tests/test_stack.py

@@ -1,41 +0,0 @@
-# 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"