comicforge 0.0.4__tar.gz → 0.2.0__tar.gz

{comicforge-0.0.4 → comicforge-0.2.0}/.claude/skills/comicforge/SKILL.md

@@ -42,13 +42,19 @@ needs no Python (see [`reference.md`](reference.md)).
    pixel_dir:  "../pixel"
    ```
 3. Validate before rendering: `cmf validate mystrip.yaml` — checks every actor,
-   scene, pixel sprite, slot variant, pose, and bubble speaker against the
-   libraries without drawing anything, and lists *all* problems at once. Unlike
-   `render`, it flags mis-spelled keys (e.g. `fcae:`) that render silently
-   ignores. Exits non-zero when anything is wrong. Works on page and `scene` specs.
+   scene, raster `image:`, pixel sprite, slot variant, pose, and bubble speaker
+   against the libraries without drawing anything, and lists *all* problems at
+   once. Unlike `render`, it flags mis-spelled keys (e.g. `fcae:`, `imge:`) that
+   render silently ignores. Exits non-zero when anything is wrong. Works on page
+   and `scene` specs.
 4. Render:
    - comic page: `cmf render mystrip.yaml -o out.pdf`
    - single illustration: `cmf scene myscene.yaml -o out.png`
+   - one panel of a page (to iterate on a single panel without re-reading the
+     whole page): `cmf panel mystrip.yaml --row 0 --col 1 -o panel.png`
+     (0-indexed; defaults to row 0 col 0), or `--all` to write every panel into a
+     directory. This is the right way to inspect one panel — **do not** render the
+     full page and crop it with ImageMagick or other tooling.
    - one character on its own (to eyeball a pose/expression):
      `cmf character bara sit happy --library examples/pes/characters`
      — extra args are bare pose/variant names or `key=value` (`pose=walk`,
@@ -69,21 +75,33 @@ Every position inside a panel is a **fraction 0..1 of that panel**:
 
 ```yaml
 title: "Optional page title"      # bold caption strip at the top
+title_style: {font_size: 26, color: "#21304a"}   # optional
 type: page                        # page (default) | scene — see below
 page: A4                          # A4 | A5 | letter | [w_mm, h_mm]
+bg: "#ffffff"                     # paper colour
 px_per_mm: 4                      # raster scale (vector PDF ignores it)
 margin_mm: 14
 gutter_mm: 6
+frame:                            # panel outline, page-wide; a panel's own
+  width: 3.5                      #   `frame:` overrides. width 0 = no line
+  color: "#21304a"
+  radius: 10                      #   corner radius (also clips the art)
 library:    "../characters"   # path to character dir
 scenes_dir: "../scenes"       # path to scenes dir (omit if no scenes used)
 pixel_dir:  "../pixel"        # path to pixel-art dir (omit if inline only)
 
 rows:                             # page is a stack of rows…
-  - height: 1.0                   # relative row height (default 1)
+  - height: 1.0                   # relative row height (default 1), or
+                                  #   height_mm: 60 for a fixed height —
+                                  #   weighted rows share what is left
     panels:                       # …each row is a left→right list of panels
       - width: 1.0                # relative panel width (default 1)
         bg: "#fbfaf6"             # optional flat panel background
+        frame: {width: 0}         # optional per-panel outline override
+        caption: "Rain came."     # narration band under the art, inside the
+                                  #   frame; or {text:, max_chars:}
         scene: dvur               # optional scene background (see below)
+        image: "art/01.png"       # optional raster background (see below)
         actors: [ ... ]           # characters (drawn back→front in list order)
         pixel:  [ ... ]           # pixel-art sprites (drawn behind actors)
         bubbles:[ ... ]           # speech/thought/shout (drawn on top)
@@ -123,22 +141,62 @@ Confirm scenes/slots with `comicforge scenes --scenes <project>/scenes`.
 Seeds in `examples/pes/`: `dvur` (farmyard, slot `weather: clear|rain`),
 `pokoj` (room, no slots). Both live in `examples/pes/scenes/`.
 
