Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions .claude/hooks/block-docs-raster.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
#!/usr/bin/env bash
# Claude Code PreToolUse hook: deny Bash git add/commit/rm/mv of marketing PNG/GIF/JPEG
# under assets/ or docs/assets/. Twin of .cursor/hooks/block-docs-raster.sh.
set -euo pipefail

input=$(cat)
command=$(
printf '%s' "$input" | python3 -c '
import json, sys
try:
data = json.load(sys.stdin)
except Exception:
print("")
raise SystemExit(0)
# PreToolUse payload: tool_input.command for Bash
tool_input = data.get("tool_input") or {}
print(tool_input.get("command") or data.get("command") or "")
' 2>/dev/null || true
)

# Fail open if we cannot parse
if [[ -z "$command" ]]; then
exit 0
fi

deny() {
local reason="$1"
python3 -c "
import json
print(json.dumps({
'hookSpecificOutput': {
'hookEventName': 'PreToolUse',
'permissionDecision': 'deny',
'permissionDecisionReason': '''$reason'''
}
}))
"
exit 0
}

# Only care about git staging/commit-ish commands
if ! printf '%s' "$command" | grep -Eq '(^|[[:space:];|&])git[[:space:]]+(add|commit|rm|mv)\b'; then
exit 0
fi

# Look for raster paths under marketing dirs in the command string
if printf '%s' "$command" | grep -Eqi '(^|[[:space:]=])((\.\/)?(assets|docs\/assets)\/[^[:space:]]+\.(png|gif|jpe?g))\b'; then
deny 'Marketing docs images must be WebP. Do not commit PNG/GIF/JPEG under assets/ or docs/assets/. Run ./scripts/convert-docs-images.sh (convert-docs-images skill), update refs, then stage .webp files.'
fi

# Catch git commit when staged index already has marketing rasters
if printf '%s' "$command" | grep -Eq 'git[[:space:]]+commit\b'; then
if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
staged=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
if printf '%s\n' "$staged" | grep -Eqi '^(assets|docs/assets)/.+\.(png|gif|jpe?g)$'; then
deny 'Staged PNG/GIF/JPEG under assets/ or docs/assets/. Unstage them, run ./scripts/convert-docs-images.sh, stage .webp files, then commit.'
fi
fi
fi

exit 0
15 changes: 15 additions & 0 deletions .claude/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-docs-raster.sh"
}
]
}
]
}
}
52 changes: 52 additions & 0 deletions .claude/skills/convert-docs-images/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
name: convert-docs-images
description: >-
Convert marketing/docs PNG/JPG/GIF under assets/ or docs/assets/ to WebP,
rewrite markdown/yml/html refs, and remove originals. Use when adding or
updating README/docs screenshots, or when a hook blocked a png/gif commit.
---

# Convert docs images to WebP

Cross-agent policy also lives in root [`AGENTS.md`](../../../AGENTS.md) (Claude Code + Cursor). This skill is mirrored under `.claude/skills/convert-docs-images/` and `.cursor/skills/convert-docs-images/`.

Enforcement hooks (block committing PNG/GIF under marketing asset dirs):
- Cursor: `.cursor/hooks.json` + `.cursor/hooks/block-docs-raster.sh`
- Claude Code: `.claude/settings.json` + `.claude/hooks/block-docs-raster.sh`

## When to use

- Adding or replacing screenshots in `assets/` or `docs/assets/`
- A Cursor hook blocked `git add`/`git commit` of `.png`/`.gif` under those dirs
- Migrating leftover rasters after a docs update

## Do not convert

- Runtime card art under `src/assets/` (e.g. Whisker AVIF litter robots)
- `coverage/`, `test-results/`, `node_modules/`, `dist/`

## Steps

1. Prefer writing new screenshots as `.webp` directly when the capture tool allows it.
2. If you only have PNG/JPG/GIF, put them under `assets/` or `docs/assets/`, then run from the **repo root**:

```bash
./scripts/convert-docs-images.sh
```

Dry-run:

```bash
./scripts/convert-docs-images.sh --dry-run
```

3. Requires `cwebp` and `gif2webp` (`brew install webp`).
4. Confirm refs in `README.md`, `docs/**`, and `mkdocs.yml` point at `.webp`.
5. Do not leave the original `.png`/`.gif` in the tree under marketing asset dirs.

## Defaults

