mosaickit 0.1.0__tar.gz

mosaickit-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+.import_linter_cache/
+.superpowers/
+docs/

mosaickit-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-10-01
+
+- Add immutable viewport, styles, namespaced themes, scenes, and generic layers.
+- Add Canvas, spanning CanvasGrid, parameter expressions, and Animation.
+- Add Matplotlib rendering with job-scoped caches.
+- Add strict TOML config and context-local defaults.
+- Add uv dependency management, pytest, Ruff, mypy, import-linter, and pre-commit.
+- Keep curve mathematics and TikZ export outside MosaicKit so it remains an
+  independent layer-composition package.
+- Add the MosaicKit brand asset and package overview README.

mosaickit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EconViz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mosaickit-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: mosaickit
+Version: 0.1.0
+Summary: Domain-neutral scenes, styles, and rendering for EconViz.
+Author: EconViz
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: matplotlib<4,>=3.6
+Requires-Dist: numpy>=1.24
+Requires-Dist: tomli>=2; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# mosaickit
+
+<p align="center">
+  <img src="assets/banner.svg" alt="mosaickit" width="480">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/mosaickit/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mosaickit?style=flat-square&color=181818&labelColor=f3f3f3&cacheSeconds=300"></a>
+  <a href="https://pypi.org/project/mosaickit/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/mosaickit?style=flat-square&color=181818&labelColor=f3f3f3"></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License" src="https://img.shields.io/badge/License-MIT-181818?style=flat-square&color=181818&labelColor=f3f3f3"></a>
+  <a href="https://github.com/EconViz/mosaickit/actions/workflows/test.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/EconViz/mosaickit/test.yml?branch=main&style=flat-square&label=tests&color=181818&labelColor=f3f3f3"></a>
+</p>
+
+A domain-neutral toolkit for assembling two-dimensional diagrams from reusable
+scenes, layers, styles, parameters, and renderers.
+
+`mosaickit` is the shared graphics foundation for the EconViz package family.
+Domain libraries define economic models and semantic roles; MosaicKit composes
+their visual layers and renders the result. It does not depend on an economic
+model package or a curve-fitting library.
+
+## Installation
+
+Add MosaicKit to a project with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add mosaickit
+```
+
+A plain `pip install mosaickit` also works. MosaicKit supports Python 3.10–3.13.
+
+## Python API
+
+```python
+from mosaickit import (
+    Canvas,
+    Fill,
+    FillLayer,
+    MarkerLayer,
+    PathLayer,
+    Stroke,
+    TextLayer,
+    quadrant_axes,
+)
+
+canvas = Canvas().extend(quadrant_axes(10, 10))
+canvas.add(
+    FillLayer(
+        [(1, 1), (1, 7), (8, 1)],
+        fill=Fill(color="#377EB8", opacity=0.12),
+        z_index=-1,
+    )
+)
+canvas.add(
+    PathLayer(
+        [(1, 8), (2, 5), (4, 3), (7, 1.5), (9, 1)],
+        stroke=Stroke(color="#984EA3", width=2),
+        id="curve",
+    )
+)
+canvas.add(MarkerLayer([(4, 3)], id="point"))
+canvas.add(TextLayer((4, 3), "A", offset=(8, 8)))
+canvas.save("diagram.svg")
+```
+
+`Canvas.add()`, `extend()`, `remove()`, and `clear()` are fluent builder
+operations. `snapshot()` returns an immutable `Scene`; `copy()` and `bind()`
+produce a new canvas without changing the original. Public layers never contain
+Matplotlib artists, and importing `mosaickit` does not import Matplotlib.
+
+## Scenes and layers
+
+The scene graph is deliberately small:
+
+- `PathLayer` joins ordered finite `(x, y)` coordinates with straight segments.
+- `FillLayer` describes filled regions.
+- `MarkerLayer`, `TextLayer`, and `ArrowLayer` add annotations.
+- `LegendLayer` builds legends from stable layer IDs.
+- `GroupLayer` groups layers without adding renderer-specific state.
+
+`AxisSpec` and `build_axes()` construct axes from the same ordinary path and text
+layers. `quadrant_axes()`, `crosshair_axes()`, and `box_frame()` cover common
+layouts. `CanvasSpec` owns ranges, physical size, DPI, labels, and title.
+
+Curve construction and TikZ export intentionally live outside MosaicKit. Domain
+packages can call a geometry package such as BezierKit directly, then pass the
+resulting coordinates or renderer-specific output to their own export pipeline.
+
+## Styles and themes
+
+```python
+from mosaickit import Config, Stroke, StyleBundle, Theme, use_config
+
+paper = Theme(
+    "paper",
+    {"utility.budget": StyleBundle(stroke=Stroke(color="#984EA3", width=2))},
+)
+
+with use_config(Config(theme=paper)):
+    canvas = Canvas()
+```
+
+Style resolution proceeds from layer style to canvas role override, configuration
+role override, theme, and finally primitive defaults. A field set to `None`
+inherits; falsey values such as `opacity=0`, `width=0`, and
+`LegendStyle(visible=False)` remain explicit overrides.
+
+Domain packages register dotted role names through `ThemeRegistry`. Typed
+`RolePack` dataclasses and `expand_roles()` let those packages author themes
+without making MosaicKit import their domain types.
+
+Configuration can also be loaded from TOML:
+
+```toml
+[canvas]
+x_range = [0, 20]
+dpi = 150
+
+[styles."utility.budget".stroke]
+color = "#984EA3"
+width = 2
+dash = "dashed"
+```
+
+Use `Config.load(path)` to validate it. Runtime defaults are isolated with
+`contextvars`, while explicit constructor arguments always take precedence.
+
+## Grids, parameters, and animation
+
+```python
+from mosaickit import Animation, Canvas, CanvasGrid, Parameter, TextLayer
+
+position = Parameter("position", value_type=float)
+template = Canvas().add(TextLayer((position, 5), "moving"))
+values = position.values([1.0, 3.0, 5.0])
+
+CanvasGrid.sweep(template, values, cols=3).save("sweep.svg")
+Animation.sweep(template, values, fps=2).save("sweep.gif")
+```
+
+`CanvasGrid` accepts flat canvases, nested rows, `None` cells, and
+`Span(canvas, rows=..., cols=...)`. A flat list infers a roughly square grid;
+explicit `rows` and `cols` may leave trailing cells empty.
+
+Parameters and expressions support arithmetic, ordered comparisons, partial
+binding, and stable structural equality. `Animation.frames()` yields
+backend-neutral scenes. GIF output uses Pillow; MP4 output requires ffmpeg.
+
+## Rendering
+
+PNG, SVG, and PDF use the built-in Matplotlib renderer:
+
+```python
+result = canvas.render()
+try:
+    result.show()
+finally:
+    result.close()
+```
+
+`canvas.save()` closes its temporary render result automatically. The public
+`Renderer` protocol and `RendererRegistry` allow other backends without placing
+backend state in the scene graph. Render plans and contexts remain private while
+the built-in backends evolve.
+
+Each render, grid, or animation job owns its cache. Pass an explicit
+`RenderCache` to reuse work across jobs. Non-hashable models bypass caching and
+emit one warning per model type and cache.
+
+## Scope
+
+MosaicKit owns domain-neutral scene composition, styles, themes, parameter
+binding, grid layout, animation frames, renderer contracts, and static/animated
+output. Economic semantics belong to packages such as UtilityViz and
+PrincipleViz. Mathematical curve construction and native TikZ path generation
+belong to geometry packages such as BezierKit.
+
+## Development
+
+```bash
+uv sync --locked
+uv run pre-commit install
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run lint-imports
+uv build
+```
+
+The lockfile pins all development dependencies.

mosaickit-0.1.0/README.md

@@ -0,0 +1,191 @@
+# mosaickit
+
+<p align="center">
+  <img src="assets/banner.svg" alt="mosaickit" width="480">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/mosaickit/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mosaickit?style=flat-square&color=181818&labelColor=f3f3f3&cacheSeconds=300"></a>
+  <a href="https://pypi.org/project/mosaickit/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/mosaickit?style=flat-square&color=181818&labelColor=f3f3f3"></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License" src="https://img.shields.io/badge/License-MIT-181818?style=flat-square&color=181818&labelColor=f3f3f3"></a>
+  <a href="https://github.com/EconViz/mosaickit/actions/workflows/test.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/EconViz/mosaickit/test.yml?branch=main&style=flat-square&label=tests&color=181818&labelColor=f3f3f3"></a>
+</p>
+
+A domain-neutral toolkit for assembling two-dimensional diagrams from reusable
+scenes, layers, styles, parameters, and renderers.
+
+`mosaickit` is the shared graphics foundation for the EconViz package family.
+Domain libraries define economic models and semantic roles; MosaicKit composes
+their visual layers and renders the result. It does not depend on an economic
+model package or a curve-fitting library.
+
+## Installation
+
+Add MosaicKit to a project with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add mosaickit
+```
+
+A plain `pip install mosaickit` also works. MosaicKit supports Python 3.10–3.13.
+
+## Python API
+
+```python
+from mosaickit import (
+    Canvas,
+    Fill,
+    FillLayer,
+    MarkerLayer,
+    PathLayer,
+    Stroke,
+    TextLayer,
+    quadrant_axes,
+)
+
+canvas = Canvas().extend(quadrant_axes(10, 10))
+canvas.add(
+    FillLayer(
+        [(1, 1), (1, 7), (8, 1)],
+        fill=Fill(color="#377EB8", opacity=0.12),
+        z_index=-1,
+    )
+)
+canvas.add(
+    PathLayer(
+        [(1, 8), (2, 5), (4, 3), (7, 1.5), (9, 1)],
+        stroke=Stroke(color="#984EA3", width=2),
+        id="curve",
+    )
+)
+canvas.add(MarkerLayer([(4, 3)], id="point"))
+canvas.add(TextLayer((4, 3), "A", offset=(8, 8)))
+canvas.save("diagram.svg")
+```
+
+`Canvas.add()`, `extend()`, `remove()`, and `clear()` are fluent builder
+operations. `snapshot()` returns an immutable `Scene`; `copy()` and `bind()`
+produce a new canvas without changing the original. Public layers never contain
+Matplotlib artists, and importing `mosaickit` does not import Matplotlib.
+
+## Scenes and layers
+
+The scene graph is deliberately small:
+
+- `PathLayer` joins ordered finite `(x, y)` coordinates with straight segments.
+- `FillLayer` describes filled regions.
+- `MarkerLayer`, `TextLayer`, and `ArrowLayer` add annotations.
+- `LegendLayer` builds legends from stable layer IDs.
+- `GroupLayer` groups layers without adding renderer-specific state.
+
+`AxisSpec` and `build_axes()` construct axes from the same ordinary path and text
+layers. `quadrant_axes()`, `crosshair_axes()`, and `box_frame()` cover common
+layouts. `CanvasSpec` owns ranges, physical size, DPI, labels, and title.
+
+Curve construction and TikZ export intentionally live outside MosaicKit. Domain
+packages can call a geometry package such as BezierKit directly, then pass the
+resulting coordinates or renderer-specific output to their own export pipeline.
+
+## Styles and themes
+
+```python
+from mosaickit import Config, Stroke, StyleBundle, Theme, use_config
+
+paper = Theme(
+    "paper",
+    {"utility.budget": StyleBundle(stroke=Stroke(color="#984EA3", width=2))},
+)
+
+with use_config(Config(theme=paper)):
+    canvas = Canvas()
+```
+
+Style resolution proceeds from layer style to canvas role override, configuration
+role override, theme, and finally primitive defaults. A field set to `None`
+inherits; falsey values such as `opacity=0`, `width=0`, and
+`LegendStyle(visible=False)` remain explicit overrides.
+
+Domain packages register dotted role names through `ThemeRegistry`. Typed
+`RolePack` dataclasses and `expand_roles()` let those packages author themes
+without making MosaicKit import their domain types.
+
+Configuration can also be loaded from TOML:
+
+```toml
+[canvas]
+x_range = [0, 20]
+dpi = 150
+
+[styles."utility.budget".stroke]
+color = "#984EA3"
+width = 2
+dash = "dashed"
+```
+
+Use `Config.load(path)` to validate it. Runtime defaults are isolated with
+`contextvars`, while explicit constructor arguments always take precedence.
+
+## Grids, parameters, and animation
+
+```python
+from mosaickit import Animation, Canvas, CanvasGrid, Parameter, TextLayer
+
+position = Parameter("position", value_type=float)
+template = Canvas().add(TextLayer((position, 5), "moving"))
+values = position.values([1.0, 3.0, 5.0])
+
+CanvasGrid.sweep(template, values, cols=3).save("sweep.svg")
+Animation.sweep(template, values, fps=2).save("sweep.gif")
+```
+
+`CanvasGrid` accepts flat canvases, nested rows, `None` cells, and
+`Span(canvas, rows=..., cols=...)`. A flat list infers a roughly square grid;
+explicit `rows` and `cols` may leave trailing cells empty.
+
+Parameters and expressions support arithmetic, ordered comparisons, partial
+binding, and stable structural equality. `Animation.frames()` yields
+backend-neutral scenes. GIF output uses Pillow; MP4 output requires ffmpeg.
+
+## Rendering
+
+PNG, SVG, and PDF use the built-in Matplotlib renderer:
+
+```python
+result = canvas.render()
+try:
+    result.show()
+finally:
+    result.close()
+```
+
+`canvas.save()` closes its temporary render result automatically. The public
+`Renderer` protocol and `RendererRegistry` allow other backends without placing
+backend state in the scene graph. Render plans and contexts remain private while
+the built-in backends evolve.
+
+Each render, grid, or animation job owns its cache. Pass an explicit
+`RenderCache` to reuse work across jobs. Non-hashable models bypass caching and
+emit one warning per model type and cache.
+
+## Scope
+
+MosaicKit owns domain-neutral scene composition, styles, themes, parameter
+binding, grid layout, animation frames, renderer contracts, and static/animated
+output. Economic semantics belong to packages such as UtilityViz and
+PrincipleViz. Mathematical curve construction and native TikZ path generation
+belong to geometry packages such as BezierKit.
+
+## Development
+
+```bash
+uv sync --locked
+uv run pre-commit install
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run lint-imports
+uv build
+```
+
+The lockfile pins all development dependencies.

