excalidraw-render 0.1.0__tar.gz

excalidraw_render-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # cairosvg needs libcairo at runtime; ubuntu-latest doesn't have it by default
+      - name: Install system libs for cairosvg
+        run: sudo apt-get update && sudo apt-get install -y libcairo2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package + dev deps
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Type-check (mypy)
+        run: mypy src
+
+      - name: Run tests
+        run: pytest -q

excalidraw_render-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Coverage / pytest / mypy / ruff
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+coverage.xml
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local rendered output
+*.local.png
+*.local.svg
+.scratch/

excalidraw_render-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-29
+
+### Added
+- Initial repo scaffold: `pyproject.toml`, package layout (`src/excalidraw_render/`), MIT license, ruff + mypy + pytest config.
+- Typed element model (`element.py`): dataclasses for every common Excalidraw element type with a tolerant JSON parser.
+- Renderers (`renderers/`): SVG output for `rectangle`, `ellipse`, `diamond`, `arrow`, `line`, `text`, `freedraw`, `image`, `frame`.
+- Arrowhead variants: `arrow`, `triangle`, `triangle_outline`, `bar`, `dot`, `diamond`, `diamond_outline`, `crowfoot_one`, `crowfoot_many`, `crowfoot_one_or_many`.
+- Stroke styles: `solid`, `dashed`, `dotted`. Opacity. Element rotation via `angle`.
+- Multi-line text with `text_align` and `vertical_align`, mapped to web-safe font families.
+- Freedraw smoothing via Catmull-Rom to cubic Bezier conversion.
+- Image elements decoded from the scene's `files` dict (data URLs embedded into SVG).
+- Frame elements rendered as labeled dashed boundary rectangles.
+- Top-level `render_svg(scene)` and `render_png(scene, out, ...)` entry points.
+- CLI `excalidraw-render FILE [DIR]` with `-o/--output`, `-f/--format {png,svg}`, `--width`, `--scale`, `--no-background`, `--padding`. Single-file and batch-directory modes.
+- 30 tests (`test_element.py`, `test_render.py`, `test_cli.py`) with hand-crafted fixtures covering every supported element type. Ruff + mypy clean.
+
+### Deferred to v0.2
+- Roughness (`roughjs`-style hand-drawn look). Pure-Python port (`pyroughjs`) on the roadmap.
+- PDF and JPEG output.
+- Container-bound text positioning fidelity (`containerId` lookup → padding-respecting text placement).
+- Hachure / cross-hatch / zigzag / dots fill patterns (currently fall back to solid).
+- Terminal output subcommands (iTerm2 OSC-1337, Kitty graphics protocol, Sixel).
+- Markdown preprocessor subcommand (replaces `mdview`).
+- Watch mode (re-render on file change).
+- Real Excalidraw export round-trip tests against the public Excalidraw repo's example files.
+
+### Known limitations
+- Shorthand `label` field on shapes (an MCP / `mdview` extension, not standard Excalidraw) is not rendered. Use a separate `text` element with `containerId` instead. Adding shorthand support is tracked for v0.2.
+- Text positioning inside container shapes is currently text-element-driven (x/y must already match the container). True container-relative layout (padding, vertical alignment relative to container) is deferred.
+- Group-level transforms are not yet applied as a single matrix; per-element rotation/transform works.

excalidraw_render-0.1.0/LICENSE

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

