Overhaul exit Picture-in-Picture algorithm by theIDinside · Pull Request #260 · w3c/picture-in-picture

theIDinside · 2026-06-16T12:27:29Z

Rework the exit Picture-in-Picture algorithm to mirror the requestPictureInPicture() overhaul (#245):

run the work on the document's picture-in-picture parallel queue
perform DOM mutation, promise resolution inside a queued global task
keep the window close in parallel since closing may be asynchronous/disjoint across implementations.

The algorithm now takes |doc| and a promise-or-null |p| as input arguments.

First commit does not deal with:

Fixing "unloading document steps". Unfortunately it can not re-use the algorithm, because it runs on the event loop, it needs to mutate DOM stuff and then enqueue work on the parallel queue to close the window.
disablePictureInPicture must call the new algorithm by enqueing steps, providing input args
when fullscreen flag is set, it must call the new algorithm by enqueing steps, providing input args

Addresses #252

Rework the exit Picture-in-Picture algorithm to mirror the requestPictureInPicture() overhaul (w3c#245): - run the work on the document's picture-in-picture parallel queue - perform DOM mutation, promise resolution inside a queued global task - keep the window close in parallel since closing may be asynchronous/disjoint across implementations. The algorithm now takes |doc| and a promise-or-null |p| as input arguments. This commit does not deal with: - Fixing "unloading document steps". Unfortunately it can not re-use the algorithm, because it runs on the event loop, it needs to mutate DOM stuff and then enqueue work on the parallel queue to close the window. - disablePictureInPicture must call the new algorithm by enqueing steps, providing input args - when fullscreen flag is set, it must call the new algorithm by enqueing steps, providing input args

theIDinside · 2026-06-16T12:28:27Z

Hmm can the spec not be formatted using specfmt?

theIDinside · 2026-06-16T12:39:22Z

@chrisn mentioned in #252 that we should update the "unloading steps" to call the exit algorithm, but unfortunately this algorithm turned out to be trickier to actually formulate than I had anticipated (though I think it's in a good/better state now).

I don't know if it's possible to actually call it from the unloading steps, because we also need to run the "window closing" steps, which just like for requestPictureInPicture is one of those thing that have to run on the queue and take forever, so I was thinking for the unloading steps, we would have to just change the "normal" order (the order when user says doc.exitPictureInPicture() or when being called from with el2.requestPictureInPicture()), from

"close window"
"Queue task to mutate DOM stuff"
To the reverse,
"mutate DOM stuff" (we are on the event loop so probably no task needed)
Enqueue steps to run on the parallel queue to close the window. (this can take forever. Needs to run on the queue)

I can add this change in a follow-up commit in this PR if that's preferable from a reviewer perspective

cc: @chrisn || @marcoscaceres

marcoscaceres · 2026-06-18T10:16:31Z

+    1. If |doc|'s [=Picture-in-Picture element=] is `null`:
+        1. [=/Resolve=] |p| if |p| is not `null`.
+        2. Return.
+    2. Let |element| be |doc|'s [=Picture-in-Picture element=].


Can element be null?

Copilot

Pull request overview

Reworks the spec’s “exit Picture-in-Picture algorithm” to follow the same concurrency model as the recent requestPictureInPicture() overhaul, by moving work onto the document’s picture-in-picture parallel queue and deferring DOM mutation/promise resolution to a queued global task.

Changes:

Updates the exit algorithm to take |doc| and promise-or-null |p|, assert parallel-queue execution, and perform DOM mutation/promise resolution in a queued global task.
Adjusts requestPictureInPicture() to invoke the new exit algorithm (with null promise) from the parallel-queue steps before enqueueing its own global task.
Refactors Document.exitPictureInPicture() to enqueue work onto the picture-in-picture parallel queue and resolve via a global task.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+2. Assert that these steps are running on the [=picture-in-picture parallel queue=].
+
+    Note: This algorithm is called from {{exitPictureInPicture}} and {{requestPictureInPicture}}.
+    The document unloading steps have to be structured differently due to running on the event loop
+    and can therefore not call this algorithm.


Demo page for testing exit PiP behavior across various destruction scenarios (window close, iframe removal, document navigation) relevant to w3c/picture-in-picture#260. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

marcoscaceres · 2026-06-18T11:02:02Z

The question of unloading might be one better handled through the document becoming non-fully active... if the document becomes not fully active, exit full screen is the observable behavior on Chrome and WebKit (PiP closes).

Could we use that that instead of the unloading steps? @chrisn and I tested this using a little demo page. https://marcoscaceres.github.io/playground/pip-test/

chrisn · 2026-06-18T11:06:37Z

Web Platform Design Principles has some detail on non-fully active: https://www.w3.org/TR/design-principles/#handle-non-fully-active-documents. But I'm not sure where we can hook into on the transition from fully active to non-fully active.

chrisn · 2026-06-18T11:20:59Z

I don't know if it's possible to actually call it from the unloading steps, because we also need to run the "window closing" steps, which just like for requestPictureInPicture is one of those thing that have to run on the queue and take forever, so I was thinking for the unloading steps, we would have to just change the "normal" order (the order when user says doc.exitPictureInPicture() or when being called from with el2.requestPictureInPicture()), from

"close window"

"Queue task to mutate DOM stuff"
To the reverse,

"mutate DOM stuff" (we are on the event loop so probably no task needed)

Enqueue steps to run on the parallel queue to close the window. (this can take forever. Needs to run on the queue)

I can add this change in a follow-up commit in this PR if that's preferable from a reviewer perspective

Makes sense to me, and adding to this PR sounds fine.

marcoscaceres · 2026-06-18T14:47:55Z

Following up on @chrisn's point about handling this through the document becoming non-fully active, and the TAG Design Principles §2.13 he linked.

I think this PR (and the spec as it stands) has a gap worth closing as part of the exit overhaul: nothing defines what happens to an active Picture-in-Picture session when its document stops being fully active, that is, when the containing <iframe> is removed or navigated, on top-level navigation, or when the document enters bfcache. The reworked algorithm only guards on pictureInPictureElement being null; it never references "fully active". Deferring the unloading-steps integration from #252 is fine, but I'd like us to agree on the model now so the deferred work has a target.

On @chrisn's open question (where can we hook into the transition from fully active to non-fully active?): there isn't a single event for it, but Fullscreen already solves the same problem and is a good precedent. It hooks the two concrete algorithms that cause non-fully-active, namely the DOM removing steps (element or subtree removed) and the HTML unloading document cleanup steps (document unloaded or navigated), and it also fails fast at call time if the document isn't fully active.

Mapping §2.13 onto exit PiP, I'd suggest we define three things:

At call time: if the relevant document is not fully active, exitPictureInPicture() (and the exit-on-replace path inside requestPictureInPicture()) should fail immediately. §2.13 suggests InvalidStateError. Today we only check pictureInPictureElement.
When the queued global task runs: an explicit "if the document is not fully active, stop with no observable effects" check, rather than leaning on the pictureInPictureElement is null proxy (§2.13 also says not to rely on garbage collection for this).
On the transition itself: define the teardown by hooking the removing steps and the unloading document cleanup steps (the Fullscreen pattern), and spell out what happens to pictureInPictureElement, whether leavepictureinpicture fires, and how any in-flight promise settles. That is all currently left to the implementation.

One thing for the group on (3): when a document becomes non-fully active mid-exit, should the returned promise reject with AbortError (§2.13's general rule for aborted async operations), or resolve, since the requested end state ("no longer in PiP") is arguably already satisfied by the teardown? I lean toward making it definite and observable either way; I don't think the current text forces a single outcome.

I put together a small test bench for these transitions (remove iframe, navigate iframe, top-level navigation, bfcache restore, and a parent holding a PictureInPictureWindow across destruction): https://marcoscaceres.github.io/playground/pip-test/. In my testing the behaviour across these paths isn't consistent today, which is the main reason I'd rather we define the model than leave it implementation-defined. It's set up so you can check your own engine.

Minimal standalone repro for exit-PiP behaviour when a document becomes non-fully active via bfcache. Linked from w3c/picture-in-picture#260 and an upcoming WebKit bug. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

marcoscaceres · 2026-06-18T17:04:31Z

WebKit tracking bug https://bugs.webkit.org/show_bug.cgi?id=317409

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>

theIDinside · 2026-06-29T13:05:11Z

The question of unloading might be one better handled through the document becoming non-fully active... if the document becomes not fully active, exit full screen is the observable behavior on Chrome and WebKit (PiP closes).

Could we use that that instead of the unloading steps? @chrisn and I tested this using a little demo page. https://marcoscaceres.github.io/playground/pip-test/

This is fantastic. Could you maybe add an example from #261 - basically a button that both does getDisplayMedia + requestPip. Effectively, it may end up being the case that, that should fail (though it doesn't on safari and chrome), given that these two requests are spec'ed on consuming and being gated by user activation.

theIDinside · 2026-06-29T16:02:53Z

Following up on @chrisn's point about handling this through the document becoming non-fully active, and the TAG Design Principles §2.13 he linked.

I think this PR (and the spec as it stands) has a gap worth closing as part of the exit overhaul: nothing defines what happens to an active Picture-in-Picture session when its document stops being fully active, that is, when the containing <iframe> is removed or navigated, on top-level navigation, or when the document enters bfcache.
...
On @chrisn's open question (where can we hook into the transition from fully active to non-fully active?): there isn't a single event for it, but Fullscreen already solves the same problem and is a good precedent. It hooks the two concrete algorithms that cause non-fully-active, namely the DOM removing steps (element or subtree removed) and the HTML unloading document cleanup steps (document unloaded or navigated), and it also fails fast at call time if the document isn't fully active.

So can we really hook into DOM removing steps (element or subtree removed)? We have tests historically that rely on unbound elements (and also being able to remove the actual element being PIP'ed). And in the case of an iframe; would the removal of the iframe eventually also mean that the HTML unloading document cleanup steps run? (thus having our "not fully active"-case be caught fully by the unloading steps?)

Mapping §2.13 onto exit PiP, I'd suggest we define three things:

1. At call time: if the relevant document is not fully active, `exitPictureInPicture()` (and the exit-on-replace path inside `requestPictureInPicture()`) should fail immediately. §2.13 suggests `InvalidStateError`. Today we only check `pictureInPictureElement`.

2. When the queued global task runs: an explicit "if the document is not fully active, stop with no observable effects" check, rather than leaning on the `pictureInPictureElement is null` proxy (§2.13 also says not to rely on garbage collection for this).

Adding these checks to exit and has filed an issue for the requestPIP part. And let's follow the recommendations; InvalidStateError for sync/pre-checks. Currently I've made the async-part resolve with undefined as per the tear down of state being satisfied, even if being different from recommendations I think we can argue that striving for simplicity also is a goal. But no hard requirement on my part.

…lag being set for a pip element.

theIDinside · 2026-06-29T17:10:08Z

Added the unloading steps in the last commit. I think that at least partially addresses most of your concerns @marcoscaceres ?

beaufortfrancois · 2026-07-01T07:50:00Z

+1. If [=this=]'s [=Picture-in-Picture element=] is `null` or [=this=] is not [=fully active=],
+    return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.


Nit:

Suggested change

1. If [=this=]'s [=Picture-in-Picture element=] is `null` or [=this=] is not [=fully active=],

return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.

1. If [=this=] is not [=fully active=],

return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.

2. If [=this=]'s [=Picture-in-Picture element=] is `null`,

return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.

Can we also have web-platform tests along this PR to help figuring out what needs to be fixed in different implementations?

I actually wrote a postMessage web platform tests specifically for this "not fully active" scenario, and it involves actually testing that something "did not happen" - and we wouldn't be able to test this here, I think. This promise will never get resolve or rejected, I believe. It should just be doing the null check.

beaufortfrancois · 2026-07-01T08:00:23Z

+4. [=Queue a global task=] on the [=media element event task source=] given |global|, to perform the
+    following steps:
+    1. If |doc| is not [=fully active=] or |doc|'s [=Picture-in-Picture element=] is `null`:
+        1. If |p| is not `null`, [=/resolve=] |p| with undefined.


I naively thought we should reject instead of resolve promise. Why not in this case?

Agree... this should reject with an InvalidStateError.

Also, these should happen both before [=Queue a global task=] and recheck after [=Queue a global task=].

See https://www.w3.org/TR/design-principles/#support-non-fully-active

Left a comment in the main thread, but I think there's an argument for that we should not be doing this check at all.

marcoscaceres · 2026-07-02T10:12:02Z

-4. Unset {{pictureInPictureElement}}.
-5. Remove one <a>item</a> matching <a>relevant settings object</a>'s <a>origin</a> from
-    <a>initiators of active Picture-in-Picture sessions</a>.
+When the <dfn>exit Picture-in-Picture algorithm</dfn> is invoked given |doc|,  and nullable


Suggested change

When the <dfn>exit Picture-in-Picture algorithm</dfn> is invoked given |doc|, and nullable

When the <dfn>exit Picture-in-Picture algorithm</dfn> is invoked given a {{Document}} |doc|, and nullable

marcoscaceres · 2026-07-02T10:14:43Z

+4. [=Queue a global task=] on the [=media element event task source=] given |global|, to perform the
+    following steps:
+    1. If |doc| is not [=fully active=] or |doc|'s [=Picture-in-Picture element=] is `null`:
+        1. If |p| is not `null`, [=/resolve=] |p| with undefined.


Agree... this should reject with an InvalidStateError.

marcoscaceres · 2026-07-02T10:18:00Z

+4. [=Queue a global task=] on the [=media element event task source=] given |global|, to perform the
+    following steps:
+    1. If |doc| is not [=fully active=] or |doc|'s [=Picture-in-Picture element=] is `null`:
+        1. If |p| is not `null`, [=/resolve=] |p| with undefined.


Also, these should happen both before [=Queue a global task=] and recheck after [=Queue a global task=].

See https://www.w3.org/TR/design-principles/#support-non-fully-active

marcoscaceres · 2026-07-02T10:18:59Z

+        2. Return.
+    2. Let |element| be |doc|'s [=Picture-in-Picture element=].
+    3. Set |doc|'s [=Picture-in-Picture element=] to `null`.
+    4. <a>Fire an event</a> named {{leavepictureinpicture}} using {{PictureInPictureEvent}} at the


[=Queue a task=] to perform the follow steps?

marcoscaceres · 2026-07-02T10:19:45Z

-As one of the <a>unloading document cleanup steps</a>, run the <a>exit
-Picture-in-Picture algorithm</a>.
+### Unloading steps ### {#unloading-steps}
+As one of the <a>unloading document cleanup steps</a> given |doc| run the following steps:


Suggested change

As one of the <a>unloading document cleanup steps</a> given |doc| run the following steps:

As one of the <a>unloading document cleanup steps</a> given {{Document}} |doc| run the following steps:

marcoscaceres · 2026-07-02T10:21:34Z


-It is RECOMMENDED to run the <a>exit Picture-in-Picture algorithm</a> when the
-{{pictureInPictureElement}} <a>fullscreen flag</a> is set.
+It is RECOMMENDED that when a [=Picture-in-Picture element=]'s <a>fullscreen flag</a> is set, the


I think we talked about this, so apologies... why is the RECOMMENDED instead of MUST?

Can we add a note here explaining why it's not a MUST requirement?

theIDinside · 2026-07-10T11:31:00Z

So I just realized something @marcoscaceres | @chrisn | @beaufortfrancois while working on other stuff in gecko, I was reminded of the idea of runnable task. We (Firefox) had a bug in postMessage, which posted a message from inside an unload handler, which would be seen by a "new" document upon reload. We don't have the concept of queuing a task like blink or webkit does as you may know, but effectively doing such a check was the fix (if document is not fully active, don't run the work posted to our internal implementation of dispatched work)

We queue tasks to run from the PIP parallel queue. And per spec these should not run if the document is not fully active which means that our "is fully active" is entirely superfluous. Because the task should not be started if the document itself is no longer active.

chrisn · 2026-07-16T10:30:55Z


-It is RECOMMENDED to run the <a>exit Picture-in-Picture algorithm</a> when the
-{{pictureInPictureElement}} <a>fullscreen flag</a> is set.
+It is RECOMMENDED that when a [=Picture-in-Picture element=]'s <a>fullscreen flag</a> is set, the


Need to invoke this from step 3 in https://fullscreen.spec.whatwg.org/#fullscreen-an-element

See also #191. But let's work on that in a follow up PR.

Right, yeah... it's basically transitioning in/out of fullscreen otherwise PiP,

marcoscaceres · 2026-07-16T10:55:55Z


-As one of the <a>unloading document cleanup steps</a>, run the <a>exit
-Picture-in-Picture algorithm</a>.
+### Unloading steps ### {#unloading-steps}


Talking to @chrisn, would be great to just move these over to HTML.

chrisn · 2026-07-16T11:09:09Z

-As one of the <a>unloading document cleanup steps</a>, run the <a>exit
-Picture-in-Picture algorithm</a>.
+### Unloading steps ### {#unloading-steps}
+As one of the <a>unloading document cleanup steps</a> given |doc| run the following steps:


Suggested change

As one of the <a>unloading document cleanup steps</a> given |doc| run the following steps:

The <dfn export>picture in picture unloading steps</dfn>, given {{Document}} |doc| are:

Exported so we can call this from HTML

See whatwg/html#12689 for the corresponding HTML change.

marcoscaceres · 2026-07-16T11:18:19Z

@theIDinside added what you requested above to https://marcoscaceres.github.io/playground/pip-test/

Fix specfmt-caused formatting errors

4fb83af

theIDinside commented Jun 16, 2026

View reviewed changes

Comment thread index.bs Outdated

marcoscaceres reviewed Jun 18, 2026

View reviewed changes

marcoscaceres requested a review from Copilot June 18, 2026 10:22

Copilot started reviewing on behalf of marcoscaceres June 18, 2026 10:23 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

theIDinside and others added 6 commits June 25, 2026 13:13

Change promise-or-null till nullable {{Promise}}

89b43f2

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>

Change use of [=/Resolve]

a63d659

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>

Use if-then wording

39a9130

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>

Change [=/Resolve] wording

846790f

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>

Remove note, use bikeshed syntax for asserts

bf7bba9

Better wording for exitPictureInPicture steps

00918f8

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>

theIDinside mentioned this pull request Jun 29, 2026

requestPictureInPicture needs to consider fully active documents #262

Open

theIDinside added 2 commits June 29, 2026 18:18

Add non-fully active document checks & enqueue steps for fullscreen f…

5330f78

…lag being set for a pip element.

Unloading steps

81e4c56

beaufortfrancois requested changes Jul 1, 2026

View reviewed changes

marcoscaceres requested changes Jul 2, 2026

View reviewed changes

chrisn reviewed Jul 16, 2026

View reviewed changes

marcoscaceres reviewed Jul 16, 2026

View reviewed changes

chrisn reviewed Jul 16, 2026

View reviewed changes

chrisn mentioned this pull request Jul 16, 2026

Add Picture in Picture to unloading document cleanup steps whatwg/html#12689

Draft

6 tasks

		1. If [=this=]'s [=Picture-in-Picture element=] is `null` or [=this=] is not [=fully active=],
		return [=a promise rejected with=] {{InvalidStateError}} {{DOMException}}.

	When the <dfn>exit Picture-in-Picture algorithm</dfn> is invoked given \|doc\|, and nullable
	When the <dfn>exit Picture-in-Picture algorithm</dfn> is invoked given a {{Document}} \|doc\|, and nullable

	As one of the <a>unloading document cleanup steps</a> given \|doc\| run the following steps:
	As one of the <a>unloading document cleanup steps</a> given {{Document}} \|doc\| run the following steps:

	As one of the <a>unloading document cleanup steps</a> given \|doc\| run the following steps:
	The <dfn export>picture in picture unloading steps</dfn>, given {{Document}} \|doc\| are:

Uh oh!

Conversation

theIDinside commented Jun 16, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theIDinside commented Jun 16, 2026

Uh oh!

theIDinside commented Jun 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

marcoscaceres commented Jun 18, 2026

Uh oh!

chrisn commented Jun 18, 2026

Uh oh!

chrisn commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marcoscaceres commented Jun 18, 2026

Uh oh!

marcoscaceres commented Jun 18, 2026

Uh oh!

theIDinside commented Jun 29, 2026

Uh oh!

theIDinside commented Jun 29, 2026

Uh oh!

theIDinside commented Jun 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theIDinside Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theIDinside commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisn Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theIDinside commented Jun 16, 2026 •

edited by pr-preview Bot

Loading

chrisn commented Jun 18, 2026 •

edited

Loading

theIDinside Jul 10, 2026 •

edited

Loading

theIDinside commented Jul 10, 2026 •

edited

Loading

chrisn Jul 16, 2026 •

edited

Loading

chrisn Jul 16, 2026 •

edited

Loading