documentation updates

warmfire540 · warmfire540 · commit 32b00d12bbe2 · 2026-05-17T15:16:08.000-04:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,39 +2,6 @@
 
 Project instructions for AI coding agents (Claude Code, Cursor, Codex, etc.). All agents working in this repo should read this file. For deeper architecture and conventions, see [CLAUDE.md](./CLAUDE.md).
 
-## Running tests
+## Scoped Guidance
 
-This is a Yarn project — use `yarn`, not `npm`.
-
-```bash
-yarn test            # full suite
-yarn test:coverage   # with NYC coverage
-yarn test:watch      # watch mode
-```
-
-### `yarn test` failing with `ERR_MODULE_NOT_FOUND` — read this first
-
-If `yarn test` fails with an error like:
-
-```
-Error: Cannot find package '@cards/...' imported from test/.../foo.spec.ts
-code: 'ERR_MODULE_NOT_FOUND'
-```
-
-**It is not a module-resolution problem.** The path aliases (`@cards/*`, `@hass/*`, `@delegates/*`, …) are configured correctly in [tsconfig.json](./tsconfig.json) and registered at runtime via `tsconfig-paths/register` in [.mocharc.json](./.mocharc.json).
-
-The real cause is a **TypeScript compilation error** somewhere in the imported file or its transitive imports. `ts-node` surfaces those as a misleading module-resolution error.
-
-**To diagnose, always run:**
-
-```bash
-npx tsc -p tsconfig.test.json --noEmit
-```
-
-Fix the type errors it reports, then rerun `yarn test`. Do not investigate `tsconfig` paths, the test config, or stash changes to compare against `main` — that is wasted effort.
-
-## Other conventions
-
-- Prettier formatting: `yarn format`
-- Build: `yarn build` (Parcel)
-- See [CLAUDE.md](./CLAUDE.md) for architecture, directory layout, and TypeScript path aliases.
+Read the nearest `AGENTS.md` before changing files in a subdirectory. Scoped files exist under `test/`, `src/cards/`, `src/config/`, `src/delegates/`, `src/editor/`, `src/hass/`, `src/html/`, `src/localize/`, `src/theme/`, `src/translations/`, `src/types/`, and `src/util/`.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -19,9 +19,11 @@ This is a **Yarn project**. Use `yarn` commands instead of `npm` for consistency
 
 ### Testing
 
-- `yarn test` - Run tests using Mocha with TypeScript
+- `yarn test` - Run unit tests using Mocha with TypeScript
 - `yarn test:coverage` - Run tests with NYC coverage reporting
 - `yarn test:watch` - Run tests in watch mode for development
+- `yarn test:e2e` - Run Playwright end-to-end tests against a live Home Assistant instance
+- `yarn test:e2e:auth` - Capture a Playwright storage state for authenticated e2e runs (requires `.env` with `PLAYWRIGHT_HA_ORIGIN` and `PLAYWRIGHT_HA_STORAGE_STATE`)
 
 ### Single Test Execution
 
@@ -46,33 +48,45 @@ This is a **Home Assistant custom card** built with **LitElement/Lit** that disp
 
 ### Key Directory Structure
 
-- **`src/cards/`**: Lit-based UI components (main card, editor, sub-components)
+- **`src/cards/`**: Lit-based UI components (main card, sub-components, badges, sliders)
+- **`src/config/`**: Configuration parsing, defaults, and schema helpers
 - **`src/delegates/`**: Business logic separated from UI (retrievers, checks, utilities)
-- **`src/theme/`**: Theming system, CSS generation, color management
+- **`src/editor/`**: Visual configuration editor and its row/sub-element editors
 - **`src/hass/`**: Home Assistant integration, types, and API wrappers
-- **`src/types/`**: TypeScript type definitions for config, sensors, etc.
 - **`src/html/`**: HTML template functions for UI rendering
+- **`src/localize/`**: Localization helpers consuming `src/translations/`
+- **`src/theme/`**: Theming system, CSS generation, color management
+- **`src/translations/`**: JSON translation bundles
+- **`src/types/`**: TypeScript type definitions for config, sensors, etc.
+- **`src/util/`**: Generic utility helpers shared across layers
 
 ### TypeScript Path Aliases
 
 The project uses path aliases defined in `tsconfig.json`:
 
 - `@cards/*` → `./src/cards/*`
