Re: Proposal for a page visibility API

For clarity, I've included the current draft of the proposal below, which
incorporates the feedback from this thread.


****

There is currently no good way for a web page to detect that it is
completely invisible to the user (for example, that it is a background tab),
although some imperfect heuristics do exist. In the future, there may be
cases where such detection is even more important, for example in the
prerendering feature that Chromium is currently in the early stages of
experimentation with.


Use cases

*  A page wants to detect when it is being prerendered so it can behave
appropriately.
*  A puzzle game has a timer that keeps track of how long the user has taken
to solve the puzzle.  It wants to pause the timer when the user has hidden
the tab.
*  A web app that uses polling to fetch dynamic content can pause polling
when it knows the page is hidden from the user.
*  A streaming video site doesn’t want to start the video until the user
actually views the tab for the first time (i.e. video shouldn’t start
automatically if a user opens the tab in the background).
*  An in-browser collaborative editing environment wants to update a user’s
status to away when the editing surface is not visible to the user.
*  A web-based chat application wants to show the user notifications via the
Web Notification API when a message is received, but only when the page is
not visible to the user.

With these use-cases in mind, there are a number of requirements.


Requirements

*  Easy for developers to write scripts that fall back on old behaviors for
browsers that do not implement this API
*  Ability to query the document’s current visibility state
*  Events fired when the document transitions between visibility states
*  Ability for browser vendors to add new visibility states in the future


API


document.visible

Returns true if document.visibilityState’s current value is in the set of
visibility states considered to be visible (see the next section for
information on document.visibilityState).  In practice document.visible is
merely a convenience property that is well-suited to simple uses.

The “visible” state is considered to be visible in all implementations.
 “hidden”, “prerender”, and “cache” are considered to be hidden in all
implementations.  The visibility of additional values, including “preview”,
are up to the discretion of the implementation (for example, an
implementation that makes use of nearly-full-size thumbnail previews may
consider “preview” to be a visible state).


document.visibilityState

A read-only property that returns a string, one of the values described in
the next section.  Developers can use the existence of this property to know
that they can rely on the rest of this API, too.
*  Values returned by all conforming implementations
  *  “visible” : the page content may be at least partially visible.
  *  “hidden” : the page content is not visible to the user at all.
*  Additional values potentially returned by some implementations in some
cases
  *  “prerender” : the page is currently being loaded off-screen and might
never be shown to the user.
  *  “cache” : the page is currently “frozen” in a cache and not displayed
on screen (e.g. the back-forward cache).
  *  “preview” : the page is currently visible only in a lower-resolution
version.

Visibility states considered to be visible, for the purposes of
document.visible, include “visible”.

States in the second set are not guaranteed to be returned in all cases
where they might otherwise appear to apply--it is left to the discretion of
the implementation.

Additional return values may be added to this API in the future.

It is up to the implementation to interpret what these values mean in the
precise context of interface and platform.  As an example, a
current-generation desktop browser might interpret the values the following
way:
“visible” : the tab is focused in its non-minimized window (regardless of
the focus state of the containing window).
“hidden” : the tab is backgrounded within its window, or the containing
window is minimized.


visibilitychange

A simple event, fired at the document object immediately after
document.visibilityState transitions between visibility states.  The event
has two properties, fromState and fromVisible, that are set to the value of
document.visibilityState and document.visible, respectively,  just before
they were changed to the current value.  The eventNote that visibility has
nothing to do with whether the document’s contents have fully loaded or not,
which implies that for any given visibility transition event, onload may or
may not have already fired.