postcanvas 0.1.0__tar.gz

postcanvas-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: postcanvas
+Version: 0.1.0
+Summary: Generate pixel-perfect social media images from Python Pydantic models
+License: MIT
+Keywords: social media,instagram,image generation,pillow,pydantic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=10.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.28
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# postcanvas 🎨
+
+> Generate pixel-perfect social-media images from Python — just describe what you want.
+
+## Install
+
+```bash
+pip install postcanvas
+```
+
+## Quick start
+
+```python
+from postcanvas import generate
+from postcanvas.presets import instagram_post
+from postcanvas.models import BackgroundConfig, TextConfig, ShadowConfig
+
+post = instagram_post(
+    background=BackgroundConfig(color="#1a1a2e"),
+    texts=[
+        TextConfig(
+            content="Hello World!",
+            y="50%",
+            font_size=96,
+            color="#e94560",
+            shadow=ShadowConfig(blur_radius=12),
+        )
+    ],
+    output_dir="./output",
+)
+
+generate(post)   # → ./output/post.png
+```
+
+## Platforms & formats
+
+| Helper | Size |
+|---|---|
+| `instagram_post()` | 1080 × 1080 |
+| `instagram_portrait()` | 1080 × 1350 |
+| `instagram_story()` | 1080 × 1920 |
+| `x_post()` | 1600 × 900 |
+| `reddit_post()` | 1920 × 1080 |
+| `blog_og()` | 1200 × 628 |
+| `linkedin_post()` | 1080 × 1080 |
+| `youtube_thumbnail()` | 1280 × 720 |
+| `facebook_post()` | 1080 × 1080 |
+| `tiktok_story()` | 1080 × 1920 |
+
+Use `preset(Platform.CUSTOM, PostFormat.CUSTOM, width=800, height=600)` for custom sizes.
+
+## Carousel / multi-image
+
+```python
+from postcanvas.models import CanvasConfig, BackgroundConfig
+
+post = instagram_post(
+    canvases=[
+        CanvasConfig(background=BackgroundConfig(color="#e94560"),
+                     texts=[TextConfig(content="Slide 1", ...)]),
+        CanvasConfig(background=BackgroundConfig(color="#0f3460"),
+                     texts=[TextConfig(content="Slide 2", ...)]),
+    ]
+)
+```
+
+## Key model reference
+
+### `PostConfig` (root)
+| Field | Type | Description |
+|---|---|---|
+| `platform` | `Platform` | Target platform |
+| `width` / `height` | `int` | Canvas size in px |
+| `background` | `BackgroundConfig` | Global background |
+| `padding` | `PaddingConfig` | Safe-area insets |
+| `texts` | `List[TextConfig]` | Global text elements |
+| `images` | `List[ImageElementConfig]` | Global image elements |
+| `shapes` | `List[ShapeConfig]` | Global shapes |
+| `canvases` | `List[CanvasConfig]` | Slides (carousel) |
+| `watermark` | `WatermarkConfig` | Applied to every slide |
+| `output_dir` | `str` | Where to save files |
+| `output_format` | `OutputFormat` | `png` / `jpeg` / `webp` |
+
+### Positioning
+Every `x`, `y`, `width`, `height` accepts:
+- **Absolute pixels**: `540`, `200`
+- **Relative string**: `"50%"`, `"80%"`
+
+### Anchors
+`anchor` can be: `topleft`, `topcenter`, `topright`, `left`, `center`,
+`right`, `bottomleft`, `bottomcenter`, `bottomright`
+
+### z_index
+Elements are composited in ascending `z_index` order across all types
+(shapes, images, texts).  Default values: shapes=1, images=5, texts=10.
+
+### Text inside images and shapes
+Both `ImageElementConfig` and `ShapeConfig` now support a `texts` list:
+
+```python
+from postcanvas.models import ImageElementConfig, ShapeConfig, ShapeType, TextConfig
+
+ShapeConfig(
+    type=ShapeType.ROUNDED_RECTANGLE,
+    x="50%", y="35%", width="70%", height="30%", anchor="center",
+    fill_color="#1f3b4d",
+    texts=[
+        TextConfig(content="Inside Shape", x="50%", y="50%", anchor="center")
+    ],
+)
+
+ImageElementConfig(
+    src="assets/photo.jpg",
+    x="50%", y="70%", width="60%", height="35%", anchor="center",
+    texts=[
+        TextConfig(content="Inside Image", x="50%", y="88%", anchor="bottomcenter")
+    ],
+)
+```
+
+Nested text coordinates are resolved relative to the element's own box, not the full canvas.
+
+### Font inheritance (Post > Canvas > Text override)
+You can define default text font at post level, override it per canvas, and still override per text:
+
+```python
+from postcanvas.presets import instagram_post
+from postcanvas.models import CanvasConfig, TextConfig
+
+post = instagram_post(
+    text_font_path="Roboto/static/Roboto-Regular.ttf",   # default for whole post
+    texts=[
+        TextConfig(content="Uses post default", x="50%", y="15%"),
+        TextConfig(content="Custom text font", x="50%", y="25%", font_path="Roboto/static/Roboto-Bold.ttf"),
+    ],
+    canvases=[
+        CanvasConfig(
+            text_font_path="Roboto/static/Roboto-Italic.ttf",  # overrides post default on this slide
+            texts=[
+                TextConfig(content="Uses canvas override", x="50%", y="50%"),
+                TextConfig(content="Text-level still wins", x="50%", y="60%", font_path="Roboto/static/Roboto-Medium.ttf"),
+            ],
+        )
+    ],
+)
+```
+
+Precedence: `TextConfig` > `CanvasConfig` > `PostConfig` > internal Arial fallback.