+### image (raster panel background)
+
+When the panel art is a finished bitmap — a generated or photographed image
+rather than a `scene:` built from SVG — point the panel at it with `image:`.
+Everything else works unchanged: bubbles, actors and pixel art all compose on
+top of it.
+
+```yaml
+image: "../refs/panels/01.png"          # path, relative to the *spec file*
+image: {src: "01.png", fit: contain}    # or the long form, to pick the fit
+```
+
+- `fit: cover` (the default) scales the image to fill the panel and
+  centre-crops the overflow — a 3:2 image in a 4:3 panel crops rather than
+  distorts, exactly like a `scene:` background.
+- `fit: contain` scales it to fit *inside* the panel; the leftover strips show
+  the panel's `bg:` colour.
+- `.png`, `.jpg`/`.jpeg`, `.gif` and `.webp` are supported.
+- The image is **embedded** as a base64 data URI, so an `.svg` or `.pdf` render
+  is one self-contained file that still works when moved. That also means the
+  output carries the full byte weight of every image on the page — expect large
+  files for a page of full-res panels.
+- `image:` and `scene:` can coexist; the scene draws over the image.
+
+A standalone illustration can be image-backed too — set `type: scene` with an
+`image:` and no `scene:`, and the canvas is sized from the image's own pixel
+dimensions times `scale:` (default `1`, i.e. one output px per image px).
+
+**Where bubbles land on a raster panel.** There are no actors to anchor to, so
+`speaker:` is meaningless — use `x`/`y`/`to` fractions, or leave them out. A
+bubble with no `y` is placed below the measured bottom of the bubble before it,
+starting near the panel top, so any number of bubbles of any length stack
+without overlapping. A bubble with no `x` is horizontally centred. Every
+bubble — explicit or automatic — is then nudged so it stays inside the panel
+(one wider or taller than the panel is centred instead). A generated spec can
+therefore emit dialogue in order and omit the coordinates entirely.
+
 ## Standalone illustration (no comic grid)
 
-Render one scene filling the whole canvas with actors/bubbles on top — good for
-covers and single panels. Render with `comicforge scene file.yaml -o out.png`.
+Render one background filling the whole canvas with actors/bubbles on top —
+good for covers and single panels. Render with
+`comicforge scene file.yaml -o out.png`.
 
 Set `type: scene` so the spec declares which command renders it: `render`
 rejects a scene spec (and `scene` rejects a page spec) with a clear message
 instead of a confusing crash, and `validate` checks the type matches the
 structure. `type:` is optional — when omitted it's inferred (a top-level
-`scene` with no `rows` == a scene) — but declare it on standalone illustrations.
+background — `scene` or `image` — with no `rows` == a scene) — but declare it
+on standalone illustrations.
 
 ```yaml
 title: "Optional"
 type: scene
-scene: {name: dvur, weather: clear}
-scale: 3                    # px per scene unit (canvas = scene viewbox × scale)
+scene: {name: dvur, weather: clear}   # …or `image: cover.png` instead
+scale: 3                    # px per scene unit (canvas = scene viewbox × scale);
+                            # with `image:` it's output px per image px, default 1
 library:    "../characters"
 scenes_dir: "../scenes"
 actors:  [ ... ]            # same actor grammar; x/y/scale are canvas fractions
@@ -153,13 +211,44 @@ bubbles: [ ... ]
   kind: speech      # speech | thought | shout
   speaker: tom      # OPTIONAL: auto-place above this actor + aim the tail at
                     #           their head. Prefer this over manual x/y/to.
+  at: tr            # OPTIONAL corner/edge to hug: tl t tr l c r bl b br.
+                    #           Each column (l/c/r) stacks its own top and
+                    #           bottom, so tl + tr sit side by side.
   x: 0.5            # OPTIONAL bubble centre (panel fraction); else from speaker
-  y: 0.18           # OPTIONAL; omit and bubbles stack downward without overlap
+  y: 0.18           # OPTIONAL; omit and bubbles stack downward by measured
+                    #           height, so they never overlap. All bubbles are
+                    #           kept inside the panel.
   to: [0.4, 0.5]    # OPTIONAL tail target (panel fraction); else speaker's head
   max_chars: 22     # wrap width (optional)
-  fs: 16            # font size px (optional)
+  fs: 16            # font size px (optional; overrides bubble_style.font_size)
+  uppercase: true   # OPTIONAL: force this bubble's text to CAPS
+                    #           (overrides bubble_style.uppercase)
 ```
 
