mandala: two more motif families — scallops and pinwheel; expand repo keywords

Completes the mandala variety work with the two families held back before:

- `scallops` — a wavy ring of N arcs bulging out from a base circle by `depth`,
  or turned in (`inward`) for a ring of cusps. Reuses `_arc_geometry`, the
  petal's own two-arc helper, with the side that bulges away from the centre —
  no new geometry, Arc only.
- `pinwheel` — small `sides`-gons on a ring, each turned with its position and
  by `twist` so the ring appears to spin. `polar_point` + Polygon, the polygon
  family's own tools.

Both are single-or-list like the other ring families, and both report their
reach so a motif past the pattern area is refused before page one (§ 8.2, § 12).
A second gallery entry, examples/10b-mandala-scallops, shows them.

12 tests, test-first; verified on a real rendered PDF. Spec § 7.11, README,
CLAUDE.md and implementation-decisions (#41) updated.

Keywords: expand pyproject `keywords` from 6 to 19 to cover what the tool
actually does (mandala, maze, staff-paper, polar, tiling, perspective, isometric,
dot-grid, cli, reproducible). The public GitHub repo's topics — previously
empty — were set to a matching 20-topic set out of band (repo metadata, not
tracked in git).

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

Author: DocAtPrompt

CLAUDE.md

@@ -21,9 +21,9 @@ things landed on the handle side, each small and each in the spec: the
 **`pattern.align`** — anchor the grid at a chosen corner (§ 8.5). Since then,
 `--embed-def` — **the PDF carries its own source** as a file attachment (§ 8.8,
 was § 15 open question 5) — open question 3 closed (reportlab is BSD-3-Clause,
-verified), and **`mandala` grew three motif families** — `petals`, `beads` and a
-single-or-list `rosette` (§ 7.11). Only M5's two device edges are left (see *Not
-done*).
+verified), and **`mandala` grew five motif families** — `petals`, `beads`,
+`scallops`, `pinwheel` and a single-or-list `rosette` (§ 7.11). Only M5's two
+device edges are left (see *Not done*).
 0.1.0 is the version in the code; nothing has been released, because releasing
 needs a human *and* the user has chosen to defer PyPI for now (see *Not done*).
 
@@ -69,7 +69,7 @@ and a PNG preview, guarded by `test_every_example_validates`.
 | **M7** PNG writer | raster at exact device resolution, one file per page, text via caps (§ 10.4) |
 | **M8** `perspective` | horizon + 1–3 vanishing-point fans, equal base division, Liang–Barsky clip, `verticals` (§ 7.11) |
 | **M8** `mandala` | sectors/rings scaffold, rosette of circles (`mirror`), inscribed regular / star polygons, on shared `polar_geometry` (§ 7.11) |
-| post-M9 `mandala` motifs | three more families: `petals` (a leaf = two arcs, `Arc` only), `beads` (dots on a ring — introduces `Dot` to the blade, § 7.11 mark line extended), and `rosette` widened to **single-or-list**; `petals`/`beads` take single-or-list too (layered bands). `check`/`_max_reach`/`describe` iterate the rings; the example gallery shows them (§ 7.11) |
+| post-M9 `mandala` motifs | five more families: `petals` (a leaf = two arcs, `Arc` only), `beads` (dots on a ring — introduces `Dot` to the blade, § 7.11 mark line extended), `scallops` (a wavy ring of arcs, `inward` for cusps), `pinwheel` (twisted small polygons on a ring), and `rosette` widened to **single-or-list**; all five ring families take single-or-list (layered bands). `check`/`_max_reach`/`describe` iterate the rings; two gallery entries (`10`, `10b`) show them (§ 7.11) |
 | **M9** `staves` clefs | `treble/bass/alto/tenor` as `Text` in a bundled, subset music font (Bravura, OFL→TrueType), SMuFL placement, 5-line only (§ 15.3) |
 | **M5** relative measure | `%w`/`%h`/`%s` as a fraction of the pattern area, resolved in seam 1 like `px`, `RelativeLengthField` opt-in across the blades (§ 8.11) |
 | post-M9 interactive | `ctrlgrid` with no args → preset browser (preset → pages → output), TTY-guarded, help otherwise (§ 11.2) |

ctrlgrid/generators/mandala.py

@@ -132,6 +132,42 @@ class Beads(Section):
     color: ColorField = "#000000"
 
 
