Merge pull request #8 from subroy13/dev

contributing docs, setup todo list, and a few bug fixes

Author: subroy13

.coverage

@@ -23,4 +23,7 @@ dist/
 .vscode/
 
 # Mac system files
-.DS_Store
+.DS_Store
+
+# Poetry
+.poetry/*

.gitignore

@@ -0,0 +1,110 @@
+# CLAUDE.md — handanim
+
+> See [repo_overview.md](repo_overview.md) for the full module map, dependency table, and known bug list.
+> See [todo.md](todo.md) for the phased roadmap and open issues.
+
+---
+
+## What this project is
+
+**handanim** is a Python library for creating whiteboard-style, hand-drawn animations programmatically. It renders to MP4, GIF, or SVG. The user writes Python code that composes shapes, styles, and timed animation events; the library takes care of the rest.
+
+The long-term arc is threefold:
+1. **A great animation toolkit** — expressive, composable, hand-drawn feel with a clean Python API
+2. **An AI-scriptable system** — LLMs should be able to think in scenes and write valid handanim code; the `handanim_ai` module scaffolds this
+3. **A handwriting font pipeline** — generate realistic single-line stroke fonts from samples of real handwriting, using RNN/transformer models
+
+---
+
+## Guiding Vision
+
+> *Reproducible, but hand-sketchy.*
+
+Every output must look like it was drawn by a careful human hand — wobbly lines, hachure fills, natural stroke pressure — while being fully reproducible from code. The aesthetic is the product, not an afterthought.
+
+This means:
+- The "roughness" and "sketchy" feel must be preserved at all costs when touching rendering code
+- New primitives should integrate with `SketchStyle` and `StrokeStyle`; they should not look crisp/digital by default
+- When adding new drawing primitives, they must produce output that a `SketchAnimation` can animate stroke-by-stroke
+
+---
+
+## Architectural Invariants — Do Not Break These
+
+### 1. Drawables are stateless and immutable
+`Drawable.translate()`, `.scale()`, `.rotate()` **return a new `TransformedDrawable`** — they do not mutate the original.  
+Always use the return value: `obj = obj.translate(dx, dy)`.  
+Never add mutable state to a `Drawable` subclass.
+
+### 2. `AnimationEvent.apply()` must be a pure function
+`apply(opsset, progress)` must not have side effects. It receives an OpsSet, returns a new one. It must not mutate `opsset`, modify `self`, or touch the scene.  
+The `Scene` caches the output of completed events and re-uses it as input to later events. Any side effect here will corrupt the timeline.
+
+### 3. OpsSet is the universal interface between layers
+Shapes produce OpsSet. Animations consume and return OpsSet. Cairo consumes OpsSet.  
+No layer should reach past OpsSet to touch Cairo directly — that is `OpsSet.render()`'s job only.
+
+### 4. Easing and progress
+The `progress` value passed to `apply()` is always in `[0.0, 1.0]`. If `easing_fun` is set on an event, apply it first: `progress = self.easing_fun(raw_progress) if self.easing_fun else raw_progress`. This is currently unimplemented everywhere — wire it in when touching any `apply()` method.
+
+---
+
+## Code Style
+
+- **No unnecessary comments** — name things well instead; only comment non-obvious invariants or external constraints
+- **Docstrings on important functions** — Add verbose docstrings for all important functions, as documentations are generated from it.
+- **Type annotations** — use them on all new public functions; prefer specific types over `Any`
+- **No defensive checks on internal paths** — only validate at system boundaries (file paths, user-supplied coordinates, external API calls)
+- **Prefer returning new objects** — consistent with the immutability design; avoid `opsset.opsset = ...` mutations inside animation code except in `OpsSet`'s own transform methods
+
+---
+
+## How the Rendering Pipeline Works (summary)
+
+```
+Scene.render()
+  └─ create_event_timeline()          # one OpsSet per frame
+       └─ for each active drawable:
+            get_animated_opsset_at_time(drawable_id, t, event_and_progress)
+              └─ recursive: apply events in order, cache completed ones
+                   └─ event.apply(opsset, progress) → OpsSet
+  └─ for each frame OpsSet:
+       viewport.apply_to_context(ctx)
+       opsset.render(ctx)              # the only Cairo call
+       write frame to video
+```
+
+The cache key for a completed event state is `"{drawable_id}__{event_id}"`.  
+The initial OpsSet (before any animation) is cached as `"{drawable_id}__init"`.
+
+---
+
+## Where to Add Things
+
+| What | Where |
+|---|---|
+| New shape | New file in `primitives/`, subclass `Drawable`, implement `draw() -> OpsSet` |
+| New animation | New file in `animations/`, subclass `AnimationEvent`, implement `apply(opsset, progress) -> OpsSet` |
+| New style option | Add field to `StrokeStyle` / `FillStyle` / `SketchStyle` in `core/styles.py` |
+| New fill pattern | `stylings/fillpatterns.py`, must return an `OpsSet` |
+| New color constant | `stylings/color.py` |
+| AI prompt | `handanim_ai/prompts/` as a `.txt` file |
+| New example | `examples/` as a standalone runnable script |
+
+---
+
+## Things to Be Careful About
+
+- **`SVG` vs `VectorSVG`** — there are two SVG importers. `VectorSVG` (using `svgelements`) is the current one with full color/transform support. `SVG` (using `svgpathtools`) is legacy, paths-only, and deprecated. Prefer `VectorSVG`. Do not add new code that imports from `primitives/svg.py`.
+- **`DrawableGroup` parallel mode** — uses `drawable_element_id` metadata on OpsSet to extract individual results after a group transformation. If you touch group animation logic in `scene.py`, test with nested groups.
+- **Viewport coordinates** — the default world space is `(0, 1777) × (0, 1000)` for a 1920×1088 scene. All primitive positions are in this coordinate system, not pixels.
+- **`SketchAnimation` and fill** — `get_partial_sketch` splits draw ops from fill ops using a `METADATA` op with `drawing_mode == "fill"`. Primitives that have both a stroked outline and a fill must emit this metadata correctly.
+
+---
+
+## Current Priorities (see todo.md for full list)
+
+1. Add visual regression tests before expanding the surface area further
+2. Implement `FlowchartNode` / `FlowchartConnector` as the next major primitive cluster
+3. Complete `apply_strokes_gradient` and wire up `ColorTransitionAnimation`
+4. Improve caching (static object cache, group transform result cache)

CLAUDE.md

@@ -0,0 +1,257 @@
+# DEVELOPMENT.md — handanim
+
+Developer reference for setting up, testing, documenting, and running handanim locally.
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- [Poetry](https://python-poetry.org/) for dependency management
+- Cairo system library (`pycairo` requires it; see platform notes below)
+
+### Cairo installation
+
+**macOS**
+```bash
+brew install cairo pkg-config
+```
+
+**Ubuntu / Debian**
+```bash
+sudo apt-get install libcairo2-dev pkg-config python3-dev
+```
+
+**Windows** — install via the [GTK for Windows Runtime](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases).
+
+---
+
+## Setup
+
+```bash
+# Clone and enter the repo
+git clone <repo-url>
+cd handanim
+
+# Install all dependencies (runtime + dev)
+poetry install --with dev
+
+# Activate the virtual environment (optional, for a plain shell)
+poetry shell
+```
+
+---
+
+## Running the Tests
+
+### Full test suite
+
+```bash
+poetry run python3 -m pytest
+```
+
+### Run a specific test file
+
+```bash
+poetry run python3 -m pytest tests/test_opsset.py
+poetry run python3 -m pytest tests/test_sketch.py
+poetry run python3 -m pytest tests/test_visuals.py
+```
+
+### Run a single test by name
+
+```bash
+poetry run python3 -m pytest -k "test_rotate_90_degrees"
+```
+
+### Verbose output
+
+```bash
+poetry run python3 -m pytest -v
+```
+
+---
+
+## Test Coverage
+
+Coverage is measured with `pytest-cov`. The `--cov-report=term-missing` flag shows exact line numbers not covered — open the file alongside the report to see which branches are untested.
+
+### Terminal report (line numbers)
+
+```bash
+poetry run python3 -m pytest --cov=src/handanim --cov-report=term-missing
+```
+
+### HTML report (browsable, colour-coded per file)
+
+```bash
+poetry run python3 -m pytest --cov=src/handanim --cov-report=html
+open htmlcov/index.html        # macOS
+xdg-open htmlcov/index.html    # Linux
+```
+
+### Single module only
+
+```bash
+poetry run python3 -m pytest --cov=src/handanim/primitives/text --cov-report=term-missing
+```
+
+### Enforce a minimum threshold (useful in CI)
+
+```bash
+poetry run python3 -m pytest --cov=src/handanim --cov-fail-under=50
+```
+
+---
+
+## Visual Regression Tests
+
+Visual regression tests live in `tests/test_visuals.py`. They render small deterministic scenes to PNG and compare them against reference files stored in `tests/snapshots/` using [SSIM](https://scikit-image.org/docs/stable/api/skimage.metrics.html#skimage.metrics.structural_similarity).
+
+**How numpy seeding makes renders deterministic:** every test runs with `numpy.random.seed(42)` (set via the `seed_numpy` autouse fixture in `conftest.py`). This makes the random jitter in rough primitives (Line, Rectangle, etc.) identical across runs.
+
+### Regenerate reference snapshots
+
+Run this after intentionally changing rendering output — for example, after modifying a primitive's draw method or a style default:
+
+```bash
+poetry run python3 -m pytest tests/test_visuals.py --snapshot-update
+```
+
+Review the diff in `tests/snapshots/` before committing to make sure the visual change is intentional.
+
+### Failure threshold
+
+A visual test fails when SSIM drops below **0.98**. This catches structural rendering changes while tolerating sub-pixel float differences across platforms.
+
+---
+
+## Building the Documentation
+
+Docs are built with [Sphinx](https://www.sphinx-doc.org/) using the [Furo](https://pradyunsg.me/furo/) theme. Docstrings are pulled in automatically via `sphinx.ext.autodoc`.
+
+```bash
+# Build HTML docs
+cd docs
+poetry run make html
+
+# Output is written to docs/build/html/
+# Open in browser
+open build/html/index.html        # macOS
+xdg-open build/html/index.html    # Linux
+```
+
+### Regenerating the API stubs
+
+If you add a new module and want it to appear in the docs, regenerate the `.rst` stubs from the project root:
+
+```bash
+poetry run sphinx-apidoc -o docs/source src/handanim --force
+```
+
+Then rebuild HTML as above.
+
+### Live reload during doc writing
+
+```bash
+poetry run sphinx-autobuild docs/source docs/build/html
+# Serves at http://127.0.0.1:8000 and reloads on file change
+```
+
+> `sphinx-autobuild` is not in the dev dependencies by default. Install it once with `poetry add --group dev sphinx-autobuild`.
+
+---
+
+## Running Examples
+
+Each script in `examples/` is a self-contained scene that renders to an MP4 (written to `examples/output/`).
+
+```bash
+# Pythagoras theorem — text, polygons, eraser
+poetry run python3 examples/pythagoras.py
+
+# (a+b)² visual proof — algebra with hand-drawn shapes
+poetry run python3 examples/a_plus_b_square.py
+
+# Distributive property with an SVG character
+poetry run python3 examples/distributive_property.py
+
+# Solar system orbit animation
+poetry run python3 examples/solar_system.py
+
+# Custom font rendering
+poetry run python3 examples/custom_font.py
+```
+
+Output files land in `examples/output/`. The examples are the canonical "does this actually work end-to-end" check — run one before and after touching rendering code.
+
+---
+
+## Quick Smoke Test (no video output)
+
+To verify a primitive renders without errors, use `OpsSet.quick_view()`. It renders to a temporary SVG and opens it in your browser:
+
+```python
+from handanim.primitives import Rectangle
+from handanim.core.styles import StrokeStyle, SketchStyle
+
+rect = Rectangle(
+    top_left=(100, 100),
+    width=400,
+    height=300,
+    stroke_style=StrokeStyle(color=(0.1, 0.1, 0.8), width=2),
+    sketch_style=SketchStyle(roughness=1),
+)
+rect.draw().quick_view()
+```
+
+Run it with:
+
+```bash
+poetry run python3 -c "
+from handanim.primitives import Rectangle
+from handanim.core.styles import StrokeStyle
+rect = Rectangle((100,100), 400, 300, stroke_style=StrokeStyle(color=(0,0,0.8), width=2))
+rect.draw().quick_view(block=False)
+"
+```
+
+---
+
+## Project Layout Cheat Sheet
+
+```
+src/handanim/
+├── core/          # OpsSet, Drawable, AnimationEvent, Scene, Viewport, styles
+├── primitives/    # Line, Rectangle, Ellipse, Arrow, Text, Math, VectorSVG, …
+├── animations/    # SketchAnimation, FadeIn/Out, Zoom, Translate
+└── stylings/      # color constants, fill patterns, stroke utilities
+
+tests/
+├── conftest.py          # shared fixtures (seed_numpy, render_to_png_bytes)
+├── snapshots/           # reference PNGs for visual regression
+├── test_opsset.py       # geometry unit tests (no Cairo)
+├── test_sketch.py       # SketchAnimation logic tests (no Cairo)
+└── test_visuals.py      # visual regression tests (Cairo + pytest-snapshot)
+
+examples/        # runnable end-to-end scene scripts
+docs/            # Sphinx source and build output
+```
+
+---
+
+## Useful One-Liners
+
+```bash
+# Check that the package imports cleanly
+poetry run python3 -c "import handanim; print('ok')"
+
+# List all test node IDs without running them
+poetry run python3 -m pytest --collect-only -q
+
+# Run only tests that don't touch Cairo (fast pure-logic subset)
+poetry run python3 -m pytest tests/test_opsset.py tests/test_sketch.py
+
+# Show which snapshot files exist
+ls tests/snapshots/
+```