feat: Add festive visual effects (#2252)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> Introduces an effects system (fireworks, ghost, hearts, shamrocks,
snow), a new `effect` action, and optional date-based loading effects,
integrated into the card with docs, schema, editor, and tests.
> 
> - **Effects System**:
> - Add `EffectsController` and `advanced-camera-card-effects` host with
lazy-loaded effect modules (`fireworks`, `ghost`, `hearts`, `shamrocks`,
`snow`).
> - New base effect component with fade-in/out; SCSS and z-index
updates.
> - **Actions**:
> - New custom action `advanced_camera_card_action: effect` with
`effect_action` (`start`|`stop`|`toggle`).
>   - Wire into `ActionFactory` and add `EffectAction` executor.
> - **Card Integration**:
> - Mount effects host in `advanced-camera-card` and expose
`getEffectsControllerAPI()` via `CardController`.
> - Loading component can trigger date-based effects (e.g., New Year
fireworks) when enabled.
> - **Configuration & Editor**:
> - Add `performance.features.card_loading_effects` (default `true`)
alongside `card_loading_indicator`.
> - Update schemas, defaults, low-performance profile (disables
effects), and editor toggles.
> - **Docs & Examples**:
>   - Document `effect` action parameters and add menu example.
>   - Update performance docs with new option.
> - **Localization & Tests**:
>   - Update i18n strings for new performance option.
> - Add comprehensive tests for effects controller, action, factory,
config defaults/profiles, and utilities.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
cffd4304fe3bd22340316f9cec53e341379b1756. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

tests/card-controller/actions/actions/effect.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from 'vitest';
+import { EffectAction } from '../../../../src/card-controller/actions/actions/effect';
+import { createEffectAction } from '../../../../src/utils/action';
+import { createCardAPI } from '../../../test-utils';
+
+describe('EffectAction', () => {
+  it('should call startEffect when action is start', async () => {
+    const api = createCardAPI();
+    const actionConfig = createEffectAction('snow', 'start');
+    const action = new EffectAction({}, actionConfig);
+
+    await action.execute(api);
+
+    expect(api.getEffectsControllerAPI()?.startEffect).toHaveBeenCalledWith('snow');
+  });
+
+  it('should call stopEffect when action is stop', async () => {
+    const api = createCardAPI();
+    const actionConfig = createEffectAction('snow', 'stop');
+    const action = new EffectAction({}, actionConfig);
+
+    await action.execute(api);
+
+    expect(api.getEffectsControllerAPI()?.stopEffect).toHaveBeenCalledWith('snow');
+  });
+
+  it('should call toggleEffect when action is toggle', async () => {
+    const api = createCardAPI();
+    const actionConfig = createEffectAction('snow', 'toggle');
+    const action = new EffectAction({}, actionConfig);
+
+    await action.execute(api);
+
+    expect(api.getEffectsControllerAPI()?.toggleEffect).toHaveBeenCalledWith('snow');
+  });
+
+  it('should not throw when effectsControllerAPI is null', async () => {
+    const api = createCardAPI();
+    vi.mocked(api.getEffectsControllerAPI).mockReturnValue(null);
+    const actionConfig = createEffectAction('snow', 'start');
+    const action = new EffectAction({}, actionConfig);
+
+    await expect(action.execute(api)).resolves.toBeUndefined();
+  });
+
+  it('should have a no-op stop method', async () => {
+    const actionConfig = createEffectAction('snow', 'stop');
+    const action = new EffectAction({}, actionConfig);
+
+    await expect(action.stop()).resolves.toBeUndefined();
+  });
+});

tests/card-controller/actions/factory.test.ts

@@ -41,6 +41,7 @@ import { ViewAction } from '../../../src/card-controller/actions/actions/view';
 import { ActionFactory } from '../../../src/card-controller/actions/factory';
 import { INTERNAL_CALLBACK_ACTION } from '../../../src/config/schema/actions/custom/internal';
 import { ActionConfig } from '../../../src/config/schema/actions/types';
+import { EffectAction } from '../../../src/card-controller/actions/actions/effect';
 
 // @vitest-environment jsdom
 describe('ActionFactory', () => {
@@ -188,6 +189,7 @@ describe('ActionFactory', () => {
         InternalCallbackAction,
       ],
       [{ advanced_camera_card_action: 'reload' as const }, ReloadAction],
+      [{ advanced_camera_card_action: 'effect' as const }, EffectAction],
     ])(
       'advanced_camera_card_action: $advanced_camera_card_action',
       (action: Partial<ActionConfig>, classObject: object) => {

tests/card-controller/config/config-manager.test.ts

@@ -152,6 +152,7 @@ describe('ConfigManager', () => {
         features: {
           animated_progress_indicator: true,
           card_loading_indicator: true,
+          card_loading_effects: true,
           media_chunk_size: 50,
         },
         style: {

tests/card-controller/controller.test.ts

@@ -32,6 +32,8 @@ import { AdvancedCameraCardEditor } from '../../src/editor';
 import { DeviceRegistryManager } from '../../src/ha/registry/device';
 import { EntityRegistryManagerLive } from '../../src/ha/registry/entity';
 import { ResolvedMediaCache } from '../../src/ha/resolved-media';
+import { EffectsControllerAPI } from '../../src/types';
+import { mock } from 'vitest-mock-extended';
 
 vi.mock('../../src/camera-manager/manager');
 vi.mock('../../src/card-controller/actions/actions-manager');
@@ -70,7 +72,7 @@ const createCardElement = (): CardHTMLElement => {
 };
 
 const createController = (): CardController => {
-  return new CardController(createCardElement(), vi.fn(), vi.fn());
+  return new CardController(createCardElement(), vi.fn(), vi.fn(), vi.fn());
 };
 
 // @vitest-environment jsdom
@@ -83,15 +85,23 @@ describe('CardController', () => {
     const element = createCardElement();
     const scrollCallback = vi.fn();
     const menuToggleCallback = vi.fn();
+    const effectsControllerAPI = mock<EffectsControllerAPI>();
+    const effectsControllerAPICallback = vi.fn().mockReturnValue(effectsControllerAPI);
 
-    const manager = new CardController(element, scrollCallback, menuToggleCallback);
+    const controller = new CardController(
+      element,
+      scrollCallback,
+      menuToggleCallback,
+      effectsControllerAPICallback,
+    );
 
     expect(CardElementManager).toBeCalledWith(
-      manager,
+      controller,
       element,
       scrollCallback,
       menuToggleCallback,
     );
+    expect(controller.getEffectsControllerAPI()).toBe(effectsControllerAPI);
   });
 
   describe('accessors', () => {