Merge branch 'master' into worktree-mosaic-library

# Conflicts:
#	docs/traceability.md

src/lib/components/player/VideoPlayer.svelte

@@ -120,10 +120,12 @@
    * Keep native's picture-in-picture state in step with the `<video>` element.
    *
    * PiP is driven by the Activity, and it only ever knew about the native
-   * ExoPlayer surface — a path behind `experimentalNativeVideo`, which defaults
-   * to off. So in the shipping configuration nothing satisfied its "is a video
-   * playing?" check and the PiP button did nothing at all. Reporting the element
-   * gives it a surface it can shrink into. (UR-041, DR-160)
+   * ExoPlayer surface — a path behind `experimentalNativeVideo`, which at the
+   * time defaulted to off. So in the then-shipping configuration nothing
+   * satisfied its "is a video playing?" check and the PiP button did nothing at
+   * all. Reporting the element gives it a surface it can shrink into, and still
+   * has to: the flag defaults to on now (DR-161) but a user who turns it off is
+   * back on the element. (UR-041, DR-160, DR-161)
    */
   function reportPipVideoState() {
     if (!useHtml5Element || !videoElement) {

src/lib/stores/nativeVideo.ts

@@ -73,7 +73,11 @@ function createExperimentalNativeVideoStore() {
   };
 }
 
-/** User opt-in for the native Android video path. Default off. */
+/**
+ * User opt-out for the native Android video path. **Defaults to on** since
+ * DR-161 — see `load()`. The name still says "experimental" because the flag
+ * remains a suppressor of Rust's backend choice, not a promoter of it.
+ */
 export const experimentalNativeVideo = createExperimentalNativeVideoStore();
 
 function createNativeVideoActiveStore() {

src/lib/utils/pictureInPicture.ts

@@ -89,14 +89,18 @@ export function setAutoEnterEnabled(enabled: boolean): void {
 /**
  * Tell native that a WebView `<video>` is (or is no longer) the playback surface.
  *
- * This is what makes PiP work at all in the shipping configuration. The native
- * side only ever knew about the ExoPlayer surface, and that path is behind
- * `experimentalNativeVideo`, which defaults to off — so `canEnterPip` was always
+ * This is what makes PiP work on the HTML5 path. The native side only ever knew
+ * about the ExoPlayer surface, and that path is behind `experimentalNativeVideo`,
+ * which defaulted to off when this was written — so `canEnterPip` was always
  * false and pressing the button did nothing. Reporting the element's state gives
  * native a surface it can legitimately shrink into, plus the intrinsic size it
  * needs for the PiP window's aspect ratio and the play state for its play/pause
  * action.
  *
+ * The flag defaults to **on** now (DR-161), so Android normally shrinks the real
+ * ExoPlayer surface instead; this remains the path for Linux and for anyone who
+ * turned the flag off.
+ *
  * Pass `active: false` when the element goes away, or PiP would be offered over a
  * video that is no longer there.
  *