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

src/card-controller/view/modifiers/substream-off.ts

@@ -1,9 +0,0 @@
-import { removeSubstream } from '../../../utils/substream';
-import { View } from '../../../view/view';
-import { ViewModifier } from '../types';
-
-export class SubstreamOffViewModifier implements ViewModifier {
-  public modify(view: View): void {
-    removeSubstream(view);
-  }
-}

src/card-controller/view/modifiers/substream-on.ts

@@ -1,46 +0,0 @@
-import { CameraManager } from '../../../camera-manager/manager';
-import { getStreamCameraID, setSubstream } from '../../../utils/substream';
-import { View } from '../../../view/view';
-import { ViewModifier } from '../types';
-
-interface SubstreamOnViewModifierAPI {
-  getCameraManager(): CameraManager;
-}
-
-export class SubstreamOnViewModifier implements ViewModifier {
-  private _api: SubstreamOnViewModifierAPI;
-
-  constructor(api: SubstreamOnViewModifierAPI) {
-    this._api = api;
-  }
-
-  public modify(view: View): void {
-    if (!view.camera) {
-      return;
-    }
-
-    const dependencies = [
-      ...this._api
-        .getCameraManager()
-        .getStore()
-        .getAllDependentCameras(view.camera, 'substream'),
-    ];
-
-    if (dependencies.length <= 1) {
-      return;
-    }
-
-    const currentOverride = getStreamCameraID(view);
-
-    /* istanbul ignore if: the if path cannot be reached, as there is a
-    view.camera guard at the start of this method and getStreamCameraID will
-    always return non-null as long as camera is present -- @preserve */
-    if (!currentOverride) {
-      return;
-    }
-    const currentIndex = dependencies.indexOf(currentOverride);
-    const newIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % dependencies.length;
-
-    setSubstream(view, dependencies[newIndex]);
-  }
-}

src/card-controller/view/modifiers/substream-select.ts

@@ -1,15 +0,0 @@
-import { setSubstream } from '../../../utils/substream';
-import { View } from '../../../view/view';
-import { ViewModifier } from '../types';
-
-export class SubstreamSelectViewModifier implements ViewModifier {
-  private _substreamID: string;
-
-  constructor(substreamID: string) {
-    this._substreamID = substreamID;
-  }
-
-  public modify(view: View): void {
-    setSubstream(view, this._substreamID);
-  }
-}

src/card-controller/view/modifiers/substream.ts

@@ -0,0 +1,30 @@
+import { View } from '../../../view/view';
+import { ViewModifier } from '../types';
+
+// The single write path for the camera-keyed `live.overrides` map (the read
+// path being `getStreamCameraID` in `view/substream`): sets a camera's
+// substream override, or clears it when `substreamID` is absent so the
+// camera's own stream is used. `cameraID` defaults to the selected camera.
+export class SubstreamViewModifier implements ViewModifier {
+  private _substreamID?: string;
+  private _cameraID?: string;
+
+  constructor(substreamID?: string, cameraID?: string) {
+    this._substreamID = substreamID;
+    this._cameraID = cameraID;
+  }
+
+  public modify(view: View): void {
+    const cameraID = this._cameraID ?? view.camera;
+    if (!cameraID) {
+      return;
+    }
+    if (!this._substreamID) {
+      view.context?.live?.overrides?.delete(cameraID);
+      return;
+    }
+    const overrides = view.context?.live?.overrides ?? new Map<string, string>();
+    overrides.set(cameraID, this._substreamID);
+    view.mergeInContext({ live: { overrides } });
+  }
+}

src/card-controller/view/view-manager.ts

@@ -1,8 +1,8 @@
 import { ViewContext } from 'view';
 import { log } from '../../utils/debug';
-import { getStreamCameraID } from '../../utils/substream';
-import { View } from '../../view/view';
+import { getStreamCameraID } from '../../view/substream';
 import { getViewTargetID } from '../../view/target-id';
+import { View } from '../../view/view';
 import { InitializationAspect } from '../initialization-manager';
 import { CardViewAPI } from '../types';
 import { ViewFactory } from './factory';
@@ -91,12 +91,25 @@ export class ViewManager implements ViewManagerInterface {
 
   setViewByParametersWithExistingQuery = async (
     options?: ViewFactoryOptions,
-  ): Promise<void> =>
+  ): Promise<void> => {
+    // Default the query to the base view's own, so a bare `baseView`
+    // re-executes its query (`_setViewThenModifyAsync` otherwise nulls it).
+    // Only an omitted query falls back; an explicit query -- including `null`
+    // to clear it -- is left as the caller specified.
+    const baseView = options?.baseView ?? this._view;
+    const explicitQuery = options?.params?.query;
     await this._setViewThenModifyAsync(
       this._viewFactory.getViewByParameters.bind(this._viewFactory),
       this._viewQueryExecutor.getExistingQueryModifiers.bind(this._viewQueryExecutor),
-      options,
+      {
+        ...options,
+        params: {
+          ...options?.params,
+          query: explicitQuery !== undefined ? explicitQuery : baseView?.query ?? null,
+        },
+      },
     );
+  };
 
   private _setViewGeneric(
     viewFactoryFunc: (options?: ViewFactoryOptions) => View | null,
@@ -374,11 +387,13 @@ export class ViewManager implements ViewManagerInterface {
 
     this._api.getStyleManager().setExpandedMode();
 
+    const stream = view ? getStreamCameraID(view) : null;
     this._api.getConditionStateManager()?.setState({
       view: view?.view,
       camera: view?.camera ?? undefined,
       displayMode: view?.displayMode ?? undefined,
       targetID: view ? getViewTargetID(view) ?? undefined : undefined,
+      substreamID: stream && stream !== view?.camera ? stream : undefined,
     });
 
     this._api.getCardElementManager().update();