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/components-lib/effects/effects-controller.ts

@@ -0,0 +1,98 @@
+import { EffectName, EffectsControllerAPI } from '../../types';
+import { EffectComponent, EffectModule, EffectOptions } from './types';
+
+const effectRegistry: Record<EffectName, () => Promise<EffectModule>> = {
+  fireworks: async () => {
+    const module = await import('../../components/effects/fireworks');
+    return { default: module.AdvancedCameraCardEffectFireworks };
+  },
+  ghost: async () => {
+    const module = await import('../../components/effects/ghost');
+    return { default: module.AdvancedCameraCardEffectGhost };
+  },
+  hearts: async () => {
+    const module = await import('../../components/effects/hearts');
+    return { default: module.AdvancedCameraCardEffectHearts };
+  },
+  shamrocks: async () => {
+    const module = await import('../../components/effects/shamrocks');
+    return { default: module.AdvancedCameraCardEffectShamrocks };
+  },
+  snow: async () => {
+    const module = await import('../../components/effects/snow');
+    return { default: module.AdvancedCameraCardEffectSnow };
+  },
+};
+
+type EffectsContainer = HTMLElement | DocumentFragment;
+
+export class EffectsController implements EffectsControllerAPI {
+  private _importedModules: Map<EffectName, EffectModule> = new Map();
+  private _activeInstances: Map<EffectName, EffectComponent | null> = new Map();
+  private _container: EffectsContainer | null = null;
+
+  public setContainer(container: EffectsContainer | null): void {
+    this._container = container;
+  }
+
+  public async startEffect(name: EffectName, options?: EffectOptions): Promise<void> {
+    if (!this._container || this._activeInstances.has(name)) {
+      return;
+    }
+
+    // Reserve the slot immediately with null to prevent concurrent starts.
+    this._activeInstances.set(name, null);
+
+    const effectModule = await this._importEffectModule(name);
+
+    // Check if the effect was cancelled during loading.
+    if (!effectModule || !this._activeInstances.has(name)) {
+      this._activeInstances.delete(name);
+      return;
+    }
+
+    const effectComponent = new effectModule.default();
+    effectComponent.fadeIn = options?.fadeIn ?? true;
+    this._container.appendChild(effectComponent);
+    this._activeInstances.set(name, effectComponent);
+  }
+
+  public async stopEffect(effect: EffectName): Promise<void> {
+    if (!this._activeInstances.has(effect)) {
+      return;
+    }
+
+    const instance = this._activeInstances.get(effect);
+    this._activeInstances.delete(effect);
+
+    // If instance is null, it's still loading - just clearing the reservation
+    // will prevent it from appearing (startEffect checks this after import).
+    if (instance) {
+      await instance.startFadeOut();
+      instance.remove();
+    }
+  }
+
+  public async toggleEffect(name: EffectName, options?: EffectOptions): Promise<void> {
+    if (this._activeInstances.has(name)) {
+      await this.stopEffect(name);
+    } else {
+      await this.startEffect(name, options);
+    }
+  }
+
+  private async _importEffectModule(name: EffectName): Promise<EffectModule | null> {
+    const existingModule = this._importedModules.get(name);
+    if (existingModule) {
+      return existingModule;
+    }
+
+    const effectModule = await effectRegistry[name]?.();
+    if (!effectModule) {
+      return null;
+    }
+
+    this._importedModules.set(name, effectModule);
+    return effectModule;
+  }
+}