postcanvas-0.1.0/README.md

@@ -0,0 +1,148 @@
+# postcanvas 🎨
+
+> Generate pixel-perfect social-media images from Python — just describe what you want.
+
+## Install
+
+```bash
+pip install postcanvas
+```
+
+## Quick start
+
+```python
+from postcanvas import generate
+from postcanvas.presets import instagram_post
+from postcanvas.models import BackgroundConfig, TextConfig, ShadowConfig
+
+post = instagram_post(
+    background=BackgroundConfig(color="#1a1a2e"),
+    texts=[
+        TextConfig(
+            content="Hello World!",
+            y="50%",
+            font_size=96,
+            color="#e94560",
+            shadow=ShadowConfig(blur_radius=12),
+        )
+    ],
+    output_dir="./output",
+)
+
+generate(post)   # → ./output/post.png
+```
+
+## Platforms & formats
+
+| Helper | Size |
+|---|---|
+| `instagram_post()` | 1080 × 1080 |
+| `instagram_portrait()` | 1080 × 1350 |
+| `instagram_story()` | 1080 × 1920 |
+| `x_post()` | 1600 × 900 |
+| `reddit_post()` | 1920 × 1080 |
+| `blog_og()` | 1200 × 628 |
+| `linkedin_post()` | 1080 × 1080 |
+| `youtube_thumbnail()` | 1280 × 720 |
+| `facebook_post()` | 1080 × 1080 |
+| `tiktok_story()` | 1080 × 1920 |
+
+Use `preset(Platform.CUSTOM, PostFormat.CUSTOM, width=800, height=600)` for custom sizes.
+
+## Carousel / multi-image
+
+```python
+from postcanvas.models import CanvasConfig, BackgroundConfig
+
+post = instagram_post(
+    canvases=[
+        CanvasConfig(background=BackgroundConfig(color="#e94560"),
+                     texts=[TextConfig(content="Slide 1", ...)]),
+        CanvasConfig(background=BackgroundConfig(color="#0f3460"),
+                     texts=[TextConfig(content="Slide 2", ...)]),
+    ]
+)
+```
+
+## Key model reference
+
+### `PostConfig` (root)
+| Field | Type | Description |
+|---|---|---|
+| `platform` | `Platform` | Target platform |
+| `width` / `height` | `int` | Canvas size in px |
+| `background` | `BackgroundConfig` | Global background |
+| `padding` | `PaddingConfig` | Safe-area insets |
+| `texts` | `List[TextConfig]` | Global text elements |
+| `images` | `List[ImageElementConfig]` | Global image elements |
+| `shapes` | `List[ShapeConfig]` | Global shapes |
+| `canvases` | `List[CanvasConfig]` | Slides (carousel) |
+| `watermark` | `WatermarkConfig` | Applied to every slide |
+| `output_dir` | `str` | Where to save files |
+| `output_format` | `OutputFormat` | `png` / `jpeg` / `webp` |
+
+### Positioning
+Every `x`, `y`, `width`, `height` accepts:
+- **Absolute pixels**: `540`, `200`
+- **Relative string**: `"50%"`, `"80%"`
+
+### Anchors
+`anchor` can be: `topleft`, `topcenter`, `topright`, `left`, `center`,
+`right`, `bottomleft`, `bottomcenter`, `bottomright`
+
+### z_index
+Elements are composited in ascending `z_index` order across all types
+(shapes, images, texts).  Default values: shapes=1, images=5, texts=10.
+
+### Text inside images and shapes
+Both `ImageElementConfig` and `ShapeConfig` now support a `texts` list:
+
+```python
+from postcanvas.models import ImageElementConfig, ShapeConfig, ShapeType, TextConfig
+
+ShapeConfig(
+    type=ShapeType.ROUNDED_RECTANGLE,
+    x="50%", y="35%", width="70%", height="30%", anchor="center",
+    fill_color="#1f3b4d",
+    texts=[
+        TextConfig(content="Inside Shape", x="50%", y="50%", anchor="center")
+    ],
+)
+
+ImageElementConfig(
+    src="assets/photo.jpg",
+    x="50%", y="70%", width="60%", height="35%", anchor="center",
+    texts=[
+        TextConfig(content="Inside Image", x="50%", y="88%", anchor="bottomcenter")
+    ],
+)
+```
+
+Nested text coordinates are resolved relative to the element's own box, not the full canvas.
+
+### Font inheritance (Post > Canvas > Text override)
+You can define default text font at post level, override it per canvas, and still override per text:
+
+```python
+from postcanvas.presets import instagram_post
+from postcanvas.models import CanvasConfig, TextConfig
+
+post = instagram_post(
+    text_font_path="Roboto/static/Roboto-Regular.ttf",   # default for whole post
+    texts=[
+        TextConfig(content="Uses post default", x="50%", y="15%"),
+        TextConfig(content="Custom text font", x="50%", y="25%", font_path="Roboto/static/Roboto-Bold.ttf"),
+    ],
+    canvases=[
+        CanvasConfig(
+            text_font_path="Roboto/static/Roboto-Italic.ttf",  # overrides post default on this slide
+            texts=[
+                TextConfig(content="Uses canvas override", x="50%", y="50%"),
+                TextConfig(content="Text-level still wins", x="50%", y="60%", font_path="Roboto/static/Roboto-Medium.ttf"),
+            ],
+        )
+    ],
+)
+```
+
+Precedence: `TextConfig` > `CanvasConfig` > `PostConfig` > internal Arial fallback.

