fix: declare templates/thumbnail extras and re-lock uv.lock on release

.github/workflows/prepare-release.yml

@@ -69,6 +69,11 @@ jobs:
           sed -i "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
           grep "^version = \"${VERSION}\"" pyproject.toml
 
+      - name: Sync uv.lock to the new version
+        run: |
+          uv lock
+          grep -A1 '^name = "bambox"' uv.lock | grep "^version = \"${{ inputs.version }}\""
+
       - name: Build changelog with towncrier
         run: |
           VERSION="${{ inputs.version }}"
@@ -87,7 +92,7 @@ jobs:
           BRANCH="release/v${VERSION}"
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add pyproject.toml CHANGELOG.md changes/
+          git add pyproject.toml uv.lock CHANGELOG.md changes/
           git commit -m "Release v${VERSION}"
           git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
           git push --force origin "$BRANCH"

README.md

@@ -69,6 +69,19 @@ Or with [uv](https://docs.astral.sh/uv/):
 
 ```bash
 uv pip install bambox
+uv tool install bambox   # just the CLI
+```
+
+The core install covers packing, repacking and validation. Two optional
+extras pull in heavier dependencies only if you need them:
+
+| Extra | Pulls in | Needed for |
+|-------|----------|------------|
+| `templates` | Jinja2 | `bambox.templates.render_template()` — rendering bundled G-code templates |
+| `thumbnail` | Pillow | `bambox.thumbnail.gcode_thumbnail()` — rendering toolpath previews |
+
+```bash
+pip install "bambox[templates,thumbnail]"
 ```
 
 ### Supported printers and filaments

changes/274.bugfix

@@ -0,0 +1 @@
+Declare the `templates` (Jinja2) and `thumbnail` (Pillow) extras that `render_template()` and `gcode_thumbnail()` already told users to install, and give `gcode_thumbnail()` the same actionable error as `render_template()` when Pillow is missing.

changes/274.misc

@@ -0,0 +1 @@
+Prepare Release now re-locks `uv.lock` with the new version, so the lockfile no longer drifts behind `pyproject.toml` after each release.

pyproject.toml

@@ -29,6 +29,12 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
+templates = [
+    "jinja2>=3.1.0",
+]
+thumbnail = [
+    "pillow>=10.0.0",
+]
 dev = [
     "pytest>=8.0.0",
     "pytest-cov>=6.0.0",

src/bambox/thumbnail.py

@@ -16,7 +16,13 @@ def gcode_thumbnail(
     Parses G0/G1 extrusion moves from the print body (skipping startup
     G-code) and draws them on a dark background. Returns PNG bytes.
     """
-    from PIL import Image, ImageDraw
+    try:
+        from PIL import Image, ImageDraw
+    except ImportError:
+        raise ImportError(
+            "Pillow is required for thumbnail rendering. "
+            "Install with: pip install bambox[thumbnail]"
+        )
 
     if isinstance(gcode, bytes):
         gcode = gcode.decode(errors="replace")

tests/test_release_readiness.py

@@ -171,3 +171,19 @@ def test_notices_force_included_in_wheel(self) -> None:
             "THIRD-PARTY-NOTICES should be placed under bambox/ in the wheel "
             "so it's discoverable next to the installed package."
         )
+
+
+# ---------------------------------------------------------------------------
+# 5. Optional extras named in ImportError hints must exist
+# ---------------------------------------------------------------------------
+
+
+class TestOptionalExtras:
+    """`pip install bambox[<extra>]` hints must point at a real extra."""
+
+    @pytest.mark.parametrize("extra", ["templates", "thumbnail"])
+    def test_extra_is_declared(self, extra: str) -> None:
+        from importlib.metadata import metadata
+
+        declared = metadata("bambox").get_all("Provides-Extra") or []
+        assert extra in declared