comicforge 0.0.1__py3-none-any.whl

comicforge/scene.py

@@ -0,0 +1,112 @@
+"""Load the scene library and compose a scene background.
+
+A scene is a directory mirroring a character:
+    base.svg, <slot>-<variant>.svg, scene.yaml
+
+It uses the same base + stackable-overlay model as characters (see
+:mod:`comicforge.library`), but a scene is always a single body (no poses) and
+instead of being placed at a height it is scaled to *cover* a panel (or the
+whole canvas, for a standalone illustration).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .library import _inner
+
+
+@dataclass
+class Scene:
+    """A background: a base body plus stackable overlay variants, one viewBox."""
+
+    name: str
+    label: str
+    w: float
+    h: float
+    slots: dict[str, list[str]]
+    defaults: dict[str, str]
+    base: str
+    variants: dict[str, str] = field(default_factory=dict)
+
+    def compose_inner(self, selection: dict[str, str]) -> str:
+        parts = [self.base]
+        for slot in self.slots:  # manifest order = draw order
+            variant = selection.get(slot, self.defaults.get(slot))
+            if variant is None:
+                continue
+            if variant not in self.slots[slot]:
+                raise ValueError(
+                    f"{self.name}: slot '{slot}' has no variant '{variant}'. "
+                    f"Available: {self.slots[slot]}"
+                )
+            parts.append(self.variants[f"{slot}-{variant}"])
+        return "\n".join(parts)
+
+
+class SceneLibrary:
+    """Loads scenes from ``<root>/<name>/`` lazily, caching parsed scenes."""
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self._cache: dict[str, Scene] = {}
+
+    def get(self, name: str) -> Scene:
+        if name in self._cache:
+            return self._cache[name]
+        sdir = self.root / name
+        if not sdir.is_dir():
+            avail = (
+                [p.name for p in self.root.iterdir() if p.is_dir()]
+                if self.root.is_dir()
+                else []
+            )
+            raise KeyError(f"scene '{name}' not found in {self.root}. Have: {avail}")
+        man = yaml.safe_load((sdir / "scene.yaml").read_text(encoding="utf-8"))
+        w, h = man["viewbox"]
+        slots = man.get("slots", {})
+        variants = {}
+        for slot, names in slots.items():
+            for v in names:
+                variants[f"{slot}-{v}"] = _inner(sdir / f"{slot}-{v}.svg")
+        scene = Scene(
+            name=man["name"],
+            label=man.get("label", man["name"]),
+            w=w,
+            h=h,
+            slots=slots,
+            defaults=man.get("default", {}),
+            base=_inner(sdir / "base.svg"),
+            variants=variants,
+        )
+        self._cache[name] = scene
+        return scene
+
+    def manifest(self) -> dict:
+        """Machine-readable contract: every scene, its slots and variants."""
+        out = {}
+        if not self.root.is_dir():
+            return out
+        for p in sorted(self.root.iterdir()):
+            if p.is_dir() and (p / "scene.yaml").exists():
+                c = self.get(p.name)
+                out[c.name] = {
+                    "label": c.label,
+                    "slots": c.slots,
+                    "default": c.defaults,
+                }
+        return out
+
+
+def cover(scene: Scene, selection, px, py, pw, ph) -> str:
+    """Place a scene so it fully covers the (px, py, pw, ph) box, centred."""
+    s = max(pw / scene.w, ph / scene.h)
+    ox = px + (pw - scene.w * s) / 2
+    oy = py + (ph - scene.h * s) / 2
+    return (
+        f'<g transform="translate({ox:.2f},{oy:.2f}) scale({s:.4f})">\n'
+        f"{scene.compose_inner(selection)}\n</g>"
+    )

comicforge/validate.py

@@ -0,0 +1,192 @@
+"""Statically check a page / scene spec against the libraries it points at.
+
+``render`` only fails on the *first* genuinely unusable thing (a missing
+character, a bad variant) and **silently ignores** keys it doesn't recognise —
+so a typo like ``fcae: happy`` or ``post: walk`` renders a default-faced,
+default-posed actor with no error at all.  ``validate`` walks the whole spec
+without drawing anything, collecting *every* problem at once:
+
+- characters / scenes / pixel sprites that don't exist in the library
+- poses an actor asks for that the character doesn't have
+- 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)
+- bubble ``speaker`` that names no actor in the panel, unknown bubble ``kind``
+- structural holes (no ``rows``, a row without ``panels``, a bubble with no text)
+
+It returns a list of human-readable problem strings (empty == the spec is sound).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .library import Library
+from .pixelart import PixelLibrary
+from .render import _as_list, _build_libs, load_spec, spec_type
+from .scene import SceneLibrary
+
+# keys on an actor / scene dict that are positioning or identity, not slots
+_ACTOR_RESERVED = {"char", "pose", "x", "y", "scale", "flip"}
+_SCENE_RESERVED = {"name"}
+_BUBBLE_KINDS = {"speech", "thought", "shout"}
+
+
+def _check_actor(actor: dict, lib: Library, where: str, problems: list[str]) -> None:
+    name = actor.get("char")
+    if not name:
+        problems.append(f"{where}: actor with no 'char'")
+        return
+    try:
+        char = lib.get(name)
+    except KeyError as e:
+        problems.append(f"{where}: {e}")
+        return
+
+    pose = actor.get("pose")
+    if pose is not None and pose not in char.poses:
+        problems.append(
+            f"{where}: {name} has no pose '{pose}'. Have: {list(char.poses)}"
+        )
+        pose = None  # fall back so slot checks still run against a real pose
+
+    slots = char.slots_for(pose)
+    for key, value in actor.items():
+        if key in _ACTOR_RESERVED:
+            continue
+        if key not in slots:
+            problems.append(
+                f"{where}: {name} has no slot '{key}' "
+                f"(ignored when rendering). Slots: {sorted(slots)}"
+            )
+        elif value not in slots[key]:
+            problems.append(
+                f"{where}: {name} slot '{key}' has no variant '{value}'. "
+                f"Have: {slots[key]}"
+            )
+
+
+def _check_scene(sc, scenes, where: str, problems: list[str]) -> None:
+    sc = {"name": sc} if isinstance(sc, str) else sc
+    name = sc.get("name")
+    if not name:
+        problems.append(f"{where}: scene with no 'name'")
+        return
+    try:
+        scene = scenes.get(name)
+    except KeyError as e:
+        problems.append(f"{where}: {e}")
+        return
+    for key, value in sc.items():
+        if key in _SCENE_RESERVED:
+            continue
+        if key not in scene.slots:
+            problems.append(
+                f"{where}: scene '{name}' has no slot '{key}' "
+                f"(ignored when rendering). Slots: {sorted(scene.slots)}"
+            )
+        elif value not in scene.slots[key]:
+            problems.append(
+                f"{where}: scene '{name}' slot '{key}' has no variant '{value}'. "
+                f"Have: {scene.slots[key]}"
+            )
+
+
+def _check_pixel(spec, pxlib, where: str, problems: list[str]) -> None:
+    if "art" in spec:
+        if pxlib is None:
+            problems.append(
+                f"{where}: pixel art '{spec['art']}' needs a pixel library "
+                "(set 'pixel_dir:' in the spec or pass --pixel-dir)"
+            )
+            return
+        try:
+            pxlib.get(spec["art"])
+        except KeyError as e:
+            problems.append(f"{where}: {e}")
+    elif "grid" not in spec:
+        problems.append(f"{where}: pixel entry has neither 'art' nor 'grid'")
+
+
+def _check_bubbles(panel: dict, where: str, problems: list[str]) -> None:
+    speakers = {a.get("char") for a in panel.get("actors", [])}
+    for b in panel.get("bubbles", []):
+        if not b.get("text"):
+            problems.append(f"{where}: bubble with no 'text'")
+        kind = b.get("kind", "speech")
+        if kind not in _BUBBLE_KINDS:
+            problems.append(
+                f"{where}: bubble kind '{kind}' unknown. Have: {sorted(_BUBBLE_KINDS)}"
+            )
+        speaker = b.get("speaker")
+        if speaker is not None and speaker not in speakers:
+            problems.append(
+                f"{where}: bubble speaker '{speaker}' is not an actor here. "
+                f"Actors: {sorted(s for s in speakers if s)}"
+            )
+
+
+def _check_panel(panel, libs, where, problems) -> None:
+    lib, scenes, pxlib = libs
+    if panel.get("scene") is not None:
+        _check_scene(panel["scene"], scenes, where, problems)
+    for spec in _as_list(panel.get("pixel")):
+        _check_pixel(spec, pxlib, where, problems)
+    for actor in panel.get("actors", []):
+        _check_actor(actor, lib, where, problems)
+    _check_bubbles(panel, where, problems)
+
+
+def validate_spec(
+    spec,
+    library: Library | None = None,
+    scenes: SceneLibrary | None = None,
+    pixel_library: PixelLibrary | None = None,
+) -> list[str]:
+    """Return every problem found in *spec* (path or dict). Empty == sound.
+
+    A page spec has ``rows`` of ``panels``; a standalone scene spec has a
+    top-level ``scene`` and acts as a single panel. Both are validated.
+    """
+    spec_dir = None
+    if not isinstance(spec, dict):
+        spec_path = Path(spec)
+        spec_dir = spec_path.parent.resolve()
+        spec = load_spec(spec_path)
+
+    problems: list[str] = []
+    try:
+        libs = _build_libs(spec, spec_dir, library, scenes, pixel_library)
+    except ValueError as e:
+        # a missing library dir is itself the headline problem; nothing else to check
+        return [str(e)]
+
+    try:
+        kind = spec_type(spec)
+    except ValueError as e:
+        return [str(e)]
+
+    if kind == "scene":  # standalone illustration, rendered with `scene`
+        if "scene" not in spec:
+            problems.append("scene spec has no top-level 'scene'")
+        if "rows" in spec:
+            problems.append(
+                "scene spec must not have 'rows' (use a 'page' spec for a grid)"
+            )
+        _check_panel(spec, libs, "scene", problems)
+        return problems
+
+    rows = spec.get("rows")
+    if not rows:
+        problems.append(
+            "page spec has no 'rows'"
+            + (" (did you mean type: scene?)" if "scene" in spec else "")
+        )
+        return problems
+    for ri, row in enumerate(rows):
+        panels = row.get("panels")
+        if not panels:
+            problems.append(f"r{ri}: row has no 'panels'")
+            continue
+        for ci, panel in enumerate(panels):
+            _check_panel(panel, libs, f"r{ri}c{ci}", problems)
+    return problems