+- `@config/*` → `./src/config/*`
 - `@delegates/*` → `./src/delegates/*`
-- `@theme/*` → `./src/theme/*`
+- `@editor/*` → `./src/editor/*`
 - `@hass/*` → `./src/hass/*`
-- `@type/*` → `./src/types/*`
-- `@config/*` → `./src/config/*`
 - `@html/*` → `./src/html/*`
+- `@localize/*` → `./src/localize/*`
+- `@theme/*` → `./src/theme/*`
+- `@type/*` → `./src/types/*`
 - `@util/*` → `./src/util/*`
+- `@test/*` → `./test/*`
+- `@/*` → `./src/*`
 
 ### Component Registration
 
-The card registers multiple custom elements:
+The card registers multiple custom elements (see `src/index.ts`):
 
 - `room-summary-card` - Main card component
 - `room-summary-card-editor` - Visual configuration editor
-- `sensor-collection`, `entity-collection`, `room-state-icon` - Sub-components
+- `sensor-collection`, `entity-collection`, `entity-slider`, `room-state-icon`, `room-badge` - Sub-components
+- `room-summary-entity-detail-editor`, `room-summary-entities-row-editor`, `room-summary-states-row-editor`, `room-summary-thresholds-row-editor`, `room-summary-badge-row-editor`, `room-summary-sub-element-editor` - Editor row/sub-element components
+
+Additional `@customElement`-decorated components are registered inline under `src/cards/components/` (e.g. `area-statistics`, `problem-entity-row`, `problem-entity-list`, `problem-dialog`, `horizontal-slider`, `room-sensor-label`, `room-entity-label`, `room-badge-label`).
 
 ### Data Flow Pattern
 
@@ -91,11 +105,12 @@ The card registers multiple custom elements:
 
 ### Testing Setup
 
-- **Framework**: Mocha + Chai + Sinon
+- **Framework**: Mocha + Chai + Sinon for unit tests
 - **TypeScript**: Tests use separate `tsconfig.test.json`
-- **DOM Testing**: Uses JSDOM for component testing
+- **DOM Testing**: Uses JSDOM (+ `@open-wc/testing`, `@testing-library/dom`) for component testing
 - **Coverage**: NYC with Istanbul for coverage reporting
 - **Setup**: `mocha.setup.ts` provides test environment configuration
+- **End-to-end**: Playwright tests run against a live Home Assistant instance via `yarn test:e2e`; auth state is captured with `yarn test:e2e:auth`
 
 ### Build System
 
diff --git a/README.md b/README.md
@@ -77,6 +77,7 @@ This project is protected under the MIT License. For more details, refer to the
 - Inspired by Home Assistant's chip design
 - Button-Card and Auto-Entities were a huge inspo
 - Thanks to all contributors!
