tutordraw 0.1.0a3__tar.gz

tutordraw-0.1.0a3/AGENTS.md

@@ -0,0 +1,42 @@
+# Working on TutorDraw
+
+## Start here
+
+Read `README.md`, `docs/HANDOFF.md`, `docs/ARCHITECTURE.md`, and
+`docs/ROADMAP.md` before implementing. Consult `docs/DECISIONS.md` for rationale.
+Inspect actual repository files rather than assuming the handoff is current.
+
+## Project boundary
+
+- This is TutorDraw, a Python tutorial-authoring library using DrawCV.
+- Depend on the `pydrawcv` distribution, imported as `drawcv`.
+- Do not modify `C:/Projects/DrawCV` as part of ordinary TutorDraw work.
+  If an upstream limitation blocks progress, document it and seek a TutorDraw
+  adapter or a reduced, explicitly documented feature first.
+- Keep drawing/rendering concerns in DrawCV and teaching concerns in TutorDraw.
+- The owner wants useful documentation for switching between AI models.
+- Proposed APIs are not existing APIs. Update documentation as implementation
+  settles, and keep examples clearly marked until verified runnable.
+
+## Development conventions
+
+- Target Python 3.12+ initially. Use a `src/tutordraw/` layout when code begins.
+- Prefer small typed public APIs and explicit validation errors.
+- Isolate DrawCV-specific lookups, bounds, and cloning in an adapter.
+- Preserve the user's source scene when producing tutorial output.
+- Prefer independent step state over replay-dependent actions for static export.
+- Test meaningful behavior: references, transformed anchors, source preservation,
+  step independence, errors, and actual image export.
+- Visually inspect rendered examples in addition to numerical tests.
+- Do not hardcode local checkout paths or invent dependency compatibility claims.
+- Do not publish a package unless the owner explicitly requests publication.
+
+## Before handing off
+
+Update `docs/HANDOFF.md` with implemented capabilities, changed files,
+commands actually run and their outcomes, unresolved issues, and the next
+concrete task. Update the roadmap checkboxes and record material design changes
+in `docs/DECISIONS.md`. Never mark a check complete without evidence.
+
+Keep these documents concise enough that another model can resume without the
+previous conversation. Never include credentials, tokens, or private indexes.

tutordraw-0.1.0a3/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+The first public release candidate is 0.1.0a3; earlier versions were local development milestones.
+
+## 0.1.0a3 — first alpha
+
+- Add installed-wheel CI for Windows, Linux, and macOS on Python 3.12–3.14.
+- Add repeatable distribution, documentation, and installed-example checks.
+- Add MIT license and author metadata approved by Nuh Yamin.
+- Document compatibility evidence, the tutorial authoring workflow, alpha API
+  expectations, and a manual publishing procedure.
+- Keep `pydrawcv==0.10.0.post1` as the tested dependency contract.
+
+No intentional public API or drawing behavior changes from 0.1.0a2.
+CI configuration alone is not evidence that every matrix environment passes.
+
+## 0.1.0a2 — static tutorial workflow
+
+- Wrapped callouts, rectangular highlights, group-aware dimming, and shared themes.
+- Ordered PNG export with collision checks and partial-failure reporting.
+- Three-step cell lesson and nested-group example; 54 passing local tests.
+
+## 0.1.0a1 — initial rendering API
+
+- Teaching targets, reusable labels, straight leader lines, independent steps,
+  and source-preserving PNG rendering.
+- Installable src-layout package, example, 30 tests, and AI handoff documentation.

tutordraw-0.1.0a3/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+Use Python 3.12 or newer. Work in a virtual environment, install from the project
+root with `python -m pip install -e ".[dev]"`, and run `python -m pytest -q`.
+On Windows the existing environment uses `.venv/Scripts/python.exe`.
+
+Read [the architecture](docs/ARCHITECTURE.md), [API guide](docs/API.md), and
+[agent instructions](AGENTS.md). Keep DrawCV rendering code upstream; implement
+teaching behavior here through the adapter.
+
+Before submitting:
+
+1. Test meaningful behavior, especially independent steps, source preservation,
+   group transforms/dimming, and export failures.
+2. Run `python tools/check_docs.py` to verify links and the README example.
+3. Run examples and inspect images after visual changes.
+4. Update the changelog and documentation for public API changes.
+5. Update [the handoff](docs/HANDOFF.md) with verification and remaining work.
+
+The installed-package check intentionally rejects editable source imports.
+Build a wheel, install it in a separate environment, and run
+`python -I tools/check_installed.py` using that environment's Python.
+CI performs this check on the built wheel automatically.
+
+The project is currently alpha. Avoid breaking public methods without documenting
+migration instructions. Do not widen the DrawCV dependency pin without testing
+released wheels. See [release preparation](docs/RELEASING.md) for package checks.

