Files
advanced-camera-card/src/card-controller/types.ts
T
Dermot Duffy ea251ca988 perf(bundle): lazy-load the nunjucks template engine (#2535)
Closes #2531.

## Summary

The full `nunjucks` templating engine (~226KB) plus `ha-nunjucks`
(~46KB) — roughly **272KB, ~13% of the eager entry chunk** — was
statically imported and downloaded by every card on initial load, even
though templates only apply when a config value contains a `{{ … }}` /
`{% … %}` delimiter. Most cards use no templates and never need the
engine.

This defers the engine behind a dynamic `import('ha-nunjucks/dist')` so
it ships in a separate, on-demand chunk instead of the eager
`card-*.js`.

## Approach

The render path (`TemplateRenderer.renderRecursively`) is **kept
synchronous** — it is called from many synchronous hot paths
(condition/trigger evaluators, picture-elements rendering, actions,
folder matchers), and making it async would be a large, high-risk
refactor of the evaluation core.

Instead:

- **New `src/card-controller/templates/engine.ts`** — a module-level
singleton lazy loader (`loadTemplateEngine()` / `getTemplateEngine()`)
shared across all `TemplateRenderer` instances, plus a
`containsTemplate()` delimiter helper.
- **Delimiter gating** — strings without a delimiter never touch the
engine (the overwhelming majority of renders).
- **Pre-warm at config time** — because every template string originates
in the config, a new mandatory `TEMPLATE_ENGINE` initialization aspect
loads the engine before first render whenever the config contains a
delimiter. This **guarantees no raw `{{ … }}` flash**: content/condition
rendering is blocked until the engine is present for template-using
cards. Cards without templates never load it.

## Result

- nunjucks + ha-nunjucks move out of the eager chunk into a separate
chunk fetched only when a card actually uses templates.
- No change to the synchronous public render API; condition/trigger
evaluation core untouched.

## Tests

- New `engine.ts` loader coverage (concurrent load, cached reuse,
not-loaded fallback).
- The 11 existing test files that render real (delimiter-bearing)
templates declare their dependency explicitly via
`beforeAll(loadTemplateEngine)` — no global/implicit setup hook.
- Full suite green (4764 tests), lint and ts-prune clean, per-file 100%
coverage maintained for the affected directories.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c

---
_Generated by [Claude
Code](https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c)_
2026-06-30 17:45:13 -07:00

376 lines
13 KiB
TypeScript

import type { CameraManager } from '../camera-manager/manager';
import type { ConditionStateManager } from '../condition-trigger/conditions/state-manager';
import type { Automation } from '../config/schema/automations';
import type { DeviceRegistryManager } from '../ha/registry/device';
import type { EntityRegistryManager } from '../ha/registry/entity/types';
import type { ResolvedMediaCache } from '../ha/resolved-media';
import type { EffectsManagerInterface } from '../types';
import type { ActionsManager } from './actions/actions-manager';
import type { AutomationsManager } from './automations-manager';
import type { CallManager } from './call/manager';
import type { CameraTriggersManager } from './camera-triggers-manager';
import type { CameraURLManager } from './camera-url-manager';
import type { CardElementManager } from './card-element-manager';
import type { ConfigManager } from './config/config-manager';
import type { DefaultManager } from './default-manager';
import type { ExpandManager } from './expand-manager';
import type { FoldersManager } from './folders/manager';
import type { FullscreenManager } from './fullscreen/fullscreen-manager';
import type { HASSManager } from './hass/hass-manager';
import type { InitializationManager } from './initialization-manager';
import type { InteractionManager } from './interaction-manager';
import type { IssueManager } from './issues/issue-manager';
import type { KeyboardStateManager } from './keyboard-state-manager';
import type { LockManager } from './lock/manager';
import type { MediaLoadedInfoManager } from './media-info-manager';
import type { MediaPlayerManager } from './media-player-manager';
import type { MicrophoneManager } from './microphone-manager';
import type { NotificationManager } from './notification-manager';
import type { PIPManager } from './pip-manager';
import type { QueryStringManager } from './query-string-manager';
import type { StatusBarItemManager } from './status-bar-item-manager';
import type { StyleManager } from './style-manager';
import type { TemplateManager } from './templates';
import type { ViewItemManager } from './view/item-manager';
import type { ViewManager } from './view/view-manager';
// *************************************************************************
// Manager APIs
// This defines a series of limited APIs that various managers use to control
// the card. Explicitly specifying them helps make coupling intentional and
// reduce cyclic dependencies.
// *************************************************************************
export interface CardActionsAPI {
getActionsManager(): ActionsManager;
getCallManager(): CallManager;
getCameraManager(): CameraManager;
getCameraURLManager(): CameraURLManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getEffectsManager(): EffectsManagerInterface;
getExpandManager(): ExpandManager;
getFoldersManager(): FoldersManager;
getFullscreenManager(): FullscreenManager;
getHASSManager(): HASSManager;
getLockManager(): LockManager;
getMediaLoadedInfoManager(): MediaLoadedInfoManager;
getMediaPlayerManager(): MediaPlayerManager;
getMicrophoneManager(): MicrophoneManager;
getNotificationManager(): NotificationManager;
getPIPManager(): PIPManager;
getIssueManager(): IssueManager;
getStatusBarItemManager(): StatusBarItemManager;
getCameraTriggersManager(): CameraTriggersManager;
getTemplateManager(): TemplateManager;
getViewItemManager(): ViewItemManager;
getViewManager(): ViewManager;
}
export type CardActionsManagerAPI = CardActionsAPI;
export interface CardAutomationsAPI {
getActionsManager(): ActionsManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getHASSManager(): HASSManager;
getInitializationManager(): InitializationManager;
getNotificationManager(): NotificationManager;
getIssueManager(): IssueManager;
getTemplateManager(): TemplateManager;
}
export interface CardCallAPI {
getCameraManager(): CameraManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getMicrophoneManager(): MicrophoneManager;
getNotificationManager(): NotificationManager;
getViewManager(): ViewManager;
}
export interface CardCameraAPI {
getActionsManager(): ActionsManager;
getConfigManager(): ConfigManager;
getDeviceRegistryManager(): DeviceRegistryManager;
getEntityRegistryManager(): EntityRegistryManager;
getHASSManager(): HASSManager;
getResolvedMediaCache(): ResolvedMediaCache;
getCameraTriggersManager(): CameraTriggersManager;
}
export interface CardCameraURLAPI {
getCameraManager(): CameraManager;
getViewManager(): ViewManager;
}
export interface CardConditionAPI {
getAutomationsManager(): AutomationsManager;
getConfigManager(): ConfigManager;
}
export interface CardConfigAPI {
getAutomationsManager(): AutomationsManager;
getCameraManager(): CameraManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getDefaultManager(): DefaultManager;
getFoldersManager(): FoldersManager;
getHASSManager(): HASSManager;
getInitializationManager(): InitializationManager;
getMediaLoadedInfoManager(): MediaLoadedInfoManager;
getMediaPlayerManager(): MediaPlayerManager;
getMicrophoneManager(): MicrophoneManager;
getIssueManager(): IssueManager;
getStatusBarItemManager(): StatusBarItemManager;
getStyleManager(): StyleManager;
getTemplateManager(): TemplateManager;
getViewManager(): ViewManager;
}
export interface CardConfigLoaderAPI {
getAutomationsManager(): AutomationsManager;
getConfigManager(): ConfigManager;
getFoldersManager(): FoldersManager;
getHASSManager(): HASSManager;
getIssueManager(): IssueManager;
}
export interface CardDefaultManagerAPI {
getAutomationsManager(): AutomationsManager;
getConfigManager(): ConfigManager;
getHASSManager(): HASSManager;
getInteractionManager(): InteractionManager;
getCameraTriggersManager(): CameraTriggersManager;
getViewManager(): ViewManager;
}
export interface CardDownloadAPI {
getCameraManager(): CameraManager;
getHASSManager(): HASSManager;
getMediaLoadedInfoManager(): MediaLoadedInfoManager;
getNotificationManager(): NotificationManager;
getViewManager(): ViewManager;
}
export interface CardElementAPI {
getActionsManager(): ActionsManager;
getCallManager(): CallManager;
getCameraManager(): CameraManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getDefaultManager(): DefaultManager;
getExpandManager(): ExpandManager;
getFullscreenManager(): FullscreenManager;
getInitializationManager(): InitializationManager;
getInteractionManager(): InteractionManager;
getHASSManager(): HASSManager;
getKeyboardStateManager(): KeyboardStateManager;
getMediaLoadedInfoManager(): MediaLoadedInfoManager;
getMediaPlayerManager(): MediaPlayerManager;
getMicrophoneManager(): MicrophoneManager;
getPIPManager(): PIPManager;
getIssueManager(): IssueManager;
getQueryStringManager(): QueryStringManager;
getCameraTriggersManager(): CameraTriggersManager;
getViewManager(): ViewManager;
}
export interface CardExpandAPI {
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getFullscreenManager(): FullscreenManager;
}
export interface CardFoldersAPI {
getConfigManager(): ConfigManager;
getHASSManager(): HASSManager;
getResolvedMediaCache(): ResolvedMediaCache;
getTemplateManager(): TemplateManager;
}
export interface CardFullscreenAPI {
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getExpandManager(): ExpandManager;
getMediaLoadedInfoManager(): MediaLoadedInfoManager;
getMediaPlayerManager(): MediaPlayerManager;
}
export interface CardPIPAPI {
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
}
export interface CardHASSAPI {
getCameraManager(): CameraManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getDefaultManager(): DefaultManager;
getInitializationManager(): InitializationManager;
getInteractionManager(): InteractionManager;
getMediaPlayerManager(): MediaPlayerManager;
getStyleManager(): StyleManager;
getCameraTriggersManager(): CameraTriggersManager;
getViewManager(): ViewManager;
}
export interface CardInitializerAPI {
createCameraManager(): void;
getCameraManager(): CameraManager;
createMicrophoneManager(): void;
getMicrophoneManager(): MicrophoneManager;
getAutomationsManager(): AutomationsManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getDefaultManager(): DefaultManager;
getEntityRegistryManager(): EntityRegistryManager;
getHASSManager(): HASSManager;
getMediaPlayerManager(): MediaPlayerManager;
getIssueManager(): IssueManager;
getQueryStringManager(): QueryStringManager;
getResolvedMediaCache(): ResolvedMediaCache;
getCameraTriggersManager(): CameraTriggersManager;
getTemplateManager(): TemplateManager;
getViewManager(): ViewManager;
}
export interface CardInteractionAPI {
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getStyleManager(): StyleManager;
getCameraTriggersManager(): CameraTriggersManager;
getViewManager(): ViewManager;
}
export interface CardKeyboardStateAPI {
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
}
export interface CardLockAPI {
getCallManager(): CallManager;
getConfigManager(): ConfigManager;
getViewManager(): ViewManager;
}
export interface CardMediaLoadedAPI {
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getFullscreenManager(): FullscreenManager;
getStyleManager(): StyleManager;
}
export interface CardMediaPlayerAPI {
getCameraManager(): CameraManager;
getConfigManager(): ConfigManager;
getEntityRegistryManager(): EntityRegistryManager;
getHASSManager(): HASSManager;
getQueryStringManager(): QueryStringManager;
}
export interface CardNotificationAPI {
getCardElementManager(): CardElementManager;
}
export interface CardIssueManagerAPI {
getCameraManager(): CameraManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getInitializationManager(): InitializationManager;
getInteractionManager(): InteractionManager;
getNotificationManager(): NotificationManager;
getViewManager(): ViewManager;
}
export interface CardMicrophoneAPI {
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
}
export interface CardQueryStringAPI {
getActionsManager(): ActionsManager;
getCardElementManager(): CardElementManager;
getConfigManager(): ConfigManager;
getViewManager(): ViewManager;
}
export interface CardStatusBarAPI {
getCardElementManager(): CardElementManager;
}
export interface CardStyleAPI {
getCardElementManager(): CardElementManager;
getConfigManager(): ConfigManager;
getExpandManager(): ExpandManager;
getFullscreenManager(): FullscreenManager;
getHASSManager(): HASSManager;
getInteractionManager(): InteractionManager;
getMediaLoadedInfoManager(): MediaLoadedInfoManager;
getViewManager(): ViewManager;
}
export interface CardCameraTriggersAPI {
getCallManager(): CallManager;
getCameraManager(): CameraManager;
getConditionStateManager(): ConditionStateManager;
getCardElementManager(): CardElementManager;
getConfigManager(): ConfigManager;
getHASSManager(): HASSManager;
getInteractionManager(): InteractionManager;
getViewManager(): ViewManager;
}
export interface CardViewAPI {
getCameraManager(): CameraManager;
getCardElementManager(): CardElementManager;
getConditionStateManager(): ConditionStateManager;
getConfigManager(): ConfigManager;
getFoldersManager(): FoldersManager;
getHASSManager(): HASSManager;
getInitializationManager(): InitializationManager;
getLockManager(): LockManager;
getMediaLoadedInfoManager(): MediaLoadedInfoManager;
getNotificationManager(): NotificationManager;
getIssueManager(): IssueManager;
getQueryStringManager(): QueryStringManager;
getStyleManager(): StyleManager;
getCameraTriggersManager(): CameraTriggersManager;
}
// *************************************************************************
// Common Types
// *************************************************************************
export interface KeysState {
[key: string]: {
state: 'down' | 'up';
ctrl: boolean;
shift: boolean;
alt: boolean;
meta: boolean;
};
}
export interface MicrophoneState {
stream?: MediaStream | null;
connected: boolean;
muted: boolean;
forbidden: boolean;
}
export interface TaggedAutomation extends Automation {
tag?: unknown;
}