hass-eink-dashboard: Instructions file for Codex

AGENTS.md

Commands

uv run --group test pytest                    # run all tests
uv run --group test pytest tests/test_render.py::TestRenderWeather::test_weather_draws_temperature  # run a single test
uv run --group lint ruff check .              # lint
uv run --group format ruff format --check .   # format check
uv run --group typecheck ty check             # typecheck
uv run --group interrogate interrogate -vv custom_components/eink_dashboard/  # docstring coverage

After making changes, ALWAYS run:

• uv run --group format ruff format . && uv run --group lint ruff check . && uv run --group format ruff format --check . && uv run --group typecheck ty check && uv run --group test pytest for Python changes
• pnpm --dir custom_components/eink_dashboard/frontend typecheck && pnpm --dir custom_components/eink_dashboard/frontend test for TypeScript changes

Architecture

This is a Home Assistant custom component (custom_components/eink_dashboard/) that renders e-ink dashboard images as PNG bytes and exposes them via an HA image entity and a public HTTP endpoint.

Key files:

• render.py — rendering orchestrator and shared helpers (delegates to svg_render.py; also holds WidgetMetrics, _compute_metrics, color_to_hex, DEFAULT_METRICS, _load_font, and other utilities imported lazily by widget modules and widgets/_helpers.py)
• svg_render.py — SVG rendering pipeline: Jinja2 templates, icon-inlining filters (_mdi_svg_filter, _weather_svg_filter), render_widget_svg(), _compose_svg(), _svg_to_png() via resvg_py
• widgets/ — per-widget SVG context builders (_build_*_context()), one module per widget type; re-exported via widgets/__init__.py
• widgets/_helpers.py — shared layout helpers for widget builders: _color_context(), _widget_dim(), _card_insets(), _metrics_context(), _title_layout(), _auto_row_height(), _fmt(), _entity_info_context(), _missing_entity_context() (blank-canvas fallback for absent entities), ResolvedEntity + _resolve_entity(), EntityIcon + _resolve_entity_icon(), _resolve_invert() (entity lookup, icon and invert_condition resolution shared by Entity, Tile, Gauge, Entities and _entity_info_context()), CardRow + _row_context() (per-row contract of the card_row macro for list widgets), _icon_stroke_width() (icon outline width, widened on 2-level displays), _ACTIVE_STATES
• image.py — EinkDashboardImage (ImageEntity), scheduled refresh, ETag tracking
• http.py — unauthenticated HTTP view at /api/eink_dashboard/{entry_id}/image.png with ETag/304 support
• store.py — EinkDashboardStore, persists widget list via HA's Store (eink_dashboard.{entry_id})
• config_flow.py — multi-step config flow: name/dimensions/interval, plus TRMNL webhook management (add/remove named webhook targets)
• optimize.py — optimize_for_eink(img, config): optional post-render pipeline (autocontrast, sharpness, contrast, grayscale level quantization)
• push.py — async_push_image(session, url, image_bytes): HTTP POST of PNG bytes to a webhook URL
• sensor.py — EinkDashboardSensor, exposes dashboard state as an HA sensor entity
• const.py — enums, shared constants, and defaults
• widget_config.py — static-only TypedDict per widget type (TileWidget, ...) plus shared mixins (WidgetBase, EntityFields, ...) that helpers accept; widgets stay plain JSON dicts at runtime. ty checks subscripts (widget["x"]) but not .get("x") keys