comicforge 0.2.3__tar.gz → 0.2.4__tar.gz

{comicforge-0.2.3 → comicforge-0.2.4}/.claude/skills/comicforge/SKILL.md

@@ -47,15 +47,21 @@ needs no Python (see [`reference.md`](reference.md)).
    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.
+   and `scene` specs. It also prints bubble layout **warnings** (out of reading
+   order, crossing tails, a bubble covering a speaker point) — they don't fail
+   the check unless `--strict`, but fix them before calling a page done.
 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.
+     directory. Add `--on-page` to get the panel exactly as the page draws it
+     (full frame stroke, page background at the corners); `--layout` prints
+     each panel's position on the page as JSON (`--all` writes it as
+     `layout.json`) to lay the renders out again. 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`,
@@ -93,7 +99,9 @@ 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), or
-                                  #   height_mm: 60 for a fixed height —
+                                  #   height_mm: 60 for a fixed height, or
+                                  #   height: auto to size it from its images
+                                  #   + captions (squeezed to fit the page) —
                                   #   weighted rows share what is left
     panels:                       # …each row is a left→right list of panels
       - width: 1.0                # relative panel width (default 1)
@@ -159,6 +167,22 @@ image: {src: "01.png", fit: contain}    # or the long form, to pick the fit
   distorts, exactly like a `scene:` background.
 - `fit: contain` scales it to fit *inside* the panel; the leftover strips show
   the panel's `bg:` colour.
+- `crop: {top, bottom, left, right}` trims that many *image pixels* off each
+  edge before fitting — the trimmed image is what `fit`, a scene canvas and a
+  `height: auto` row see.
+- `at: t|b|l|r|tl|tr|bl|br|c` pins the image to that edge, so `fit: cover`
+  crops from the other side (`at: t` keeps heads, loses feet). Default centred.
+- **Making a page of images fit:** give the rows `height: auto`. Each row is as
+  tall as its images want at their panel width plus the caption band; if the
+  rows overflow the page their art (never the captions) is squeezed by one
+  common factor and `cover` crops the excess. Steer what gets lost with `at:`
+  per image, and `crop:` away empty sky/floor first so the squeeze is smaller.
+  Don't compute row `height_mm` from image sizes and caption wraps yourself.
+  To paginate, call `comicforge.page_squeeze(spec)` (1.0 = fits unsqueezed) on
+  a candidate page and break when it drops below what you tolerate.
+- Captions in panels of varying width: `caption_style: {max_chars: auto}` wraps
+  to the band's width; `em` (default 1.0) scales the measure for a narrower
+  (<1) or wider (>1) font than DejaVu Sans.
 - `.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
@@ -171,13 +195,27 @@ A standalone illustration can be image-backed too — set `type: scene` with an
 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.
+mark each speaking head with a panel-level `speakers: {name: [x, y]}` (panel
+fractions) and give bubbles `speaker: name`. The tail then aims at the point
+(unless `to:` is given), and every bubble with a speaker and no `x`/`y`/`at` is
+placed **in reading order**: on its speaker's side, its top clearly below the
+previous bubble's top, clear of speaker points and earlier tails. So a
+right-hand first speaker gets the top right and the reply goes lower left. Emit
+the lines in the order they are spoken and omit coordinates.
+
+Without `speakers:`, a bubble with no `y` is placed below the measured bottom of
+the bubble before it, starting near the panel top, and 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).
+
+```yaml
+image: "art/03.png"
+speakers: {ema: [0.72, 0.3], jan: [0.25, 0.42]}
+bubbles:
+  - {text: "Kde jsi byl?", speaker: ema}
+  - {text: "Venku.",       speaker: jan}
+```
 
 ## Standalone illustration (no comic grid)
 
@@ -212,6 +250,7 @@ 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.
+                    #           Also names a panel `speakers:` point (actors win).
   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.
@@ -221,9 +260,21 @@ bubbles: [ ... ]
                     #           kept inside the panel.
   to: [0.4, 0.5]    # OPTIONAL tail target (panel fraction); else speaker's head
   max_chars: 22     # wrap width (optional)
+  glue_singles: false  # OPTIONAL let a one-letter word end a line (default: it
+                    #          is tied to the next word; see Line breaks below)
   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)
