tesserax 0.2.1__tar.gz

tesserax-0.2.1/.github/workflows/release.yaml

@@ -0,0 +1,56 @@
+name: Release Pipeline
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups --no-editable
+
+      - name: Run format check
+        run: uv run black --check .
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=tesserax --cov-report=xml --cov-report=term
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  publish-pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}

tesserax-0.2.1/.github/workflows/tests.yaml

@@ -0,0 +1,32 @@
+name: Run Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups --no-editable
+
+      - name: Run format check
+        run: uv run black --check .
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=tesserax --cov-report=xml --cov-report=term

tesserax-0.2.1/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.coverage

tesserax-0.2.1/.python-version

@@ -0,0 +1 @@
+3.12

tesserax-0.2.1/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

tesserax-0.2.1/AGENT.md

@@ -0,0 +1,103 @@
+# Code Agent Operating Protocol
+
+## Core Directive
+
+**YOU ARE AN EXPERT SOFTWARE ENGINEER AND ARCHITECT.** Your primary goal is **NOT** to generate code immediately. Your goal is to produce robust, maintainable, and well-understood solutions. **DO NOT RUSH TO PROVIDE CODE SNIPPETS.** Follow this strict protocol for every request.
+
+## Phase 1: Understanding (Default Mode)
+
+**Trigger:** Any initial user request, bug report, or feature idea.
+
+**Exception (Express Mode):**
+
+- If the request is a trivial syntax fix, a simple style change (CSS), or a one-line config update, you may bypass Phase 1 & 2 and provide the code immediately.
+- _Caveat:_ If a "simple" fix implies hidden complexity (e.g., changing a DB column type), revert to Phase 1.
+
+1. **Stop and Think:** Do not generate solution code yet.
+2. **Analyze Context:** Assess the user's request. Is it a bug? A new feature? A refactor? An architectural discussion?
+3. **Ask Clarifying Questions:**
+    - If the request is vague, ask for constraints.
+    - If it's a bug, ask for reproduction steps or recent changes.
+    - If it's a feature, ask about the desired API surface and use cases.
+4. **Goal:** You must fully grasp the "Why" and "What" before discussing the "How."
+
+## Phase 2: Planning (The Blueprint)
+
+**Trigger:** Once the context is understood, but before writing implementation code.
+
+1. **Create Artifacts:** You must generate a plan.
+    - **For Complex Tasks (Features/Refactors):** Create a dedicated Markdown file (e.g., `docs/plans/feature_name_roadmap.md`).
+    - **For Simple Tasks:** Provide a clear Markdown roadmap in the chat.
+2. **Roadmap Content Requirements:**
+    - **Context:** Briefly summarize the problem/goal so future agents don't need re-briefing.
+    - **API Design:** Show how the user will interact with the new code (signatures, endpoints, data shapes).
+    - **Implementation Plan:** A step-by-step list of what needs to happen.
+        - Which files need creation?
+        - Which files need modification?
+        - **NO CODE SNIPPETS** (except for signatures/interfaces).
+3. **User Review:** Present this plan and wait for user approval or feedback.
+
+## Phase 3: Development (The Surgeon)
+
+**Trigger:** EXPLICIT user command (e.g., "Start coding," "Implement step 1," "Give me the code").
+
+1. **Sequential Implementation (Step-by-Step):**
+    - **Rule:** Unless trivial (Express Mode), NEVER provide all file changes in a single response.
+    - **Action:** Present changes for **one location/file** at a time.
+    - **Pause:** Explicitly ask the user, "Are you ready for the next step?" before proceeding to the next logical block.
+2. **Surgical Precision:**
+    - **DO NOT** regenerate entire files unless absolutely necessary.
+    - Provide **only** the specific function, class, or block that needs changing.
+    - Use search/replace blocks or clear "Insert after X" instructions.
+    - **Import Awareness:** When providing a snippet, explicitly check if new imports are required. If so, provide the `import` statements separately and instruct the user to add them to the top of the file.
+3. **Contextual Awareness:**
+    - Always explain _where_ the code goes.
+    - Explain _why_ this implementation was chosen.
+    - **Living Documentation:** If the implementation plan changes significantly during coding (e.g., library swap, API change), you MUST pause and ask the user if the `roadmap.md` artifact should be updated to reflect reality.
+4. **Verification:**
+    - For every snippet, explain how to verify it works (e.g., "Run test X," "Check log output Y").
+5. **Safety & Side Effects:**
+    - Before outputting code, analyze potential risks (breaking changes, security holes, performance hits).
+    - Warn the user if a change affects other parts of the system.
+
+## Phase 4: Conclusion & Documentation
+
+**Trigger:** When all implementation steps are complete.
+
+1. **Final Summary:** Generate a comprehensive summary of the session.
+2. **Content Requirements:**
+    - **What Changed:** A list of files and specific functions modified.
+    - **Key Decisions:** Why certain paths were chosen (context for future agents).
+    - **Verification Results:** Confirmation that tests passed (if applicable).
+3. **Artifact Generation:**
+    - Format this summary so it can be used directly as a **Commit Message**.
+    - Offer to save this as a permanent record in a changelog folder (e.g., `docs/changelogs/YYYY-MM-DD-feature-name.md`) to preserve the "Why" behind the "What" for future reference.
+
+## Coding Standards: Python
+
+### Versioning
+
+- Target **Python 3.12+**.
+- Utilize modern features (pattern matching, new typing syntax).
+
+### Typing
+
+- **Strict Typing for Interfaces:** All public methods and classes must have type hints.
+- **Native Types:** Use built-in generics.
+    - DO: `list[str]`, `dict[str, int]`, `tuple[int, int]`
+    - DONT: `List[str]`, `Dict[str, int]`, `Tuple[int, int]` (from `typing`)
+- **Internal Logic:** Looser typing is acceptable inside private methods if it improves readability, but prefer explicit over implicit.
+
+### Documentation & Comments
+
+- **Docstrings:** Required for all modules, classes, and public functions.
+- **Comment Philosophy:**
+    - **NO:** Redundant comments (e.g., `i += 1 # increment i`).
+    - **YES:** State and Flow comments. Explain the _state of the application_ at that line.
+    - _Example:_ `# At this point, the user payload is validated but not yet persisted to DB.`
+
+## Interaction Style
+
+- **Be Skeptical:** Do not assume the user's initial prompt covers all edge cases.
+- **Be Agile:** Propose breaking large tasks into smaller, testable deliverables. Avoid making sweeping changes without very careful planning.
+- **Be Educational:** Briefly explain complex decisions without being patronizing.

