feat: add frontend service for theme lookups (#229)

## Summary

Adds a new frontend service for retrieving Home Assistant themes,
following the same pattern as the addon service.

## Changes

- **New FrontendService**: `hass.frontend.getThemes()` method that
fetches themes via websocket
- **ThemeDefinition interface**: Defines common theme properties
including:
- Common CSS variables (primary-color, accent-color, divider-color,
etc.)
  - Support for theme modes (light/dark)
  - Index signature for additional properties
- **HassThemeMapping interface**: Type-safe mapping of all available
theme names with their supported modes
  - Themes without modes: `true`
  - Themes with modes: string union (e.g., `"light" | "dark"`)
- **Tests**: Comprehensive test suite following the addon service
pattern
- **Service registration**: Frontend service registered in
`hass.module.mts`

## Type Safety

The service returns `Record<keyof HassThemeMapping, ThemeDefinition>`,
ensuring type safety for theme names and their definitions.

## Testing

- ✅ Tests for successful theme retrieval
- ✅ Tests for empty theme responses
- ✅ Follows existing addon service test patterns

Author: zoe-codez

cspell.config.yaml

@@ -22,16 +22,21 @@ words:
   - rgbww
   - hacs
   - mireds
+  - gbuttons
   - rrule
   - rtsp
   - sonarjs
+  - cardassia
+  - zeldaar
+  - breen
   - mbit
   - datetime
   - kbit
   - postdata
   - ssdp
   - systype
   - tvshow
+  - lcars
   - zeroconf
   - templow
   - partlycloudy

src/dev/mappings.mts

@@ -163,4 +163,33 @@ declare module "../user.mts" {
     _downstairs: "switch.kitchen_cabinets" | "switch.living_room_mood_lights";
     _upstairs: "switch.bedroom_lamp";
   }
+
+  export interface HassThemeMapping {
+    "(DO NOT USE/MODIFY)=== LCARS variables": true;
+    "(DO NOT USE/MODIFY)=== Base customizations": true;
+    "(DO NOT USE/MODIFY)=== card-mod CSS": true;
+    "LCARS Default": true;
+    "LCARS Classic": true;
+    "LCARS Nemesis Blue": true;
+    "LCARS Lower Decks I": true;
+    "LCARS Lower Decks II": true;
+    "LCARS Romulus": true;
+    "LCARS Kronos": true;
+    "LCARS Cardassia": true;
+    "LCARS Zeldaar": true;
+    "LCARS Modern": true;
+    "LCARS Picard I": true;
+    "LCARS Picard II": true;
+    "LCARS Red Alert": true;
+    "LCARS TNG": true;
+    "LCARS TNGbuttons": true;
+    "LCARS Transporter": true;
+    "LCARS Navigation": true;
+    "LCARS 25C": true;
+    "LCARS 25C (Red Alert)": true;
+    "LCARS 25C (Yellow Alert)": true;
+    "LCARS 25C (Blue Alert)": true;
+    "LCARS Breen": true;
+    "Minimal Ninja": "light" | "dark";
+  }
 }

src/hass.module.mts

