createHidden

spec.bs

@@ -108,6 +108,7 @@ partial interface Window {
 interface DocumentPictureInPicture : EventTarget {
   [NewObject] Promise<Window> requestWindow(
     optional DocumentPictureInPictureOptions options = {});
+  void show(Window window);
   readonly attribute Window window;
   attribute EventHandler onenter;
 };
@@ -117,6 +118,7 @@ dictionary DocumentPictureInPictureOptions {
   [EnforceRange] unsigned long long height = 0;
   boolean disallowReturnToOpener = false;
   boolean preferInitialWindowPlacement = false;
+  boolean createHidden = false;
 };
 
 [Exposed=Window, SecureContext]
@@ -231,6 +233,27 @@ previous position or size of any previously closed |pip traversable| window.
     and is <code>true</code>, the user agent should not display UI affordances
     on the picture-in-picture window that allow the user to return to the
     opener window.
+15. If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] exists
+    and is <code>true</code>, the user agent should not show the picture-in-picture
+    window immediately.  Instead, it will wait until either:
+    1. {{DocumentPictureInPicture/show()}} is called, with the corresponding
+        window as its argument.
+    2. The UA shows the window automatically after some time has elapsed.
+    Calls to {{DocumentPictureInPicture/show()}} after the picture-in-picture window
+    is shown, or after it is closed, will do nothing.  A call that provides a window argument
+    that was not returned by {{DocumentPictureInPicture/requestWindow()}} will throw a
+    "{{NotAllowedError}}" {{DOMException}}.
+    If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] does not exist
+    or is not true, then the picture-in-picture window will be shown immediately after
+    it is created.
+<p class="note">
+The intention to automatically show the window after a timeout is to allow the UA to
+prevent a site from waiting indefinitely to show a window.  For example, a UA might
+choose to use the remaining lifetime of the transient activation that allowed the call to
+{{DocumentPictureInPicture/requestWindow()}} to succeed, so that the site cannot show
+the window any later than it could by simply waiting to open the picture-in-picture
+window.  The UA is free to choose any timeout, including "forever".
+</p>
 
 <p class="note">
 For both video and document picture-in-picture, user agents often display a
@@ -786,6 +809,18 @@ await documentPictureInPicture.requestWindow({
 });
 </pre>
 
+## Defer showing the picture-in-picture window ## {#example-create-hidden}
+
+If the site would like to configure the picture-in-picture window contents
+before showing the window, it may use the
+{{DocumentPictureInPictureOptions/createHidden}} option to do so.
+
+<pre class="lang-javascript">
+let pip = await documentPictureInPicture.requestWindow({ createHidden: true });
+// Add things to pip.document here!
+documentPictureInPicture.show(pip);
+</pre>
+
 # Acknowledgments # {#acknowledgments}
 
 Many thanks to Frank Liberato, Mark Foltz, Klaus Weidner, François Beaufort,