| Source | Encoder | Flags |
|--------|---------|-------|
| PNG/JPG | `cwebp` | `-near_lossless 40 -metadata icc -m 6` |
| GIF | `gif2webp` | `-q 80 -m 4 -mt -mixed` (animated WebP) |
12 changes: 12 additions & 0 deletions .cursor/hooks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"version": 1,
"hooks": {
"beforeShellExecution": [
{
"command": ".cursor/hooks/block-docs-raster.sh",
"matcher": "git\\s+(add|commit|rm|mv)",
"failClosed": false
}
]
}
}
52 changes: 52 additions & 0 deletions .cursor/hooks/block-docs-raster.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
#!/usr/bin/env bash
# Deny git add/commit/rm/mv that stages marketing PNG/GIF/JPEG under assets/ or docs/assets/.
set -euo pipefail

input=$(cat)
command=$(printf '%s' "$input" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("command",""))' 2>/dev/null || true)

# Fail open if we cannot parse
if [[ -z "$command" ]]; then
echo '{ "permission": "allow" }'
exit 0
fi

# Only care about git staging/commit-ish commands
if ! printf '%s' "$command" | grep -Eq '(^|[[:space:];|&])git[[:space:]]+(add|commit|rm|mv)\b'; then
echo '{ "permission": "allow" }'
exit 0
fi

# Look for raster paths under marketing dirs in the command string
if printf '%s' "$command" | grep -Eqi '(^|[[:space:]=])((\.\/)?(assets|docs\/assets)\/[^[:space:]]+\.(png|gif|jpe?g))\b'; then
python3 - <<'PY'
import json
print(json.dumps({
"permission": "deny",
"user_message": "Blocked: do not commit PNG/GIF/JPEG under assets/ or docs/assets/. Convert with ./scripts/convert-docs-images.sh (convert-docs-images skill) and use .webp.",
"agent_message": "Marketing docs images must be WebP. Run ./scripts/convert-docs-images.sh (see convert-docs-images skill), update refs, then stage the .webp files instead."
}))
PY
exit 0
fi

# Also catch bare globs like `git add assets/` when staged index would include rasters — best-effort via git status if available
if printf '%s' "$command" | grep -Eq 'git[[:space:]]+commit\b'; then
if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
staged=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
if printf '%s\n' "$staged" | grep -Eqi '^(assets|docs/assets)/.+\.(png|gif|jpe?g)$'; then
python3 - <<'PY'
import json
print(json.dumps({
"permission": "deny",
"user_message": "Blocked: staged PNG/GIF/JPEG under assets/ or docs/assets/. Convert with ./scripts/convert-docs-images.sh first.",
"agent_message": "Staged marketing rasters found. Unstage them, run ./scripts/convert-docs-images.sh, stage .webp files, then commit."
}))
PY
exit 0
fi
fi
fi

echo '{ "permission": "allow" }'
exit 0
13 changes: 13 additions & 0 deletions .cursor/rules/docs-images-webp.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
description: Marketing/docs images must be WebP; never commit PNG/GIF under assets or docs/assets
alwaysApply: true
---

# Docs images must be WebP

Marketing and documentation screenshots live under `assets/` and `docs/assets/`.

- Store new docs/marketing images as **`.webp` only** (animated WebP for former GIFs).
- Do **not** add or commit `.png`, `.jpg`, `.jpeg`, or `.gif` under `assets/` or `docs/assets/`.
- When replacing an existing raster, convert with `scripts/convert-docs-images.sh` (see the `convert-docs-images` skill) and update all markdown/yml/html refs.
- **Exempt:** runtime card art under `src/assets/` (e.g. Whisker AVIF litter robots) and generated junk (`coverage/`, `test-results/`, `node_modules/`, `dist/`).
53 changes: 53 additions & 0 deletions .cursor/skills/convert-docs-images/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
name: convert-docs-images
description: >-
Convert marketing/docs PNG/JPG/GIF under assets/ or docs/assets/ to WebP,
rewrite markdown/yml/html refs, and remove originals. Use when adding or
updating README/docs screenshots, or when a hook blocked a png/gif commit.
---

# Convert docs images to WebP

Cross-agent policy also lives in root [`AGENTS.md`](../../../AGENTS.md) (Claude Code + Cursor). This skill is mirrored under `.claude/skills/convert-docs-images/` and `.cursor/skills/convert-docs-images/`.

Enforcement hooks (block committing PNG/GIF under marketing asset dirs):

- Cursor: `.cursor/hooks.json` + `.cursor/hooks/block-docs-raster.sh`
- Claude Code: `.claude/settings.json` + `.claude/hooks/block-docs-raster.sh`

## When to use

- Adding or replacing screenshots in `assets/` or `docs/assets/`
- A Cursor hook blocked `git add`/`git commit` of `.png`/`.gif` under those dirs
- Migrating leftover rasters after a docs update

## Do not convert

- Runtime card art under `src/assets/` (e.g. Whisker AVIF litter robots)
- `coverage/`, `test-results/`, `node_modules/`, `dist/`