comicforge-0.0.1.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: comicforge
+Version: 0.0.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
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: inspire
+Requires-Dist: python-dotenv>=1.0; extra == 'inspire'
+Requires-Dist: replicate>=1.0; extra == 'inspire'
+Description-Content-Type: text/markdown
+
+# 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).
+
+## Start a project
+
+ComicForge ships no art and a project needs no Python — a project is just YAML
+specs + SVG / pixel art that the CLI points at. Install the engine globally and
+scaffold one:
+
+```bash
+uv tool install comicforge         # puts `cmf` on your PATH (no venv needed)
+cmf init my-comic                  # scaffold characters/ scenes/ pixel/ pages/ + skill
+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.
+
+## Working on the engine
+
+```bash
+uv sync                            # create .venv and install deps
+```
+
+## Use
+
+```bash
+# render a comic page
+cmf render examples/pes/pages/slepice.yaml -o slepice.png
+cmf render examples/pes/pages/slepice.yaml -o slepice.pdf
+
+# render a standalone scene illustration (one background, no comic grid)
+cmf scene examples/pes/pages/dvur-scene.yaml -o dvur.png
+
+# render individual panels at low res for quick review
+cmf panel examples/pes/pages/slepice.yaml -o panel.png --row 0 --col 0
+cmf panel examples/pes/pages/slepice.yaml -o panels/ --all --scale 0.5
+
+# print the machine-readable contracts (characters / scenes, slots, variants)
+cmf characters --library examples/pes/characters
+cmf scenes --scenes examples/pes/scenes
+```
+
+Or from Python:
+```python
+from comicforge import render_spec
+render_spec("examples/pes/pages/slepice.yaml", "out.pdf")
+```
+
+## How it fits together
+
+ComicForge is a **content-free engine** plus **self-contained projects**. There is
+no shared asset library: every project owns all of its own art. A real downstream
+project just does `pip install comicforge` and brings its own characters — none of
+the example art comes with the engine.
+
+| Layer | Path | Purpose |
+|---|---|---|
+| Engine | `comicforge/` | Pure code — loads assets, composes SVG, writes output. No hardcoded content. |
+| Project | `examples/<name>/` | A self-contained comic: its own characters, scenes, pixel art, and page specs. |
+
+A project is one directory with four asset folders:
+
+```
+examples/pes/
+  characters/tom/             flat: base.svg + <slot>-<variant>.svg + character.yaml
+  characters/bara/            posed: shared faces + character.yaml + poses/{sit,walk}/
+  scenes/{dvur,pokoj}/        base.svg + <slot>-<variant>.svg + scene.yaml
+  pixel/{heart,sun,...}.yaml  grid + palette
+  pages/
+    slepice.yaml              2×2 comic — Tom and Bára watch chickens
+    kosticka.yaml             Strip with scenes, pixel art, multiple bubble types
+    dvur-scene.yaml           Standalone illustration (use `comicforge scene`)
+
+comicforge/library.py         loads a character, stacks base+overlays, places it
+comicforge/scene.py           loads a scene, stacks overlays, scales it to cover a box
+comicforge/bubbles.py         speech / thought / shout bubbles with word-wrap + tail
+comicforge/pixelart.py        grid+palette → SVG sprite
+comicforge/render.py          row/panel pages + standalone scenes → SVG → PNG/PDF
+comicforge/cli.py             `render`, `scene`, `panel`, `characters`, `scenes` commands
+```
+
+### Asset directories
+
+Each spec declares where its assets live via top-level keys (paths are relative to
+the spec file's directory). For a spec under `pages/`, the sibling asset folders
+are one level up:
+
+```yaml
+library:    "../characters"   # character art
+scenes_dir: "../scenes"       # scene backgrounds
+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.
+
+## Design choices
+
+- **Base + overlays** in one shared local canvas — "posing" is just choosing which
+  overlay SVGs to stack. No rig math; each pose/expression is a small SVG you can
+  edit by hand.
+- **Declarative spec** — the whole agent surface is YAML + the `characters` JSON.
+- **SVG all the way down**, rasterized only at the end — crisp vector PDF for print.
+- **Content-free engine** — `comicforge/` ships no art. Each project owns all its
+  own assets, so the engine is a dependency, not a content bundle.
+
+## Roadmap ideas
+
+- A FastAPI + HTMX preview server (live re-render on spec edit).
+- An MCP server exposing `list_characters` / `render_page` as tools.
+- Part-anchored slots (separate eyes/mouth/limb pivots) for finer posing.
+- Free-form panel shapes and a gutter/layout DSL.
+- AI-image panels (drop a generated raster into a panel like pixel art).