@@ -12,6 +12,7 @@ import {
   FetchAPI,
   FetchInternals,
   Floor,
+  FrontendService,
   HassDiagnosticsService,
   HassFeatureService,
   IDByExtension,
@@ -208,6 +209,11 @@ export const LIB_HASS = CreateLibrary({
      */
     floor: Floor,
 
+    /**
+     * frontend interactions
+     */
+    frontend: FrontendService,
+
     /**
      * search for entity ids in a type safe way
      */

src/helpers/frontend.mts

@@ -0,0 +1,19 @@
+export interface ThemeDefinition {
+  "accent-color"?: string;
+  "app-header-background-color"?: string;
+  "app-header-edit-background-color"?: string;
+  "app-header-text-color"?: string;
+  "card-mod-root-yaml"?: string;
+  "divider-color"?: string;
+  "ha-card-border-radius"?: string;
+  "ha-card-border-width"?: string;
+  "paper-listbox-background-color"?: string;
+  "primary-color"?: string;
+  "sidebar-background-color"?: string;
+  "sidebar-menu-button-background-color"?: string;
+  modes?: {
+    light?: Record<string, unknown>;
+    dark?: Record<string, unknown>;
+  };
+  [key: string]: unknown;
+}

src/helpers/index.mts

@@ -7,6 +7,7 @@ export * from "./entity-state.mts";
 export * from "./features.mts";
 export * from "./fetch.mts";
 export * from "./fetch/index.mts";
+export * from "./frontend.mts";
 export * from "./id-by.mts";
 export * from "./interfaces.mts";
 export * from "./languages.mts";

src/helpers/interfaces.mts

@@ -3,10 +3,11 @@ import type EventEmitter from "events";
 import type { EmptyObject } from "type-fest";
 import type WS from "ws";
 
-import type { AddonDetails } from "../index.mts";
+import type { AddonDetails, ThemeDefinition } from "../index.mts";
 import type {
   ALL_DOMAINS,
   ANY_ENTITY,
+  HassThemeMapping,
   HassUniqueIdMapping,
   iCallService,
   PICK_ENTITY,
@@ -54,6 +55,10 @@ export type HassAddonService = {
   list: () => Promise<AddonDetails[]>;
 };
 
+export type HassFrontendService = {
+  getThemes: () => Promise<Record<keyof HassThemeMapping, ThemeDefinition>>;
+};
+
 export type HassAreaService = {
   apply: (
     area: TAreaId,

src/services/addon.service.mts

@@ -5,11 +5,12 @@ import type { AddonDetails, HassAddonService } from "../index.mts";
 export function AddonService({ hass, logger }: TServiceParams): HassAddonService {
   async function list() {
     logger.trace({ name: "list" }, "fetching addon list");
-    return await hass.socket.sendMessage<AddonDetails[]>({
+    const { addons } = await hass.socket.sendMessage<{ addons: AddonDetails[] }>({
       endpoint: "/addons",
       method: "get",
       type: "supervisor/api",
     });
+    return addons;
   }
 
   return {

src/services/frontend.service.mts

@@ -0,0 +1,20 @@
+import type { TServiceParams } from "@digital-alchemy/core";
+
+import type { HassFrontendService, ThemeDefinition } from "../index.mts";
+import type { HassThemeMapping } from "../user.mts";
+
+export function FrontendService({ hass, logger }: TServiceParams): HassFrontendService {
+  async function getThemes() {
+    logger.trace({ name: "getThemes" }, "fetching themes");
+    const result = await hass.socket.sendMessage<{
+      themes: Record<keyof HassThemeMapping, ThemeDefinition>;
+    }>({
+      type: "frontend/get_themes",
+    });
+    return result.themes;
+  }
+
+  return {
+    getThemes,
+  };
+}

src/services/index.mts

@@ -10,6 +10,7 @@ export * from "./events.service.mts";
 export * from "./feature.service.mts";
 export * from "./fetch-api.service.mts";
 export * from "./floor.service.mts";
+export * from "./frontend.service.mts";
 export * from "./id-by.service.mts";
 export * from "./internal.service.mts";
 export * from "./label.service.mts";

src/testing/addon.spec.mts

@@ -34,7 +34,9 @@ describe("Addon Service", () => {
       ];
 
       await hassTestRunner.run(({ lifecycle, hass }) => {
-        const spy = vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => mockAddons);
+        const spy = vi
+          .spyOn(hass.socket, "sendMessage")
+          .mockImplementation(async () => ({ addons: mockAddons }));
 
         lifecycle.onReady(async () => {
           const result = await hass.addon.list();
@@ -51,7 +53,7 @@ describe("Addon Service", () => {
     it("should return empty array when no addons are available", async () => {
       expect.assertions(1);
       await hassTestRunner.run(({ lifecycle, hass }) => {
-        vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => []);
+        vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => ({ addons: [] }));
 
         lifecycle.onReady(async () => {
           const result = await hass.addon.list();