+**Page-wide bubble defaults** — set `bubble_style` at the *top level* of a
+page or scene spec to style every bubble at once; per-bubble keys override:
+
+```yaml
+bubble_style:
+  uppercase: true   # render all bubble text in CAPS (classic comic lettering)
+  font_size: 16     # default font size px for all bubbles
+  pad: 14           # text inset from the outline
+  radius: 18        # speech-bubble corner radius
+  stroke: "#21304a" # outline colour;  stroke_width: 3;  fill: "#ffffff"
+  ink: "#21304a"    # text colour;  font: "DejaVu Sans, sans-serif"
+  em: 1.0           # width scale of the text measure — 0.8 for a narrow
+                    #   handwriting font, so bubbles hug the words
+rows: [ ... ]
+```
+
+**Captions** — narration, as opposed to a character's bubble — go in a band
+along the bottom of the panel, inside the frame, separated from the art by a
+hairline in the frame colour. The art box shrinks to make room, so bubble and
+actor coordinates stay relative to the picture. Page-wide look via
+`caption_style` (`font`, `font_size`, `ink`, `bg`, `pad`, `max_chars`,
+`align: left|center`, `rule`, `uppercase`); `comicforge.caption.height(text, style)` tells
+you how tall a band will be, for sizing rows.
+
 `thought` draws an ellipse with a trail of dots; `shout` draws a spiky burst.
 The tail is a slim line dropping from the bubble underside; its tip is capped
 short so it never overlaps the figure.

{comicforge-0.0.4 → comicforge-0.2.0}/.claude/skills/comicforge/reference.md

@@ -435,10 +435,14 @@ renders a default-faced, default-posed actor with no error. `validate` flags:
 - poses an actor asks for that the character lacks
 - slot variants that don't exist for the chosen character+pose / scene
 - actor / scene keys that aren't reserved and aren't a real slot (likely typos)
+- panel keys the renderer doesn't know — `imge:` for `image:`, say
+- raster `image:` files that are missing, unreadable, or of an unsupported type;
+  an `image:` with no `src`, an unknown image key, an unknown `fit`
 - bubble `speaker` naming no actor in the panel; unknown bubble `kind`
 - structural holes (a page with no `rows`, a row with no `panels`, a bubble with
-  no `text`); an unknown `type:`, or a `type:` that contradicts the structure
-  (a `scene` spec carrying `rows`)
+  no `text`, a `scene` spec with neither `scene:` nor `image:`); an unknown
+  `type:`, or a `type:` that contradicts the structure (a `scene` spec carrying
+  `rows`)
 
 Exits `0` when the spec is sound, `1` (with a bulleted problem list) otherwise —
 so it works in a pre-render check or CI.
@@ -588,14 +592,41 @@ Do **not** auto-vectorize the result — hand/LLM-author the SVG using it as a g
 
 For the full spec grammar, see [SKILL.md](SKILL.md). Key points:
 
-- **Page-level keys**: `title`, `page` (A4/A5/letter/[w,h]), `px_per_mm`,
-  `margin_mm`, `gutter_mm`, `library`, `scenes_dir`, `pixel_dir`
-- **Rows and panels**: `rows[].height` (relative weight), `rows[].panels[].width`
-  (relative weight), panel keys: `bg`, `scene`, `actors`, `pixel`, `bubbles`
+- **Page-level keys**: `title`, `title_style` (`font_size`, `color`, `font`),
+  `page` (A4/A5/letter/[w,h]), `bg` (paper colour), `px_per_mm`, `margin_mm`,
+  `gutter_mm`, `library`, `scenes_dir`, `pixel_dir`,
+  `frame` (panel outline: `width` in px, 0 for none; `color`; `radius` — the
+  corner radius also clips the art),
+  `bubble_style` (page-wide bubble look: `font`, `font_size`, `pad`, `radius`,
+  `stroke`, `stroke_width`, `fill`, `ink`, `uppercase`, `em` — width scale of
+  the text measure for narrower fonts)
+- **Rows and panels**: `rows[].height` (relative weight) or `rows[].height_mm`
+  (fixed; weighted rows share the rest, all-fixed leaves the bottom blank),
+  `rows[].panels[].width` (relative weight), panel keys: `bg`, `frame`
+  (per-panel override), `caption` (narration band under the art, inside the
+  frame: a string or `{text, max_chars}`; page-wide `caption_style` with
+  `font`, `font_size`, `ink`, `bg`, `pad`, `max_chars`, `align`, `rule`, `uppercase`),
+  `scene`, `image`, `actors`, `pixel`, `bubbles` — `validate` flags any other
+  panel key as a typo
+- **Image keys**: `image: path.png` or `image: {src:, fit:}` with
+  `fit: cover` (default; scale-to-fill + centre-crop) or `contain`
+  (fit inside + letterbox). The path resolves against the spec file's dir and
+  the image is embedded as a base64 data URI, so SVG/PDF output stays
+  self-contained. A `type: scene` spec can use `image:` in place of `scene:`,
+  and takes its canvas size from the image
 - **Actor keys**: `char`, `pose` (optional; defaults to the character's default
   pose), per-slot variant keys (`face`, `arms`, etc.), `x`, `y`, `scale`, `flip`
 - **Bubble keys**: `text`, `kind` (speech/thought/shout), `speaker`, optional