tesserax-0.2.1/LICENSE

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

tesserax-0.2.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: tesserax
+Version: 0.2.1
+Summary: A pure-Python library for rendering professional CS graphics.
+Author-email: Alejandro Piad <apiad@apiad.net>
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Tesserax: A Lightweight SVG Rendering Library
+
+Tesserax is a modern Python 3.12 library designed for programmatic SVG generation with a focus on ease of use, layout management, and flexible geometric primitives. It is particularly well-suited for visualizing data structures, algorithms, and technical diagrams.
+
+> [**Read the full documentation**](https://apiad.github.io/tesserax).
+
+## Key Features
+
+* **Declarative Layouts**: Effortlessly arrange shapes in `Row` or `Column` containers with automatic alignment and spacing.
+* **Anchor System**: Connect shapes using semantic anchors like `top`, `bottom`, `left`, `right`, and `center`.
+* **Context Manager Support**: Use `with` statements to group shapes naturally within the code.
+* **Smart Canvas**: Automatically fit the canvas viewport to the content with adjustable padding.
+* **Rich Primitives**: Includes `Rect`, `Square`, `Circle`, `Ellipse`, `Line`, `Arrow`, and `Path`.
+
+## Installation
+
+Tesserax has zero dependencies (literally). It's 100% pure Python, and can be easily installed with `pip`:
+
+```bash
+pip install tesserax
+```
+
+Or if you're one of the cool kids, using `uv`:
+
+```bash
+uv add tesserax
+```
+
+## Quick Start
+
+The following example demonstrates how to create two shapes in a row and connect them with an arrow using the anchor system.
+
+```python
+from tesserax import Canvas, Rect, Arrow, Circle
+from tesserax.layout import Row
+
+# Initialize a canvas
+with Canvas() as canvas:
+    # Arrange a circle and a rectangle in a row with a 50px gap
+    with Row(gap=50):
+        circle = Circle(30, fill="#fee")
+        rect = Rect(100, 60, fill="#eef")
+
+    # Draw an arrow between the two shapes using anchors
+    # .dx() provides a small offset for better visual spacing
+    Arrow(
+        circle.anchor("right").dx(5),
+        rect.anchor("left").dx(-5)
+    )
+
+# Fit the viewport to the shapes and render
+canvas.fit(padding=10).display()
+```
+
+The `display()` method in the `Canvas` class is an IPython/Jupyter/Quarto compatible  shortcut to automatically include the rendered SVG (in all its beautiful vectorial glory) directly in a notebook. But you can also use `Canvas.save()` to generate a plain old, boring SVG file on this, and `str(canvas)` to get the actual SVG code as a plain string.
+
+## Core Components
+
+Tesserax comes with all basic components you need to draw the spectrum of SVG shapes.
+All shapes support standard SVG attributes like `stroke` and `fill`.
+
+* **Rect & Square**: Defined by width/height or a single size.
+* **Circle & Ellipse**: Defined by radii.
+* **Groups**: For grouping shapes and applying transforms to them as a single shape.
+* **Arrow**: A specialized line that automatically includes an arrowhead marker.
+* **Path**: Supports a fluent API for complex paths using `move_to`, `line_to`, `cubic_to`, and `close`.
+
+### Layouts
+
+Layouts are a unique feature of Tesserax to automate the positioning of child elements. We currently have three layouts, but these are very easy to extend:
+
+* **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
+* **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
+* **ForceLayout**: Typically used to draw graphs.
+
+### Transforms
+
+Every shape has a `Transform` object allowing for:
+
+* **Translation**: `shape.translated(dx, dy)`.
+* **Rotation**: `shape.rotated(degrees)`.
+* **Scaling**: `shape.scaled(factor)`.
+
+Groups of shapes also have their own transform, and this can be composed _ad-infinitum_ to create complex drawing.
+
+## Why Tesserax?
+
+In the Python ecosystem, there is a clear divide between **data visualization** (plotting numbers) and **diagrammatic representation** (drawing concepts). Tesserax is built for the latter.
+
+It is designed for researchers, educators, and authors who need the geometric precision of a professional drafting tool combined with the power of a modern programming language.
+
+### Tesserax vs. The Alternatives
+
+#### Precision over Statistics
+
+Libraries like **Matplotlib**, **Seaborn**, or **Altair** are designed to map data points to visual encodings (bars, lines, scatter points).
+
+**The Difference**: Tesserax does not compete with these libraries because it does not render data graphs. You wouldn't use Tesserax to plot a CSV. Instead, Tesserax is for "the rest" of the figures in a paper: the schematics, the geometric proofs, the architectural diagrams, and the algorithmic walkthroughs where exact spatial relationships convey the meaning.
+
+#### Control over Constraints
+
+**Mermaid** and **Graphviz** are excellent for quickly rendering flowcharts using "black-box" layout engines.
+
+**The Difference**: These tools sacrifice control for convenience. If you need an arrow to point exactly at the tangent of a rotated ellipse, or a shape to be sized exactly according to a geometric ratio, Mermaid cannot help you. Tesserax is for **Scientific Drawing**—providing the low-level primitives needed for total layout authority.
+
+#### The "TikZ for Python" Philosophy
+
+**TikZ** is the industry standard for academic figures, but it requires learning a specialized, often cryptic macro language.
+
+**The Difference**: Tesserax brings the "low-level, total-control" philosophy of TikZ into **Python 3.12**. You get coordinate-invariant precision and semantic anchoring while using Python’s loops, logic, and types. We are building from the bottom up: starting with geometric atoms and moving toward high-level scientific abstractions (like automated neural network architectures or commutative diagrams) that maintain the ability to "drop down" and tweak a single pixel.
+
+### The SVG Advantage
+
+While TikZ is the gold standard for LaTeX-based PDF generation, it belongs to a "print-first" era. Tesserax leverages **SVG (Scalable Vector Graphics)** as its native format, offering a portability that TikZ cannot match without significant friction.
+
+* **Native Web Rendering**: Tesserax figures are native SVGs. They render instantly in any browser, remain crisp at any zoom level, and can be embedded directly into HTML or Markdown (via Quarto) without conversion.
+* **WYSIWYG Portability**: Converting TikZ to SVG for blog posts or online journals often results in broken fonts or misaligned elements. Because Tesserax *starts* with SVG, what you see in your development notebook is exactly what appears in your final PDF and your website.
+* **Accessibility & Interaction**: Unlike static PDFs, Tesserax SVGs can include metadata and ARIA labels for screen readers. Since they are part of the DOM, they can also be styled with CSS or even animated for interactive educational content.
+* **Perfect Print**: SVG is fully convertible to high-quality, vector-perfect PDF, meeting the highest standards for academic journals and book publishing.
+
+## Contribution
+
+Tesserax is free as in both free beer and free speech. License is MIT.
+
+Contributions are always welcomed! Fork, clone, and submit a pull request.

tesserax-0.2.1/README.md

@@ -0,0 +1,125 @@
+# Tesserax: A Lightweight SVG Rendering Library
+
+Tesserax is a modern Python 3.12 library designed for programmatic SVG generation with a focus on ease of use, layout management, and flexible geometric primitives. It is particularly well-suited for visualizing data structures, algorithms, and technical diagrams.
+
+> [**Read the full documentation**](https://apiad.github.io/tesserax).
+
+## Key Features
+
+* **Declarative Layouts**: Effortlessly arrange shapes in `Row` or `Column` containers with automatic alignment and spacing.
+* **Anchor System**: Connect shapes using semantic anchors like `top`, `bottom`, `left`, `right`, and `center`.
+* **Context Manager Support**: Use `with` statements to group shapes naturally within the code.
+* **Smart Canvas**: Automatically fit the canvas viewport to the content with adjustable padding.
+* **Rich Primitives**: Includes `Rect`, `Square`, `Circle`, `Ellipse`, `Line`, `Arrow`, and `Path`.
+
+## Installation
+
+Tesserax has zero dependencies (literally). It's 100% pure Python, and can be easily installed with `pip`:
+
+```bash
+pip install tesserax
+```
+
+Or if you're one of the cool kids, using `uv`:
+
+```bash
+uv add tesserax
+```
+
+## Quick Start
+
+The following example demonstrates how to create two shapes in a row and connect them with an arrow using the anchor system.
+
+```python
+from tesserax import Canvas, Rect, Arrow, Circle
+from tesserax.layout import Row
+
+# Initialize a canvas
+with Canvas() as canvas:
+    # Arrange a circle and a rectangle in a row with a 50px gap
+    with Row(gap=50):
+        circle = Circle(30, fill="#fee")
+        rect = Rect(100, 60, fill="#eef")
+
+    # Draw an arrow between the two shapes using anchors
+    # .dx() provides a small offset for better visual spacing
+    Arrow(
+        circle.anchor("right").dx(5),
+        rect.anchor("left").dx(-5)
+    )
+
+# Fit the viewport to the shapes and render
+canvas.fit(padding=10).display()
+```
+
+The `display()` method in the `Canvas` class is an IPython/Jupyter/Quarto compatible  shortcut to automatically include the rendered SVG (in all its beautiful vectorial glory) directly in a notebook. But you can also use `Canvas.save()` to generate a plain old, boring SVG file on this, and `str(canvas)` to get the actual SVG code as a plain string.
+
+## Core Components
+
+Tesserax comes with all basic components you need to draw the spectrum of SVG shapes.
+All shapes support standard SVG attributes like `stroke` and `fill`.
+
+* **Rect & Square**: Defined by width/height or a single size.
+* **Circle & Ellipse**: Defined by radii.
+* **Groups**: For grouping shapes and applying transforms to them as a single shape.
+* **Arrow**: A specialized line that automatically includes an arrowhead marker.
+* **Path**: Supports a fluent API for complex paths using `move_to`, `line_to`, `cubic_to`, and `close`.
+
+### Layouts
+
+Layouts are a unique feature of Tesserax to automate the positioning of child elements. We currently have three layouts, but these are very easy to extend:
+
+* **Row**: Aligns shapes horizontally. Baselines can be set to `start`, `middle`, or `end`.
+* **Column**: Aligns shapes vertically with `start`, `middle`, or `end` alignment.
+* **ForceLayout**: Typically used to draw graphs.
+
+### Transforms
+
+Every shape has a `Transform` object allowing for:
+
+* **Translation**: `shape.translated(dx, dy)`.
+* **Rotation**: `shape.rotated(degrees)`.
+* **Scaling**: `shape.scaled(factor)`.
+
+Groups of shapes also have their own transform, and this can be composed _ad-infinitum_ to create complex drawing.
+
+## Why Tesserax?
+
+In the Python ecosystem, there is a clear divide between **data visualization** (plotting numbers) and **diagrammatic representation** (drawing concepts). Tesserax is built for the latter.
+
+It is designed for researchers, educators, and authors who need the geometric precision of a professional drafting tool combined with the power of a modern programming language.
+
+### Tesserax vs. The Alternatives
+
+#### Precision over Statistics
+
+Libraries like **Matplotlib**, **Seaborn**, or **Altair** are designed to map data points to visual encodings (bars, lines, scatter points).
+
+**The Difference**: Tesserax does not compete with these libraries because it does not render data graphs. You wouldn't use Tesserax to plot a CSV. Instead, Tesserax is for "the rest" of the figures in a paper: the schematics, the geometric proofs, the architectural diagrams, and the algorithmic walkthroughs where exact spatial relationships convey the meaning.
+
+#### Control over Constraints
+
+**Mermaid** and **Graphviz** are excellent for quickly rendering flowcharts using "black-box" layout engines.
+
+**The Difference**: These tools sacrifice control for convenience. If you need an arrow to point exactly at the tangent of a rotated ellipse, or a shape to be sized exactly according to a geometric ratio, Mermaid cannot help you. Tesserax is for **Scientific Drawing**—providing the low-level primitives needed for total layout authority.
+
+#### The "TikZ for Python" Philosophy
+
+**TikZ** is the industry standard for academic figures, but it requires learning a specialized, often cryptic macro language.
+
+**The Difference**: Tesserax brings the "low-level, total-control" philosophy of TikZ into **Python 3.12**. You get coordinate-invariant precision and semantic anchoring while using Python’s loops, logic, and types. We are building from the bottom up: starting with geometric atoms and moving toward high-level scientific abstractions (like automated neural network architectures or commutative diagrams) that maintain the ability to "drop down" and tweak a single pixel.
+
+### The SVG Advantage
+
+While TikZ is the gold standard for LaTeX-based PDF generation, it belongs to a "print-first" era. Tesserax leverages **SVG (Scalable Vector Graphics)** as its native format, offering a portability that TikZ cannot match without significant friction.
+
+* **Native Web Rendering**: Tesserax figures are native SVGs. They render instantly in any browser, remain crisp at any zoom level, and can be embedded directly into HTML or Markdown (via Quarto) without conversion.
+* **WYSIWYG Portability**: Converting TikZ to SVG for blog posts or online journals often results in broken fonts or misaligned elements. Because Tesserax *starts* with SVG, what you see in your development notebook is exactly what appears in your final PDF and your website.
+* **Accessibility & Interaction**: Unlike static PDFs, Tesserax SVGs can include metadata and ARIA labels for screen readers. Since they are part of the DOM, they can also be styled with CSS or even animated for interactive educational content.
+* **Perfect Print**: SVG is fully convertible to high-quality, vector-perfect PDF, meeting the highest standards for academic journals and book publishing.
+
+## Contribution
+
+Tesserax is free as in both free beer and free speech. License is MIT.
+
+Contributions are always welcomed! Fork, clone, and submit a pull request.

tesserax-0.2.1/docs/.gitignore

@@ -0,0 +1,4 @@
+/.quarto/
+_freeze
+_site
+index_files

tesserax-0.2.1/docs/_quarto.yml

@@ -0,0 +1,24 @@
+project:
+  type: website
+  output-dir: _site
+
+website:
+  title: "Tesserax"
+  navbar:
+    left:
+      - href: index.qmd
+        text: Home
+      - href: core.qmd
+        text: Core Concepts
+      - href: gallery.qmd
+        text: Gallery
+
+format:
+  html:
+    theme: cosmo
+    css: styles.css
+    toc: true
+    code-fold: true
+
+execute:
+  freeze: auto  # Re-render only when source changes

tesserax-0.2.1/docs/core.qmd

@@ -0,0 +1,143 @@
+This "Core Concepts" guide will walk you through building a scene from scratch, demonstrating how **Tesserax** handles shapes, positioning, and composition.
+
+## The Canvas and the First Shape
+
+Every drawing starts with a `Canvas`. In Tesserax, the `Canvas` acts as the root container and provides a context manager to automatically add shapes created within its block.
+
+We will start by creating a simple 100x50 rectangle.
+
+```{python}
+from tesserax import Canvas, Rect
+
+# Initialize the canvas
+with Canvas() as canvas:
+    # Adding our first shape
+    # Primitives support standard SVG attributes like fill
+    Rect(100, 50, fill="lightblue")
+
+# fit() adjusts the viewport to the content
+# display() renders it directly in the documentation
+canvas.fit(padding=10).display()
+
+```
+
+## Adding and Transforming Shapes
+
+While you can add shapes and manually set their coordinates, Tesserax provides a fluent API for transformations. Here, we add a `Circle` and use `translated()` to move it into position.
+
+```{python}
+from tesserax import Canvas, Rect, Circle
+
+with Canvas() as canvas:
+    Rect(100, 50, fill="lightblue")
+
+    # Adding a second shape and moving it manually
+    # Circle is defined by its radius
+    Circle(30, fill="salmon").translated(150, 25)
+
+canvas.fit(padding=10).display()
+
+```
+
+## Simplifying with Layouts
+
+Manually calculating offsets (like the `150, 25` above) becomes tedious in complex diagrams. **Layouts** automate this positioning. The `Row` layout arranges its children horizontally with an optional `gap`.
+
+```{python}
+from tesserax import Canvas, Rect, Circle
+from tesserax.layout import Row
+
+with Canvas() as canvas:
+    # Row is also a context manager
+    with Row(gap=20):
+        Rect(100, 50, fill="lightblue")
+        Circle(30, fill="salmon")
+
+canvas.fit(padding=10).display()
+
+```
+
+## Composing Transforms and Groups
+
+Because Layouts are themselves a type of `Group`, you can apply transformations to the entire layout at once. In this step, we will:
+
+1. Create a `Row` layout.
+2. Rotate that entire row by 45 degrees.
+3. Add a new shape outside of that row.
+4. Wrap everything in another `Group` to demonstrate hierarchical composition.
+
+
+```{python}
+from tesserax import Canvas, Rect, Circle, Group
+from tesserax.layout import Row
+
+with Canvas() as canvas:
+    # Create and rotate a layout
+    with Row(gap=20).rotated(45):
+        Rect(100, 50, fill="lightblue")
+        Circle(30, fill="salmon")
+
+    # Add another shape to the scene
+    Rect(40, 40, fill="lightgreen").translated(100, -50)
+
+    # All shapes here are already part of the Canvas group.
+
+canvas.fit(padding=10).display()
+
+```
+
+By nesting Layouts and Groups, you can build extremely complex diagrams without ever having to manually compute a single SVG coordinate string.
+
+## Bridging Contexts with Anchors
+
+One of the most powerful features of Tesserax is the **Anchor System**. When you place a shape inside a `Layout` or a `Group`, its local coordinates change to reflect its position within that container. However, Tesserax allows you to retrieve the "global" position of a shape's anchors, making it trivial to connect objects across different coordinate systems.
+
+In this example, we will connect the `Circle` (which is inside a rotated `Row`) to the `Rect` (which is outside) using an `Arrow`, and the two shapes inside the row.
+
+```{python}
+from tesserax import Canvas, Rect, Circle, Arrow
+from tesserax.layout import Row
+
+with Canvas() as canvas:
+    # 1. Create a Row and rotate it
+    with Row(gap=40) as row:
+        r1 = Rect(80, 40, fill="aliceblue")
+        c1 = Circle(30, fill="mistyrose")
+
+    row.rotated(30).translated(50, 50)
+
+    # 2. Create a target rectangle outside the layout
+    target = Rect(60, 60, fill="honeydew").translated(250, 0)
+
+    # 3. Connect them!
+    # We use .anchor() to get semantic points.
+    # Even though c1 is inside a rotated row, c1.anchor("right")
+    # returns the correct global coordinate for the arrow.
+    Arrow(
+        c1.anchor("top").dy(5),
+        target.anchor("left").dx(-5),
+        stroke="grey",
+        width=2,
+    )
+
+    Arrow(
+        r1.anchor("right").dx(5),
+        c1.anchor("left").dx(-5),
+        stroke="grey",
+        width=2,
+    )
+
+canvas.fit(padding=10).display()
+```
+
+### How Coordinate Mapping Works
+
+When you call `shape.anchor(name)`, Tesserax performs the following behind the scenes:
+
+1. **Local Geometry**: It identifies the point on the shape (e.g., the rightmost edge of the `Circle`).
+2. **Transformation Path**: It traverses up the hierarchy (from the `Circle` to the `Row`, then to the `Canvas`), applying every rotation, scale, and translation encountered along the way.
+3. **Global Result**: It returns a `Point` that represents exactly where that anchor sits on the final SVG canvas.
+
+This means you never have to manually calculate `sin()` or `cos()` to find where a rotated object's edge is located—you just ask for the anchor.
+
+For explicit anchoring, you can use `Shape.resolve(p: Point)` to map a point in local space to the global space, this way you can, e.g., get the point at 2/3rds of the way inside a rectangle and map it to global space.