comicforge 0.1.0__tar.gz → 0.2.1__tar.gz

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

@@ -17,7 +17,8 @@ description: >
 You write a **comic page as a YAML spec**; the engine renders it to SVG/PNG/PDF.
 This file is the authoring contract. For deeper explanations (path resolution,
 how to add characters/scenes, pixel-art format, Python API, full CLI reference)
-see [`reference.md`](reference.md) in this skill directory.
+see [`reference.md`](reference.md) in this skill directory, or the documentation
+site at <https://mojzis.github.io/comicforge/>.
 
 ## Loop
 
@@ -75,20 +76,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 +212,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 +233,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.1}/.claude/skills/comicforge/reference.md

@@ -4,6 +4,9 @@ This guide covers everything you need to author comics with ComicForge — for b
 humans and LLMs. The [SKILL.md](SKILL.md) file is the quick-reference contract;
 this document goes deeper on structure, paths, and how all the pieces fit together.
 
+The same material, with rendered examples beside every spec, is published at
+<https://mojzis.github.io/comicforge/>.
+
 ---
 
 ## Engine + self-contained projects
@@ -592,12 +595,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 +620,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.2.1/.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "examples/**"     # the gallery renders from the demo project
+      - "comicforge/**"   # …through the engine, so a renderer change matters
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "examples/**"
+      - "comicforge/**"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # Every image on the site is rendered at build time by
+      # docs/hooks/render_demos.py, so the docs build needs cairo just like a
+      # normal render does.
+      - name: Install cairo
+        run: sudo apt-get update && sudo apt-get install -y libcairo2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Sync docs dependencies
+        run: uv sync --group docs
+
+      # --strict fails the build on a broken cross-reference, a dead anchor, a
+      # missing snippet, or a demo spec that no longer renders.
+      - name: Build site
+        run: uv run mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site/
+
+  deploy:
+    # Pull requests get the build as a check; only main publishes.
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

{comicforge-0.1.0 → comicforge-0.2.1}/.gitignore

@@ -34,3 +34,12 @@ review.html
 
 # Source archive (redundant after flattening)
 *.zip