+class Scallops(Section):
+    """A wavy ring: N arcs bulging out from (or into) a base circle (§ 7.11).
+
+    The scallops sit on a base circle at `at` of the outer radius; each arc runs
+    between two adjacent points and bulges by `depth` (a share of the outer
+    radius). `inward` turns the bulge in, for a ring of cusps rather than lobes.
+    Only `Arc`. Count defaults to the sector count.
+    """
+
+    at: float = Field(gt=0.0)
+    count: int | None = Field(default=None, ge=1)
+    depth: float = Field(default=0.06, gt=0.0)
+    inward: bool = False
+    weight: LengthField = HAIRLINE
+    color: ColorField = "#000000"
+
+
+class Pinwheel(Section):
+    """Small polygons repeated round a ring, each twisted (§ 7.11).
+
+    N little `sides`-gons of circumradius `size` (a share of the outer radius)
+    sit on a ring at `at`. Each is turned with its position and by an extra
+    `twist`, which is what makes the ring spin rather than sit still. Only
+    `Polygon`. Count defaults to the sector count.
+    """
+
+    at: float = Field(gt=0.0)
+    size: float = Field(gt=0.0)
+    sides: int = Field(default=4, ge=3)
+    count: int | None = Field(default=None, ge=1)
+    twist: float = 0.0
+    weight: LengthField = HAIRLINE
+    color: ColorField = "#000000"
+    fill_color: ColorField = None
+
+
 class PolygonSpec(Section):
     """An inscribed regular polygon or star polygon (§ 7.11).
 
@@ -165,6 +201,8 @@ class MandalaConfig(BaseModel):
     rosette: Rosette | tuple[Rosette, ...] | None = None
     petals: Petals | tuple[Petals, ...] | None = None
     beads: Beads | tuple[Beads, ...] | None = None
+    scallops: Scallops | tuple[Scallops, ...] | None = None
+    pinwheel: Pinwheel | tuple[Pinwheel, ...] | None = None
     polygons: tuple[PolygonSpec, ...] | None = None
 
     @property
@@ -179,14 +217,24 @@ def petal_rings(self) -> tuple[Petals, ...]:
     def bead_rings(self) -> tuple[Beads, ...]:
         return _as_rings(self.beads)
 
+    @property
+    def scallop_rings(self) -> tuple[Scallops, ...]:
+        return _as_rings(self.scallops)
+
+    @property
+    def pinwheels(self) -> tuple[Pinwheel, ...]:
+        return _as_rings(self.pinwheel)
+
     @model_validator(mode="after")
     def _something_has_to_be_drawn(self) -> MandalaConfig:
-        if not any(
-            (self.rings, self.spokes, self.rosette, self.petals, self.beads, self.polygons)
-        ):
+        if not any((
+            self.rings, self.spokes, self.rosette, self.petals, self.beads,
+            self.scallops, self.pinwheel, self.polygons,
+        )):
             raise ValueError(
-                "a mandala needs `rings`, `spokes`, a `rosette`, `petals`, `beads` or "
-                "`polygons` — with none there is only an empty disc (§ 7.11)"
+                "a mandala needs `rings`, `spokes`, a `rosette`, `petals`, `beads`, "
+                "`scallops`, a `pinwheel` or `polygons` — with none there is only an "
+                "empty disc (§ 7.11)"
             )
         return self
 
@@ -244,6 +292,14 @@ def describe(self, cfg: MandalaConfig) -> list[str]:
         for beads in cfg.bead_rings:
             count = beads.count if beads.count is not None else cfg.sectors
             lines.append(f"beads: {count} at {beads.at:.2f} of the radius")
+        for scallops in cfg.scallop_rings:
+            count = scallops.count if scallops.count is not None else cfg.sectors
+            lines.append(f"scallops: {count} at {scallops.at:.2f} of the radius")
+        for pinwheel in cfg.pinwheels:
+            count = pinwheel.count if pinwheel.count is not None else cfg.sectors
+            lines.append(
+                f"pinwheel: {count} {pinwheel.sides}-gons at {pinwheel.at:.2f} of the radius"
+            )
         for index, spec in enumerate(cfg.polygons or ()):
             sides = spec.sides if spec.sides is not None else cfg.sectors
             shape = f"{{{sides}/{spec.step}}}" if spec.step > 1 else f"{sides}-gon"
@@ -296,6 +352,10 @@ def generate(
             yield from _petals(petals, cfg.sectors, center, outer)
         for beads in cfg.bead_rings:
             yield from _beads(beads, cfg.sectors, center, outer)
+        for scallops in cfg.scallop_rings:
+            yield from _scallops(scallops, cfg.sectors, center, outer)
+        for pinwheel in cfg.pinwheels:
+            yield from _pinwheel(pinwheel, cfg.sectors, center, outer)
         for spec in cfg.polygons or ():
             yield _polygon(spec, cfg.sectors, center, outer)
 
@@ -420,6 +480,63 @@ def _beads(beads: Beads, sectors: int, center: Point, outer: Um) -> Iterator[Dot
         )
 
 
+def _scallops(scallops: Scallops, sectors: int, center: Point, outer: Um) -> Iterator[Arc]:
+    """A closed wavy ring: one arc between each pair of adjacent base points."""
+    count = scallops.count if scallops.count is not None else sectors
+    at = round(scallops.at * outer)
+    depth = round(scallops.depth * outer)
+    points = [polar_point(center, at, UP + i * 360.0 / count) for i in range(count)]
+    for i in range(count):
+        p1, p2 = points[i], points[(i + 1) % count]
+        side = _outward_side(p1, p2, center, inward=scallops.inward)
+        o, radius, start, sweep = _arc_geometry(p1, p2, depth, side)
+        yield Arc(
+            center=o,
+            radius=radius,
+            start_angle=start,
+            sweep=sweep,
+            weight=scallops.weight.mm,
+            color=scallops.color or "#000000",
+            layer=Layer.PATTERN,
+        )
+
+
+def _outward_side(p1: Point, p2: Point, center: Point, *, inward: bool) -> float:
+    """Which side of the chord bulges away from the centre (§ 7.11).
+
+    `_arc_geometry` bulges toward the perpendicular `(-dy, dx)` scaled by the
+    returned sign; picking the sign that points away from the centre makes a
+    lobe, its opposite makes a cusp.
+    """
+    mx, my = (p1.x + p2.x) / 2, (p1.y + p2.y) / 2
+    dx, dy = p2.x - p1.x, p2.y - p1.y
+    outward = (-dy) * (mx - center.x) + dx * (my - center.y)
+    side = 1.0 if outward >= 0 else -1.0
+    return -side if inward else side
+
+
+def _pinwheel(pinwheel: Pinwheel, sectors: int, center: Point, outer: Um) -> Iterator[Polygon]:
+    """Small polygons round a ring, each turned with its place and by `twist`."""
+    count = pinwheel.count if pinwheel.count is not None else sectors
+    at = round(pinwheel.at * outer)
+    size = round(pinwheel.size * outer)
+    for i in range(count):
+        angle = UP + i * 360.0 / count
+        hub = polar_point(center, at, angle)
+        points = tuple(
+            polar_point(hub, size, angle + pinwheel.twist + k * 360.0 / pinwheel.sides)
+            for k in range(pinwheel.sides)
+        )
+        yield Polygon(
+            points=points,
+            closed=True,
+            weight=pinwheel.weight.mm,
+            color=pinwheel.color or "#000000",
+            fill_color=pinwheel.fill_color,
+            layer=Layer.PATTERN,
+        )
+
+
 def _rosette(rosette: Rosette, sectors: int, center: Point, outer: Um) -> Iterator[Arc]:
     at = round(rosette.at * outer)
     radius = round(rosette.radius * outer)
@@ -478,6 +595,12 @@ def _max_reach(cfg: MandalaConfig, outer: Um) -> tuple[Um, str]:
         reaches.append((round(share * outer), "petals"))
     for beads in cfg.bead_rings:
         reaches.append((round(beads.at * outer) + round(beads.size.um / 2), "beads"))
+    for scallops in cfg.scallop_rings:
+        # Outward lobes reach `at + depth`; cusps turned in reach only the ring.
+        share = scallops.at + (0.0 if scallops.inward else scallops.depth)
+        reaches.append((round(share * outer), "scallops"))
+    for pinwheel in cfg.pinwheels:
+        reaches.append((round((pinwheel.at + pinwheel.size) * outer), "pinwheel"))
     for index, spec in enumerate(cfg.polygons or ()):
         reaches.append((round(spec.radius * outer), f"polygons.{index}"))
     return max(reaches, key=lambda item: item[0])

docs/implementation-decisions.md

@@ -635,13 +635,13 @@ no extension — a preset name like `millimeter-a4` is not a filename until it d
 **§ 7.11.** Making `mandala` more varied added three families (`petals`,
 `beads`, and a widened `rosette`). Three calls were made where § 7.11 was silent:
 
-- **A motif ring is single *or* a list.** `rosette`, `petals` and `beads` each
-  accept one mapping or a list of them (`Rosette | tuple[Rosette, ...]`), so a
-  band can be stacked at several radii. A single mapping still validates, so the
-  old example and preset are untouched — backward compatibility over a second
-  plural key. `polygons` stays a plain list, as it already was. A `_as_rings`
-  helper normalises to a tuple so `generate`/`check`/`describe`/`_max_reach`
-  iterate one shape.
+- **A motif ring is single *or* a list.** `rosette`, `petals`, `beads`,
+  `scallops` and `pinwheel` each accept one mapping or a list of them
+  (`Rosette | tuple[Rosette, ...]`), so a band can be stacked at several radii. A
+  single mapping still validates, so the old example and preset are untouched —
+  backward compatibility over a second plural key. `polygons` stays a plain list,
+  as it already was. A `_as_rings` helper normalises to a tuple so
+  `generate`/`check`/`describe`/`_max_reach` iterate one shape.
 - **A petal is two arcs, not a new primitive.** § 6 fixes six primitives and
   § 15.2 forbids free paths. A pointed leaf is two circular arcs meeting at a
   base and a tip: `_arc_geometry` turns two endpoints and a sagitta into a
@@ -653,9 +653,17 @@ no extension — a preset name like `millimeter-a4` is not a filename until it d
   bead ring is not new vocabulary, only a mark the blade had not used; the
   spec's § 7.11 mark line is extended to say so rather than adding it silently.
 
+Two later families joined on the same terms. **`scallops`** — a wavy ring — is N
+arcs between adjacent base points, each reusing `_arc_geometry` with the side
+that bulges away from the centre (`inward` flips it to cusps); no new geometry,
+the petal's own two-arc helper. **`pinwheel`** — small polygons turned round a
+ring — is `polar_point` + `Polygon`, the polygon family's own tools. Both are
+single-or-list like the rest.
+
 The area check follows the existing rule (§ 8.2, § 12 point 13): each ring
 reports its reach — petal tip (`outer`, with a lateral term for a fat leaf),
-bead ring (`at + size/2`) — so a motif past the pattern area is refused before
+bead ring (`at + size/2`), scallop lobe (`at + depth`, or `at` for cusps),
+pinwheel (`at + size`) — so a motif past the pattern area is refused before
 page one, named, never clipped.
 
 ---

examples/10b-mandala-scallops.pdf

@@ -0,0 +1,54 @@
+# mandala (variant) — the same blade, a different character: a scalloped outer
+# border, a pinwheel of tilted squares, a second scalloped ring turned inward
+# around a flower-of-life centre, and a small bead ring. Sixteen-fold. A4.
+# Regenerate:  ctrlgrid -d examples/10b-mandala-scallops.yaml -o out.pdf
+version: 1
+
+defs:
+  guide: &guide "#c2c8d0"
+  petal: &petal "#8aa0b8"
+  star:  &star  "#2f5686"
+
+page:
+  format: a4
+  margin: 16mm
+
+generator: mandala
+sectors: 16
+outer_radius: 48%s
+
+rings:
+  count: 4
+  weight: 0.15pt
+  color: *guide
+spokes:
+  inner: 0.06
+  weight: 0.15pt
+  color: *guide
+
+# Two wavy rings: thirty-two lobes bulging out at the rim, and sixteen turned
+# inward (cusps) around the centre.
+scallops:
+  - {at: 0.98, count: 32, depth: 0.05, color: *star}
+  - {at: 0.62, count: 16, depth: 0.05, inward: true, color: *petal}
+
+# A pinwheel: sixteen little squares on a ring, each twisted 22° so the ring
+# looks to spin.
+pinwheel:
+  at: 0.80
+  size: 0.10
+  sides: 4
+  count: 16
+  twist: 22
+  weight: 0.2pt
+  color: *star
+
+# A flower-of-life rosette and a small bead ring at the middle.
+rosette:
+  at: 0.34
+  radius: 0.16
+  mirror: true
+  weight: 0.2pt
+  color: *petal
+beads:
+  - {at: 0.16, count: 16, size: 1.0mm, color: *star}

examples/10b-mandala-scallops.yaml

@@ -30,6 +30,7 @@ proportionally.
 | <img src="previews/08-form-weekly.png" width="220"> | **`form`** — a weekly planner: seven day rows with a done-box, then a notes block.<br>[`08-form-weekly.yaml`](08-form-weekly.yaml) · [PDF](08-form-weekly.pdf) |
 | <img src="previews/09-perspective-2pt.png" width="220"> | **`perspective`** — a two-point drawing grid: a horizon, two vanishing points off the sheet, and true verticals.<br>[`09-perspective-2pt.yaml`](09-perspective-2pt.yaml) · [PDF](09-perspective-2pt.pdf) |
 | <img src="previews/10-mandala.png" width="220"> | **`mandala`** — a twelve-fold template: guide rings and spokes, a flower-of-life rosette, a double ring of lotus petals, two bead rings and a twelve-sided frame.<br>[`10-mandala.yaml`](10-mandala.yaml) · [PDF](10-mandala.pdf) |
+| <img src="previews/10b-mandala-scallops.png" width="220"> | **`mandala`** (variant) — the same blade, a different character: a scalloped outer border, a pinwheel of tilted squares, an inward-turned scalloped ring and a flower-of-life centre.<br>[`10b-mandala-scallops.yaml`](10b-mandala-scallops.yaml) · [PDF](10b-mandala-scallops.pdf) |
 | <img src="previews/11-cover-calibration.png" width="220"> | **`--cover`** — the calibration cover sheet (§ 8.8): a 50 mm square and 100 mm rule to catch a scaling print driver, a ladder of stroke weights so you see how each one prints, and a settings summary. The preview is the cover; the grid it precedes is page two.<br>[`11-cover-calibration.yaml`](11-cover-calibration.yaml) · [PDF](11-cover-calibration.pdf) |
 
 The maze booklet uses a fixed seed for a reproducible set — regenerate it with:

examples/README.md

@@ -1105,12 +1105,18 @@ Die Motivfamilien (jede optional):
 - **`beads`** — Punkte gleichmäßig auf einem Ring (`at`, `count`, `size`,
   `rotate`); führt `Dot` ein. `Dot` ist ein reguläres Primitiv (§ 6), also kein
   neues Vokabular, nur eine bisher ungenutzte Marke.
+- **`scallops`** — ein gewellter Ring aus N Bögen, die von einem Basiskreis
+  (`at`) um `depth` nach außen wölben; `inward` dreht die Wölbung nach innen
+  (Spitzen statt Lappen). Nur `Arc`.
+- **`pinwheel`** — kleine `sides`-Ecke (Umkreisradius `size`) auf einem Ring
+  (`at`), jede mit ihrer Position und um `twist` gedreht — ein Windrad. Nur
+  `Polygon`.
 - **`polygons`** — einbeschriebene reguläre oder Sternpolygone.
 
-**Motivring einzeln oder als Liste.** `rosette`, `petals` und `beads` nehmen
-entweder eine einzelne Angabe **oder** eine Liste — gestapelte Bänder in
-verschiedenen Radien. Eine einzelne Map bleibt gültig, ältere Defs laufen
-unverändert. (`polygons` ist wie bisher stets eine Liste.)
+**Motivring einzeln oder als Liste.** `rosette`, `petals`, `beads`, `scallops`
+und `pinwheel` nehmen entweder eine einzelne Angabe **oder** eine Liste —
+gestapelte Bänder in verschiedenen Radien. Eine einzelne Map bleibt gültig,
+ältere Defs laufen unverändert. (`polygons` ist wie bisher stets eine Liste.)
 
 Beide sind bewusst **nicht** in v1. Sie stehen hier, damit die Architektur sie
 nicht ausschließt — insbesondere `Arc` und `Polygon` im Vokabular (§ 6) und die

examples/previews/10b-mandala-scallops.png

@@ -14,7 +14,12 @@ license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.11"
 authors = [{ name = "DocAtPrompt (Alexander Erben)" }]
-keywords = ["pdf", "graph-paper", "grid", "template", "eink", "remarkable"]
+keywords = [
+    "pdf", "pdf-generation", "graph-paper", "grid-paper", "dot-grid",
+    "isometric", "printable", "template", "reproducible", "cli",
+    "eink", "remarkable", "mandala", "maze", "staff-paper", "sheet-music",
+    "polar-graph", "tiling", "perspective-grid",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",