postcanvas-0.1.0/postcanvas/__init__.py

@@ -0,0 +1,31 @@
+"""
+postcanvas – Generate social-media images with Python.
+
+Quick start
+-----------
+from postcanvas import generate
+from postcanvas.presets import instagram_post
+from postcanvas.models import BackgroundConfig, TextConfig, ShadowConfig
+
+post = instagram_post(
+    background=BackgroundConfig(color="#1a1a2e"),
+    texts=[
+        TextConfig(
+            content="Hello World",
+            y="45%",
+            font_size=96,
+            color="#e94560",
+            shadow=ShadowConfig(blur_radius=12),
+        )
+    ],
+    output_dir="./out",
+)
+
+paths = generate(post)
+"""
+
+from .renderer import generate, render_one
+from . import models, presets
+
+__version__ = "0.1.0"
+__all__ = ["generate", "render_one", "models", "presets"]

postcanvas-0.1.0/postcanvas/models/__init__.py

@@ -0,0 +1,24 @@
+from .enums import (
+    Platform, PostFormat, GradientType, ImageFit, TextAlign, FontWeight,
+    ShapeType, BlendMode, OutputFormat, FilterType, TextTransform
+)
+from .primitives import (
+    ShadowConfig, StrokeConfig, GradientStop, GradientConfig,
+    PaddingConfig, BorderConfig, FilterConfig
+)
+from .background import BackgroundConfig
+from .text import TextConfig
+from .elements import ImageElementConfig, ShapeConfig
+from .watermark import WatermarkConfig
+from .meta import MetaConfig
+from .canvas import CanvasConfig
+from .post import PostConfig
+
+__all__ = [
+    "Platform", "PostFormat", "GradientType", "ImageFit", "TextAlign",
+    "FontWeight", "ShapeType", "BlendMode", "OutputFormat", "FilterType",
+    "TextTransform", "ShadowConfig", "StrokeConfig", "GradientStop",
+    "GradientConfig", "PaddingConfig", "BorderConfig", "FilterConfig",
+    "BackgroundConfig", "TextConfig", "ImageElementConfig", "ShapeConfig",
+    "WatermarkConfig", "MetaConfig", "CanvasConfig", "PostConfig",
+]