+  tail_from: r      # OPTIONAL where the tail leaves: edge t/b/l/r, a position
+                    #           0..1 along the auto edge, or {edge: r, pos: 0.8}
+  tail: curve       # OPTIONAL wedge (default) | curve: tapered comic tail with
+                    #           curved sides | line: a thin line running to just
+                    #           short of the speaker | none. Any kind; a thought
+                    #           keeps its circles (dotted along a line)
+  tail_bend: 0.4    # OPTIONAL curve/line bow, -1..1, 0 straight, + = right of
+                    #           travel; omit for a gentle bend away from the
+                    #           nearest bubble (or panel centre)
+  tail_gap: 12      # OPTIONAL px a line tail stops short of its target
 ```
 
 **Page-wide bubble defaults** — set `bubble_style` at the *top level* of a
@@ -239,6 +290,8 @@ bubble_style:
   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
+  tail: wedge       # wedge | curve | line | none;  tail_bend: (auto)
+                    #   tail_gap: 12;  tail_from: (auto)
 rows: [ ... ]
 ```
 
@@ -247,12 +300,28 @@ 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
+`align: left|center`, `rule`, `uppercase`, `glue_singles`);
+`comicforge.caption.height(text, style)` tells
 you how tall a band will be, for sizing rows.
 
+**Line breaks.** Wrapping breaks between words, with two exceptions, in bubbles
+and captions alike. A one-letter word is tied to the word after it, because
+Czech typography does not leave a one-letter preposition or conjunction
+(`k s v z o u a i`) at the end of a line — set `glue_singles: false` on the
+style or the line to allow it. A no-break space (`U+00A0`, or `U+202F`) is
+never broken at, so type one to tie words the automatic rule cannot know about
+(`v roce 1223`, a name and its title). Ordinary runs of spaces and newlines
+still collapse to one space.
+
 `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.
+The tail is a slim wedge dropping from the bubble underside; its tip is capped
+short so it never overlaps the figure (`tail: curve` draws the classic curved
+comic tail, `tail: line` a thin line to just short of the speaker, `tail: none`
+nothing).
+
+`cmf validate` also prints layout **warnings** (exit 0 unless `--strict`): a
+bubble out of reading order, crossing tails, a bubble covering a speaker point.
+When one shows up, nudge that bubble with `at:` or `x`/`y`.
 
 ### pixel art
 

{comicforge-0.2.3 → comicforge-0.2.4}/.claude/skills/comicforge/reference.md

@@ -440,15 +440,21 @@ renders a default-faced, default-posed actor with no error. `validate` flags:
 - 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`
