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 -->

src/card-controller/actions/actions/effect.ts

@@ -0,0 +1,21 @@
+import { EffectActionConfig } from '../../../config/schema/actions/custom/effect';
+import { CardActionsAPI } from '../../types';
+import { AdvancedCameraCardAction } from './base';
+
+export class EffectAction extends AdvancedCameraCardAction<EffectActionConfig> {
+  public async execute(api: CardActionsAPI): Promise<void> {
+    await super.execute(api);
+
+    switch (this._action.effect_action) {
+      case 'start':
+        api.getEffectsControllerAPI()?.startEffect(this._action.effect);
+        break;
+      case 'stop':
+        api.getEffectsControllerAPI()?.stopEffect(this._action.effect);
+        break;
+      case 'toggle':
+        api.getEffectsControllerAPI()?.toggleEffect(this._action.effect);
+        break;
+    }
+  }
+}

src/card-controller/actions/factory.ts

@@ -10,6 +10,7 @@ import { DefaultAction } from './actions/default';
 import { DisplayModeSelectAction } from './actions/display-mode-select';
 import { DownloadAction } from './actions/download';
 import { ExpandAction } from './actions/expand';
+import { EffectAction } from './actions/effect';
 import { FullscreenAction } from './actions/fullscreen';
 import { InternalCallbackAction } from './actions/internal-callback';
 import { LogAction } from './actions/log';
@@ -103,6 +104,8 @@ export class ActionFactory {
         return new DownloadAction(context, action, options?.config);
       case 'camera_ui':
         return new CameraUIAction(context, action, options?.config);
+      case 'effect':
+        return new EffectAction(context, action, options?.config);
       case 'expand':
         return new ExpandAction(context, action, options?.config);
       case 'fullscreen':

src/card-controller/controller.ts

@@ -8,6 +8,7 @@ import { EntityRegistryManagerLive } from '../ha/registry/entity';
 import { EntityCache, EntityRegistryManager } from '../ha/registry/entity/types';
 import { ResolvedMediaCache } from '../ha/resolved-media';
 import { LovelaceCardEditor } from '../ha/types';
+import { EffectsControllerAPI } from '../types';
 import { ActionsManager } from './actions/actions-manager';
 import { AutomationsManager } from './automations-manager';
 import { CameraURLManager } from './camera-url-manager';
@@ -63,6 +64,8 @@ import {
 import { ViewItemManager } from './view/item-manager';
 import { ViewManager } from './view/view-manager';
 
+type EffectsControllerAPICallback = () => EffectsControllerAPI | null;
+
 export class CardController
   implements
     CardActionsManagerAPI,
@@ -90,6 +93,8 @@ export class CardController
     CardViewAPI,
     ReactiveController
 {
+  protected _effectsControllerAPICallback: EffectsControllerAPICallback;
+
   protected _conditionStateManager = new ConditionStateManager();
 
   // These properties may be used in the construction of 'managers' (and should
@@ -127,6 +132,7 @@ export class CardController
     host: CardHTMLElement,
     scrollCallback: ScrollCallback,
     menuToggleCallback: MenuToggleCallback,
+    effectsControllerAPICallback: EffectsControllerAPICallback,
   ) {
     host.addController(this);
 
@@ -136,6 +142,7 @@ export class CardController
       scrollCallback,
       menuToggleCallback,
     );
+    this._effectsControllerAPICallback = effectsControllerAPICallback;
   }
 
   // *************************************************************************
@@ -186,6 +193,10 @@ export class CardController
     return this._deviceRegistryManager;
   }
 
+  public getEffectsControllerAPI(): EffectsControllerAPI | null {
+    return this._effectsControllerAPICallback();
+  }
+
   public getEntityRegistryManager(): EntityRegistryManager {
     return this._entityRegistryManager;
   }

src/card-controller/types.ts

@@ -3,6 +3,7 @@ import type { ConditionStateManager } from '../conditions/state-manager';
 import type { Automation } from '../config/schema/automations';
 import type { EntityRegistryManager } from '../ha/registry/entity/types';
 import type { ResolvedMediaCache } from '../ha/resolved-media';
+import type { EffectsControllerAPI } from '../types';
 import type { ActionsManager } from './actions/actions-manager';
 import type { AutomationsManager } from './automations-manager';
 import type { CameraURLManager } from './camera-url-manager';
@@ -41,6 +42,7 @@ export interface CardActionsAPI {
   getCardElementManager(): CardElementManager;
   getConditionStateManager(): ConditionStateManager;
   getConfigManager(): ConfigManager;
+  getEffectsControllerAPI(): EffectsControllerAPI | null;
   getExpandManager(): ExpandManager;
   getFoldersManager(): FoldersManager;
   getFullscreenManager(): FullscreenManager;