+- Maintained by [Patrick Masters](https://github.com/warmfire540) / [Curious Cat Consulting](https://curiouscat.consulting/projects/ha-room-summary-card?utm_source=github-room-summary-card&utm_medium=readme&utm_campaign=oss-presence&utm_content=maintained-by)
 
 [![contributors](https://contrib.rocks/image?repo=homeassistant-extras/room-summary-card)](https://github.com/homeassistant-extras/room-summary-card/graphs/contributors)
 
diff --git a/docs/index.md b/docs/index.md
@@ -378,3 +378,8 @@ This project is protected under the MIT License. For more details, refer to the
 ## Build & Code Quality
 
 Check out **[Build Documentation](BUILD.md)**!
+---
+
+<p align="center">
+    <em>Built and maintained by <a href="https://curiouscat.consulting/projects/ha-room-summary-card?utm_source=github-room-summary-card&utm_medium=docs-site&utm_campaign=oss-presence&utm_content=footer">Curious Cat Consulting</a></em>
+</p>
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -58,3 +58,6 @@ extra:
       link: https://github.com/homeassistant-extras/room-summary-card
     - icon: fontawesome/brands/discord
       link: https://discord.gg/NpH4Pt8Jmr
+    - icon: fontawesome/solid/globe
+      link: https://curiouscat.consulting/projects/ha-room-summary-card?utm_source=github-room-summary-card&utm_medium=docs-site&utm_campaign=oss-presence&utm_content=nav-link
+      name: Maintained by Curious Cat Consulting
diff --git a/package.json b/package.json
@@ -1,9 +1,20 @@
 {
   "name": "room-summary-card",
   "version": "0.68.0",
-  "author": "Patrick Masters",
+  "author": {
+    "name": "Patrick Masters",
+    "url": "https://curiouscat.consulting/projects/ha-room-summary-card?utm_source=github-room-summary-card&utm_medium=package-metadata&utm_campaign=oss-presence&utm_content=author-url"
+  },
   "license": "ISC",
   "description": "Custom card Home Assistant which can show a summary of room entities.",
+  "homepage": "https://homeassistant-extras.github.io/room-summary-card/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/homeassistant-extras/room-summary-card.git"
+  },
+  "bugs": {
+    "url": "https://github.com/homeassistant-extras/room-summary-card/issues"
+  },
   "source": "src/index.ts",
   "module": "dist/room-summary-card.js",
   "targets": {
diff --git a/src/cards/AGENTS.md b/src/cards/AGENTS.md
@@ -0,0 +1,9 @@
+# AGENTS.md - Cards
+
+This folder contains Lit-based card UI, editors, mixins, and card-specific components.
+
+- Keep rendering logic declarative and close to the component that owns the UI state.
+- Use delegates, helpers, or common utilities for business logic that can be tested without DOM rendering.
+- Preserve Home Assistant custom element registration patterns used by the repo.
+- Keep editor components focused on config editing and emitting config change events.
+- Prefer existing local component, mixin, and style patterns before adding new abstractions.
diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md
@@ -0,0 +1,8 @@
+# AGENTS.md - Config
+
+This folder contains feature flags, config schemas, defaults, and config-related helpers.
+
+- Preserve backwards compatibility for shipped dashboard config unless the user explicitly asks for a breaking change.
+- Keep config defaults and validation behavior close together when possible.
+- Update editor schemas and tests when adding or changing user-facing config options.
+- Avoid silently changing persisted config shape without a migration or cleanup path.
diff --git a/src/delegates/AGENTS.md b/src/delegates/AGENTS.md
@@ -0,0 +1,9 @@
+# AGENTS.md - Delegates
+
+This folder contains business logic, retrievers, action handlers, subscriptions, and data-processing helpers.
+
+- Keep delegate code independent from Lit rendering whenever practical.
+- Prefer pure functions for transforms, filtering, sorting, and state calculations.
+- Keep Home Assistant API access behind existing retriever/subscription patterns.
+- Add or update focused unit tests when changing behavior here.
+- Do not move UI concerns into delegates; return data that cards can render.
diff --git a/src/editor/AGENTS.md b/src/editor/AGENTS.md
@@ -0,0 +1,8 @@
+# AGENTS.md - Editor
+
+This folder contains shared editor schemas, config cleanup, and editor support utilities.
+
+- Keep editor helpers aligned with the card config types and defaults.
+- Emit Home Assistant config change events using the repo's existing helper pattern.
+- Keep schema changes backwards compatible with existing dashboard YAML/UI config where practical.
+- Test config cleanup and schema utilities when behavior changes.
diff --git a/src/hass/AGENTS.md b/src/hass/AGENTS.md
@@ -0,0 +1,9 @@
+# AGENTS.md - Home Assistant Code
+
+This folder contains copied or adapted Home Assistant frontend types, helpers, and integration glue.
+
+- Treat these files as upstream Home Assistant frontend code unless clearly documented otherwise.
+- Keep copied files matching upstream 100% when they are vendored from Home Assistant.
+- If a local change is unavoidable, document why it diverges from upstream.
+- Prefer copying the smallest needed upstream surface instead of inventing parallel types.
+- Be careful with import paths so shared HASS helpers stay portable across card repos.
diff --git a/src/html/AGENTS.md b/src/html/AGENTS.md
@@ -0,0 +1,9 @@
+# AGENTS.md - HTML Helpers
+
+This folder contains render helpers and template-building functions.
+
+- Keep helpers small, composable, and free of side effects.
+- Return Lit templates or values expected by the surrounding card components.
+- Avoid embedding business logic here; calculate data in delegates/helpers first.
+- Reuse existing state-display, icon, section, and row helpers before adding new ones.
+- Add tests for non-trivial conditional rendering or formatting behavior.
diff --git a/src/localize/AGENTS.md b/src/localize/AGENTS.md
@@ -0,0 +1,8 @@
+# AGENTS.md - Localize
+
+This folder contains localization helpers used by card code.
+
+- Keep localization helpers deterministic and easy to test.
+- Preserve fallback behavior for missing languages or keys.
+- Do not hard-code translated user-facing strings in card components when a localization path exists.
+- Keep helper behavior aligned with the JSON files in `src/translations/` when that folder exists.
diff --git a/src/theme/AGENTS.md b/src/theme/AGENTS.md
@@ -0,0 +1,8 @@
+# AGENTS.md - Theme
+
+This folder contains styles, theme utilities, color logic, and CSS rendering helpers.
+
+- Keep styling tokens and render helpers consistent with the repo's existing theme model.
+- Avoid hard-coded colors when an existing theme variable or Home Assistant token fits.
+- Preserve visual behavior across supported Home Assistant themes.
+- Add tests for non-trivial color, threshold, or style-conversion logic.
diff --git a/src/translations/AGENTS.md b/src/translations/AGENTS.md
@@ -0,0 +1,8 @@
+# AGENTS.md - Translations
+
+This folder contains JSON translation files.
+
+- Keep translation keys stable once used by released card config or UI.
+- Update every supported language file when adding a key, or document the fallback gap in `TODO.md`.
+- Keep JSON sorted or grouped according to the existing file style.
+- Do not change key names just to improve wording; add compatibility or migrate callers first.
diff --git a/src/types/AGENTS.md b/src/types/AGENTS.md
@@ -0,0 +1,8 @@
+# AGENTS.md - Types
+
+This folder contains TypeScript contracts for configs, entities, locale data, and Home Assistant-facing shapes.
+
+- Keep exported types stable when they represent user config or public card APIs.
+- Prefer specific types over broad `any` or unstructured records.
+- Reuse Home Assistant types from `src/hass/` rather than duplicating incompatible shapes.
+- Keep type-only modules free of runtime side effects.
diff --git a/src/util/AGENTS.md b/src/util/AGENTS.md
@@ -0,0 +1,8 @@
+# AGENTS.md - Util
+
+This folder contains miscellaneous utilities that do not fit a more specific domain folder.
+
+- Prefer moving broadly shared utilities to `src/common/` when they are used across domains.
+- Keep utility functions small, deterministic, and easy to test.
+- Avoid adding catch-all modules that mix unrelated concerns.
+- Add tests for behavior that affects rendering, config, or Home Assistant state handling.
diff --git a/test/AGENTS.md b/test/AGENTS.md
@@ -0,0 +1,44 @@
+# AGENTS.md - Tests
+
+This is a Yarn project. Use `yarn`, not `npm`.
+
+```bash
+yarn test            # full suite
+yarn test:coverage   # with NYC coverage
+yarn test:watch      # watch mode
+```
+
+## Single Test Execution
+
+To run a specific test file, prefer the repo's Mocha setup and test TypeScript config:
+
+```bash
+TS_NODE_PROJECT='./tsconfig.test.json' npx mocha test/path/to/specific.spec.ts
+```
+
+## `yarn test` failing with `ERR_MODULE_NOT_FOUND`
+
+If `yarn test` fails with an error like:
+
+```text
+Error: Cannot find package '@cards/...' imported from test/.../foo.spec.ts
+code: 'ERR_MODULE_NOT_FOUND'
+```
+
+It is usually not a module-resolution problem. The path aliases (`@cards/*`, `@hass/*`, `@delegates/*`, and similar aliases) are configured in `tsconfig.json` and registered at runtime by the test setup.
+
+The common cause is a TypeScript compilation error somewhere in the imported file or its transitive imports. `ts-node` can surface those as a misleading module-resolution error.
+
+To diagnose, run:
+
+```bash
+npx tsc -p tsconfig.test.json --noEmit
+```
+
+Fix the type errors it reports, then rerun `yarn test`. Do not investigate path aliases, test config, or stash changes to compare against `main` until the typecheck is clean.
+
+## Other Commands
+
+- Format with `yarn format`.
+- Build with `yarn build`.
+- Check `CLAUDE.md` for repo-specific architecture, directory layout, and aliases.