comicforge-0.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+comicforge/__init__.py,sha256=YP6JJ-C6JXrSgKRaYKkFW7pPSsKjl1CnsKXUhwoGN3Q,334
+comicforge/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+comicforge/bubbles.py,sha256=BxjBvvbKG_F0ZvujwSvNPjDZIOcKQOKg8PAC4Cwi8Vk,4727
+comicforge/cli.py,sha256=XTVDJZQb0b1yLQHcEJr7mX8md2q2tIcQmWGY9SQ6dWg,13125
+comicforge/inspire.py,sha256=uVBhhNIFvfh9wdhFs4uqPDyu9Yh2dt3dQliM6LPa-lk,9089
+comicforge/library.py,sha256=SdR7qtju_JArhInbbqrypP1i5mifR7QyRl1mnDo-mmo,9124
+comicforge/pixelart.py,sha256=ZwvAffhvTZzI0Qm6YtE2dBliMrTtAd6jyJD_BqjRalg,2697
+comicforge/render.py,sha256=9tyHIDlBvFW-JzwP8Qua4_SWrjmrf4kOmOF3P3vVGBM,18839
+comicforge/scaffold.py,sha256=kk0Cqh6ipju5gJFeHtBuDvnsoNDr5iu2jWxzpt745ms,4826
+comicforge/scene.py,sha256=F_R50iyPEera4Qrm1UTVnSCRxu6swTvBDRia-e0CBcQ,3683
+comicforge/validate.py,sha256=0JP3_zXF2SG86guTdKUX4NAPgAirJvp1Q9w_JKdcZgY,6983
+comicforge/_skill/SKILL.md,sha256=StwT5_nJUbpOUCAlHz886SDbO_p2NMDxVAhdwWx3ADg,13772
+comicforge/_skill/reference.md,sha256=FmjJlAKHtOfzmR3Rb2PKeoMxEWR5BZNTze_S2KECj9M,22081
+comicforge-0.0.1.dist-info/METADATA,sha256=yn_ZwEya1emxHogLK8wjOwMvNHYsAvP-_olDuvH3TNY,5652
+comicforge-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+comicforge-0.0.1.dist-info/entry_points.txt,sha256=-79dTD3fWo81P5RApa0IJ_N8HIYCXnacavJtOY_Tg6k,77
+comicforge-0.0.1.dist-info/RECORD,,

comicforge-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

comicforge-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cmf = comicforge.cli:main
+comicforge = comicforge.cli:main