mosaickit-0.1.0/assets/banner.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 160" width="640" height="160" role="img" aria-label="mosaickit">
+  <title>mosaickit</title>
+
+  <!-- A small scene assembled from independent tiles/layers. -->
+  <g transform="translate(24, 24)" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="4" y="4" width="48" height="48" rx="8" fill="#181818"/>
+    <rect x="60" y="4" width="48" height="48" rx="8" fill="#8a8a8a"/>
+    <rect x="4" y="60" width="48" height="48" rx="8" fill="#c9c9c9"/>
+    <rect x="60" y="60" width="48" height="48" rx="8" fill="#f3f3f3" stroke="#181818" stroke-width="3"/>
+
+    <!-- Primitive layers crossing tile boundaries form one coherent diagram. -->
+    <path d="M 16 91 L 34 72 L 49 80 L 70 35 L 94 18" fill="none" stroke="#ffffff" stroke-width="5"/>
+    <circle cx="34" cy="72" r="5" fill="#181818" stroke="#ffffff" stroke-width="2.5"/>
+    <path d="M 69 92 L 92 69" fill="none" stroke="#181818" stroke-width="5"/>
+    <path d="M 84 69 H 92 V 77" fill="none" stroke="#181818" stroke-width="4"/>
+  </g>
+
+  <!-- Wordmark follows the BezierKit family treatment. -->
+  <text x="160" y="98" font-family="'JetBrains Mono','SFMono-Regular',Consolas,monospace" font-size="52" font-weight="700" letter-spacing="-1" fill="#181818">mosaic<tspan fill="#8a8a8a">kit</tspan></text>
+</svg>