tutordraw-0.1.0a3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nuh Yamin
+
+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.

tutordraw-0.1.0a3/MANIFEST.in

@@ -0,0 +1,6 @@
+include AGENTS.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tools *.py

tutordraw-0.1.0a3/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: tutordraw
+Version: 0.1.0a3
+Summary: Author step-by-step visual tutorials using DrawCV drawings.
+Author: Nuh Yamin
+License-Expression: MIT
+Project-URL: Repository, https://github.com/nuhyamin1/tutordraw
+Project-URL: Issues, https://github.com/nuhyamin1/tutordraw/issues
+Project-URL: Documentation, https://github.com/nuhyamin1/tutordraw#readme
+Keywords: tutorial,drawing,education,diagram,drawcv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydrawcv==0.10.0.post1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# TutorDraw
+
+**Explain what you draw, one step at a time.**
+
+TutorDraw is a Python library for authoring visual tutorials using [DrawCV](https://pypi.org/project/pydrawcv/). DrawCV supplies drawing objects and rendering; TutorDraw attaches teaching annotations and organizes them into independent lesson steps.
+
+## Status
+
+**Early alpha `0.1.0a3`.** TutorDraw provides the static tutorial workflow described below. Licensed under MIT, authored by Nuh Yamin. See the compatibility notes before relying on it in production.
+
+Implemented:
+
+- Register existing DrawCV objects or groups as teaching targets.
+- Attach labels with optional straight leader lines.
+- Configure bounds anchors, gap, offset, padding, and font scale.
+- Keep labels attached when targets move, including through group transforms.
+- Define independent steps and render them to DrawCV canvases and PNG images.
+- Preserve source content and undo history, including on rendering failure.
+- Add step-local wrapped callouts, rectangular highlights, and group-aware dimming.
+- Customize shared typography, spacing, and colors through an immutable theme.
+- Export ordered PNGs with collision checks and partial-failure reporting.
+- Validate references/options and warn about off-canvas annotations.
+
+Video, interactive playback, rich typography, and automatic collision avoidance remain planned.
+
+## Install the alpha
+
+```shell
+python -m pip install tutordraw==0.1.0a3
+```
+
+The exact version selects this prerelease explicitly. Requires Python 3.12+.
+
+## Develop from this repository
+
+Requires **Python 3.12+**. From the repository root:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest -q
+.\.venv\Scripts\python.exe examples/cell_tutorial.py
+```
+
+On macOS/Linux, use `.venv/bin/python` instead. Windows/Python 3.12 passes 62 tests. CI is configured for Windows, Linux, and macOS on Python 3.12–3.14; hosted results are pending. If `python` is unavailable, use the absolute path to an installed Python 3.12+ executable for the first command.
+
+No DrawCV checkout is needed. TutorDraw pins the tested published dependency `pydrawcv==0.10.0.post1`, which imports as `drawcv`. A broader compatibility range is future work. Use an explicit version or `--pre` when selecting an alpha release.
+
+## Working example
+
+```python
+from drawcv import Circle, Color, FillStyle, Point, Scene
+from tutordraw import Tutorial
+
+scene = Scene(640, 360, background=Color.white())
+shape = Circle(
+    center=Point(180, 180), radius=45,
+    fill=FillStyle(color=Color(131, 151, 218)),
+)
+scene.add(shape)
+
+tutorial = Tutorial(scene, title="Inside a cell")
+nucleus = tutorial.target(shape, name="nucleus")
+label = nucleus.label("Nucleus", anchor="top", leader=True)
+
+intro = tutorial.step("Meet the nucleus").show(label)
+intro.highlight(nucleus)
+intro.explain(nucleus, "The nucleus contains the cell's DNA.", max_width=220)
+tutorial.step("Review the drawing")
+
+tutorial.render_step(0).save("output/nucleus.png")
+tutorial.render_step(1).save("output/plain.png")
+# Batch export refuses existing files unless overwrite=True is explicit.
+tutorial.export_steps("output/readme", overwrite=True)
+```
+
+Each step starts from the current source scene. The second step has no labels because it does not explicitly show any. Rendering order does not affect results. Tutorial and step titles are metadata; add DrawCV text if you want visible titles.
+
+Run [the cell example](https://github.com/nuhyamin1/tutordraw/blob/master/examples/cell_tutorial.py) for a composed diagram. It writes `output/cell/step-001.png` through `step-003.png`. Rerunning explicitly overwrites these example images. [The nested-group example](https://github.com/nuhyamin1/tutordraw/blob/master/examples/group_focus.py) illustrates focusing a child while dimming its siblings.
+
+## Current limits
+
+- Labels support **single-line printable ASCII**; callouts additionally support newlines and measured word wrapping. Other scripts and rich typography are not implemented yet.
+- Anchors use transformed axis-aligned `get_bounds()` results, including supported shape strokes but excluding post-processing effect extents.
+- Labels stay upright and spacing uses canvas pixels. Automatic collision avoidance and routed leaders are deferred.
+- Off-canvas annotations issue `LayoutWarning` and may be clipped. Callout widths measure the text area; padding adds to the panel width.
+- Dimming multiplies artwork opacity, not the background. Complex masks, blend modes, and occlusion are not pixel-level spotlight isolation. Hidden or zero-opacity attention targets are rejected; clipping and masks are not used to infer visibility.
+- Scenes must round-trip through DrawCV serialization; unsupported copying raises `SceneCopyError`. Arbitrary custom drawables/assets are not guaranteed supported.
+- Rendering uses authored scene state without sampling a timeline. Concurrent source edits during rendering are unsupported.
+- Missing registered targets fail rendering, even if their label is not shown in that step. Hidden artwork does not suppress an explicitly shown label.
+
+## Documentation and continuation
+
+- [Practical tutorial](https://github.com/nuhyamin1/tutordraw/blob/master/docs/TUTORIAL.md): build a lesson from a DrawCV scene.
+- [API guide](https://github.com/nuhyamin1/tutordraw/blob/master/docs/API.md): implemented methods and errors.
+- [Compatibility](https://github.com/nuhyamin1/tutordraw/blob/master/docs/COMPATIBILITY.md): evidence, fonts, and alpha API expectations.
+- [Release procedure](https://github.com/nuhyamin1/tutordraw/blob/master/docs/RELEASING.md): exact artifact checks and manual publishing.
+- [Changelog](https://github.com/nuhyamin1/tutordraw/blob/master/CHANGELOG.md): milestone history.
+- [Contributing](https://github.com/nuhyamin1/tutordraw/blob/master/CONTRIBUTING.md): local development and installed-package checks.
+- [Product scope](https://github.com/nuhyamin1/tutordraw/blob/master/docs/PRODUCT.md): intended tutorial capabilities.
+- [Architecture](https://github.com/nuhyamin1/tutordraw/blob/master/docs/ARCHITECTURE.md): foundation and future design.
+- [Roadmap](https://github.com/nuhyamin1/tutordraw/blob/master/docs/ROADMAP.md): milestones and acceptance checks.
+- [AI handoff](https://github.com/nuhyamin1/tutordraw/blob/master/docs/HANDOFF.md): current state, verification, and continuation prompt.
+- [Decisions](https://github.com/nuhyamin1/tutordraw/blob/master/docs/DECISIONS.md): choices and remaining questions.
+- [Agent instructions](https://github.com/nuhyamin1/tutordraw/blob/master/AGENTS.md): repository conventions.
+
+To continue with another AI model, ask it to read `AGENTS.md` and `docs/HANDOFF.md` first. Hosted CI verification remains pending; see the handoff for the latest release state. DrawCV remains a separate project.
+
+## License
+
+[MIT](https://github.com/nuhyamin1/tutordraw/blob/master/LICENSE), copyright 2026 Nuh Yamin.

tutordraw-0.1.0a3/README.md

@@ -0,0 +1,111 @@
+# TutorDraw
+
+**Explain what you draw, one step at a time.**
+
+TutorDraw is a Python library for authoring visual tutorials using [DrawCV](https://pypi.org/project/pydrawcv/). DrawCV supplies drawing objects and rendering; TutorDraw attaches teaching annotations and organizes them into independent lesson steps.
+
+## Status
+
+**Early alpha `0.1.0a3`.** TutorDraw provides the static tutorial workflow described below. Licensed under MIT, authored by Nuh Yamin. See the compatibility notes before relying on it in production.
+
+Implemented:
+
+- Register existing DrawCV objects or groups as teaching targets.
+- Attach labels with optional straight leader lines.
+- Configure bounds anchors, gap, offset, padding, and font scale.
+- Keep labels attached when targets move, including through group transforms.
+- Define independent steps and render them to DrawCV canvases and PNG images.
+- Preserve source content and undo history, including on rendering failure.
+- Add step-local wrapped callouts, rectangular highlights, and group-aware dimming.
+- Customize shared typography, spacing, and colors through an immutable theme.
+- Export ordered PNGs with collision checks and partial-failure reporting.
+- Validate references/options and warn about off-canvas annotations.
+
+Video, interactive playback, rich typography, and automatic collision avoidance remain planned.
+
+## Install the alpha
+
+```shell
+python -m pip install tutordraw==0.1.0a3
+```
+
+The exact version selects this prerelease explicitly. Requires Python 3.12+.
+
+## Develop from this repository
+
+Requires **Python 3.12+**. From the repository root:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest -q
+.\.venv\Scripts\python.exe examples/cell_tutorial.py
+```
+
+On macOS/Linux, use `.venv/bin/python` instead. Windows/Python 3.12 passes 62 tests. CI is configured for Windows, Linux, and macOS on Python 3.12–3.14; hosted results are pending. If `python` is unavailable, use the absolute path to an installed Python 3.12+ executable for the first command.
+
+No DrawCV checkout is needed. TutorDraw pins the tested published dependency `pydrawcv==0.10.0.post1`, which imports as `drawcv`. A broader compatibility range is future work. Use an explicit version or `--pre` when selecting an alpha release.
+
+## Working example
+
+```python
+from drawcv import Circle, Color, FillStyle, Point, Scene
+from tutordraw import Tutorial
+
+scene = Scene(640, 360, background=Color.white())
+shape = Circle(
+    center=Point(180, 180), radius=45,
+    fill=FillStyle(color=Color(131, 151, 218)),
+)
+scene.add(shape)
+
+tutorial = Tutorial(scene, title="Inside a cell")
+nucleus = tutorial.target(shape, name="nucleus")
+label = nucleus.label("Nucleus", anchor="top", leader=True)
+
+intro = tutorial.step("Meet the nucleus").show(label)
+intro.highlight(nucleus)
+intro.explain(nucleus, "The nucleus contains the cell's DNA.", max_width=220)
+tutorial.step("Review the drawing")
+
+tutorial.render_step(0).save("output/nucleus.png")
+tutorial.render_step(1).save("output/plain.png")
+# Batch export refuses existing files unless overwrite=True is explicit.
+tutorial.export_steps("output/readme", overwrite=True)
+```
+
+Each step starts from the current source scene. The second step has no labels because it does not explicitly show any. Rendering order does not affect results. Tutorial and step titles are metadata; add DrawCV text if you want visible titles.
+
+Run [the cell example](https://github.com/nuhyamin1/tutordraw/blob/master/examples/cell_tutorial.py) for a composed diagram. It writes `output/cell/step-001.png` through `step-003.png`. Rerunning explicitly overwrites these example images. [The nested-group example](https://github.com/nuhyamin1/tutordraw/blob/master/examples/group_focus.py) illustrates focusing a child while dimming its siblings.
+
+## Current limits
+
+- Labels support **single-line printable ASCII**; callouts additionally support newlines and measured word wrapping. Other scripts and rich typography are not implemented yet.
+- Anchors use transformed axis-aligned `get_bounds()` results, including supported shape strokes but excluding post-processing effect extents.
+- Labels stay upright and spacing uses canvas pixels. Automatic collision avoidance and routed leaders are deferred.
+- Off-canvas annotations issue `LayoutWarning` and may be clipped. Callout widths measure the text area; padding adds to the panel width.
+- Dimming multiplies artwork opacity, not the background. Complex masks, blend modes, and occlusion are not pixel-level spotlight isolation. Hidden or zero-opacity attention targets are rejected; clipping and masks are not used to infer visibility.
+- Scenes must round-trip through DrawCV serialization; unsupported copying raises `SceneCopyError`. Arbitrary custom drawables/assets are not guaranteed supported.
+- Rendering uses authored scene state without sampling a timeline. Concurrent source edits during rendering are unsupported.
+- Missing registered targets fail rendering, even if their label is not shown in that step. Hidden artwork does not suppress an explicitly shown label.
+
+## Documentation and continuation
+
+- [Practical tutorial](https://github.com/nuhyamin1/tutordraw/blob/master/docs/TUTORIAL.md): build a lesson from a DrawCV scene.
+- [API guide](https://github.com/nuhyamin1/tutordraw/blob/master/docs/API.md): implemented methods and errors.
+- [Compatibility](https://github.com/nuhyamin1/tutordraw/blob/master/docs/COMPATIBILITY.md): evidence, fonts, and alpha API expectations.
+- [Release procedure](https://github.com/nuhyamin1/tutordraw/blob/master/docs/RELEASING.md): exact artifact checks and manual publishing.
+- [Changelog](https://github.com/nuhyamin1/tutordraw/blob/master/CHANGELOG.md): milestone history.
+- [Contributing](https://github.com/nuhyamin1/tutordraw/blob/master/CONTRIBUTING.md): local development and installed-package checks.
+- [Product scope](https://github.com/nuhyamin1/tutordraw/blob/master/docs/PRODUCT.md): intended tutorial capabilities.
+- [Architecture](https://github.com/nuhyamin1/tutordraw/blob/master/docs/ARCHITECTURE.md): foundation and future design.
+- [Roadmap](https://github.com/nuhyamin1/tutordraw/blob/master/docs/ROADMAP.md): milestones and acceptance checks.
+- [AI handoff](https://github.com/nuhyamin1/tutordraw/blob/master/docs/HANDOFF.md): current state, verification, and continuation prompt.
+- [Decisions](https://github.com/nuhyamin1/tutordraw/blob/master/docs/DECISIONS.md): choices and remaining questions.
+- [Agent instructions](https://github.com/nuhyamin1/tutordraw/blob/master/AGENTS.md): repository conventions.
+
+To continue with another AI model, ask it to read `AGENTS.md` and `docs/HANDOFF.md` first. Hosted CI verification remains pending; see the handoff for the latest release state. DrawCV remains a separate project.
+
+## License
+
+[MIT](https://github.com/nuhyamin1/tutordraw/blob/master/LICENSE), copyright 2026 Nuh Yamin.

tutordraw-0.1.0a3/docs/API.md

@@ -0,0 +1,102 @@
+# Implemented API — 0.1.0a3
+
+Public symbols import from `tutordraw`. Create targets/annotations/steps through the factory methods below rather than calling their constructors directly.
+
+## Tutorial
+
+`Tutorial(scene, *, title="", theme=None)` holds a DrawCV Scene reference and a Theme (defaults to `Theme()`). The scene is read at each render. Titles are metadata, not automatically drawn text.
+
+`tutorial.target(drawable, *, name=None) -> Target` registers an existing object/group, including nested children. Re-registration returns the same target. Explicit names must be nonempty and unique; conflicting names raise `ValidationError`.
+
+`tutorial.step(title) -> Step` appends an independent step. Nonempty titles are required; duplicate titles are allowed. `tutorial.steps` returns a tuple.
+
+`tutorial.render_step(index, *, alpha=False) -> drawcv.Canvas` renders a zero-based step through a copied scene. Negative indices and booleans are rejected. Use `alpha=True` for BGRA output; source background transparency is respected. `canvas.save(path)` uses DrawCV's save behavior and can overwrite existing files.
+
+## Labels
+
+```python
+label = target.label(
+    "Nucleus", anchor="right", leader=True,
+    gap=None, offset=(0, 0), font_scale=None, padding=None,
+)
+step.show(label)
+```
+
+Labels are immutable reusable definitions, absent until explicitly shown. Target fields `id`, `drawable_id`, and `name` are immutable.
+
+| Option | Behavior |
+| --- | --- |
+| `text` | Nonempty, single-line printable ASCII |
+| `anchor` | `left`, `right`, `top`, `bottom`, or `center` of world-space bounds |
+| `leader` | Boolean, enables a straight leader |
+| `gap` | Nonnegative pixel distance from anchor to panel edge; theme default 32 |
+| `offset` | Additional `(x, y)` pixels, either sign |
+| `font_scale` | Hershey scale, >0 and <=10; theme default 0.7 |
+| `padding` | Nonnegative pixels around text; theme default 10 |
+
+`None` uses the theme default at authoring time. Center-anchored labels are placed to the right of the target center. Text remains upright. Leaders terminate on panel edges; if the target lies within the panel, its leader is omitted. Spacing uses canvas pixels and does not inherit object scaling.
+
+`step.show(*labels) -> Step` accepts registered labels from the same tutorial, ignores duplicates, and leaves the step unchanged if any argument is invalid. `step.labels` is a tuple. Steps never inherit presentation state from each other.
+
+## Callouts
+
+```python
+callout = step.explain(
+    target, "The nucleus contains DNA.\nThis information guides cell activity.",
+    anchor="right", max_width=260, gap=40,
+)
+```
+
+`step.explain` accepts all label layout options plus `max_width=None` and `line_spacing=None`. It returns a `Callout` and automatically shows it only in this step. Callouts cannot be passed to `show` in another step; call `explain` there instead. `step.callouts` returns a tuple.
+
+`max_width` limits the **text area**, excluding panel padding. Default: theme `callout_width=260`. Words wrap using DrawCV measurements. Oversized words split at characters; a width too narrow for one character raises `ValidationError` when rendered. Explicit newlines preserve paragraph breaks, including blank lines; other spaces normalize. Text remains printable ASCII plus newlines. Line spacing is at least 1, default 1.35 times measured line height.
+
+## Highlights and dimming
+
+```python
+step.highlight(target, padding=8, color=(226, 146, 33), width=3)
+step.dim_others(target, another_target, opacity=0.25)
+```
+
+`highlight(target, *, padding=None, color=None, width=None) -> Step` creates a rectangular outline around transformed axis-aligned bounds. None uses theme defaults. Width must be positive; padding nonnegative; color is an RGB tuple. Repeating this call for the same target replaces its settings. `step.highlights` exposes a tuple of definitions.
+
+`dim_others(*targets, opacity=None) -> Step` preserves one or more targets and multiplies unrelated artwork opacity by a factor in [0,1]. The theme default is 0.25. Repeating it replaces the focus set. A selected group preserves its subtree; a selected child preserves its ancestors while unrelated branches dim exactly once. Existing ancestor opacity still applies. Annotations are never dimmed.
+
+Highlight/focus requests for targets under hidden or zero-opacity objects/layers fail at render time. Empty/all-hidden groups are rejected. Masks, clipping, blend modes, and occlusion are not visibility tests. Dimming is opacity reduction, not pixel-level spotlight isolation. Background color is unchanged. Titles drawn into the source are artwork too; register and focus them if they should stay undimmed.
+
+## Theme
+
+`Theme(...)` is an immutable set of validated defaults:
+
+| Field | Default |
+| --- | --- |
+| `text_color` | `(28, 43, 65)` |
+| `panel_color` | `(255, 255, 255)` |
+| `border_color` | `(194, 207, 223)` |
+| `leader_color` | `(75, 104, 140)` |
+| `highlight_color` | `(226, 146, 33)` |
+| `font_scale`, `padding`, `gap` | `0.7`, `10`, `32` |
+| `leader_width`, `border_width`, `highlight_width` | `2`, `1`, `3` |
+| `highlight_padding` | `8` |
+| `callout_width`, `line_spacing` | `260`, `1.35` |
+| `dim_opacity` | `0.25` |
+
+Colors are immutable RGB tuples, channels 0–255. Numeric annotation defaults and highlight settings resolve at creation time. Panel/text/leader colors and border/leader widths come from the tutorial's current theme at render time. Supply a theme when constructing the tutorial for consistent styling.
+
+## Ordered PNG export
+
+`tutorial.export_steps(directory, *, overwrite=False, alpha=False) -> list[Path]` writes `step-001.png`, `step-002.png`, etc. Returned paths follow step order. Empty tutorials raise `ValidationError`. Titles never become filesystem paths.
+
+Every filename is checked before export; collisions raise `FileExistsError` unless overwrite is explicit. Symlinks and non-file destinations are rejected even with overwrite. Concurrent file creation after preflight also cannot overwrite a file when overwrite is false.
+
+Frames encode in temporary files. Explicit overwrite replaces an existing file only after successful encoding; a failed newly-created file is removed. This is not a transaction across the batch: successful earlier files remain if a later step fails. A new file may be visible during its copy. Permission/directory failures during preflight can propagate as filesystem exceptions.
+
+## Errors and warnings
+
+- `TutorDrawError`: base exception.
+- `ValidationError`: invalid options/references/indices, hidden attention targets, or layout that cannot fit a character. Also a ValueError.
+- `SceneCopyError`: failure copying through DrawCV's document API, with chained cause.
+- `ExportError`: failure after export starts. Inspect zero-based `step_index`, `path`, `completed_paths` (tuple), and `__cause__`.
+- `LayoutWarning`: an annotation extends outside the canvas. Rendering proceeds and may clip it.
+
+Direct render/save errors from DrawCV propagate; batch export wraps per-step failures in ExportError. Rendering preserves source content and history even on failure. Automatic label collision avoidance, rich fonts, timeline sampling, and concurrent source editing are not supported.