-  `x`/`y`/`to`/`max_chars`/`fs`
+  `at`/`x`/`y`/`to`/`max_chars`/`fs`/`uppercase` (`fs` and `uppercase` override
+  the page-level `bubble_style`). Omit `y` and bubbles stack down by their
+  measured height without overlapping; omit `x` and they centre (or sit above
+  their `speaker`). `at` hugs a corner or edge instead — `tl`, `t`, `tr`, `l`,
+  `c`, `r`, `bl`, `b`, `br` — and each column keeps its own top and bottom
+  stack, so `tl` + `tr` sit side by side and `bl` climbs up from the bottom.
+  `to: [x, y]` (panel fractions) aims a tail without a speaker. Every bubble is
+  kept inside the panel — so a generated spec over raster panels, which has no
+  `speaker` to anchor to, can omit coordinates entirely, or place each with `at`
+  to keep it off the faces
 - **Pixel keys**: `art` (library name) or `grid`+`palette`, plus `x`/`y`/`scale`
 
 ---

{comicforge-0.0.4 → comicforge-0.2.0}/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libcairo2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
 
@@ -70,7 +70,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libcairo2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
 

{comicforge-0.0.4 → comicforge-0.2.0}/.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v10.0.1
 
       - name: Build sdist + wheel
         run: uv build