postcanvas-0.1.0/postcanvas/models/background.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel, Field
+from .enums import ImageFit
+from .primitives import GradientConfig
+
+class BackgroundConfig(BaseModel):
+    # Solid colour (hex / rgb() / rgba())
+    color: Optional[str] = None
+
+    # Gradient (overrides colour when set)
+    gradient: Optional[GradientConfig] = None
+
+    # Image source (local path or URL)
+    image_path:    Optional[str]   = None
+    image_url:     Optional[str]   = None
+    image_fit:     ImageFit        = ImageFit.COVER
+    image_opacity: float           = Field(default=1.0, ge=0.0, le=1.0)
+    image_blur:    float           = 0.0
+
+    # Colour overlay painted on top of the image
+    overlay_color:   Optional[str] = None
+    overlay_opacity: float         = Field(default=0.4, ge=0.0, le=1.0)

postcanvas-0.1.0/postcanvas/models/canvas.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from typing import List, Optional
+from pydantic import BaseModel, Field
+from .background import BackgroundConfig
+from .text import TextConfig
+from .elements import ImageElementConfig, ShapeConfig
+from .watermark import WatermarkConfig
+from .meta import MetaConfig
+from .primitives import PaddingConfig, FilterConfig
+
+class CanvasConfig(BaseModel):
+    """
+    One slide / frame in a carousel (or the only frame for a single image).
+
+    Every field is optional – unset fields fall back to the parent PostConfig.
+    Elements (texts, images, shapes) are MERGED with the parent's by default;
+    set replace_elements=True to use ONLY the elements defined here.
+    """
+
+    # Override parent dimensions
+    width:  Optional[int] = None
+    height: Optional[int] = None
+
+    # Override parent background / padding
+    background: Optional[BackgroundConfig] = None
+    padding:    Optional[PaddingConfig]    = None
+
+    # Default text font for this canvas (overrides PostConfig defaults)
+    text_font_family: Optional[str] = None
+    text_font_path:   Optional[str] = None
+
+    # Canvas-specific elements (merged with parent unless replace_elements=True)
+    texts:  List[TextConfig]         = Field(default_factory=list)
+    images: List[ImageElementConfig] = Field(default_factory=list)
+    shapes: List[ShapeConfig]        = Field(default_factory=list)
+
+    # If True, these elements replace (not extend) the parent's element lists
+    replace_elements: bool = False
+
+    # Per-canvas post-processing
+    canvas_filters: List[FilterConfig] = Field(default_factory=list)
+
+    # Watermark override (None = use parent watermark)
+    watermark: Optional[WatermarkConfig] = None
+
+    # Output filename without extension (e.g. "slide_01")
+    output_filename: Optional[str] = None
+
+    meta: MetaConfig = Field(default_factory=MetaConfig)