+  an `image:` with no `src`, an unknown image key, an unknown `fit` or `at`,
+  a bad `crop` (unknown side, negative, or trimming the whole image); a row
+  `height` that is neither a weight nor `auto`, an `auto` row with no image
+- bubble `speaker` naming neither an actor nor a `speakers:` point in the panel;
+  a malformed `speakers:` point; unknown bubble `kind`, `tail`, `tail_from`,
+  or a `tail_bend` outside -1..1
 - structural holes (a page with no `rows`, a row with no `panels`, a bubble with
   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.
+so it works in a pre-render check or CI. It also lays out the bubbles and
+prints **warnings** — a bubble out of reading order, tails that cross, a bubble
+covering a speaker point — which only fail the check with `--strict`.
 
 ```bash
 cmf validate examples/pes/pages/slepice.yaml   # -> "...: ok"
@@ -479,6 +485,13 @@ cmf panel <spec.yaml> [-o <output>]   # default: output/<spec>-r<R>c<C>-<ts>.png
   [--all]                   # render every panel into a directory
                             # (default: output/<spec>-panels-<ts>/)
   [--scale 0.5]             # size vs full-page (default 0.5 = low res)
+  [--on-page]               # crop panel + half a gutter out of the page render,
+                            # so frame/corners look exactly as on the page
+  [--layout]                # print each panel's page position as JSON, no render
+                            # ({width, height, panels: [{row, col, file,
+                            #   box: {x,y,w,h}, image: {x,y,w,h}}]}, page px;
+                            #  image = what the render covers, honours --on-page);
+                            # --all also writes it as layout.json
   [--library <dir>]
   [--scenes  <dir>]
   [--pixel-dir <dir>]
@@ -602,34 +615,63 @@ For the full spec grammar, see [SKILL.md](SKILL.md). Key points:
   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)
+  the text measure for narrower fonts; `tail` `wedge`/`curve`/`line`/`none`,
+  `tail_bend`, `tail_gap`, `tail_from`)
 - **Rows and panels**: `rows[].height` (relative weight) or `rows[].height_mm`
-  (fixed; weighted rows share the rest, all-fixed leaves the bottom blank),
+  (fixed; weighted rows share the rest, all-fixed leaves the bottom blank) or
+  `rows[].height: auto` (tallest of each panel's image aspect at its width,
+  after `crop:`, plus its caption band; auto rows that overflow the page have
+  their art — not their captions — squeezed by one common factor, the excess
+  cropped by `cover`; needs an `image:` panel; fixed rows are measured first,
+  weighted rows get what is left; `comicforge.page_squeeze(spec)` returns that
+  art factor, 1.0 when nothing is squeezed — use it to paginate),
   `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
+  `font`, `font_size`, `ink`, `bg`, `pad`, `max_chars` (a count, or `auto` to
+  wrap to the band's width), `em` (width scale of the `auto` measure),
+  `align`, `rule`, `uppercase`, `glue_singles`),
+  `scene`, `image`, `actors`, `pixel`, `bubbles`, `speakers` (`{name: [x, y]}`
+  head points in panel fractions that bubbles' `speaker:` resolves to when no
+  actor has that char) — `validate` flags any other panel key as a typo
+- **Line breaking** (bubbles and captions): a one-letter word is tied to the
+  word after it with a no-break space, so a Czech one-letter preposition or
+  conjunction (`k s v z o u a i`) never ends a line; `glue_singles: false` on
+  the style or the individual line turns that off. A no-break space in the
+  text (`U+00A0`, `U+202F`) is never a break point, which is how an author
+  ties words the rule cannot know about. Other whitespace runs collapse to one
+  space.
+- **Image keys**: `image: path.png` or `image: {src:, fit:, at:, crop:}` with
   `fit: cover` (default; scale-to-fill + centre-crop) or `contain`
-  (fit inside + letterbox). The path resolves against the spec file's dir and
+  (fit inside + letterbox); `at:` (`t`, `b`, `l`, `r`, `tl`, `tr`, `bl`, `br`,
+  `c` — default centre) pins the image to that edge so `cover` crops the
+  opposite side; `crop: {top, bottom, left, right}` trims image pixels off
+  each edge before fitting (and before a `height: auto` row or a scene canvas
+  measures it). 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
-  `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
+  `at`/`x`/`y`/`to`/`max_chars`/`fs`/`uppercase`/`glue_singles` (`fs`,
+  `uppercase` and `glue_singles` 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
+  `to: [x, y]` (panel fractions) aims a tail without a speaker. `tail_from`
+  (`t`/`b`/`l`/`r`, a position 0..1, or `{edge, pos}`) picks where the tail
+  leaves; `tail` (`wedge`/`curve`/`line`/`none`, any kind) picks the look
+  and `tail_bend` (-1..1, auto: away from the nearest bubble) bows a curve
+  or line. On a panel with
+  `speakers:`, bubbles with a speaker and no `x`/`y`/`at` are placed in
+  reading order (speaker's side, each top clearly below the previous one's,
+  clear of heads and earlier tails). Every bubble is
+  kept inside the panel — so a generated spec over raster panels marks the heads
+  in `speakers:`, emits the lines in spoken order with a `speaker` each, and
+  omits coordinates; reach for `at` or `x`/`y` only when `validate` warns
 - **Pixel keys**: `art` (library name) or `grid`+`palette`, plus `x`/`y`/`scale`
 
 ---
@@ -645,6 +687,10 @@ render_spec("examples/pes/pages/slepice.yaml", "slepice.png")
 # Render a standalone scene
 render_scene("examples/pes/pages/dvur-scene.yaml", "dvur.png")
 
+# Bubble boxes + tail endpoints of one panel, in panel fractions, no render
+from comicforge import bubble_layout
+bubble_layout("examples/pes/pages/slepice.yaml", row=0, col=1)["bubbles"]
+
 # Load a spec dict for inspection
 spec = load_spec("examples/pes/pages/slepice.yaml")
 

{comicforge-0.2.3 → comicforge-0.2.4}/.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@v10.0.1
+        uses: astral-sh/setup-uv@v10.1.0
         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@v10.0.1
+        uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
 

{comicforge-0.2.3 → comicforge-0.2.4}/.github/workflows/docs.yml

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

{comicforge-0.2.3 → comicforge-0.2.4}/.github/workflows/release.yml

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

{comicforge-0.2.3 → comicforge-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comicforge
-Version: 0.2.3
+Version: 0.2.4
 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.2.3 → comicforge-0.2.4}/comicforge/__init__.py

@@ -5,6 +5,13 @@ 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
+from .render import (  # noqa: F401
+    bubble_layout,
+    load_spec,
+    page_squeeze,
+    panel_layout,
+    render_scene,
+    render_spec,
+)
 
 __version__ = "0.2.0"