fix: improved service responses and card debug logging (closes #28)

[rusty4444]

Summary

This PR addresses the ongoing card rendering issues in issue #28 with three categories of fixes:

1. Service response handling

• add_light and remove_light services now support return_response with proper {"ok": true/false, "error": "..."} dicts instead of silently returning when validation fails
• Previously, if a light entity didn't exist in HA states, the add silently failed with zero feedback to the card

2. Card rendering robustness

• Added fallback color (var(--light-color, #888)) to .light-dot CSS, preventing invisible dots when CSS custom properties aren't set due to theme overrides or stale resource loads
• Added console.debug logging in _renderGrid() that logs:
  • Why the grid is empty (no layout / no lights array / empty lights)
  • Light count when rendering starts, confirming the code path is reached

3. Version identity

• Card now sets window.__haLightfxCardVersion = "1.1.13" on load
• Logs "HA LightFX card loaded: v1.1.13" to console on startup
• This lets users check __haLightfxCardVersion in browser console to confirm which card version is actually running (critical when stale cached resources are suspected)

Testing

• Build passes (npm run build:card)
• All changes verified in built output
• User confirms lights render with this version

Fixes #28

[rusty4444]

Hermes Agent Review

Verdict: Reviewed; not auto-merged.

Summary

The service-response and card-debugging changes match the PR title. I verified the frontend bundle rebuilds successfully with npm run build:card, and the Python integration files compile with python3 -m py_compile.

Comments

• add_light / remove_light now correctly opt into SupportsResponse.OPTIONAL and return explicit ok/error payloads when callers request a response.
• The light-dot CSS fallback avoids invisible indicators when --light-color is absent.
• The added console.debug logging is intentionally diagnostic and uses debug-level console output.
• This PR has no reported CI checks (gh pr checks: no checks reported), so it remains ineligible for automation merge under the daily PR safety policy.

Reviewed by Hermes Agent daily PR automation.

[rusty4444]

Hermes Agent Review

Verdict: Reviewed; not auto-merged.

Summary

The latest changes in this PR look reasonable: service response support now returns explicit ok/error payloads when Home Assistant callers request a response, frontend debug/version logging is bounded to console.debug, the light-dot color fallback addresses invisible markers, and the custom-card dedupe hardening now guards window.customCards defensively with descriptor/try-catch handling.

Checks run

• python3 -m py_compile custom_components/ha_lightfx/__init__.py custom_components/ha_lightfx/lightfx_engine.py — passed.
• Manual frontend source checks for the property guard, extended dedupe timers, RAF loop, and var(--light-color, #888) fallback — passed.
• python3 -m pytest tests/test_frontend_card_source.py -q — not runnable in this cron environment because homeassistant is not installed (ModuleNotFoundError: No module named 'homeassistant').

Notes

• No blocking code-review findings found in the diff.
• This PR still has no GitHub status checks reported (statusCheckRollup is empty), so automation did not merge it. Add/enable CI before auto-merge can treat it as safe.

---

Reviewed by Hermes Agent

[rusty4444]

Code Review: PR #44

Verdict: Looks good — manually review + merge when ready

This is the comprehensive fix for issue #28, addressing three categories of rendering problems.

✅ What's Good

Service response handling (__init__.py)

• add_light and remove_light now return structured {"ok": true/false, "error": "..."} dicts when return_response is requested — clean, backwards-compatible
• Properly checks hass.states.get(entity_id) before attempting to add, with clear error messages
• SupportsResponse.OPTIONAL registration is correct

Card robustness (ha-lightfx-card.js)

• var(--light-color, #888) fallback prevents invisible dots when CSS custom properties don't resolve — solid defensive CSS
• Console.debug logging in _renderGrid() will dramatically help debugging: logs why the grid is empty and light count on render
• window.__haLightfxCardVersion is a smart addition — users can verify which version is actually loaded in the browser

Deduplication guard

• Object.defineProperty with try/catch is the correct approach — if the host page freezes the property, the card still loads (unlike PR fix: robust custom card deduplication to prevent stale resource pile-up #43 which would throw)
• RAF-based dedup loop running every frame for 2 seconds catches late-arriving parallel resources
• Extended timeouts up to 10s provide reasonable safety margin

Tests

• 4 new test cases covering: reassignment survival, late parallel load detection, CSS fallback verification
• Tests check the built output, not source — catches build-time issues

⚠️ Minor Notes (non-blocking)

• The version bump is in manifest.json only — consider also bumping in hacs.json if one exists
• The console.debug calls in _renderGrid() fire on every render cycle — acceptable for debugging, but consider removing or gating behind a flag in a future release once the issue is confirmed resolved
• No newline at end of manifest.json (pre-existing)

🔒 Merge Safety

• CI: Not configured — no status checks to verify. This repo needs a CI workflow (at minimum: pytest for Python, a build check for the JS bundle)
• No breaking changes — the return_response behavior is opt-in, existing callers are unaffected
• PR fix: robust custom card deduplication to prevent stale resource pile-up #43 should be closed first as this PR supersedes it

---

Reviewed by Hermes Agent (daily cron)

[rusty4444]

Hermes Agent Code Review

Verdict: ✅ Looks good — manual merge recommended

✅ Python (init.py)

• Service responses: Clean addition of dict | None return type + supports_response=SupportsResponse.OPTIONAL on add_light and remove_light. Correct HA pattern — no issues.
• remove_light: Added check on engine.remove_light() return value before saving — good defensive coding. Prevents silent failures.

✅ Card JS (ha-lightfx-card.js)

• Version tracking: CARD_VERSION + window.__haLightfxCardVersion — helpful for debugging production issues.
• Debug logging: Added detailed _renderGrid empty-state logging — will save hours of head-scratching.
• CSS fallback: var(--light-color, #888) on dot background and box-shadow — prevents invisible dots when CSS custom property is unset.
• customCards guard: Property descriptor interception with dedup on replacement — correct fix for stale entries from parallel-resource-load race conditions.
• RAF dedup: 2-second animation-frame loop — clean, self-terminating, no permanent overhead.

⚠️ Note

• No CI configured (empty statusCheckRollup). Consider adding CI to this repo before merging. At minimum, run the test suite locally.

---

Reviewed by Hermes Agent

[rusty4444]

🤖 Hermes Agent Code Review

Verdict: ✅ Approved

Well-scoped fix for issue #28 that adds proper return_response support to add_light and remove_light services, improves card debugging via console.debug logs and CSS fallback colors, and hardens the custom card picker against stale resource loads.

✅ What's Good

• return_response pattern matches upstream HA conventions correctly
• Light entity validation added before add operations
• SupportsResponse.OPTIONAL correctly set on service registrations
• Debug logging guarded behind console.debug (safe in production)
• CSS fallback colors maintain visual consistency when HA styles aren't loaded
• No security issues, no breaking changes
• No credentials, no user input interpolation

💡 Minor Suggestions

• remove_light could skip the _save() when nothing was removed (harmless but wasteful)
• Consider adding a CHANGELOG.md entry for the new debug features

---

Reviewed by Hermes Agent — CI status: no checks reported on this branch

[rusty4444]

Hermes automated PR review

Verdict: Approved by automated review

Reviewed the provided PR metadata and diff, inspected the relevant backend/frontend source from the PR branch, and checked syntax/build-output indicators. No files were modified. Code review approval is OK, but auto-merge remains blocked because GitHub reports no passing status checks.

Review notes

• No blocking correctness, security, style, or breaking-change issues found in the diff.
• The add_light and remove_light handlers correctly opt into SupportsResponse.OPTIONAL, check call.return_response, and return structured success/error dictionaries while preserving the previous no-response behaviour for callers that do not request responses.
• The frontend version/debug logging and CSS fallback are low risk, and the bundled card output appears to include the updated source changes.
• Caveat: the Lovelace card still calls _hass.callService(...) without requesting or consuming a service response, so the new {ok:false} service responses help callers that explicitly request responses but will not by themselves surface add/remove validation failures in the card UI.
• No visible CI/status checks are reported for this PR, so it should not be auto-merged under the stated policy even though the diff review is approving.

Merge gate

• No CI configured / no checks reported

— Hermes Agent daily PR automation