mosaickit-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "mosaickit"
+version = "0.1.0"
+description = "Domain-neutral scenes, styles, and rendering for EconViz."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "EconViz" }]
+dependencies = ["numpy>=1.24", "matplotlib>=3.6,<4", "tomli>=2; python_version < '3.11'"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mosaickit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "assets", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml", "uv.lock"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.8", "pre-commit>=4", "mypy>=1.13", "import-linter>=2", "build>=1", "pillow>=10"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --import-mode=importlib"
+
+[tool.mypy]
+files = ["src/mosaickit"]
+ignore_missing_imports = true
+check_untyped_defs = true
+
+[tool.importlinter]
+root_package = "mosaickit"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "Models do not depend on rendering or canvas"
+type = "forbidden"
+source_modules = ["mosaickit.scene", "mosaickit.styles", "mosaickit.themes", "mosaickit.parameter"]
+forbidden_modules = ["mosaickit.rendering", "mosaickit.canvas"]
+
+[[tool.importlinter.contracts]]
+name = "Core never imports domain packages"
+type = "forbidden"
+source_modules = ["mosaickit"]
+forbidden_modules = ["econ_viz", "utility_viz", "micro_viz", "macro_viz", "trade_viz", "dsge_viz", "principle_viz"]

mosaickit-0.1.0/src/mosaickit/__init__.py

@@ -0,0 +1,103 @@
+"""Domain-neutral diagram construction and rendering."""
+
+from mosaickit.canvas import Animation, Canvas, CanvasGrid, Layout, Span
+from mosaickit.canvas_spec import CanvasSpec
+from mosaickit.colors import TRANSPARENT, Color
+from mosaickit.config import Config, use_config
+from mosaickit.errors import BindingError, ConfigurationError, MosaicKitError, RenderError
+from mosaickit.interval import Interval
+from mosaickit.parameter import Constant, Expression, Parameter, ParameterValues
+from mosaickit.rendering import (
+    CacheBypassWarning,
+    CacheKey,
+    RenderCache,
+    Renderer,
+    RendererRegistry,
+    SaveOptions,
+)
+from mosaickit.scene import (
+    ArrowLayer,
+    AxisSpec,
+    FillLayer,
+    GroupLayer,
+    Layer,
+    LegendLayer,
+    MarkerLayer,
+    PathLayer,
+    Scene,
+    TextLayer,
+    box_frame,
+    build_axes,
+    crosshair_axes,
+    quadrant_axes,
+)
+from mosaickit.styles import (
+    ArrowPlacement,
+    ArrowStyle,
+    DashStyle,
+    Fill,
+    LegendStyle,
+    Marker,
+    SparseStyle,
+    Stroke,
+    TextStyle,
+)
+from mosaickit.themes import RolePack, StyleBundle, Theme, ThemeRegistry, expand_roles
+
+__version__ = "0.1.0"
+__all__ = [
+    "Animation",
+    "ArrowLayer",
+    "ArrowPlacement",
+    "ArrowStyle",
+    "AxisSpec",
+    "BindingError",
+    "CacheBypassWarning",
+    "CacheKey",
+    "Canvas",
+    "CanvasGrid",
+    "CanvasSpec",
+    "Color",
+    "Config",
+    "ConfigurationError",
+    "Constant",
+    "DashStyle",
+    "MosaicKitError",
+    "Expression",
+    "Fill",
+    "FillLayer",
+    "GroupLayer",
+    "Interval",
+    "Layer",
+    "Layout",
+    "LegendLayer",
+    "LegendStyle",
+    "Marker",
+    "MarkerLayer",
+    "Parameter",
+    "ParameterValues",
+    "PathLayer",
+    "RenderCache",
+    "RenderError",
+    "Renderer",
+    "RendererRegistry",
+    "RolePack",
+    "SaveOptions",
+    "Scene",
+    "Span",
+    "SparseStyle",
+    "Stroke",
+    "StyleBundle",
+    "TRANSPARENT",
+    "TextLayer",
+    "TextStyle",
+    "Theme",
+    "ThemeRegistry",
+    "__version__",
+    "box_frame",
+    "build_axes",
+    "crosshair_axes",
+    "expand_roles",
+    "quadrant_axes",
+    "use_config",
+]

mosaickit-0.1.0/src/mosaickit/canvas/__init__.py

@@ -0,0 +1,7 @@
+from mosaickit.canvas.animation import Animation
+from mosaickit.canvas.canvas import Canvas
+from mosaickit.canvas.grid import CanvasGrid
+from mosaickit.canvas.layout import Layout
+from mosaickit.canvas.span import Span
+
+__all__ = ["Animation", "Canvas", "CanvasGrid", "Layout", "Span"]

mosaickit-0.1.0/src/mosaickit/canvas/animation.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mosaickit.canvas.canvas import Canvas
+from mosaickit.errors import ConfigurationError, RenderError
+from mosaickit.parameter import Parameter, ParameterValues
+from mosaickit.rendering import RenderCache, Renderer
+from mosaickit.scene import Scene
+
+
+@dataclass(frozen=True, slots=True)
+class Animation:
+    template: Canvas
+    parameter: Parameter
+    values: tuple[Any, ...]
+    fps: int = 30
+
+    def __post_init__(self) -> None:
+        if isinstance(self.fps, bool) or not isinstance(self.fps, int) or self.fps < 1:
+            raise ConfigurationError("Animation.fps must be a positive integer")
+        values = ParameterValues(self.parameter, self.values).values
+        if not values:
+            raise ConfigurationError("Animation requires at least one value")
+        object.__setattr__(self, "values", values)
+        object.__setattr__(self, "template", self.template.copy())
+
+    @staticmethod
+    def sweep(canvas: Canvas, values: ParameterValues, *, fps: int = 30) -> Animation:
+        return Animation(canvas, values.parameter, values.values, fps)
+
+    def frames(self) -> Iterator[Scene]:
+        for value in self.values:
+            yield self.template.bind(self.parameter, value).snapshot()
+
+    def save(
+        self,
+        path: str | Path,
+        *,
+        renderer: Renderer | str | None = None,
+        cache: RenderCache | None = None,
+    ) -> list[Path]:
+        selected = self.template._renderer(renderer)
+        if not hasattr(selected, "save_animation"):
+            raise RenderError(f"Renderer {selected.name!r} does not support animation output")
+        return selected.save_animation(
+            self, Path(path), cache if cache is not None else RenderCache()
+        )