+
+# Docs site: `mkdocs build` output, and the demo renders the build hook draws
+# (every image on the site is regenerated from a spec — never checked in).
+site/
+docs/assets/renders/
+
+# …except the one raster the `image:` demo needs as *input*, which `*.png` above
+# would otherwise swallow.
+!docs/demos/raster-art/*.png

{comicforge-0.1.0 → comicforge-0.2.1}/CLAUDE.md

@@ -21,6 +21,7 @@ comicforge/              The engine — pure code, no bundled art.
 examples/pes/            A self-contained demo project (characters, scenes, pixel, pages).
                          Develop against the engine the same way a downstream project would.
 skills/comicforge/       The portable authoring skill (SKILL.md + reference.md).
+docs/                    The documentation site (MkDocs Material) — see below.
 tests/                   pytest suite.
 ```
 
@@ -82,6 +83,29 @@ cmf scene  examples/pes/pages/dvur-scene.yaml -o dvur.png
 cmf panel  examples/pes/pages/slepice.yaml -o panels/ --all
 ```
 
+## Docs site
+
+`docs/` is a MkDocs Material site published to GitHub Pages by
+`.github/workflows/docs.yml`.
+
+```bash
+uv sync --group docs
+poe docs          # serve with live reload
+poe docs-build    # mkdocs build --strict — what CI runs
+```
+
+**Every image on the site is rendered at build time** by
+`docs/hooks/render_demos.py`, from a spec in `docs/demos/` or from
+`examples/pes/`. Nothing is a checked-in screenshot, so a renderer change that
+breaks a demo breaks the docs build. To add an illustrated example: write
+`docs/demos/<name>.yaml` (small custom `page:`, `library:` pointing at
+`../../examples/pes/characters`), `cmf validate` it, then reference
+`assets/renders/<name>.png` and include the spec with a `pymdownx.snippets`
+include — see `docs/guide/bubbles.md` for the pattern.
+
+`--strict` plus the `validation:` block in `mkdocs.yml` fails the build on a
+broken cross-reference, a dead anchor, a missing snippet or a missing render.
+
 ## Conventions / invariants
 
 - **Content-free engine:** never hardcode an asset name, path, or default project
@@ -91,7 +115,8 @@ cmf panel  examples/pes/pages/slepice.yaml -o panels/ --all
 - The CLI subcommands (`render`/`scene`/`panel`/`characters`/`scenes`) are the
   stable surface; `characters`/`scenes` emit JSON manifests other tools depend on.
 - When you change the spec grammar or CLI, update the authoring skill in
-  `skills/comicforge/` (both `SKILL.md` and `reference.md`) in the same change.
+  `skills/comicforge/` (both `SKILL.md` and `reference.md`) **and** the affected
+  pages under `docs/` in the same change.
 - Demo art is hand/LLM-authored crisp SVG, edited directly in `examples/pes/`
   (there is no procedural generator). Use `comicforge inspire` for *reference*
   images only — never auto-vectorize them; it breaks overlay/anchor registration.

{comicforge-0.1.0 → comicforge-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comicforge
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -13,12 +13,18 @@ Description-Content-Type: text/markdown
 
 # ComicForge
 
+**📖 Documentation: <https://mojzis.github.io/comicforge/>**
+
 A tiny, scriptable comic-page engine. Characters are a **base SVG + stackable
 variant overlays** (faces, arms, …); a comic page is a **declarative YAML spec**;
 output is **SVG / PNG / PDF**. Built so an LLM (or you) can author pages as plain
-text — see the authoring skill [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md)
-for the full authoring contract and [`skills/comicforge/reference.md`](skills/comicforge/reference.md)
-for a deeper reference. Working **on the engine** instead? See [`CLAUDE.md`](CLAUDE.md).
+text.
+
+- [Your first comic](https://mojzis.github.io/comicforge/quickstart/) — a project, a character, a strip
+- [Spec reference](https://mojzis.github.io/comicforge/reference/spec/) · [CLI reference](https://mojzis.github.io/comicforge/reference/cli/) · [Gallery](https://mojzis.github.io/comicforge/gallery/)
+- [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md) — the authoring contract an LLM reads
+- Working **on the engine**? See [`CLAUDE.md`](CLAUDE.md) and
+  [Contributing](https://mojzis.github.io/comicforge/contributing/).
 
 ## Start a project
 
@@ -32,13 +38,17 @@ cmf init my-comic                  # scaffold characters/ scenes/ pixel/ pages/
 cd my-comic && cmf render pages/hello.yaml
 ```
 
-See [`docs/starting-a-project.md`](docs/starting-a-project.md) for the data-only
-setup, version pinning, and when to make it a real Python project.
+See [Starting a project](https://mojzis.github.io/comicforge/starting-a-project/)
+for the data-only setup, version pinning, and when to make it a real Python
+project.
 
 ## Working on the engine
 
 ```bash
 uv sync                            # create .venv and install deps
+uv run poe test                    # the tight loop
+uv run poe check                   # everything, before opening a PR
+uv run poe docs                    # serve the documentation site locally
 ```
 
 ## Use
@@ -114,8 +124,10 @@ pixel_dir:  "../pixel"        # pixel-art sprites
 CLI flags (`--library`, `--scenes`, `--pixel-dir`) override spec keys and are
 treated as relative to the current working directory.
 
-See [`skills/comicforge/reference.md`](skills/comicforge/reference.md) for the full path
-resolution rule, how to add characters/scenes/sprites, and the complete CLI reference.
+The [documentation site](https://mojzis.github.io/comicforge/) covers the full
+path-resolution rule, how to add characters / scenes / sprites, and the complete
+CLI and spec references — every picture on it is rendered from a spec at build
+time.
 
 ## Design choices
 

{comicforge-0.1.0 → comicforge-0.2.1}/README.md

@@ -1,11 +1,17 @@
 # ComicForge
 
+**📖 Documentation: <https://mojzis.github.io/comicforge/>**
+
 A tiny, scriptable comic-page engine. Characters are a **base SVG + stackable
 variant overlays** (faces, arms, …); a comic page is a **declarative YAML spec**;
 output is **SVG / PNG / PDF**. Built so an LLM (or you) can author pages as plain
-text — see the authoring skill [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md)
-for the full authoring contract and [`skills/comicforge/reference.md`](skills/comicforge/reference.md)
-for a deeper reference. Working **on the engine** instead? See [`CLAUDE.md`](CLAUDE.md).
+text.
+
+- [Your first comic](https://mojzis.github.io/comicforge/quickstart/) — a project, a character, a strip
+- [Spec reference](https://mojzis.github.io/comicforge/reference/spec/) · [CLI reference](https://mojzis.github.io/comicforge/reference/cli/) · [Gallery](https://mojzis.github.io/comicforge/gallery/)
+- [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md) — the authoring contract an LLM reads
+- Working **on the engine**? See [`CLAUDE.md`](CLAUDE.md) and
+  [Contributing](https://mojzis.github.io/comicforge/contributing/).
 
 ## Start a project
 
@@ -19,13 +25,17 @@ cmf init my-comic                  # scaffold characters/ scenes/ pixel/ pages/
 cd my-comic && cmf render pages/hello.yaml
 ```
 
-See [`docs/starting-a-project.md`](docs/starting-a-project.md) for the data-only
-setup, version pinning, and when to make it a real Python project.
+See [Starting a project](https://mojzis.github.io/comicforge/starting-a-project/)
+for the data-only setup, version pinning, and when to make it a real Python
+project.
 
 ## Working on the engine
 
 ```bash
 uv sync                            # create .venv and install deps
+uv run poe test                    # the tight loop
+uv run poe check                   # everything, before opening a PR
+uv run poe docs                    # serve the documentation site locally
 ```
 
 ## Use
@@ -101,8 +111,10 @@ pixel_dir:  "../pixel"        # pixel-art sprites
 CLI flags (`--library`, `--scenes`, `--pixel-dir`) override spec keys and are
 treated as relative to the current working directory.
 
-See [`skills/comicforge/reference.md`](skills/comicforge/reference.md) for the full path
-resolution rule, how to add characters/scenes/sprites, and the complete CLI reference.
+The [documentation site](https://mojzis.github.io/comicforge/) covers the full
+path-resolution rule, how to add characters / scenes / sprites, and the complete
+CLI and spec references — every picture on it is rendered from a spec at build
+time.
 
 ## Design choices
 

{comicforge-0.1.0 → comicforge-0.2.1}/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.1/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"/>'