comicforge 0.1.0__tar.gz → 0.2.0__tar.gz

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

@@ -75,20 +75,31 @@ 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)
@@ -200,6 +211,9 @@ 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 by measured
                     #           height, so they never overlap. All bubbles are
@@ -218,9 +232,23 @@ page or scene spec to style every bubble at once; per-bubble keys override:
 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.1.0 → comicforge-0.2.0}/.claude/skills/comicforge/reference.md

@@ -592,12 +592,22 @@ 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`,
-  `bubble_style` (page-wide bubble defaults: `uppercase`, `font_size`)
-- **Rows and panels**: `rows[].height` (relative weight), `rows[].panels[].width`
-  (relative weight), panel keys: `bg`, `scene`, `image`, `actors`, `pixel`,
-  `bubbles` — `validate` flags any other panel key as a typo
+- **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
@@ -607,12 +617,16 @@ For the full spec grammar, see [SKILL.md](SKILL.md). Key points:
 - **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`/`uppercase` (`fs` and `uppercase` override
+  `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`). 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
+  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.1.0 → comicforge-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comicforge
-Version: 0.1.0
+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.1.0 → 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)