imagespec 0.1.0__tar.gz

imagespec-0.1.0/LICENSE

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

imagespec-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE README.md
+recursive-include src/imagespec/fonts *.ttf *.otf *.json *.md
+recursive-include src/imagespec/icons *.ttf *.otf *.json *.md
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include docs *.md

imagespec-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: imagespec
+Version: 0.1.0
+Summary: Render images from a declarative YAML/dict spec — shapes, text, charts, QR/barcodes — for e-paper ESL tags and label printers.
+Author: eigger
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eigger/imagespec
+Project-URL: Repository, https://github.com/eigger/imagespec
+Keywords: image,render,yaml,spec,e-paper,esl,label,pillow
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow>=10.0
+Requires-Dist: qrcode[pil]>=7.4
+Requires-Dist: python-barcode>=0.15
+Requires-Dist: requests>=2.25
+Provides-Extra: datamatrix
+Requires-Dist: pyStrich>=0.8; extra == "datamatrix"
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# imagespec
+
+Render images from a declarative **YAML/dict spec** — shapes, text, charts,
+QR/barcodes — for e-paper ESL tags and label printers.
+
+This is the shared rendering core extracted from
+[`hass-gicisky`](https://github.com/eigger/hass-gicisky) and
+[`hass-niimbot`](https://github.com/eigger/hass-niimbot). Both integrations had
+near-identical renderers that had drifted apart; `imagespec` unifies them and
+removes the Home Assistant dependency so the engine can be reused and tested
+standalone.
+
+## Status
+
+✅ **26 elements** (21 ported + 5 new) rendering, with a 74-test suite.
+Architecture (HA-decoupled context, registry dispatch, device-specific rotation
++ palette) is in place. Remaining work is packaging polish and switching the two
+components over to it.
+
+## Design
+
+- **No framework dependency.** The core never imports Home Assistant. Anything
+  host-specific is injected through `RenderContext`:
+  - `font_resolver(name) -> path | None` — e.g. an integration's
+    `hass.config.path("www/fonts")` lookup.
+  - `history_provider(entity_ids, start, end) -> states` — for the `plot`
+    element (HA recorder). Optional.
+  - `palette` — the device's supported colors (see below).
+- **Registry dispatch.** Each element `type` is a handler registered with
+  `@element("type")` in `imagespec/elements/`, replacing the original giant
+  `if/elif` chain. Adding an element = adding a function.
+- **`RenderState`.** Threaded through handlers; holds the (reassignable) `img`
+  and the `pos_y` flow cursor.
+- **Device-dependent palette** (`RenderContext.palette`), *not* unified — panels
+  support different colors. Define it as a **list of the colors the device
+  supports** (names, HEX, or RGBA tuples):
+
+  ```python
+  RenderContext(palette=["black", "white", "red"])          # names
+  RenderContext(palette=["#000000", "#ffffff", "#ff0000"])  # HEX
+  RenderContext(palette=[(0, 0, 0), (255, 255, 255)])       # RGBA tuples
+  ```
+
+  Shorthand names are optional convenience for common panels: `"2"`/`"bw"`,
+  `"3"`/`"bwr"`, `"4"`, `"7"`/`"acep"`. Any requested color in a payload is then
+  quantized to the nearest color in this list — on a 2-color device `red`
+  becomes black; on 4-color a blue `#1e90ff` becomes white; on 7-color it stays
+  blue.
+- **Merged behaviour.** Where the two sources differed, the superset wins:
+  - qrcode gains `eclevel` (niimbot)
+- **Device-dependent rotation** (`rotate_mode`), *not* unified — both behaviours
+  are kept because they are physically different:
+  - `"canvas"` (gicisky): background/canvas rotates; output stays `width×height`
+    (fixed-resolution e-ink panel).
+  - `"image"` (niimbot): drawing rotates; output dimensions swap (variable-size
+    label printer).
+
+## Usage
+
+```python
+from imagespec import render, RenderContext
+
+ctx = RenderContext(
+    font_resolver=my_font_lookup,        # optional
+    history_provider=my_history_lookup,  # optional, only for `plot`
+)
+image = render(payload, width=296, height=128, rotate=0,
+               background="white", context=ctx)   # -> PIL.Image (RGB)
+```
+
+Run the smoke test (no fonts required):
+
+```bash
+pip install -e .
+python examples/smoke_test.py
+```
+
+## Development & testing
+
+```bash
+pip install -e ".[dev,datamatrix]"
+pytest                 # 74 tests: every element, palettes, rotation, dither, errors
+ruff check . && ruff format --check .   # lint + format
+python -m build        # build sdist + wheel (bundles fonts/icons)
+```
+
+CI runs on every push/PR (`.github/workflows/ci.yml`): ruff lint+format, the test
+suite on Python 3.11/3.12/3.13, and a build that asserts the bundled fonts/icons
+are present in the wheel. Pushing a `v*` tag triggers
+`.github/workflows/release.yml` to build and publish to PyPI (trusted publishing).
+
+The test matrix (`tests/test_elements.py`) asserts it covers *every* registered
+element type, so adding a new `@element(...)` without a sample fails the suite —
+keeping coverage exhaustive by construction.
+
+**Robustness built in:**
+
+- Each handler error is wrapped with element context — you get
+  `error rendering element #3 (type 'text'): ...`, not a raw PIL traceback.
+- `render()` validates `rotate`/`rotate_mode`/size and rejects non-dict elements;
+  unknown element types are warned-and-skipped.
+- `dlimg` only allows `http(s)`/`data:` URLs by default; local paths require
+  `RenderContext(allow_local_images=True)`. Network failures become `RenderError`.
+- Clear errors for missing required args, invalid barcode symbology, malformed
+  `polygon` points, and a `diagram` too small for its bars.
+
+## Elements
+
+All ported from the original renderers (superset behaviour where they differed):
+
+| Element             | Module    | Notes |
+|---------------------|-----------|-------|
+| `line`              | shapes    | + dashed lines |
+| `rectangle`         | shapes    | |
+| `rectangle_pattern` | shapes    | |
+| `circle`            | shapes    | |
+| `ellipse`           | shapes    | |
+| `arc`               | shapes    | |
+| `polygon`           | shapes    | |
+| `gauge`             | shapes    | |
+| `text`              | text      | + rotation, background box |
+| `text_box`          | text      | |
+| `multiline`         | text      | |
+| `new_multiline`     | text      | fit-to-width/height autosize (niimbot) |
+| `text_fit`          | text      | fit text into a fixed box: shrink font / ellipsis / wrap |
+| `table`             | text      | |
+| `qrcode`            | codes     | + `eclevel` (niimbot) |
+| `barcode`           | codes     | |
+| `datamatrix`        | codes     | optional dep `pyStrich` (`imagespec[datamatrix]`) |
+| `icon`              | media     | Material Design Icons; needs bundled `icons/` assets |
+| `dlimg`             | media     | + fit modes (stretch/fit/fill/contain) |
+| `diagram`           | charts    | bar chart |
+| `plot`              | charts    | needs `history_provider`; + area_fill, xlegend |
+| `progress_bar`      | charts    | + rounded corners |
+| `pie`               | charts    | **new** — pie / donut (`inner_radius`) |
+| `sparkline`         | charts    | **new** — compact axis-less line from inline values |
+| `rich_text`         | text      | **new** — inline spans: icon + text + color on one line |
+| `group`             | layout    | **new** — container: child elements at an offset, clipped, optionally rotated |
+
+Plus enhancements: `dlimg` gained `dither` (Floyd–Steinberg to palette) and
+`circle`/`mask` (circular crop); `render(..., dither=True)` dithers the whole
+output; `text_fit` fits text into a fixed box (shrink / ellipsis / wrap).
+
+## Fonts & assets
+
+Bundled in the package (offline baseline):
+
+- `icons/materialdesignicons-webfont.ttf` + `_meta.json` — required by `icon`.
+- `fonts/NotoSansKR-Regular.ttf` (default) and `fonts/ppb.ttf` (niimbot default).
+
+Anything else is resolved at runtime, in order: `font_resolver` (host) →
+bundled font of the same basename → bundled default. Helpers in
+`imagespec.resolvers`:
+
+- `directory_resolver(dir)` — look up fonts in a host directory (e.g. `www/fonts`).
+- `caching_resolver(cache_dir, sources)` — **download on first use, cache to
+  disk, reuse offline** (internet needed only once per font).
+- `chain_resolvers(a, b, ...)` — try several in order.
+
+This is why the core bundles only the essentials (~11 MB) and **not** gicisky's
+full 74 MB font set — decorative fonts are better downloaded-and-cached or served
+from `www/fonts`.
+
+## Open decisions
+
+- **Default font.** `NotoSansKR-Regular.ttf` (gicisky) vs `ppb.ttf` (niimbot).
+  Default is Noto; bundle both so existing payloads render unchanged.
+
+> Resolved: rotation is now a per-device `rotate_mode` (`"canvas"` for gicisky,
+> `"image"` for niimbot), and `RenderState.canvas_width/height` always reflect
+> the actual drawing surface — so `plot`/`diagram` default extents are
+> consistent in both modes.
+
+## Integrating back into the components
+
+Replace each component's renderer with a thin adapter (see
+[`docs/migration.md`](docs/migration.md)) and add to `manifest.json`:
+
+```json
+"requirements": ["imagespec==0.1.0"]
+```

imagespec-0.1.0/README.md

@@ -0,0 +1,181 @@
+# imagespec
+
+Render images from a declarative **YAML/dict spec** — shapes, text, charts,
+QR/barcodes — for e-paper ESL tags and label printers.
+
+This is the shared rendering core extracted from
+[`hass-gicisky`](https://github.com/eigger/hass-gicisky) and
+[`hass-niimbot`](https://github.com/eigger/hass-niimbot). Both integrations had
+near-identical renderers that had drifted apart; `imagespec` unifies them and
+removes the Home Assistant dependency so the engine can be reused and tested
+standalone.
+
+## Status
+
+✅ **26 elements** (21 ported + 5 new) rendering, with a 74-test suite.
+Architecture (HA-decoupled context, registry dispatch, device-specific rotation
++ palette) is in place. Remaining work is packaging polish and switching the two
+components over to it.
+
+## Design
+
+- **No framework dependency.** The core never imports Home Assistant. Anything
+  host-specific is injected through `RenderContext`:
+  - `font_resolver(name) -> path | None` — e.g. an integration's
+    `hass.config.path("www/fonts")` lookup.
+  - `history_provider(entity_ids, start, end) -> states` — for the `plot`
+    element (HA recorder). Optional.
+  - `palette` — the device's supported colors (see below).
+- **Registry dispatch.** Each element `type` is a handler registered with
+  `@element("type")` in `imagespec/elements/`, replacing the original giant
+  `if/elif` chain. Adding an element = adding a function.
+- **`RenderState`.** Threaded through handlers; holds the (reassignable) `img`
+  and the `pos_y` flow cursor.
+- **Device-dependent palette** (`RenderContext.palette`), *not* unified — panels
+  support different colors. Define it as a **list of the colors the device
+  supports** (names, HEX, or RGBA tuples):
+
+  ```python
+  RenderContext(palette=["black", "white", "red"])          # names
+  RenderContext(palette=["#000000", "#ffffff", "#ff0000"])  # HEX
+  RenderContext(palette=[(0, 0, 0), (255, 255, 255)])       # RGBA tuples
+  ```
+
+  Shorthand names are optional convenience for common panels: `"2"`/`"bw"`,
+  `"3"`/`"bwr"`, `"4"`, `"7"`/`"acep"`. Any requested color in a payload is then
+  quantized to the nearest color in this list — on a 2-color device `red`
+  becomes black; on 4-color a blue `#1e90ff` becomes white; on 7-color it stays
+  blue.
+- **Merged behaviour.** Where the two sources differed, the superset wins:
+  - qrcode gains `eclevel` (niimbot)
+- **Device-dependent rotation** (`rotate_mode`), *not* unified — both behaviours
+  are kept because they are physically different:
+  - `"canvas"` (gicisky): background/canvas rotates; output stays `width×height`
+    (fixed-resolution e-ink panel).
+  - `"image"` (niimbot): drawing rotates; output dimensions swap (variable-size
+    label printer).
+
+## Usage
+
+```python
+from imagespec import render, RenderContext
+
+ctx = RenderContext(
+    font_resolver=my_font_lookup,        # optional
+    history_provider=my_history_lookup,  # optional, only for `plot`
+)
+image = render(payload, width=296, height=128, rotate=0,
+               background="white", context=ctx)   # -> PIL.Image (RGB)
+```
+
+Run the smoke test (no fonts required):
+
+```bash
+pip install -e .
+python examples/smoke_test.py
+```
+
+## Development & testing
+
+```bash
+pip install -e ".[dev,datamatrix]"
+pytest                 # 74 tests: every element, palettes, rotation, dither, errors
+ruff check . && ruff format --check .   # lint + format
+python -m build        # build sdist + wheel (bundles fonts/icons)
+```
+
+CI runs on every push/PR (`.github/workflows/ci.yml`): ruff lint+format, the test
+suite on Python 3.11/3.12/3.13, and a build that asserts the bundled fonts/icons
+are present in the wheel. Pushing a `v*` tag triggers
+`.github/workflows/release.yml` to build and publish to PyPI (trusted publishing).
+
+The test matrix (`tests/test_elements.py`) asserts it covers *every* registered
+element type, so adding a new `@element(...)` without a sample fails the suite —
+keeping coverage exhaustive by construction.
+
+**Robustness built in:**
+
+- Each handler error is wrapped with element context — you get
+  `error rendering element #3 (type 'text'): ...`, not a raw PIL traceback.
+- `render()` validates `rotate`/`rotate_mode`/size and rejects non-dict elements;
+  unknown element types are warned-and-skipped.
+- `dlimg` only allows `http(s)`/`data:` URLs by default; local paths require
+  `RenderContext(allow_local_images=True)`. Network failures become `RenderError`.
+- Clear errors for missing required args, invalid barcode symbology, malformed
+  `polygon` points, and a `diagram` too small for its bars.
+
+## Elements
+
+All ported from the original renderers (superset behaviour where they differed):
+
+| Element             | Module    | Notes |
+|---------------------|-----------|-------|
+| `line`              | shapes    | + dashed lines |
+| `rectangle`         | shapes    | |
+| `rectangle_pattern` | shapes    | |
+| `circle`            | shapes    | |
+| `ellipse`           | shapes    | |
+| `arc`               | shapes    | |
+| `polygon`           | shapes    | |
+| `gauge`             | shapes    | |
+| `text`              | text      | + rotation, background box |
+| `text_box`          | text      | |
+| `multiline`         | text      | |
+| `new_multiline`     | text      | fit-to-width/height autosize (niimbot) |
+| `text_fit`          | text      | fit text into a fixed box: shrink font / ellipsis / wrap |
+| `table`             | text      | |
+| `qrcode`            | codes     | + `eclevel` (niimbot) |
+| `barcode`           | codes     | |
+| `datamatrix`        | codes     | optional dep `pyStrich` (`imagespec[datamatrix]`) |
+| `icon`              | media     | Material Design Icons; needs bundled `icons/` assets |
+| `dlimg`             | media     | + fit modes (stretch/fit/fill/contain) |
+| `diagram`           | charts    | bar chart |
+| `plot`              | charts    | needs `history_provider`; + area_fill, xlegend |
+| `progress_bar`      | charts    | + rounded corners |
+| `pie`               | charts    | **new** — pie / donut (`inner_radius`) |
+| `sparkline`         | charts    | **new** — compact axis-less line from inline values |
+| `rich_text`         | text      | **new** — inline spans: icon + text + color on one line |
+| `group`             | layout    | **new** — container: child elements at an offset, clipped, optionally rotated |
+
+Plus enhancements: `dlimg` gained `dither` (Floyd–Steinberg to palette) and
+`circle`/`mask` (circular crop); `render(..., dither=True)` dithers the whole
+output; `text_fit` fits text into a fixed box (shrink / ellipsis / wrap).
+
+## Fonts & assets
+
+Bundled in the package (offline baseline):
+
+- `icons/materialdesignicons-webfont.ttf` + `_meta.json` — required by `icon`.
+- `fonts/NotoSansKR-Regular.ttf` (default) and `fonts/ppb.ttf` (niimbot default).
+
+Anything else is resolved at runtime, in order: `font_resolver` (host) →
+bundled font of the same basename → bundled default. Helpers in
+`imagespec.resolvers`:
+
+- `directory_resolver(dir)` — look up fonts in a host directory (e.g. `www/fonts`).
+- `caching_resolver(cache_dir, sources)` — **download on first use, cache to
+  disk, reuse offline** (internet needed only once per font).
+- `chain_resolvers(a, b, ...)` — try several in order.
+
+This is why the core bundles only the essentials (~11 MB) and **not** gicisky's
+full 74 MB font set — decorative fonts are better downloaded-and-cached or served
+from `www/fonts`.
+
+## Open decisions
+
+- **Default font.** `NotoSansKR-Regular.ttf` (gicisky) vs `ppb.ttf` (niimbot).
+  Default is Noto; bundle both so existing payloads render unchanged.
+
+> Resolved: rotation is now a per-device `rotate_mode` (`"canvas"` for gicisky,
+> `"image"` for niimbot), and `RenderState.canvas_width/height` always reflect
+> the actual drawing surface — so `plot`/`diagram` default extents are
+> consistent in both modes.
+
+## Integrating back into the components
+
+Replace each component's renderer with a thin adapter (see
+[`docs/migration.md`](docs/migration.md)) and add to `manifest.json`:
+
+```json
+"requirements": ["imagespec==0.1.0"]
+```

imagespec-0.1.0/docs/migration.md

@@ -0,0 +1,158 @@
+# Migrating the components onto imagespec
+
+This describes how `hass-gicisky` and `hass-niimbot` will later drop their own
+renderers (`renderer.py` / `imagegen.py`) and call `imagespec` instead. **Not
+done yet** — this is the plan to follow when the swap happens.
+
+The strategy: keep a **thin adapter** with the same public function name each
+component already exposes, so nothing else in the component changes. The
+adapter's only jobs are to build a `RenderContext` (font lookup + history +
+palette) and translate `imagespec.RenderError` into `HomeAssistantError`.
+
+All 26 element types are implemented, so no payloads will regress; unknown
+element types are warned-and-skipped rather than raising.
+
+---
+
+## 1. Declare the dependency in `manifest.json`
+
+`imagespec` ships from GitHub. Use a PEP 508 direct reference pinned to a tag:
+
+```json
+"requirements": [
+  "imagespec[datamatrix] @ git+https://github.com/eigger/imagespec.git@v0.1.0"
+]
+```
+
+- The `[datamatrix]` extra pulls in `pyStrich` (only needed for the `datamatrix`
+  element); drop it if a component never uses datamatrix.
+- Pin to a **tag** (`@v0.1.0`), not a branch, so installs are reproducible.
+- If/when published to PyPI, this simplifies to `"imagespec[datamatrix]==0.1.0"`.
+
+**Remove the now-duplicated deps.** `qrcode[pil]`, `python-barcode` and `pyStrich`
+become transitive deps of `imagespec`, so delete them from each component's
+`manifest.json`. (Leaving them in causes no conflict — the existing pins
+`qrcode[pil]==7.4.2`, `python-barcode==0.15.1`, `pyStrich==0.10` all satisfy
+imagespec's ranges — but removing them is the point of consolidating.)
+
+---
+
+## 2. A shared adapter helper
+
+Both adapters build a `RenderContext` the same way; only `default_font` and
+`palette` differ. Factor it once:
+
+```python
+import os
+
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.components.recorder.history import get_significant_states
+
+from imagespec import RenderContext, RenderError, render
+
+
+def _make_context(hass, *, default_font, palette):
+    def font_resolver(name):
+        # check www/fonts; return None to fall back to imagespec's bundled fonts
+        cand = os.path.join(hass.config.path("www/fonts"), os.path.basename(name))
+        return cand if os.path.exists(cand) else None
+
+    def history_provider(entity_ids, start, end):
+        return get_significant_states(
+            hass, start_time=start, entity_ids=list(entity_ids),
+            significant_changes_only=False, minimal_response=True, no_attributes=False,
+        )
+
+    return RenderContext(
+        font_resolver=font_resolver,
+        history_provider=history_provider,
+        default_font=default_font,
+        palette=palette,  # list of supported colors (names/hex/rgba) or "2"/"4"/"7" shorthand
+    )
+```
+
+---
+
+## 3. gicisky — `renderer.py`
+
+`render_image(entity_id, device, service, hass)` derives the canvas size from
+`device` and uses the **`canvas`** rotation mode (fixed-resolution ESL panel):
+
+```python
+def render_image(entity_id, device, service, hass):
+    try:
+        return render(
+            payload=service.data.get("payload", ""),
+            width=device.width,
+            height=device.height,
+            rotate=int(service.data.get("rotate", 0)),
+            rotate_mode="canvas",   # ESL panel: fixed resolution, background rotates
+            background=service.data.get("background", "white"),
+            context=_make_context(hass, default_font="NotoSansKR-Regular.ttf",
+                                  palette=device.palette),  # "2"/"4"/"7" per model
+        )
+    except RenderError as err:
+        raise HomeAssistantError(str(err)) from err
+```
+
+Also narrow the `from .renderer import *` in `__init__.py` to
+`from .renderer import render_image` once the old helper soup is gone.
+
+---
+
+## 4. niimbot — `imagegen.py`
+
+`customimage(entity_id, service, hass)` takes the canvas size from `service.data`
+and uses the **`image`** rotation mode (variable-size label printer):
+
+```python
+def customimage(entity_id, service, hass):
+    try:
+        return render(
+            payload=service.data.get("payload", ""),
+            width=service.data.get("width", 400),
+            height=service.data.get("height", 240),
+            rotate=service.data.get("rotate", 0),
+            rotate_mode="image",    # label printer: variable size, drawing rotates
+            background=service.data.get("background", "white"),
+            context=_make_context(hass, default_font="ppb.ttf", palette="bw"),
+        )
+    except RenderError as err:
+        raise HomeAssistantError(str(err)) from err
+```
+
+---
+
+## 5. Per-device specifics (don't unify these away)
+
+| Concern | gicisky | niimbot |
+|---|---|---|
+| `rotate_mode` | `"canvas"` (output stays W×H) | `"image"` (output dims swap) |
+| `palette` | varies by model (`"2"`/`"4"`/`"7"`) | usually `"bw"` |
+| `default_font` | `NotoSansKR-Regular.ttf` | `ppb.ttf` |
+| canvas size | from `device.width/height` | from `service.data["width"/"height"]` |
+
+Colors in a payload are auto-quantized to the device `palette`, so the same
+payload renders correctly on a 2/4/7-color panel without changes.
+
+---
+
+## 6. Optional cleanups enabled by the move
+
+- **Delete bundled fonts** from each component that `imagespec` already ships
+  (`NotoSansKR-Regular.ttf`, `ppb.ttf`, the MDI webfont + meta). Decorative fonts
+  the components still need can stay in `www/fonts`, or be downloaded on demand
+  via `imagespec.resolvers.caching_resolver` (download-once, cache offline).
+- **Image quality**: pass `dither=True` to `render(...)`, or `"dither": true` on a
+  `dlimg`, for Floyd–Steinberg dithering on limited-color panels.
+
+---
+
+## Swap checklist (per component)
+
+1. Add the `imagespec[...] @ git+...@vX.Y.Z` requirement; remove qrcode/barcode/
+   pyStrich.
+2. Replace the body of `render_image` / `customimage` with the adapter above.
+3. Delete the old rendering code and duplicated font/icon assets.
+4. Smoke-test the component's existing example payloads (every element type is
+   supported, so they should render unchanged).

imagespec-0.1.0/examples/smoke_test.py

@@ -0,0 +1,43 @@
+"""Minimal runnable check that the core renders without Home Assistant.
+
+Uses only font-free elements (shapes + qrcode) so it works before any fonts are
+bundled. Run from the repo root:
+
+    pip install -e .
+    python examples/smoke_test.py
+"""
+
+from __future__ import annotations
+
+from imagespec import RenderContext, render
+
+payload = [
+    {
+        "type": "rectangle",
+        "x_start": 2,
+        "y_start": 2,
+        "x_end": 293,
+        "y_end": 125,
+        "outline": "black",
+        "width": 2,
+        "radius": 8,
+    },
+    {
+        "type": "line",
+        "x_start": 10,
+        "y_start": 30,
+        "x_end": 286,
+        "y_end": 30,
+        "fill": "red",
+        "width": 1,
+        "dash": [4, 3],
+    },
+    {"type": "circle", "x": 250, "y": 70, "radius": 20, "outline": "black", "width": 2},
+    {"type": "gauge", "x": 60, "y": 75, "radius": 28, "progress": 65, "fill": "red", "outline": "black", "width": 6},
+    {"type": "qrcode", "x": 150, "y": 50, "data": "https://example.com", "boxsize": 2},
+]
+
+ctx = RenderContext()  # no font_resolver / history needed for this payload
+img = render(payload, width=296, height=128, rotate=0, background="white", context=ctx)
+img.save("smoke_test.png")
+print(f"OK - wrote smoke_test.png ({img.size[0]}x{img.size[1]})")