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/view/modifiers/substream-off.test.ts

@@ -1,20 +0,0 @@
-import { expect, it } from 'vitest';
-import { createView } from '../../../test-utils';
-import { SubstreamOffViewModifier } from '../../../../src/card-controller/view/modifiers/substream-off';
-import { hasSubstream, setSubstream } from '../../../../src/utils/substream';
-
-it('should turn off substream', () => {
-  const view = createView({
-    view: 'live',
-    camera: 'camera',
-    displayMode: 'grid',
-  });
-
-  setSubstream(view, 'substream');
-  expect(hasSubstream(view)).toBe(true);
-
-  const modifier = new SubstreamOffViewModifier();
-  modifier.modify(view);
-
-  expect(hasSubstream(view)).toBe(false);
-});

tests/card-controller/view/modifiers/substream-on.test.ts

@@ -1,119 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { CardController } from '../../../../src/card-controller/controller';
-import { SubstreamOnViewModifier } from '../../../../src/card-controller/view/modifiers/substream-on';
-import { RawAdvancedCameraCardConfig } from '../../../../src/config/types';
-import {
-  getStreamCameraID,
-  hasSubstream,
-  setSubstream,
-} from '../../../../src/utils/substream';
-import {
-  createCameraConfig,
-  createCameraManager,
-  createCapabilities,
-  createCardAPI,
-  createConfig,
-  createStore,
-  createView,
-} from '../../../test-utils';
-
-const createAPIWithSubstreams = (
-  config?: RawAdvancedCameraCardConfig,
-): CardController => {
-  const api = createCardAPI();
-  const store = createStore([
-    {
-      cameraID: 'camera.office',
-      capabilities: createCapabilities({
-        live: true,
-        substream: true,
-      }),
-      config: createCameraConfig({
-        dependencies: {
-          all_cameras: true,
-        },
-      }),
-    },
-    {
-      cameraID: 'camera.kitchen',
-      capabilities: createCapabilities({
-        substream: true,
-      }),
-    },
-  ]);
-  vi.mocked(api.getCameraManager).mockReturnValue(createCameraManager(store));
-  vi.mocked(api.getConfigManager().getConfig).mockReturnValue(createConfig(config));
-  return api;
-};
-
-describe('should turn on substream', () => {
-  it('substream available', () => {
-    const view = createView({
-      view: 'live',
-      camera: 'camera.office',
-    });
-
-    expect(hasSubstream(view)).toBe(false);
-
-    const api = createAPIWithSubstreams();
-
-    const modifier = new SubstreamOnViewModifier(api);
-    modifier.modify(view);
-
-    expect(hasSubstream(view)).toBe(true);
-    expect(getStreamCameraID(view)).toBe('camera.kitchen');
-
-    modifier.modify(view);
-
-    expect(hasSubstream(view)).toBe(false);
-    expect(getStreamCameraID(view)).toBe('camera.office');
-  });
-
-  it('malformed substream', () => {
-    const view = createView({
-      view: 'live',
-      camera: 'camera.office',
-    });
-
-    const api = createAPIWithSubstreams();
-
-    setSubstream(view, 'NOT_A_REAL_CAMERA');
-
-    const modifier = new SubstreamOnViewModifier(api);
-    modifier.modify(view);
-
-    expect(hasSubstream(view)).toBe(false);
-    expect(getStreamCameraID(view)).toBe('camera.office');
-  });
-
-  it('substream unavailable', () => {
-    const view = createView({
-      view: 'live',
-      camera: 'camera.office',
-    });
-
-    expect(hasSubstream(view)).toBe(false);
-
-    const api = createCardAPI();
-    const cameraManager = createCameraManager(createStore([]));
-    vi.mocked(api.getCameraManager).mockReturnValue(cameraManager);
-
-    const modifier = new SubstreamOnViewModifier(api);
-    modifier.modify(view);
-
-    expect(hasSubstream(view)).toBe(false);
-  });
-
-  it('without camera', () => {
-    const view = createView({
-      camera: null,
-      view: 'live',
-    });
-
-    const api = createCardAPI();
-    const modifier = new SubstreamOnViewModifier(api);
-    modifier.modify(view);
-
-    expect(hasSubstream(view)).toBe(false);
-  });
-});

tests/card-controller/view/modifiers/substream-select.test.ts

@@ -1,19 +0,0 @@
-import { expect, it } from 'vitest';
-import { SubstreamSelectViewModifier } from '../../../../src/card-controller/view/modifiers/substream-select';
-import { getStreamCameraID, hasSubstream } from '../../../../src/utils/substream';
-import { createView } from '../../../test-utils';
-
-it('should select substream', () => {
-  const view = createView({
-    view: 'live',
-    camera: 'camera.office',
-  });
-
-  expect(hasSubstream(view)).toBe(false);
-
-  const modifier = new SubstreamSelectViewModifier('substream');
-  modifier.modify(view);
-
-  expect(hasSubstream(view)).toBe(true);
-  expect(getStreamCameraID(view)).toBe('substream');
-});

