feat: Add 'call' support to improve 2-way audio experience (#2486)

Draws significant inspiration (and direct styling) from
https://github.com/dermotduffy/advanced-camera-card/pull/2447 . Thank
you @Maudfer !

BREAKING CHANGE:

The microphone condition previously bundled two unrelated signals —
whether a two-way-audio session was connected and whether the microphone
was muted. Connection state is now its own dedicated call condition, and
microphone is reserved purely for mute state. Configs are upgraded
automatically (the card rewrites affected conditions under overrides,
elements, and automations). If you maintain config by hand, convert as
follows:

If you only used connected:

# Before
```yaml
condition: microphone
connected: true
```

# After
```yaml
condition: call
call: true
```
If you used both connected and muted — they must be split into two
conditions, since they no longer live together:

# Before
```yaml
condition: microphone
connected: true
muted: false
```

# After
```yaml
condition: and
conditions:
  - condition: call
    call: true
  - condition: microphone
    muted: false
```

tests/card-controller/actions/actions/call-end.test.ts

@@ -0,0 +1,18 @@
+import { expect, it } from 'vitest';
+import { CallEndAction } from '../../../../src/card-controller/actions/actions/call-end';
+import { createCardAPI } from '../../../test-utils';
+
+it('should handle call_end action', async () => {
+  const api = createCardAPI();
+  const action = new CallEndAction(
+    {},
+    {
+      action: 'fire-dom-event',
+      advanced_camera_card_action: 'call_end',
+    },
+  );
+
+  await action.execute(api);
+
+  expect(api.getCallManager().end).toBeCalled();
+});

tests/card-controller/actions/actions/call-start.test.ts

@@ -0,0 +1,38 @@
+import { expect, it } from 'vitest';
+import { CallStartAction } from '../../../../src/card-controller/actions/actions/call-start';
+import { createCardAPI } from '../../../test-utils';
+
+it('should handle call_start action without a camera or stream', async () => {
+  const api = createCardAPI();
+  const action = new CallStartAction(
+    {},
+    {
+      action: 'fire-dom-event',
+      advanced_camera_card_action: 'call_start',
+    },
+  );
+
+  await action.execute(api);
+
+  expect(api.getCallManager().start).toBeCalledWith(undefined, undefined);
+});
+
+it('should handle call_start action with a camera and stream', async () => {
+  const api = createCardAPI();
+  const action = new CallStartAction(
+    {},
+    {
+      action: 'fire-dom-event',
+      advanced_camera_card_action: 'call_start',
+      camera: 'camera.front',
+      stream: 'camera.front_doorbell',
+    },
+  );
+
+  await action.execute(api);
+
+  expect(api.getCallManager().start).toBeCalledWith(
+    'camera.front',
+    'camera.front_doorbell',
+  );
+});

tests/card-controller/actions/actions/substream-off.test.ts

@@ -1,7 +1,7 @@
 import { expect, it } from 'vitest';
 import { SubstreamOffAction } from '../../../../src/card-controller/actions/actions/substream-off';
+import { SubstreamViewModifier } from '../../../../src/card-controller/view/modifiers/substream';
 import { createCardAPI } from '../../../test-utils';
-import { SubstreamOffViewModifier } from '../../../../src/card-controller/view/modifiers/substream-off';
 
 it('should handle live_substream_off action', async () => {
   const api = createCardAPI();
@@ -16,6 +16,6 @@ it('should handle live_substream_off action', async () => {
   await action.execute(api);
 
   expect(api.getViewManager().setViewByParameters).toBeCalledWith({
-    modifiers: [expect.any(SubstreamOffViewModifier)],
+    modifiers: [expect.any(SubstreamViewModifier)],
   });
 });

tests/card-controller/actions/actions/substream-on.test.ts

@@ -1,11 +1,20 @@
-import { expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+import { CameraManagerStore } from '../../../../src/camera-manager/store';
 import { SubstreamOnAction } from '../../../../src/card-controller/actions/actions/substream-on';
-import { createCardAPI } from '../../../test-utils';
-import { SubstreamOnViewModifier } from '../../../../src/card-controller/view/modifiers/substream-on';
+import { applyViewModifiers } from '../../../../src/card-controller/view/modifiers';
+import { getStreamCameraID } from '../../../../src/view/substream';
+import { View } from '../../../../src/view/view';
+import {
+  createCameraConfig,
+  createCameraManager,
+  createCapabilities,
+  createCardAPI,
+  createStore,
+  createView,
+} from '../../../test-utils';
 
-it('should handle live_substream_on action', async () => {
-  const api = createCardAPI();
-  const action = new SubstreamOnAction(
+const createAction = (): SubstreamOnAction =>
+  new SubstreamOnAction(
     {},
     {
       action: 'fire-dom-event',
@@ -13,9 +22,88 @@ it('should handle live_substream_on action', async () => {
     },
   );
 
-  await action.execute(api);
+// A store where `camera.office` has one substream dependency, `camera.kitchen`.
+const createStoreWithSubstreams = (): CameraManagerStore =>
+  createStore([
+    {
+      cameraID: 'camera.office',
+      capabilities: createCapabilities({ live: true, substream: true }),
+      config: createCameraConfig({ dependencies: { all_cameras: true } }),
+    },
+    {
+      cameraID: 'camera.kitchen',
+      capabilities: createCapabilities({ substream: true }),
+    },
+  ]);
 
-  expect(api.getViewManager().setViewByParameters).toBeCalledWith({
-    modifiers: [expect.any(SubstreamOnViewModifier)],
+// Runs the on-action for `view`, applies the modifier it produces (via the real
+// `applyViewModifiers`), and returns the resulting engaged stream.
+const getStreamAfterSubstreamOn = async (
+  view: View,
+  store: CameraManagerStore = createStoreWithSubstreams(),
+): Promise<string | null> => {
+  const api = createCardAPI();
+  vi.mocked(api.getViewManager().getView).mockReturnValue(view);
+  vi.mocked(api.getCameraManager).mockReturnValue(createCameraManager(store));
+
+  await createAction().execute(api);
+
+  const params = vi.mocked(api.getViewManager().setViewByParameters).mock.calls[0]?.[0];
+  applyViewModifiers(view, params?.modifiers);
+  return getStreamCameraID(view);
+};
+
+describe('SubstreamOnAction', () => {
+  it('should advance to the next dependency', async () => {
+    expect(
+      await getStreamAfterSubstreamOn(
+        createView({ view: 'live', camera: 'camera.office' }),
+      ),
+    ).toBe('camera.kitchen');
+  });
+
+  it('should wrap back to the parent camera', async () => {
+    const view = createView({
+      view: 'live',
+      camera: 'camera.office',
+      context: {
+        live: { overrides: new Map([['camera.office', 'camera.kitchen']]) },
+      },
+    });
+
+    expect(await getStreamAfterSubstreamOn(view)).toBe('camera.office');
+  });
+
+  it('should treat a malformed override as the start of the cycle', async () => {
+    const view = createView({
+      view: 'live',
+      camera: 'camera.office',
+      context: {
+        live: { overrides: new Map([['camera.office', 'NOT_A_REAL_CAMERA']]) },
+      },
+    });
+
+    expect(await getStreamAfterSubstreamOn(view)).toBe('camera.office');
+  });
+
+  it('should engage no substream when there are no usable dependencies', async () => {
+    const view = createView({ view: 'live', camera: 'camera.office' });
+
+    expect(await getStreamAfterSubstreamOn(view, createStore())).toBe('camera.office');
+  });
+
+  it('should engage no substream when the view has no camera', async () => {
+    expect(
+      await getStreamAfterSubstreamOn(createView({ view: 'live', camera: null })),
+    ).toBeNull();
+  });
+
+  it('should do nothing without a view', async () => {
+    const api = createCardAPI();
+    vi.mocked(api.getViewManager().getView).mockReturnValue(null);
+
+    await createAction().execute(api);
+
+    expect(api.getViewManager().setViewByParameters).not.toBeCalled();
   });
 });

tests/card-controller/actions/actions/substream-select.test.ts

@@ -1,7 +1,7 @@
 import { expect, it } from 'vitest';
 import { SubstreamSelectAction } from '../../../../src/card-controller/actions/actions/substream-select';
+import { SubstreamViewModifier } from '../../../../src/card-controller/view/modifiers/substream';
 import { createCardAPI } from '../../../test-utils';
-import { SubstreamSelectViewModifier } from '../../../../src/card-controller/view/modifiers/substream-select';
 
 it('should handle live_substream_select action', async () => {
   const api = createCardAPI();
@@ -16,9 +16,7 @@ it('should handle live_substream_select action', async () => {
 
   await action.execute(api);
 
-  expect(api.getViewManager().setViewByParameters).toBeCalledWith(
-    expect.objectContaining({
-      modifiers: expect.arrayContaining([expect.any(SubstreamSelectViewModifier)]),
-    }),
-  );
+  expect(api.getViewManager().setViewByParameters).toBeCalledWith({
+    modifiers: [expect.any(SubstreamViewModifier)],
+  });
 });

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

@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
+import { CallEndAction } from '../../../src/card-controller/actions/actions/call-end';
 import { CallServiceAction } from '../../../src/card-controller/actions/actions/call-service';
+import { CallStartAction } from '../../../src/card-controller/actions/actions/call-start';
 import { CameraSelectAction } from '../../../src/card-controller/actions/actions/camera-select';
 import { CameraUIAction } from '../../../src/card-controller/actions/actions/camera-ui';
 import { CustomAction } from '../../../src/card-controller/actions/actions/custom';
@@ -87,6 +89,8 @@ describe('ActionFactory', () => {
 
   describe('custom actions', () => {
     it.each([
+      [{ advanced_camera_card_action: 'call_end' as const }, CallEndAction],
+      [{ advanced_camera_card_action: 'call_start' as const }, CallStartAction],
       [{ advanced_camera_card_action: 'camera_select' as const }, CameraSelectAction],
       [{ advanced_camera_card_action: 'camera_ui' as const }, CameraUIAction],
       [{ advanced_camera_card_action: 'clip' as const }, ViewAction],