excalidraw_render-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: excalidraw-render
+Version: 0.1.0
+Summary: Clean, deterministic, browser-free renderer for .excalidraw files (PNG/SVG).
+Project-URL: Homepage, https://github.com/shivama205/excalidraw-render
+Project-URL: Source, https://github.com/shivama205/excalidraw-render
+Project-URL: Issues, https://github.com/shivama205/excalidraw-render/issues
+Author: Shivam Mathur
+License: MIT License
+        
+        Copyright (c) 2026 Shivam Mathur
+        
+        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.
+License-File: LICENSE
+Keywords: diagram,excalidraw,png,renderer,svg
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: cairosvg>=2.7
+Requires-Dist: pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# excalidraw-render
+
+[![CI](https://github.com/shivama205/excalidraw-render/actions/workflows/ci.yml/badge.svg)](https://github.com/shivama205/excalidraw-render/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/excalidraw-render.svg)](https://pypi.org/project/excalidraw-render/)
+[![Python](https://img.shields.io/pypi/pyversions/excalidraw-render.svg)](https://pypi.org/project/excalidraw-render/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Clean, deterministic, browser-free renderer for `.excalidraw` files. Pure Python + cairosvg. No Node, no headless browser, no `node-canvas`.
+
+![hero](docs/hero.png)
+
+```bash
+pip install excalidraw-render
+
+excalidraw-render diagram.excalidraw                    # → diagram.png
+excalidraw-render diagram.excalidraw -f svg             # → diagram.svg
+excalidraw-render diagram.excalidraw --width 1200       # PNG at 1200px wide
+excalidraw-render ./docs/                               # batch: every .excalidraw → .png
+```
+
+## Why this exists
+
+The Excalidraw ecosystem's existing exporters either need Node + `node-canvas` ([`excalidraw_export`](https://www.npmjs.com/package/excalidraw_export)) or a headless browser running React ([`@excalidraw/excalidraw`](https://www.npmjs.com/package/@excalidraw/excalidraw)). Both are heavy, fragile in CI, and slow to start.
+
+`excalidraw-render` is Python + cairosvg. Single-digit-megabyte install, instant startup, no native canvas libs, no Chromium. Useful for:
+
+- **Static-site generators** (Hugo, MkDocs, Sphinx) baking `.excalidraw` to PNG at build time
+- **CI/screenshot pipelines** where pulling Chromium is overkill
+- **Doc + slide generators** that want predictable, deterministic vector output
+- **Terminal viewers** (Kitty, iTerm2, Sixel) — coming in v0.2
+
+## Trade-off: no hand-drawn style
+
+Excalidraw's signature squiggly look comes from [`roughjs`](https://roughjs.com/), a JavaScript library with no native Python port. `excalidraw-render` produces **clean vector output** instead. This is a deliberate trade-off — clean output is what most doc / slide / report pipelines actually want, and skipping roughjs removes the heaviest dependency.
+
+A pure-Python roughjs port (`pyroughjs`) is on the v0.2 roadmap. Until then, if you need the hand-drawn look, use Excalidraw's official export.
+
+## Comparison
+
+| | `excalidraw-render` | [`excalidraw_export`](https://www.npmjs.com/package/excalidraw_export) | [`@excalidraw/excalidraw`](https://www.npmjs.com/package/@excalidraw/excalidraw) |
+|---|---|---|---|
+| Language | Python | Node | React + Node |
+| Hand-drawn (roughjs) | No (v0.2 stretch) | Yes | Yes |
+| PNG output | Yes | via `rsvg-convert` | Yes |
+| SVG output | Yes | Yes | Yes |
+| PDF output | v0.2 | via `rsvg-convert` | No |
+| Headless browser needed | No | No | Yes |
+| Native canvas / image libs | No | Yes (`node-canvas`) | No |
+| Install size | ~10 MB | ~150 MB | Depends |
+| Batch / watch mode | Batch ✓ / watch v0.2 | No | No |
+| Terminal protocols | v0.2 (iTerm / Kitty / Sixel) | No | No |
+
+## Install
+
+```bash
+pip install excalidraw-render
+```
+
+On Linux you may need `libcairo2`:
+```bash
+sudo apt-get install libcairo2          # Debian / Ubuntu
+sudo dnf install cairo                  # Fedora
+sudo pacman -S cairo                    # Arch
+```
+
+On macOS, Cairo is typically already present via Homebrew. If not:
+```bash
+brew install cairo
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Single file → PNG next to source
+excalidraw-render diagram.excalidraw
+
+# Specify output + format
+excalidraw-render diagram.excalidraw -o /tmp/out.svg -f svg
+
+# Higher resolution PNG
+excalidraw-render diagram.excalidraw --width 1600
+
+# Or scale instead of fixed width
+excalidraw-render diagram.excalidraw --scale 2.0
+
+# Transparent background
+excalidraw-render diagram.excalidraw --no-background
+
+# Batch mode: every .excalidraw in a directory
+excalidraw-render ./docs/diagrams/ -o ./public/diagrams/
+```
+
+### Python API
+
+```python
+from excalidraw_render.render import load_scene, render_svg, render_png
+
+scene = load_scene("diagram.excalidraw")
+
+# SVG as a string
+svg = render_svg(scene)
+
+# PNG to a file
+render_png(scene, "diagram.png", width=1200)
+
+# PNG to a binary stream
+import io
+buf = io.BytesIO()
+render_png(scene, buf, scale=2.0)
+```
+
+## What's supported in v0.1
+
+**Elements:** rectangle, ellipse, diamond, arrow, line, text, freedraw, image, frame.
+**Arrowheads:** `arrow`, `triangle`, `triangle_outline`, `bar`, `dot`, `diamond`, `diamond_outline`, `crowfoot_one`, `crowfoot_many`, `crowfoot_one_or_many`.
+**Styling:** stroke color/width, fill color, stroke style (solid/dashed/dotted), opacity, per-element rotation.
+**Text:** multi-line, text-align (left/center/right), vertical-align (top/middle/bottom), Excalidraw font families mapped to web-safe fonts.
+**Freedraw:** smooth path via Catmull-Rom → cubic Bezier conversion.
+**Image:** embedded raster data from the scene's `files` dict.
+**Frame:** dashed boundary box with optional label.
+
+Coverage matrix: [`docs/elements.md`](docs/elements.md).
+
+## What's not supported yet
+
+Documented in [`CHANGELOG.md`](CHANGELOG.md). Highlights:
+
+- Roughness / hand-drawn look (v0.2 — needs roughjs port)
+- PDF / JPEG output (v0.2)
+- Hachure / cross-hatch / zigzag / dots fill patterns (currently fall back to solid)
+- Container-bound text positioning fidelity (padding-aware layout)
+- Terminal output (iTerm / Kitty / Sixel) — v0.2
+- Markdown preprocessor subcommand — v0.2
+- Watch mode — v0.2
+
+## Contributing
+
+This is pre-alpha and breaking changes between minor versions are likely until v1.0. Issues, ideas, and PRs welcome — please file at https://github.com/shivama205/excalidraw-render/issues.
+
+Local dev:
+```bash
+git clone https://github.com/shivama205/excalidraw-render
+cd excalidraw-render
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+.venv/bin/ruff check src tests
+.venv/bin/mypy src
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

excalidraw_render-0.1.0/README.md

@@ -0,0 +1,154 @@
+# excalidraw-render
+
+[![CI](https://github.com/shivama205/excalidraw-render/actions/workflows/ci.yml/badge.svg)](https://github.com/shivama205/excalidraw-render/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/excalidraw-render.svg)](https://pypi.org/project/excalidraw-render/)
+[![Python](https://img.shields.io/pypi/pyversions/excalidraw-render.svg)](https://pypi.org/project/excalidraw-render/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Clean, deterministic, browser-free renderer for `.excalidraw` files. Pure Python + cairosvg. No Node, no headless browser, no `node-canvas`.
+
+![hero](docs/hero.png)
+
+```bash
+pip install excalidraw-render
+
+excalidraw-render diagram.excalidraw                    # → diagram.png
+excalidraw-render diagram.excalidraw -f svg             # → diagram.svg
+excalidraw-render diagram.excalidraw --width 1200       # PNG at 1200px wide
+excalidraw-render ./docs/                               # batch: every .excalidraw → .png
+```
+
+## Why this exists
+
+The Excalidraw ecosystem's existing exporters either need Node + `node-canvas` ([`excalidraw_export`](https://www.npmjs.com/package/excalidraw_export)) or a headless browser running React ([`@excalidraw/excalidraw`](https://www.npmjs.com/package/@excalidraw/excalidraw)). Both are heavy, fragile in CI, and slow to start.
+
+`excalidraw-render` is Python + cairosvg. Single-digit-megabyte install, instant startup, no native canvas libs, no Chromium. Useful for:
+
+- **Static-site generators** (Hugo, MkDocs, Sphinx) baking `.excalidraw` to PNG at build time
+- **CI/screenshot pipelines** where pulling Chromium is overkill
+- **Doc + slide generators** that want predictable, deterministic vector output
+- **Terminal viewers** (Kitty, iTerm2, Sixel) — coming in v0.2
+
+## Trade-off: no hand-drawn style
+
+Excalidraw's signature squiggly look comes from [`roughjs`](https://roughjs.com/), a JavaScript library with no native Python port. `excalidraw-render` produces **clean vector output** instead. This is a deliberate trade-off — clean output is what most doc / slide / report pipelines actually want, and skipping roughjs removes the heaviest dependency.
+
+A pure-Python roughjs port (`pyroughjs`) is on the v0.2 roadmap. Until then, if you need the hand-drawn look, use Excalidraw's official export.
+
+## Comparison
+
+| | `excalidraw-render` | [`excalidraw_export`](https://www.npmjs.com/package/excalidraw_export) | [`@excalidraw/excalidraw`](https://www.npmjs.com/package/@excalidraw/excalidraw) |
+|---|---|---|---|
+| Language | Python | Node | React + Node |
+| Hand-drawn (roughjs) | No (v0.2 stretch) | Yes | Yes |
+| PNG output | Yes | via `rsvg-convert` | Yes |
+| SVG output | Yes | Yes | Yes |
+| PDF output | v0.2 | via `rsvg-convert` | No |
+| Headless browser needed | No | No | Yes |
+| Native canvas / image libs | No | Yes (`node-canvas`) | No |
+| Install size | ~10 MB | ~150 MB | Depends |
+| Batch / watch mode | Batch ✓ / watch v0.2 | No | No |
+| Terminal protocols | v0.2 (iTerm / Kitty / Sixel) | No | No |
+
+## Install
+
+```bash
+pip install excalidraw-render
+```
+
+On Linux you may need `libcairo2`:
+```bash
+sudo apt-get install libcairo2          # Debian / Ubuntu
+sudo dnf install cairo                  # Fedora
+sudo pacman -S cairo                    # Arch
+```
+
+On macOS, Cairo is typically already present via Homebrew. If not:
+```bash
+brew install cairo
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Single file → PNG next to source
+excalidraw-render diagram.excalidraw
+
+# Specify output + format
+excalidraw-render diagram.excalidraw -o /tmp/out.svg -f svg
+
+# Higher resolution PNG
+excalidraw-render diagram.excalidraw --width 1600
+
+# Or scale instead of fixed width
+excalidraw-render diagram.excalidraw --scale 2.0
+
+# Transparent background
+excalidraw-render diagram.excalidraw --no-background
+
+# Batch mode: every .excalidraw in a directory
+excalidraw-render ./docs/diagrams/ -o ./public/diagrams/
+```
+
+### Python API
+
+```python
+from excalidraw_render.render import load_scene, render_svg, render_png
+
+scene = load_scene("diagram.excalidraw")
+
+# SVG as a string
+svg = render_svg(scene)
+
+# PNG to a file
+render_png(scene, "diagram.png", width=1200)
+
+# PNG to a binary stream
+import io
+buf = io.BytesIO()
+render_png(scene, buf, scale=2.0)
+```
+
+## What's supported in v0.1
+
+**Elements:** rectangle, ellipse, diamond, arrow, line, text, freedraw, image, frame.
+**Arrowheads:** `arrow`, `triangle`, `triangle_outline`, `bar`, `dot`, `diamond`, `diamond_outline`, `crowfoot_one`, `crowfoot_many`, `crowfoot_one_or_many`.
+**Styling:** stroke color/width, fill color, stroke style (solid/dashed/dotted), opacity, per-element rotation.
+**Text:** multi-line, text-align (left/center/right), vertical-align (top/middle/bottom), Excalidraw font families mapped to web-safe fonts.
+**Freedraw:** smooth path via Catmull-Rom → cubic Bezier conversion.
+**Image:** embedded raster data from the scene's `files` dict.
+**Frame:** dashed boundary box with optional label.
+
+Coverage matrix: [`docs/elements.md`](docs/elements.md).
+
+## What's not supported yet
+
+Documented in [`CHANGELOG.md`](CHANGELOG.md). Highlights:
+
+- Roughness / hand-drawn look (v0.2 — needs roughjs port)
+- PDF / JPEG output (v0.2)
+- Hachure / cross-hatch / zigzag / dots fill patterns (currently fall back to solid)
+- Container-bound text positioning fidelity (padding-aware layout)
+- Terminal output (iTerm / Kitty / Sixel) — v0.2
+- Markdown preprocessor subcommand — v0.2
+- Watch mode — v0.2
+
+## Contributing
+
+This is pre-alpha and breaking changes between minor versions are likely until v1.0. Issues, ideas, and PRs welcome — please file at https://github.com/shivama205/excalidraw-render/issues.
+
+Local dev:
+```bash
+git clone https://github.com/shivama205/excalidraw-render
+cd excalidraw-render
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+.venv/bin/ruff check src tests
+.venv/bin/mypy src
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

excalidraw_render-0.1.0/RELEASING.md

@@ -0,0 +1,88 @@
+# Releasing `excalidraw-render`
+
+This is the runbook for publishing a new version to PyPI.
+
+## Prerequisites (one-time)
+
+1. PyPI account: https://pypi.org/account/register/
+2. Optional: TestPyPI account (a separate registration): https://test.pypi.org/account/register/
+3. Generate a PyPI API token scoped to this project:
+   - https://pypi.org/manage/account/token/
+   - Scope: "Project: excalidraw-render" (after the first release; before that, scope it more broadly and re-scope later)
+4. Save the token securely. Suggested: `~/.pypirc` with `[pypi]` and `[testpypi]` sections, or use `keyring`.
+   ```ini
+   # ~/.pypirc — chmod 600
+   [pypi]
+     username = __token__
+     password = pypi-...
+
+   [testpypi]
+     repository = https://test.pypi.org/legacy/
+     username = __token__
+     password = pypi-...
+   ```
+
+## Release procedure
+
+```bash
+cd ~/Projects/Hobby/excalidraw-render
+
+# 1. Sanity: clean tree, tests green
+git status                      # no uncommitted changes
+.venv/bin/pytest -q             # all tests pass
+.venv/bin/ruff check src tests  # clean
+.venv/bin/mypy src              # clean
+
+# 2. Bump version in src/excalidraw_render/_version.py
+#    Also update CHANGELOG.md: move [Unreleased] section to [vX.Y.Z] - YYYY-MM-DD
+
+# 3. Commit the version bump
+git add src/excalidraw_render/_version.py CHANGELOG.md
+git commit -m "release: vX.Y.Z"
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin main --follow-tags
+
+# 4. Clean any previous build artifacts
+rm -rf dist/ build/ *.egg-info
+
+# 5. Build wheel + sdist
+.venv/bin/python -m build
+
+# 6. Validate
+.venv/bin/twine check dist/*
+
+# 7. (Optional but recommended for the first release) upload to TestPyPI first
+.venv/bin/twine upload --repository testpypi dist/*
+
+# Verify in a clean venv:
+python -m venv /tmp/verify-test-pypi
+/tmp/verify-test-pypi/bin/pip install --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ excalidraw-render
+/tmp/verify-test-pypi/bin/excalidraw-render --help
+
+# 8. Upload to real PyPI
+.venv/bin/twine upload dist/*
+
+# 9. Create a GitHub release tied to the tag
+gh release create vX.Y.Z dist/* \
+  --title "vX.Y.Z" \
+  --notes-file CHANGELOG.md \
+  --repo shivama205/excalidraw-render
+```
+
+## Version scheme
+
+Semver:
+- `0.1.0` — first public release. Anything ≥ 0.1.0 is considered usable.
+- `0.2.0` — first feature-release after 0.1.0. (Backlog: roughness, terminal, markdown subcommand, etc.)
+- `0.x.y` — `x` minor bumps for features; `y` patches for bugfixes.
+- Pre-1.0: API may break between minor versions; CHANGELOG.md flags any breakage.
+- `1.0.0` — API stabilized. After this, semver is strict.
+
+Pre-release suffixes (`a1`, `b1`, `rc1`) and dev releases (`.dev0`) are allowed for testing on TestPyPI without burning version numbers on real PyPI.
+
+## After every release
+
+- Update CHANGELOG.md: open a new `[Unreleased]` section above the released one.
+- Bump version to the next `.dev0` (e.g. after releasing `0.1.0`, set `_version.py` to `0.2.0.dev0`).
+- Commit and push.