tests/card-controller/view/modifiers/substream.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { SubstreamViewModifier } from '../../../../src/card-controller/view/modifiers/substream';
+import { createView } from '../../../test-utils';
+
+describe('SubstreamViewModifier', () => {
+  it('should write the override for the selected camera', () => {
+    const view = createView({ camera: 'camera' });
+
+    new SubstreamViewModifier('substream').modify(view);
+
+    expect(view.context?.live?.overrides?.get('camera')).toBe('substream');
+  });
+
+  it('should clear the selected camera override when no substream is given', () => {
+    const view = createView({
+      camera: 'camera',
+      context: { live: { overrides: new Map([['camera', 'substream']]) } },
+    });
+
+    new SubstreamViewModifier().modify(view);
+
+    expect(view.context?.live?.overrides?.get('camera')).toBeUndefined();
+  });
+
+  it('should write the override for an explicit camera', () => {
+    const view = createView({
+      camera: 'camera',
+      context: { live: { overrides: new Map([['camera', 'substream']]) } },
+    });
+
+    new SubstreamViewModifier('other-substream', 'other-camera').modify(view);
+
+    expect(view.context?.live?.overrides?.get('other-camera')).toBe('other-substream');
+    expect(view.context?.live?.overrides?.get('camera')).toBe('substream');
+  });
+
+  it('should clear the override for an explicit camera', () => {
+    const view = createView({
+      camera: 'camera',
+      context: { live: { overrides: new Map([['other-camera', 'other-substream']]) } },
+    });
+
+    new SubstreamViewModifier(undefined, 'other-camera').modify(view);
+
+    expect(view.context?.live?.overrides?.get('other-camera')).toBeUndefined();
+  });
+
+  it('should no-op for a view without a camera', () => {
+    const view = createView({ camera: null });
+
+    new SubstreamViewModifier('substream').modify(view);
+
+    expect(view.context).toBeNull();
+  });
+});

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

@@ -51,10 +51,29 @@ describe('should act correctly when view is set', () => {
       camera: 'camera',
       displayMode: 'grid',
       targetID: 'camera',
+      substreamID: undefined,
     });
     expect(api.getCardElementManager().update).toBeCalled();
   });
 
+  it('should set the engaged substream in condition state', () => {
+    const view = createView({
+      view: 'live',
+      camera: 'camera',
+      context: { live: { overrides: new Map([['camera', 'substream']]) } },
+    });
+
+    const factory = mock<ViewFactory>();
+    factory.getViewDefault.mockReturnValue(view);
+
+    const api = createInitializedCardAPI();
+    new ViewManager(api, { viewFactory: factory }).setViewDefault();
+
+    expect(api.getConditionStateManager()?.setState).toBeCalledWith(
+      expect.objectContaining({ substreamID: 'substream' }),
+    );
+  });
+
   it('should set view with minor changes without scroll', () => {
     const view_1 = createView({
       view: 'live',
@@ -305,6 +324,48 @@ it('should set view by parameters with existing query', async () => {
   expect(manager.getView()?.camera).toBe('camera');
 });
 
+it('should set view by parameters with an explicitly provided existing query', async () => {
+  const viewFactory = mock<ViewFactory>();
+  viewFactory.getViewByParameters.mockReturnValue(createView());
+
+  const viewQueryExecutor = mock<ViewQueryExecutor>();
+  viewQueryExecutor.getExistingQueryModifiers.mockResolvedValue([]);
+
+  const manager = new ViewManager(createInitializedCardAPI(), {
+    viewFactory: viewFactory,
+    viewQueryExecutor: viewQueryExecutor,
+  });
+
+  const query = new UnifiedQuery();
+  await manager.setViewByParametersWithExistingQuery({ params: { query } });
+
+  // An explicitly-passed query is used as-is rather than the base view's.
+  expect(viewFactory.getViewByParameters).toBeCalledWith(
+    expect.objectContaining({ params: expect.objectContaining({ query }) }),
+  );
+});
+
+it('should clear the query when an explicit null query is passed', async () => {
+  const viewFactory = mock<ViewFactory>();
+  viewFactory.getViewByParameters.mockReturnValue(createView());
+
+  const viewQueryExecutor = mock<ViewQueryExecutor>();
+  viewQueryExecutor.getExistingQueryModifiers.mockResolvedValue([]);
+
+  const manager = new ViewManager(createInitializedCardAPI(), {
+    viewFactory: viewFactory,
+    viewQueryExecutor: viewQueryExecutor,
+  });
+
+  await manager.setViewByParametersWithExistingQuery({ params: { query: null } });
+
+  // An explicit `null` is respected (clears the query), not overridden by the
+  // base view's query.
+  expect(viewFactory.getViewByParameters).toBeCalledWith(
+    expect.objectContaining({ params: expect.objectContaining({ query: null }) }),
+  );
+});
+
 describe('should handle exceptions', () => {
   it('should retry with failSafe when no existing view in sync calls', () => {
     const viewFactory = mock<ViewFactory>();