## Steps

1. Prefer writing new screenshots as `.webp` directly when the capture tool allows it.
2. If you only have PNG/JPG/GIF, put them under `assets/` or `docs/assets/`, then run from the **repo root**:

```bash
./scripts/convert-docs-images.sh
```

Dry-run:

```bash
./scripts/convert-docs-images.sh --dry-run
```

3. Requires `cwebp` and `gif2webp` (`brew install webp`).
4. Confirm refs in `README.md`, `docs/**`, and `mkdocs.yml` point at `.webp`.
5. Do not leave the original `.png`/`.gif` in the tree under marketing asset dirs.

## Defaults

| Source | Encoder | Flags |
| ------- | ---------- | --------------------------------------- |
| PNG/JPG | `cwebp` | `-q 90 -m 6` |
| GIF | `gif2webp` | `-q 80 -m 4 -mt -mixed` (animated WebP) |
12 changes: 12 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,18 @@
!examples/**
!yarn.lock

!scripts/
!scripts/**
!*.sh
!*.mdc
!.cursor/hooks.json
!.cursor/rules/**
!.cursor/skills/**
!.cursor/hooks/**
!.claude/skills/**

!.claude/hooks/**
!.claude/settings.json
# Ignore folders.
node_modules
dist
Expand Down
3 changes: 2 additions & 1 deletion .mocharc.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
"require": [
"ts-node/register",
"tsconfig-paths/register",
"@homeassistant-extras/config/mocha/setup.card"
"@homeassistant-extras/config/mocha/setup.card",
"./test/setup.ts"
],
"extensions": ["ts"],
"spec": ["test/**/*.spec.ts"],
Expand Down
6 changes: 6 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,9 @@ Run `yarn pass` (format + typecheck + lint + test) before shipping changes. Use
## Scoped Guidance

Read the nearest `AGENTS.md` before changing files in a subdirectory. Scoped files exist under `test/`, `src/cards/`, `src/common/`, `src/config/`, `src/delegates/`, `src/hass/`, `src/helpers/`, `src/html/`, `src/localize/`, `src/translations/`, and `src/types/`.

## Docs images (WebP)

Marketing/docs screenshots live under `assets/` and `docs/assets/`. Store them as **`.webp` only** (animated WebP for former GIFs). Do not add `.png` / `.gif` / `.jpg` there. Runtime card art under `src/assets/` is exempt (e.g. Whisker AVIF).

If you only have a PNG/GIF, run `./scripts/convert-docs-images.sh` from the repo root (needs `cwebp` / `gif2webp` from `brew install webp`). See `.claude/skills/convert-docs-images/SKILL.md` and `.cursor/skills/convert-docs-images/SKILL.md`.
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

_A comprehensive card to display and organize your Home Assistant device entities_

![Device Card](docs/assets/cards.png)
![Device Card](docs/assets/cards.webp)

![Home Assistant](https://img.shields.io/badge/home%20assistant-%2341BDF5.svg?style=for-the-badge&logo=home-assistant&logoColor=white)
[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg?style=for-the-badge)](https://github.com/hacs/integration)
Expand Down Expand Up @@ -50,6 +50,8 @@ integration: zwave_js

## Installation

Requires Home Assistant **2026.11.0** or newer.

### HACS (Recommended)

[![HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-extras&repository=device-card&category=dashboard)
Expand Down
Binary file removed docs/assets/attributes.png
Binary file not shown.
Binary file added docs/assets/attributes.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/cards.png
Binary file not shown.
Binary file added docs/assets/cards.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/collapsible-card.png
Binary file not shown.
Binary file added docs/assets/collapsible-card.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/compact-mode.png
Binary file not shown.
Binary file added docs/assets/compact-mode.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/editor.png
Binary file not shown.
Binary file added docs/assets/editor.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/expanded.png
Binary file not shown.
Binary file added docs/assets/expanded.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/icon.png
Binary file not shown.
Binary file added docs/assets/icon.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/integration-card.png
Binary file not shown.
Binary file added docs/assets/integration-card.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/integration-picker.png
Binary file not shown.
Binary file added docs/assets/integration-picker.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/percent-colors.png
Binary file not shown.
Binary file added docs/assets/percent-colors.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/percent-gauges.png
Binary file not shown.
Binary file added docs/assets/percent-gauges.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/pinned-entity-state.png
Binary file not shown.
Binary file added docs/assets/pinned-entity-state.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/assets/portraits.png
Binary file not shown.
Binary file added docs/assets/portraits.webp
Binary file removed docs/assets/problems.png
Diff not rendered.
Binary file added docs/assets/problems.webp
Loading
Loading