{comicforge-0.0.4 → comicforge-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: comicforge
-Version: 0.0.4
+Version: 0.2.0
 Summary: A tiny, scriptable comic-page engine — author comics as YAML, render to SVG / PNG / PDF
 Requires-Python: >=3.13
 Requires-Dist: cairosvg>=2.7

{comicforge-0.0.4 → comicforge-0.2.0}/comicforge/__init__.py

@@ -7,4 +7,4 @@ Designed so an LLM (or you) can author pages as plain declarative text.
 from .pixelart import PixelLibrary  # noqa: F401
 from .render import load_spec, render_scene, render_spec  # noqa: F401
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

comicforge-0.2.0/comicforge/bubbles.py

@@ -0,0 +1,232 @@
+"""Speech bubbles: speech, thought, and shout, with naive word-wrap + tails.
+
+All coordinates here are absolute page px. A bubble is positioned by its centre
+(bx, by); the tail points toward `tail` (also page px).
+"""
+
+from __future__ import annotations
+
+import math
+from xml.sax.saxutils import escape
+
+FONT = "DejaVu Sans, Helvetica, Arial, sans-serif"
+INK = "#21304a"
+
+# Every knob a bubble's look has. A page's `bubble_style:` overrides any of
+# these for the whole page; a bubble's own keys override again.
+DEFAULT_STYLE = {
+    "font": FONT,
+    "font_size": 16,
+    "pad": 14,  # text inset from the outline
+    "radius": 18,  # corner radius of a speech bubble (capped at half height)
+    "stroke": INK,  # outline colour
+    "stroke_width": 3,
+    "fill": "#ffffff",
+    "ink": INK,  # text colour
+    "uppercase": False,
+    "em": 1.0,  # width scale for the text measure: <1 for a narrower font
+}
+
+
+def resolve_style(*layers) -> dict:
+    """Merge style dicts over ``DEFAULT_STYLE``; later layers win, ``None`` skipped."""
+    out = dict(DEFAULT_STYLE)
+    for layer in layers:
+        if layer:
+            out.update({k: v for k, v in layer.items() if v is not None})
+    return out
+
+
+def _wrap(text: str, max_chars: int) -> list[str]:
+    lines, cur = [], ""
+    for word in text.split():
+        if cur and len(cur) + 1 + len(word) > max_chars:
+            lines.append(cur)
+            cur = word
+        else:
+            cur = f"{cur} {word}".strip()
+    if cur:
+        lines.append(cur)
+    return lines or [""]
+
+
+# Rough advance widths in em for a humanist sans (DejaVu Sans is the default
+# font): capitals are a good third wider than lowercase, so an all-caps bubble
+# must be measured as such or the text runs past its outline.
+_EM = {"upper": 0.70, "lower": 0.56, "digit": 0.64, "space": 0.32, "other": 0.34}
+
+
+def text_width(text: str, fs: float) -> float:
+    """Estimated rendered width of *text* at font size *fs*, in px."""
+
+    def em(ch):
+        if ch.isupper():
+            return _EM["upper"]
+        if ch.islower():
+            return _EM["lower"]
+        if ch.isdigit():
+            return _EM["digit"]
+        if ch.isspace():
+            return _EM["space"]
+        return _EM["other"]
+
+    return sum(em(ch) for ch in text) * fs
+
+
+def _box(text, max_chars, fs, pad, em=1.0):
+    """Wrap *text* and return (lines, line_height, body_width, body_height)."""
+    lines = _wrap(text, max_chars)
+    lh = fs * 1.25
+    longest = max((text_width(ln, fs) * em for ln in lines), default=fs)
+    w = max(longest + 2 * pad, 60)
+    h = len(lines) * lh + 2 * pad
+    return lines, lh, w, h
+
+
+# how far each bubble kind's outline reaches beyond the text body box
+_OUTSET = {"thought": (12, 16), "shout": (16, 16)}
+
+
+def bubble_size(text, kind="speech", max_chars=22, fs=None, pad=None, style=None):
+    """Outer (width, height) a `bubble` call will occupy, tail excluded.
+
+    `thought` and `shout` draw outside the text body, so callers that stack
+    bubbles or keep them inside a panel need this, not just the body box.
+    """
+    st = resolve_style(style)
+    fs = st["font_size"] if fs is None else fs
+    pad = st["pad"] if pad is None else pad
+    _lines, _lh, w, h = _box(text, max_chars, fs, pad, st["em"])
+    ow, oh = _OUTSET.get(kind, (0, 0))
+    return w + ow, h + oh
+
+
+def _text_block(lines, cx, top, fs, lh, st):
+    spans = []
+    for i, ln in enumerate(lines):
+        spans.append(
+            f'<tspan x="{cx:.1f}" y="{top + fs + i * lh:.1f}">{escape(ln)}</tspan>'
+        )
+    return (
+        f'<text text-anchor="middle" font-family="{st["font"]}" '
+        f'font-size="{fs}" fill="{st["ink"]}">{"".join(spans)}</text>'
+    )
+
+
+def _paint(st, scale=1.0):
+    """fill/stroke attributes shared by every outline a bubble draws."""
+    return (
+        f'fill="{st["fill"]}" stroke="{st["stroke"]}" '
+        f'stroke-width="{st["stroke_width"] * scale:.2f}"'
+    )
+
+
+def bubble(
+    text, bx, by, tail=None, kind="speech", max_chars=22, fs=None, pad=None, style=None
+):
+    st = resolve_style(style)
+    fs = st["font_size"] if fs is None else fs
+    pad = st["pad"] if pad is None else pad
+    lines, lh, w, h = _box(text, max_chars, fs, pad, st["em"])
+    x, y = bx - w / 2, by - h / 2
+    txt = _text_block(lines, bx, y + pad, fs, lh, st)
+
+    if kind == "shout":
+        body = _burst(x, y, w, h, st)
+    elif kind == "thought":
+        rx, ry = w / 2 + 6, h / 2 + 8
+        body = (
+            f'<ellipse cx="{bx:.1f}" cy="{by:.1f}" rx="{rx:.1f}" ry="{ry:.1f}" '
+            f"{_paint(st)}/>"
+        )
+    else:
+        body = (
+            f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" '
+            f'rx="{min(st["radius"], h / 2):.1f}" {_paint(st)}/>'
+        )
+
+    tail_svg = ""
+    if tail is not None:
+        tail_svg = _tail(bx, by, w, h, tail, kind, st)
+
+    return f"<g>{body}{tail_svg}{txt}</g>"
+
+
+def _tail(bx, by, w, h, tail, kind, st):
+    """A slim tail from the bubble's underside (or its top, when the speaker is
+    above it) pointing toward the target — but stopping well short of it, so
+    the tip never reaches the figure."""
+    tx, ty = tail
+    # exit from the edge facing the target: a side edge when the target lies
+    # further out beside the bubble than above or below it (relative to the
+    # body's own size), else top/bottom — nudged toward the target but kept
+    # within the middle of that edge
+    over_x = (abs(tx - bx) - w / 2) / (w / 2)
+    over_y = (abs(ty - by) - h / 2) / (h / 2)
+    if over_x > 0 and over_x > over_y:
+        ex = bx - w / 2 if tx < bx else bx + w / 2
+        ey = min(max(ty, by - h * 0.3), by + h * 0.3)
+    else:
+        ex = min(max(tx, bx - w * 0.3), bx + w * 0.3)
+        ey = by - h / 2 if ty < by - h / 2 else by + h / 2
+    dx, dy = tx - ex, ty - ey
+    dist = math.hypot(dx, dy) or 1.0
+    reach = min(dist * 0.45, 46)  # capped length keeps the tip off the figure
+    ux, uy = dx / dist, dy / dist
+    tipx, tipy = ex + ux * reach, ey + uy * reach
+
+    if kind == "thought":
+        dots = ""
+        for f in (0.45, 0.74, 1.0):
+            r = 6 * (1 - f) + 2.5
+            dots += (
+                f'<circle cx="{ex + ux * reach * f:.1f}" '
+                f'cy="{ey + uy * reach * f:.1f}" r="{r:.1f}" {_paint(st, 0.85)}/>'
+            )
+        return dots
+    # narrow tapered tail for speech/shout
+    perp = math.atan2(uy, ux) + math.pi / 2
+    base = 6
+    ax = ex + math.cos(perp) * base
+    ay = ey + math.sin(perp) * base
+    bx2 = ex - math.cos(perp) * base
+    by2 = ey - math.sin(perp) * base
+    return (
+        f'<path d="M{ax:.1f} {ay:.1f} L{tipx:.1f} {tipy:.1f} '
+        f'L{bx2:.1f} {by2:.1f} Z" {_paint(st, 0.85)} stroke-linejoin="round"/>'
+    )
+
+
+def _cloud(x, y, w, h):
+    # rounded body + scalloped top edge via overlapping circles
+    rx = min(20, h / 2)
+    body = (
+        f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" '
+        f'rx="{rx:.1f}" fill="#ffffff" stroke="{INK}" stroke-width="3"/>'
+    )
+    bumps = ""
+    n = max(3, int(w // 34))
+    for i in range(n):
+        cx = x + (i + 0.5) * w / n
+        bumps += (
+            f'<circle cx="{cx:.1f}" cy="{y:.1f}" r="13" '
+            f'fill="#ffffff" stroke="{INK}" stroke-width="3"/>'
+        )
+    # mask the inner stroke segments by redrawing body fill on top edge
+    cover = (
+        f'<rect x="{x + 3:.1f}" y="{y:.1f}" width="{w - 6:.1f}" height="14" '
+        f'fill="#ffffff" stroke="none"/>'
+    )
+    return body + bumps + cover + body.replace('fill="#ffffff"', 'fill="none"')
+
+
+def _burst(x, y, w, h, st):
+    cx, cy = x + w / 2, y + h / 2
+    rx, ry = w / 2 + 8, h / 2 + 8
+    n = 18
+    pts = []
+    for i in range(n * 2):
+        a = math.pi * i / n
+        rr = 1.0 if i % 2 == 0 else 0.78
+        pts.append(f"{cx + math.cos(a) * rx * rr:.1f},{cy + math.sin(a) * ry * rr:.1f}")
+    return f'<polygon points="{" ".join(pts)}" {_paint(st)} stroke-linejoin="round"/>'

comicforge-0.2.0/comicforge/caption.py

@@ -0,0 +1,91 @@
+"""Narration captions: a text band inside the panel frame, under the art.
+
+A panel's ``caption:`` is the narrator's voice ("Rain came. Snow came.") as
+opposed to a bubble, which is a character's. It is drawn as a flat band along
+the bottom of the panel, separated from the art by a hairline; the art box
+shrinks to make room, so bubbles and actors keep their coordinates relative to
+the picture, not the band. A page's ``caption_style:`` sets the look for every
+caption; a panel can give ``caption: {text:, max_chars:}`` to wrap differently.
+"""
+
+from __future__ import annotations
+
+from xml.sax.saxutils import escape
+
+from .bubbles import FONT, INK, _wrap
+
+DEFAULT_STYLE = {
+    "font": FONT,
+    "font_size": 13,
+    "ink": INK,  # text colour
+    "bg": "#ffffff",  # band colour
+    "pad": 8,  # text inset from the band edge
+    "max_chars": 60,  # wrap width; a panel's caption can override
+    "align": "left",  # left | center
+    "rule": True,  # hairline between art and band (in the frame colour)
+    "uppercase": False,
+}
+
+
+def normalize(value) -> dict | None:
+    """``caption: text`` or ``caption: {text, max_chars}`` -> dict, or None."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        value = {"text": value}
+    if not isinstance(value, dict) or not value.get("text"):
+        raise ValueError("caption must be a string or a {text, max_chars} mapping")
+    return value
+
+
+def resolve_style(*layers) -> dict:
+    out = dict(DEFAULT_STYLE)
+    for layer in layers:
+        if layer:
+            out.update({k: v for k, v in layer.items() if v is not None})
+    return out
+
+
+def lines(caption: dict, style: dict) -> list[str]:
+    text = " ".join(caption["text"].split())
+    if caption.get("uppercase", style["uppercase"]):
+        text = text.upper()
+    return _wrap(text, caption.get("max_chars", style["max_chars"]))
+
+
+def height(caption, style=None) -> float:
+    """Band height in px a caption will take, 0 when there is none."""
+    cap = normalize(caption)
+    if cap is None:
+        return 0.0
+    st = resolve_style(style)
+    return len(lines(cap, st)) * st["font_size"] * 1.25 + 2 * st["pad"]
+
+
+def band(caption: dict, style: dict, x, y, w, h, rule_color, rule_width) -> str:
+    """SVG for the band occupying the (x, y, w, h) box."""
+    st = style
+    fs, lh = st["font_size"], st["font_size"] * 1.25
+    parts = [
+        f'<rect x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}" '
+        f'fill="{st["bg"]}"/>'
+    ]
+    if st["rule"] and rule_width > 0:
+        parts.append(
+            f'<line x1="{x:.1f}" y1="{y:.1f}" x2="{x + w:.1f}" y2="{y:.1f}" '
+            f'stroke="{rule_color}" stroke-width="{rule_width}"/>'
+        )
+    if st["align"] == "center":
+        tx, anchor = x + w / 2, "middle"
+    else:
+        tx, anchor = x + st["pad"], "start"
+    top = y + st["pad"] + fs
+    spans = "".join(
+        f'<tspan x="{tx:.1f}" y="{top + i * lh:.1f}">{escape(ln)}</tspan>'
+        for i, ln in enumerate(lines(caption, st))
+    )
+    parts.append(
+        f'<text text-anchor="{anchor}" font-family="{st["font"]}" font-size="{fs}" '
+        f'fill="{st["ink"]}">{spans}</text>'
+    )
+    return "".join(parts)

{comicforge-0.0.4 → comicforge-0.2.0}/comicforge/cli.py

@@ -323,9 +323,7 @@ def main(argv=None):  # noqa: PLR0912, PLR0915 — flat CLI dispatcher; clearer
             ):
                 rich_print(f"wrote {o}")
         else:
-            out = args.out or _default_out(
-                f"{args.spec.stem}-r{args.row}c{args.col}"
-            )
+            out = args.out or _default_out(f"{args.spec.stem}-r{args.row}c{args.col}")
             render_panel(
                 args.spec,
                 out,