predictygraph 0.2.3__tar.gz → 0.2.5__tar.gz

{predictygraph-0.2.3 → predictygraph-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: predictygraph
-Version: 0.2.3
+Version: 0.2.5
 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.3 → predictygraph-0.2.5}/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.3 → predictygraph-0.2.5}/pyproject.toml

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

{predictygraph-0.2.3 → predictygraph-0.2.5}/src/predictygraph/layout.py

@@ -144,14 +144,13 @@ class LineLayout(Layout):
         return (pos, cross) if horizontal else (cross, pos)
 
     def label_gaps(self, horizontal: bool) -> dict[int, float]:
-        """Gap needed after child i so labels of edges between neighbours i and i+1 fit
-        (a row only: a label runs along the gap). Room = label width + arrowhead + margin."""
-        if not horizontal:
-            return {}
+        """Gap needed after child i so what sits on the edges between neighbours i and i+1
+        fits. Row: the edge label (plus its step circle) runs along the gap. Column: a step
+        circle sits beside the edge, so the gap must be at least one circle plus margins."""
         index = {k.id: i for i, k in enumerate(self.kids)}
         need: dict[int, float] = {}
         for e in self.doc.edges:
-            if not e.label:
+            if not (e.label if horizontal else e.attrs.get("step")):
                 continue
             a, b = direct_child(self.doc.items[e.src], self.g), direct_child(self.doc.items[e.dst], self.g)
             if a is None or b is None or a is b:
@@ -159,8 +158,15 @@ class LineLayout(Layout):
             i, j = sorted((index[a.id], index[b.id]))
             if j != i + 1:
                 continue
-            w, _, _ = text_block(e.label, e.label_style or e.style, 11, bold=False)
-            need[i] = max(need.get(i, 0.0), w + 34)
+            step = 0.0
+            if e.attrs.get("step"):  # circle diameter, as drawn by SceneBuilder.step_badge
+                sw, sh, _ = text_block(e.attrs["step"][:3], e.step_style or e.style, 11, bold=True)
+                step = max(sw, sh) + 6
+            if horizontal:
+                w, _, _ = text_block(e.label, e.label_style or e.style, 11, bold=False)
+                need[i] = max(need.get(i, 0.0), w + (step + 6 if step else 0.0) + 34)
+            else:
+                need[i] = max(need.get(i, 0.0), step + 14)
         return need
 
 
@@ -570,20 +576,26 @@ def shift(item: Item, dx: float) -> None:
 
 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. It only moves within its parent's content box and
-    never past a sibling, so nothing overlaps and no group is resized."""
+    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]
-        sibs = [s for s in p.children if s is not item]
-        lo = max([s.ax + s.w + 8 for s in sibs if s.ax + s.w <= item.ax + 1e-6], default=p.ax + p.ox)
-        hi = min([s.ax - 8 for s in sibs if s.ax >= item.ax + item.w - 1e-6], default=p.ax + p.w - pr)
-        new = min(max(ref.cx - item.w / 2, lo), hi - item.w)
-        if abs(new - item.ax) > 0.01:
-            shift(item, new - item.ax)
+        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:

{predictygraph-0.2.3 → predictygraph-0.2.5}/src/predictygraph/scene.py

@@ -477,8 +477,10 @@ class SceneBuilder:
         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."""
+        """Numbered circle for an edge. Next to the label when there is one; on the line a
+        third of the way along when the edge is long enough to hold it with room to spare;
+        otherwise beside the middle of the edge, so a short arrow between stacked boxes
+        stays a visible line and the circle never sits on a box."""
         st = e.step_style or e.style
         st = {**st, "font-weight": st.get("font-weight", "bold")}
         fs = font_size(st, 11)
@@ -488,12 +490,51 @@ class SceneBuilder:
         if label_box:
             cx, cy = label_box["x"] - r - 3, label_box["y"] + label_box["h"] / 2
         else:
-            cx, cy = point_along(poly, 1 / 3)
+            cx, cy = self._step_spot(e, poly, r)
         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 * LINE_H / 2, fs, st)
 
+    STEP_ROOM = 3.0  # an edge must be this many circle diameters long to carry its step
+
+    def _step_spot(self, e, poly, r) -> tuple[float, float]:
+        """Where a label-less step circle goes (see step_badge)."""
+        length = sum(math.dist(a, b) for a, b in zip(poly, poly[1:]))
+        on_line = point_along(poly, 1 / 3)
+        if length >= self.STEP_ROOM * 2 * r and not self._on_a_box(on_line, r, e):
+            return on_line
+        mx, my = point_along(poly, 1 / 2)
+        # the segment holding the midpoint gives the edge's direction there
+        ax, ay, bx, by = *poly[0], *poly[-1]
+        acc, half = 0.0, length / 2
+        for a, b in zip(poly, poly[1:]):
+            seg = math.dist(a, b)
+            if acc + seg >= half:
+                (ax, ay), (bx, by) = a, b
+                break
+            acc += seg
+        d = math.hypot(bx - ax, by - ay) or 1.0
+        nx, ny = -(by - ay) / d, (bx - ax) / d  # unit normal
+        off = r + 4
+        sides = [(mx - nx * off, my - ny * off), (mx + nx * off, my + ny * off)]
+        if abs(by - ay) >= abs(bx - ax):  # vertical-ish edge: prefer the left side
+            sides.sort(key=lambda p: p[0])
+        else:                             # horizontal-ish edge: prefer above
+            sides.sort(key=lambda p: p[1])
+        free = [p for p in sides if not self._on_a_box(p, r, e)]
+        return (free or sides)[0]
+
+    def _on_a_box(self, p, r, e) -> bool:
+        """Would a circle of radius r at p overlap any node box (with a small margin)?"""
+        x, y = p
+        for n in self.doc.walk():
+            if isinstance(n, Group):
+                continue
+            if n.ax - r - 2 < x < n.ax + n.w + r + 2 and n.ay - r - 2 < y < n.ay + n.h + r + 2:
+                return True
+        return False
+
     @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.2.3 → predictygraph-0.2.5}/tests/test_annotations.py

@@ -105,3 +105,22 @@ def test_left_label_is_rotated_and_takes_a_column():
             rotated.append(e.geom["text"])
         stack += e.children
     assert rotated == ["Kernel space"]
+
+
+def test_step_on_short_arrow_sits_beside_it_and_clear_of_boxes():
+    doc, sc = scene('graph layout=column gap=4 steps=auto\na "top box"\nb "bottom box"\na -> b\n')
+    circles = []
+    stack = list(sc.layers)
+    while stack:
+        e = stack.pop()
+        if e.kind == "circle" and "pdg-step" in (e.cls or ""):
+            circles.append(e.geom)
+        stack += e.children
+    (c,) = circles
+    for n in (doc.items["a"], doc.items["b"]):
+        inside_x = n.ax - c["r"] < c["cx"] < n.ax + n.w + c["r"]
+        inside_y = n.ay - c["r"] < c["cy"] < n.ay + n.h + c["r"]
+        assert not (inside_x and inside_y)
+    # the column gap grew to fit the circle, even though gap=4 was asked for
+    a, b = doc.items["a"], doc.items["b"]
+    assert b.ay - (a.ay + a.h) >= 2 * c["r"]

{predictygraph-0.2.3 → predictygraph-0.2.5}/tests/test_stack.py

@@ -82,3 +82,17 @@ def test_accent_bar_stays_inside_rounded_corners():
     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