postcanvas-0.1.0/postcanvas/models/elements.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+from typing import List, Optional, Tuple
+from pydantic import BaseModel, Field
+from .enums import ImageFit, BlendMode, ShapeType, Dimension
+from .primitives import ShadowConfig, BorderConfig, FilterConfig, GradientConfig
+from .text import TextConfig
+
+class ImageElementConfig(BaseModel):
+    src: str                                 # local path or URL
+
+    # Position & size
+    x:      Dimension         = "50%"
+    y:      Dimension         = "50%"
+    width:  Optional[Dimension] = None       # None = intrinsic
+    height: Optional[Dimension] = None
+    fit:    ImageFit          = ImageFit.CONTAIN
+    anchor: str               = "center"
+
+    # Visual
+    border_radius:   float  = 0.0
+    opacity:         float  = Field(default=1.0, ge=0.0, le=1.0)
+    rotation:        float  = 0.0
+    flip_horizontal: bool   = False
+    flip_vertical:   bool   = False
+
+    # Adjustments (1.0 = neutral)
+    brightness: float = 1.0
+    contrast:   float = 1.0
+    saturation: float = 1.0
+
+    # Decorations
+    shadow: Optional[ShadowConfig] = None
+    border: Optional[BorderConfig] = None
+    texts:  List[TextConfig]       = Field(default_factory=list)
+
+    # Compositing
+    blend_mode: BlendMode = BlendMode.NORMAL
+    z_index:    int       = 5
+    visible:    bool      = True
+    filters:    List[FilterConfig] = Field(default_factory=list)
+
+class ShapeConfig(BaseModel):
+    type: ShapeType = ShapeType.RECTANGLE
+
+    # Position & size
+    x:      Dimension = 0
+    y:      Dimension = 0
+    width:  Dimension = 100
+    height: Dimension = 100
+    anchor: str       = "topleft"
+
+    # Fill
+    fill_color:     Optional[str]            = None
+    fill_gradient:  Optional[GradientConfig] = None
+
+    # Stroke
+    stroke_color: Optional[str] = None
+    stroke_width: int           = 0
+
+    # Shape-specific
+    border_radius: float              = 0.0       # ROUNDED_RECTANGLE
+    sides:         int                = 6         # POLYGON (regular)
+    star_points:   int                = 5         # STAR
+    star_inner_r:  float              = 0.4       # STAR inner ratio
+    points:        Optional[List[Tuple[float, float]]] = None  # POLYGON custom
+
+    # Compositing
+    opacity:    float     = Field(default=1.0, ge=0.0, le=1.0)
+    rotation:   float     = 0.0
+    blend_mode: BlendMode = BlendMode.NORMAL
+    z_index:    int       = 1
+    visible:    bool      = True
+    shadow:     Optional[ShadowConfig] = None
+    texts:      List[TextConfig]       = Field(default_factory=list)

postcanvas-0.1.0/postcanvas/models/enums.py

@@ -0,0 +1,96 @@
+from enum import Enum
+
+class Platform(str, Enum):
+    INSTAGRAM = "instagram"
+    X         = "x"
+    TWITTER   = "twitter"
+    REDDIT    = "reddit"
+    BLOG      = "blog"
+    LINKEDIN  = "linkedin"
+    FACEBOOK  = "facebook"
+    TIKTOK    = "tiktok"
+    YOUTUBE   = "youtube"
+    CUSTOM    = "custom"
+
+class PostFormat(str, Enum):
+    SQUARE    = "square"
+    PORTRAIT  = "portrait"
+    LANDSCAPE = "landscape"
+    STORY     = "story"
+    COVER     = "cover"
+    BANNER    = "banner"
+    CUSTOM    = "custom"
+
+class GradientType(str, Enum):
+    LINEAR = "linear"
+    RADIAL = "radial"
+    CONIC  = "conic"
+
+class ImageFit(str, Enum):
+    COVER   = "cover"
+    CONTAIN = "contain"
+    FILL    = "fill"
+    CENTER  = "center"
+
+class TextAlign(str, Enum):
+    LEFT    = "left"
+    CENTER  = "center"
+    RIGHT   = "right"
+    JUSTIFY = "justify"
+
+class FontWeight(str, Enum):
+    THIN      = "thin"
+    LIGHT     = "light"
+    REGULAR   = "regular"
+    MEDIUM    = "medium"
+    SEMIBOLD  = "semibold"
+    BOLD      = "bold"
+    EXTRABOLD = "extrabold"
+    BLACK     = "black"
+
+class ShapeType(str, Enum):
+    RECTANGLE         = "rectangle"
+    CIRCLE            = "circle"
+    ELLIPSE           = "ellipse"
+    LINE              = "line"
+    ROUNDED_RECTANGLE = "rounded_rectangle"
+    TRIANGLE          = "triangle"
+    POLYGON           = "polygon"
+    STAR              = "star"
+
+class BlendMode(str, Enum):
+    NORMAL     = "normal"
+    MULTIPLY   = "multiply"
+    SCREEN     = "screen"
+    OVERLAY    = "overlay"
+    DARKEN     = "darken"
+    LIGHTEN    = "lighten"
+    DIFFERENCE = "difference"
+    EXCLUSION  = "exclusion"
+
+class OutputFormat(str, Enum):
+    PNG  = "png"
+    JPEG = "jpeg"
+    JPG  = "jpg"
+    WEBP = "webp"
+
+class FilterType(str, Enum):
+    NONE       = "none"
+    BLUR       = "blur"
+    SHARPEN    = "sharpen"
+    GRAYSCALE  = "grayscale"
+    SEPIA      = "sepia"
+    BRIGHTNESS = "brightness"
+    CONTRAST   = "contrast"
+    SATURATION = "saturation"
+    INVERT     = "invert"
+    VIGNETTE   = "vignette"
+
+class TextTransform(str, Enum):
+    NONE       = "none"
+    UPPERCASE  = "uppercase"
+    LOWERCASE  = "lowercase"
+    CAPITALIZE = "capitalize"
+
+# Dimension type: int/float = absolute px, str "50%" = relative
+Dimension = int | float | str

