From e832dec28d96a081d3525d20c0fa60ac89e31670 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gre=CC=81goire=20Parant?= <gregoire@workadventu.re>
Date: Thu, 2 Apr 2026 15:18:07 +0200
Subject: [PATCH] fix: robust Document Picture-in-Picture detection and
 deferred visibility refresh
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# Our usage
WorkAdventure opens Document PiP with documentPictureInPicture.requestWindow(), then appends a root div (meeting layout + <video> elements) to pipWindow.document.body. The enter listener in the SDK can run in the same turn before that append completes. Deferring the visibility refresh aligns with WorkAdventure’s flow: append the subtree into the PiP document, then update app state—so remote tracks attached to those <video> elements are evaluated only once they actually live under the PiP document.

# Issue
For Document Picture-in-Picture (documentPictureInPicture), the enter event can be delivered before the host application has finished appending its DOM (including <video> elements) into documentPictureInPicture.window.document.

In that case, onEnterPiP ran isElementInPiP immediately, while pipWin.document.contains(element) was still false, so the track was incorrectly treated as not in PiP and adaptive-stream visibility could be wrong.

# Change
In private onEnterPiP, defer the isElementInPiP update and handleVisibilityChanged to the next microtask and requestAnimationFrame, so embedder code can attach the subtree first and the check becomes reliable.
---
 .changeset/busy-icons-notice.md    |  5 +++++
 src/room/track/RemoteVideoTrack.ts | 10 ++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/busy-icons-notice.md

diff --git a/.changeset/busy-icons-notice.md b/.changeset/busy-icons-notice.md
new file mode 100644
index 0000000000..a50b1c9b5a
--- /dev/null
+++ b/.changeset/busy-icons-notice.md
@@ -0,0 +1,5 @@
+---
+'livekit-client': patch
+---
+
+Defer `onEnterPiP` visibility update until after the next microtask and animation frame so Document Picture-in-Picture embedders can append DOM into the PiP window before `isElementInPiP` runs.
diff --git a/src/room/track/RemoteVideoTrack.ts b/src/room/track/RemoteVideoTrack.ts
index b3d585db04..d7d1c9436f 100644
--- a/src/room/track/RemoteVideoTrack.ts
+++ b/src/room/track/RemoteVideoTrack.ts
@@ -384,8 +384,14 @@ class HTMLElementInfo implements ElementInfo {
 
   private onEnterPiP = () => {
     window.documentPictureInPicture?.window?.addEventListener('pagehide', this.onLeavePiP);
-    this.isPiP = isElementInPiP(this.element);
-    this.handleVisibilityChanged?.();
+    // Document PiP: the browser may fire 'enter' before the app has appended its subtree into
+    // documentPictureInPicture.window. Defer so pipWin.document.contains(video) is reliable.
+    queueMicrotask(() => {
+      requestAnimationFrame(() => {
+        this.isPiP = isElementInPiP(this.element);
+        this.handleVisibilityChanged?.();
+      });
+    });
   };
 
   private onLeavePiP = () => {