Intent to Implement and Ship: Unprefixed Fullscreen API

[Philip Jägenstedt]

Contact emails

phi...@opera.com

Spec

http://fullscreen.spec.whatwg.org/#api

Summary

Unprefix and ship these APIs, which are already shipping prefixed:

partial interface Element {

  void requestFullscreen();

};

partial interface Document {

  readonly attribute boolean fullscreenEnabled;

  readonly attribute Element? fullscreenElement;

  void exitFullscreen();

  attribute EventHandler onfullscreenchange;

  attribute EventHandler onfullscreenerror;

};

Motivation

The prefixed API has been enabled by default since Chrome 15 (2011) and non-trivial amounts of Web content depends on it:

http://www.chromestatus.com/metrics/feature/timeline/popularity/176

http://www.chromestatus.com/metrics/feature/timeline/popularity/322

http://www.chromestatus.com/metrics/feature/timeline/popularity/323

In the attempts to remove the HTMLVideoElement-specific prefixed fullscreen API, the migration story is a bit sad, since one would have to migrate to another prefixed API. Having an unprefixed API to point to makes things less confusing for developers and will save them the trouble of updating the code twice because of Blink changes. (Assuming the eventual removal of the HTMLVideoElement-specific API will happen after shipping the unprefixed API.)

Compatibility Risk

AFAIK, Opera Presto is the engine to have shipped the unprefixed API so far.

Given the way that people use prefixed APIs, treating them all as aliases, there are no obvious problems. However, since the unprefixed code paths haven't been exercised since the demise of Presto, it's likely that there will be some small bumps. I suggest shipping with a RuntimeEnabledFeature first and removing that once the API has successfully reached the stable channel.

Ongoing technical constraints

There are two relevant earlier threads on the topic:

https://groups.google.com/a/chromium.org/d/msg/blink-dev/iElkfxDU7d4/3gsk0R3shUMJ

https://groups.google.com/a/chromium.org/d/msg/blink-dev/11Y16asREPg/NAe3Tr88HKAJ

Last time, Matt Falkenhagen was hoping to implement the "top layer" concept before unprefixing: https://code.google.com/p/chromium/issues/detail?id=240576

That work was stalled, but in my opinion this need not block shipping the unprefixed API. The most common use case (fullscreen video) is not affected and we will want to keep the prefixed and unprefixed APIs in sync anyway. In private correspondence with Matt, he agreed with decoupling unprefixing from that work.

Will this feature be supported on all five Blink platforms (Windows, Mac, Linux, Chrome OS and Android)?

Yes.

OWP launch tracking bug?

None.

Link to entry on the feature dashboard

http://www.chromestatus.com/features/5259513871466496

Requesting approval to ship?

Yes.

[addyo...@gmail.com]

LGTM. There's an interesting related discussion over on bugzilla about how Mozilla are considering handling their unprefixing of this API.

They talk about how long they should maintain the prefixed version of the API vs aliasing and so on.

[Adam Barth]

LGTM

[Ojan Vafai]

LGTM2

[TAMURA, Kent]

LGTM3.  Adding unprefixed functions should be safe.

--
TAMURA Kent
Software Engineer, Google

[Philip Jägenstedt]

Hi all,

It's been over a month since this intent passed, so an update is in order. This is the tracking bug:

https://code.google.com/p/chromium/issues/detail?id=383813

Some changes have landed, but not the unprefixing itself. I expected it to be trivial, but was wrong.

First, the event target and bubbles flag will not be the same with the prefixed and unprefixed API. The spec fires non-bubbling events at the document. All non-WebKit implementation fire bubbling events at the document, while WebKit/Blink fire bubbling events at the fullscreen element. I intend to follow the spec with the unprefixed event, since it makes sense and is closer to other implementations. Nevertheless, it could break, and I have found a few problems in existing libraries:

https://github.com/jwplayer/jwplayer/pull/103

https://github.com/johndyer/mediaelement/pull/1240

For the Web archaeologists out there, I've written a longer post:

http://blog.foolip.org/2014/07/21/history-of-the-fullscreen-api/

Second, it's not always obvious if the prefixed or the unprefixed event should be fired, because:

1. The prefixed and unprefixed APIs can be mixed within a document and across an iframe hierarchy of documents.
2. Exiting fullscreen in a document will also fire events on its ancestor documents and some descendant documents, which may have used another flavor of the API or neither API in the case of ancestor documents.
3. A document can exit fullscreen implicitly, e.g. by user request, so that there's no prefixed/unprefixed information available when exiting.

I've gone back and forth and back again, and eventually decided to store the request type together with the element when pushing to the fullscreen element stack. When exiting fullscreen, the request type at the top of the stack is used to pick the event name. This means that if requestFullscreen() is used to enter fullscreen, the fullscreenchange event will be fired when exiting, even if webkitExitFullscreen() was used to exit.

I don't think firing both events is a serious option, because combined with the event target difference, it's too easy to mess up the fullscreenchange event handler and accidentally depend on webkitfullscreenchange.

Third, I forgot to mention CSS in the original mail. We currently have :-webkit-full-screen, :-webkit-full-screen-ancestor and :-webkit-full-screen-document pseudo-classes. I will add :fullscreen as an alias of :-webkit-full-screen and investigate when/if the prefixed names can be dropped.

Finally, there's a spec-compliance problem with how the fullscreen element stack is updated. Per spec, requestFullscreen() should return early and continue asynchronously. In Blink, however, the element is pushed to the stack synchronously. A script can currently tell the difference by looking at webkitFullscreenElement after webkitRequestFullscreen(). No libraries I've looked at do this, though. Oddly enough, webkitCurrentFullScreenElement is not an alias of webkitFullscreenElement, it's managed separately and updated when the element actually enters fullscreen.

I think that the sane thing is to follow the spec and also to synchronize the stack push and fullscreenchange event with animation frames, so that the fullscreenElement/webkitFullscreenElement/webkitCurrentFullScreenElement properties and :fullscreen/:-webkit-full-screen pseudo-classes all toggle on the first frame after entering or exiting fullscreen. It would change observable behavior for which we have no use counter data, but it seems fairly likely to be safe. If it turns out to break something, I don't think fixing this need block shipping the unprefixed fullscreen API. Does that make sense?

Please let me know if you have any concerns.

Philip

[Vincent Scheib]

These points and conclusions seem well reasoned to me, I support this continued approach.