postcanvas-0.1.0/postcanvas/models/meta.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+class MetaConfig(BaseModel):
+    """Non-rendered metadata – useful for tracking, CMS integration, etc."""
+    title:       Optional[str]       = None
+    description: Optional[str]       = None
+    tags:        List[str]           = Field(default_factory=list)
+    author:      Optional[str]       = None
+    created_at:  Optional[str]       = None
+    custom:      Dict[str, Any]      = Field(default_factory=dict)

postcanvas-0.1.0/postcanvas/models/post.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+from typing import List, Optional
+from pydantic import BaseModel, Field
+from .enums import Platform, PostFormat, OutputFormat
+from .background import BackgroundConfig
+from .text import TextConfig
+from .elements import ImageElementConfig, ShapeConfig
+from .watermark import WatermarkConfig
+from .meta import MetaConfig
+from .primitives import PaddingConfig, FilterConfig
+from .canvas import CanvasConfig
+
+class PostConfig(BaseModel):
+    """
+    Root configuration for a social-media post.
+
+    All settings here act as DEFAULTS for every canvas.
+    A CanvasConfig inside `canvases` can override any of them.
+
+    Single image  → leave `canvases` empty.
+    Carousel      → populate `canvases` (one entry per slide).
+    """
+
+    # ── Platform & format preset ─────────────────────────────────────────────
+    platform: Platform   = Platform.INSTAGRAM
+    format:   PostFormat = PostFormat.SQUARE
+
+    # ── Canvas dimensions ────────────────────────────────────────────────────
+    width:  int = 1080
+    height: int = 1080
+
+    # ── Background (default for all slides) ──────────────────────────────────
+    background: BackgroundConfig = Field(default_factory=BackgroundConfig)
+
+    # ── Safe-area padding ────────────────────────────────────────────────────
+    padding: PaddingConfig = Field(default_factory=PaddingConfig)
+
+    # ── Default text font (can be overridden by canvas/text) ───────────────
+    text_font_family: Optional[str] = None
+    text_font_path:   Optional[str] = None
+
+    # ── Global elements (appear on EVERY slide unless overridden) ─────────────
+    texts:  List[TextConfig]         = Field(default_factory=list)
+    images: List[ImageElementConfig] = Field(default_factory=list)
+    shapes: List[ShapeConfig]        = Field(default_factory=list)
+
+    # ── Slides (carousel / multi-image) ──────────────────────────────────────
+    canvases: List[CanvasConfig] = Field(default_factory=list)
+
+    # ── Post-processing ──────────────────────────────────────────────────────
+    canvas_filters: List[FilterConfig]    = Field(default_factory=list)
+    watermark:      Optional[WatermarkConfig] = None
+
+    # ── Output ───────────────────────────────────────────────────────────────
+    output_dir:      str          = "./output"
+    output_format:   OutputFormat = OutputFormat.PNG
+    output_filename: str          = "post"
+    quality:         int          = Field(default=95, ge=1, le=100)
+    dpi:             int          = 96
+
+    # ── Metadata ─────────────────────────────────────────────────────────────
+    meta: MetaConfig = Field(default_factory=MetaConfig)
+
+    @property
+    def slide_count(self) -> int:
+        return max(1, len(self.canvases))