index.bs

<pre class="metadata">
Title: Generic Sensor API
Shortname: generic-sensor
Status: ED
Group: dap
ED: https://w3c.github.io/sensors/
TR: https://www.w3.org/TR/generic-sensor/
Previous Version: https://www.w3.org/TR/2017/WD-generic-sensor-20170130/
Editor: Tobie Langel 78102, Intel Corporation, http://tobie.me, tobie@sensors.codespeaks.com
Editor: Rick Waldron 50572, JS Foundation
Abstract:
  This specification defines a framework for exposing sensor data
  to the Open Web Platform in a consistent way.
  It does so by defining a blueprint for writing
  specifications of concrete sensors along with an abstract Sensor interface
  that can be extended to accommodate different sensor types.
!Feedback: <a href="https://github.com/w3c/sensors">GitHub</a> (<a href="https://github.com/w3c/sensors/issues/new">new issue</a>, <a href="https://github.com/w3c/sensors/milestone/2">level 1 issues</a>, <a href="https://github.com/w3c/sensors/issues">all issues</a>)
!Other: <a href="https://github.com/w3c/web-platform-tests/tree/master/generic-sensor">Test suite</a>, <a href="https://github.com/w3c/sensors/commits/gh-pages/index.bs">version history</a>
Indent: 2
Repository: w3c/sensors
Markup Shorthands: markdown on
Boilerplate: omit issues-index, omit conformance, omit feedback-header
Default Biblio Status: current
</pre>
<pre class="anchors">
urlPrefix: https://dom.spec.whatwg.org; spec: DOM
  type: dfn
    text: dispatch; url: concept-event-dispatch
    text: event; url: concept-event
urlPrefix: https://html.spec.whatwg.org/multipage/; spec: HTML
  type: dfn
    urlPrefix: webappapis.html
      text: task; url: concept-task
      text: fire a simple event
      text: trusted; url: concept-events-trusted
    urlPrefix: browsers.html
      text: origin; url: origin-2
      text: navigating; url: navigate
      text: browsing context
urlPrefix: http://w3c.github.io/hr-time/; spec: HR-TIME-2
  type: interface
    text: DOMHighResTimeStamp; url: dom-domhighrestimestamp
  type: dfn
    text: time origin
urlPrefix: https://w3c.github.io/page-visibility; spec: PAGE-VISIBILITY
  type: dfn
    text: visibility states; url: dfn-visibility-states
    text: steps to determine the visibility state; url: dfn-steps-to-determine-the-visibility-state
</pre>

<pre class=link-defaults>
spec: webidl; type:dfn; text:attribute
</pre>


<h2 id="intro">Introduction</h2>

Increasingly, sensor data is used in application development to
enable new use cases such as geolocation,
counting steps or head-tracking.
This is especially true on mobile devices where new sensors are added regularly.

Exposing sensor data to the Web
has so far been both slow-paced and ad-hoc.
Few sensors are already exposed to the Web.
When they are, it is often in ways that limit their possible use cases
(for example by exposing abstractions that are too [=high-level=]
and which don't perform well enough).
APIs also vary greatly from one sensor to the next
which increases the cognitive burden of Web application developers
and slows development.

The goal of the Generic Sensor API is to
promote consistency across sensor APIs,
enable advanced use cases thanks to performant [=low-level=] APIs,
and increase the pace at which new sensors can be exposed to the Web
by simplifying the specification and implementation processes.

Issue: This lacks an informative section with examples for developers.
Should contain different use of the API,
including using it in conjunction with `requestAnimationFrame`.


<h2 id="scope">Scope</h2>

<em>This section is non-normative</em>.

The scope of this specification is currently limited
to specifying primitives
which enable expose data from local sensors.

Exposing remote sensors
or sensors found on personal area networks (e.g. Bluetooth)
is out of scope.
As work in these areas mature,
it is possible that common, lower-level primitives be found,
in which case this specification will be updated accordingly.
This should have little to no effects on implementations, however.

This specification also does not currently expose a
sensor discovery API.
This is because the limited number of sensors currently available to user agents
does not warrant such an API.
Using feature detection, such as described in [[#feature-detection]],
is good enough for now.
A subsequent version of this specification might specify such an API,
and the current API has been designed with this in mind.


<h2 id="background">Background</h2>

<em>This section is non-normative</em>.

Issue: This section is ill-named.
It principally covers default sensors
and explains the reasoning behind them.
It should be renamed accordingly and moved,
either to another section of the spec
or to an external explainer document.

The Generic Sensor API is designed to make the most common use cases straightforward
while still enabling more complex use cases.

Most devices deployed today do not carry more than one
[=sensor=] of each [=sensor type|sensor types=].
This shouldn't come as a surprise since use cases for more than
a [=sensor=] of a given [=sensor types|type=] are rare
and generally limited to specific [=sensor types=],
such as proximity sensors.

The API therefore makes it easy to interact with
the device's default (and often unique) [=sensor=]
for each [=sensor types|type=]
simply by instantiating the corresponding {{Sensor}} subclass.

Indeed, without specific information identifying a particular [=sensor=]
of a given [=sensor type|type=],
the default [=sensor=] is chosen.

<div class="example">
    Listening to geolocation changes:

    <pre highlight="js">
    let sensor = new GeolocationSensor({ accuracy: "high" });

    sensor.onchange = function(event) {
        var coords = [sensor.latitude, sensor.longitude];
        updateMap(null, coords, sensor.accuracy);
    };

    sensor.onerror = function(error) {
        updateMap(error);
    };
    sensor.start();
    </pre>
</div>

Note: extension to this specification may choose not to define a default sensor
when doing so wouldn't make sense.
For example, it might be difficult to agree on an obvious default [=sensor=] for
proximity [=sensors=].

In cases where
multiple [=sensors=] of the same [=sensor type|type=]
may coexist on the same device,
specification extension will have to
define ways to uniquely identify each one.

<div class="example">
    For example checking the pressure of the left rear tire:

    <pre highlight="js">
    var sensor = new DirectTirePressureSensor({ position: "rear", side: "left" });
    sensor.onchange = _ => console.log(sensor.pressure);
    sensor.start();
    </pre>
</div>


<h2 id="feature-detection">A note on Feature Detection of Hardware Features</h2>

<em>This section is non-normative.</em>

Feature detection is an established Web development best practice.
Resources on the topic are plentiful on and offline and
the purpose of this section is not to discuss it further,
but rather to put it in the context of detecting hardware-dependent features.

Consider the below feature detection examples:

<div class="example">
    <pre highlight="js">
        if (typeof Gyroscope === "function") {
            // run in circles...
        }

        if ("ProximitySensor" in window) {
            // watch out!
        }

        if (window.AmbientLightSensor) {
            // go dark...
        }

        // etc.
    </pre>
</div>

All of these tell you something about the presence
and possible characteristics of an API.
They do not tell you anything, however, about whether
that API is actually connected to a real hardware sensor,
whether that sensor works,
if its still connected,
or even whether the user is going to allow you to access it.
Note you can check the latter using the Permissions API [[PERMISSIONS]].

In an ideal world, information about the underlying status
would be available upfront.
The problem with this is twofold.
First, getting this information out of the hardware is costly,
in both performance and battery time,
and would sit in the critical path.
Secondly, the status of the underlying hardware can evolve over time.
The user can revoke permission, the connection to the sensor be severed,
the operating system may decide to limit sensor usage below a certain battery threshold,
etc.

Therefore, an effective strategy is to combine feature detection,
which checks whether an API for the sought-after sensor actually exists,
and defensive programming which includes:

1.  checking for error thrown when instantiating a {{Sensor}} object,
2.  listening to errors emitted by it,
3.  handling all of the above graciously so that the user's experience is
    enhanced by the possible usage of a sensor, not degraded by its
    absence.

<div class="example">
    <pre highlight="js">
        try { // No need to feature detect thanks to try..catch block.
            var sensor = new GeolocationSensor();
            sensor.start();
            sensor.onerror = error => gracefullyDegrade(error);
            sensor.onchange = _ => updatePosition(sensor.latitude, sensor.longitude);
        } catch(error) {
            gracefullyDegrade(error);
        }
    </pre>
</div>


<h2 id="security-and-privacy">Security and privacy considerations</h2>

Issue: This section needs to be reorganized.
It probably needs a section that lists threats
and one that lists mitigation strategies,
with links between both.

Privacy risks can arise when [=sensors=] are used
with each other,
in combination with other functionality,
or when used over time,
specifically with the risk of correlation of data
and user identification through fingerprinting.
Web application developers using these JavaScript APIs should
consider how this information might be correlated with other information
and the privacy risks that might be created.
The potential risks of collection of such data over a longer period of time
should also be considered.

Variations in [=sensor readings=]
as well as event firing rates
offer the possibility of fingerprinting to identify users.
User agents may reduce the risk by
limiting event rates available to web application developers.

Note: do we really want this mitigation strategy?

Frequency polling in [=periodic=] [=reporting mode=]
might allow the fingerprinting of hardware or implementation types,
by probing which actual frequencies are supported by the platform.

Minimizing the accuracy of a sensor's readout
generally decreases the risk of fingerprinting.
User agents should not provide unnecessarily verbose readouts of sensors data.
Each [=sensor type=] should be assessed individually.

If the same JavaScript code using the API can be
used simultaneously in different window contexts on the same device
it may be possible for that code to correlate the user across those two contexts,
creating unanticipated tracking mechanisms.

User agents should consider providing the user
an indication of when the [=sensor=] is used
and allowing the user to disable it.
Additionally, user agents may consider
allowing the user to verify past and current sensor use patterns.

Web application developers that use [=sensors=] should
perform a privacy impact assessment of their application
taking all aspects of their application into consideration.

Ability to detect a full working set of sensors on a device can form an
identifier and could be used for fingerprinting.

A combination of selected sensors can potentially be used to form an out of
band communication channel between devices.

Sensors can potentially be used in cross-device linking and tracking of a user.


<h3 id="browsing-context">Browsing Context</h3>

[=Sensor readings=] must only be available in the
[=top-level browsing context=] to avoid the privacy risk of
sharing the information defined in this specification
(and specifications extending it)
with contexts unfamiliar to the user.
For example, a mobile device will only fire the event on
the active tab, and not on the background tabs or within iframes.

Note: [Feature Policy](https://docs.google.com/document/d/1k0Ua-ZWlM_PsFCFdLMa8kaVTo32PeNZ4G7FFHqpFx4E/edit)
should allow securely lifting those restrictions once it matures.

<h3 id="secure-context">Secure Context</h3>

[=Sensor readings=] are explicitly flagged by the
Secure Contexts specification [[POWERFUL-FEATURES]]
as a high-value target for network attackers.
Thus all interfaces defined by this specification
or extension specifications
must only be available within a [=secure context=].


<h3 id="permissioning">Obtaining Explicit User Permission</h3>

Permission to access [=sensor readings=] must be obtained
through the Permissions API [[!PERMISSIONS]].


<h2 id="concepts">Concepts</h2>


<h3 id="concepts-sensors">Sensors</h3>

A [=sensor=] measures different physical quantities
and provide corresponding <dfn>raw sensor readings</dfn>
which are a source of information about the user and their environment.

Each [=raw sensor reading|reading=] is composed of the <dfn lt="reading value">values</dfn>
of the different physical quantities measured by the [=sensor=]
at time <var ignore>t<sub>n</sub></var>.

Known, <em>predictable</em> discrepancies between [=raw sensor readings=]
and the corresponding physical quantities being measured
are corrected through <dfn>calibration</dfn>.

Known but <em>unpredictable</em> discrepancies need to be addressed dynamically
through a process called [=sensor fusion=].

[=calibration|Calibrated=] [=raw sensor readings=] are referred to as <dfn>sensor readings</dfn>,
whether or not they have undergone [=sensor fusion=].


<h3 id="concepts-sensor-types">Sensor Types</h3>

Different [=sensor types=] measure different physical quantities
such as temperature, air pressure, heart-rate, or luminosity.

For the purpose of this specification we distinguish between
[=high-level=] and [=low-level=] [=sensor types=].

[=Sensor types=] which are characterized by their implementation
are referred to as <dfn>low-level</dfn> sensors.
For example a Gyroscope is a [=low-level=] [=sensor type=].

[=Sensors=] named after their [=sensor readings|readings=],
regardless of the implementation,
are said to be <dfn>high-level</dfn> sensors.
For instance, geolocation sensors provide information about the user's location,
but the precise means by which this data is obtained
is purposefully left opaque
(it could come from a GPS chip, network cell triangulation,
wifi networks, etc. or any combination of the above)
and depends on various, implementation-specific heuristics.
[=High-level=] sensors are generally the fruits of
applying algorithms to [=low-level=] sensors--
for example, a pedometer can be built using only the output of a gyroscope--
or of [=sensor fusion=].

That said, the distinction between
[=high-level=] and [=low-level=] [=sensor types=]
is somewhat arbitrary and the line between the two is often blurred.
For instance, a barometer, which measures air pressure,
would be considered [=low-level=] for most common purposes,
even though it is the product of the [=sensor fusion=] of
resistive piezo-electric pressure and temperature sensors.
Exposing the sensors that compose it would serve no practical purpose;
who cares about the temperature of a piezo-electric sensor?
A pressure-altimeter would probably fall in the same category,
while a nondescript altimeter--
which could get its data from either a barometer or a GPS signal--
would clearly be categorized as a [=high-level=] [=sensor type=].

Because the distinction is somewhat blurry,
extensions to this specification (see [[#extensibility]])
are encouraged to provide domain-specific definitions of
[=high-level=] and [=low-level=] sensors
for the given [=sensor types=] they are targeting.

[=Sensor readings=] from different [=sensor types=] can be combined together
through a process called <dfn>sensor fusion</dfn>.
This process provides [=high-level|higher-level=] or
more accurate data (often at the cost of increased latency).
For example, the [=sensor readings|readings=] of a three-axis magnetometer
needs to be combined with the [=sensor readings|readings=] of an accelerometer
to provide a correct bearing.

<dfn>Smart sensors</dfn> and <dfn>sensor hubs</dfn>
have built-in compute resources which allow them
to carry out [=calibration=] and [=sensor fusion=] at the hardware level,
freeing up CPU resources
and lowering battery consumption
in the process.

But [=sensor fusion=] can also be carried out in software.
This is particularly useful when performance requirements can only be met
by relying on application-specific data.
For example, head tracking for virtual or augmented reality applications
requires extremely low latency
to avoid causing motion sickness.
That low-latency is best provided
by using the raw output of a gyroscope
and waiting for quick rotational movements of the head
to compensate for drift.

Note: [=sensors=] created through [=sensor fusion=] are sometimes
called virtual or synthetic sensors.
However, the specification doesn't make any practical differences between them,
preferring instead to differentiate [=sensors=] as to whether they describe
the kind of [=sensor readings|readings=] produced--these are [=high-level=] sensors--
or how the sensor is implemented ([=low-level=] sensors).


<h3 id="concepts-reporting-modes">Reporting Modes</h3>

Issue: **This feature is at risk.**
It is not clear whether there is value
in splitting up [=sensor types=] between
those that fire events at regular intervals
and those which don't.

[=Sensors=] have different <dfn>reporting modes</dfn>.
When [=sensor readings=] are reported at regular intervals,
at an adjustable <dfn>frequency</dfn> measured in hertz (Hz),
the [=reporting mode=] is said to be <dfn>periodic</dfn>.
On [=sensor types=] with support for [=periodic|periodic reporting mode=],
[=periodic|periodic reporting mode=] is triggered
by requesting a specific [=frequency=].

[=Sensor types=] which do not support [=periodic|periodic reporting mode=]
are said to operate in an <dfn>implementation specific</dfn> way.
When the [=reporting mode=] is [=implementation specific=],
[=sensor readings=] may be provided at regular intervals, irregularly,
or only when a [=sensor readings|reading=] change is observed.
This allows user agents more latitude to
carry out power- or CPU-saving strategies,
and support multiple hardware configurations.
[=periodic|Periodic reporting mode=], on the other hand,
allows a much more fine-grained approach
and is essential for use cases with, for example,
low latency requirements.

[=Sensors=] which support [=periodic|periodic reporting mode=]
<dfn>fallback</dfn> to [=implementation specific|implementation specific reporting mode=]
when no requirements are made as to what [=frequency=] they should operate at.

Note: [=reporting mode=] is distinct from,
but related to,
[=sensor readings=] acquisition.
If [=sensors=] are polled at regular interval,
as is generally the case,
[=reporting mode=] can be either [=periodic=] or [=implementation specific=].
However, when the underlying implementation itself only provides [=sensor readings=]
when it measures change,
perhaps because is is relying on [=smart sensors=] or a [=sensor hubs=],
the [=reporting mode=] cannot be [=periodic=],
as that would require data inference.

Issue: This lacks a description of
the different data acquisition modes,
notably polling vs. on change,
both at the platform and HW layer.

Issue: It would be useful to describe
the process of sensor polling and
how increased sensor polling frequency decreases latency.

Issue: A definition of sensor accuracy and
how it affects threshold,
and thus "on change" sensors would be useful.


<h2 id="model">Model</h2>

Issue: A diagram would really help here.

<h3 id="model-sensor-type">Sensor Type</h3>

A <dfn>sensor type</dfn> has an associated [=interface=]
whose [=inherited interfaces=] contains {{Sensor}}.

A [=sensor type=] has a [=ordered set|set=] of <dfn export>associated sensors</dfn>.

If a [=sensor type=] has more than one [=sensor=],
it must have a set of associated <dfn export>identifying parameters</dfn>
to select the right [=sensor=] to associate to each new {{Sensor}} objects.

A [=sensor type=] may have a <dfn export>default sensor</dfn>.

A [=sensor type=] has an associated {{PermissionName}}.

Note: multiple [=sensor types=] may share the same {{PermissionName}}.

A [=sensor type=] has a [=permission revocation algorithm=].

<div algorithm>

    To invoke the <dfn lt="generic sensor permission revocation algorithm">permission revocation algorithm</dfn>
    with {{PermissionName}} |permission_name|, run the following steps:

    1.  For each |sensor_type| which has an associated {{PermissionName}} |permission_name|:
        1.  [=set/For each=] |sensor| in |sensor_type|'s [=ordered set|set=] of [=associated sensors=],
            1.  Invoke the [=revoke sensor permission=] abstract operation with |sensor| as argument.
</div>


<h3 id="model-sensor">Sensor</h3>

A <dfn id=concept-sensor>sensor</dfn> has an associated [=ordered set|set=]
of <dfn>activated Sensor objects</dfn>.
This set is initially [=set/is empty|empty=].

A [=sensor=] has an associated <dfn>latest reading</dfn> [=ordered map|map=]
which holds the latest available [=sensor readings=].

Issue: does the [=latest reading=] map need to be
tied to an origin?

The [=latest reading=] [=ordered map|map=]
contains an [=map/entry=]
whose [=map/key=] is "timestamp" and
whose [=map/value=] is a high resolution timestamp of the time
at which the [=latest reading=] was obtained
expressed in milliseconds that passed since the [=time origin=].
[=latest reading=]["timestamp"] is initially set to `null`,
unless the [=latest reading=] [=ordered map|map=] caches a previous [=sensor readings|reading=].

The other [=map/entries=] of the [=latest reading=] [=ordered map|map=]
hold the values of the different quantities measured by the [=sensor=].
The [=map/keys=] of these [=map/entries=] must match
the [=attribute=] names defined by
the [=sensor type=]'s associated interface,
so that the getter of the `foo` attribute
can simply return [=latest reading=]["foo"].

The [map/value] of all [=latest reading=] [=map/entries=]
is initially set to `null`.
<!-- ,
unless the [=latest reading=] [=ordered map|map=]
caches a previous [=sensor readings|reading=].

Note: there are additional privacy concerns when using cached [=sensor readings|readings=]
which predate either [=navigating=] to resources in the current [=origin=],
or being granted permission to access the [=sensor=]. -->

A [=sensor=] <dfn>supports periodic reporting mode</dfn> if
its associated [=sensor type=] does.

A [=sensor=] has an associated <dfn>reporting flag</dfn> which is initially unset.

A [=sensor=] has an associated <dfn>periodic reporting mode flag</dfn> which is initially unset.

A [=sensor=] has an associated <dfn>current polling frequency</dfn> which is initially `null`.

<h2 id="api">API</h2>


<h3 id="the-sensor-interface">The Sensor Interface</h3>

<pre class="idl">
[SecureContext]
interface Sensor : EventTarget {
  readonly attribute SensorState state;
  readonly attribute DOMHighResTimeStamp? timestamp;
  void start();
  void stop();
  attribute EventHandler onchange;
  attribute EventHandler onactivate;
  attribute EventHandler onerror;
};

dictionary SensorOptions {
  double? frequency;
};

enum SensorState {
  "unconnected",
  "activating",
  "activated",
  "idle",
  "errored"
};
</pre>

A {{Sensor}} object has an associated [=sensor=].

Each {{Sensor}} object has a [=task source=]
called a <dfn>sensor task source</dfn>, initially empty.
A [=sensor task source=] can be enabled or disabled,
and is initially enabled.
When enabled,
the [=event loop=] must use it as one of its [=task sources=].
The [=task source=] for the [=tasks=] mentioned in this specification
is the [=sensor task source=].

When the [=visibility state=] of the [=Document=] in
the [=top-level browsing context=] changes,
let |current_visibility_state| be the result of running
the [=steps to determine the visibility state=] of the [=Document=].
If |current_visibility_state| is "visible",
enable the sensor task source,
otherwise, disable it.

Note: user agents are encouraged to stop sensor polling
when [=sensor task sources=] are disabled in order
to save battery.

### Sensor internal slots ### {#sensor-internal-slots}

Instances of {{Sensor}} are created
with the internal slots described in the following table:

<table id="sensor-slots" class="vert data">
    <thead>
        <tr><th>Internal Slot</th><th>Description (non-normative)</th></tr>
    </thead>
    <tbody>
        <tr>
            <td><dfn export>\[[state]]</dfn></td>
            <td>The current state of {{Sensor}} object which is one of
                <a enum-value>"unconnected"</a>,
                <a enum-value>"activating"</a>,
                <a enum-value>"activated"</a>,
                <a enum-value>"idle"</a>, and
                <a enum-value>"errored"</a>.
                It is initially <a enum-value>"unconnected"</a>.
            </td>
        </tr>
        <tr>
            <td><dfn>\[[desiredPollingFrequency]]</dfn></td>
            <td>The requested polling frequency. It is initially unset.</td>
        </tr>
        <tr>
            <td><dfn>\[[lastEventFiredAt]]</dfn></td>
            <td>the high resolution timestamp of the latest [=sensor reading=]
                that was sent to observers of the {{Sensor}} object,
                expressed in milliseconds that passed since the [=time origin=].
                It is initially `null`.
            </td>
        </tr>
        <tr>
            <td><dfn>\[[waitingForUpdate]]</dfn></td>
            <td>A boolean which indicates wether the observers have been updated
                or whether the object is waiting for a new reading to do so.
                It is initially `true`.</td>
        </tr>
        <tr>
            <td><dfn>\[[identifyingParameters]]</dfn></td>
            <td>
                A [=sensor type=]-epecific group of [=dictionary members=]
                used to select the correct [=sensor=]
                to associate to this {{Sensor}} object.
            </td>
        </tr>
    </tbody>
</table>


### Sensor.state ### {#sensor-state}

The getter of the {{Sensor/state!!attribute}} attribute returns <emu-val>this</emu-val>.\[[state]].

### Sensor.timestamp ### {#sensor-timestamp}

The getter of the {{Sensor/timestamp!!attribute}} attribute returns
[=latest reading=]["timestamp"].

### Sensor.start() ### {#sensor-start}

<div algorithm="to start a sensor">
The {{Sensor/start()}} method must run these steps or their [=equivalent=]:
    1.  Let |sensor_state| be the value of sensor_instance|.[=[[state]]=].
    1.  If |sensor_state| is either <a enum-value>"activating"</a>
        or <a enum-value>"activated"</a>, then return.
    1.  Set |sensor_instance|.[=[[state]]=] to <a enum-value>"activating"</a>.
    1.  Run these sub-steps [=in parallel=]:
        1.  If |sensor_state| is <a enum-value>"unconnected"</a>, then:
            1.  let |connected| be the result of invoking
                the [=Connect to Sensor=] abstract operation.
            1.  If |connected| is `false`, then abort these steps.
        1.  Let |permission_state| be the result of invoking
            the [=Request Sensor Access=] abstract operation,
            passing it |sensor_instance| as argument.
        1.  If |permission_state| is "granted",
            1.  Invoke [=Register a Sensor Object=] passing it |sensor_instance| as argument.
        1.  Otherwise, if |permission_state| is "denied",
            1.  let |e| be the result of [=created|creating=]
                a "{{NotAllowedError!!exception}}" {{DOMException}}.
            1.  Invoke the [=Handle Errors=] abstract operation,
                passing it |e| and |sensor_instance| as arguments.
</div>

### Sensor.stop() ### {#sensor-stop}

<div algorithm="to stop a sensor">
The {{Sensor/stop()}} method must run these steps or their [=equivalent=]:

    1.  If |sensor_instance|.[=[[state]]=] is neither <a enum-value>"activating"</a>
        nor <a enum-value>"activated"</a>, then return.
    1.  Set |sensor_instance|.[=[[state]]=] to <a enum-value>"idle"</a>.
    1.  Run these sub-steps [=in parallel=]:
        1.  Invoke [=Unregister a Sensor=] passing it |sensor_instance| as argument.
</div>

### Sensor.onchange ### {#sensor-onchange}

{{Sensor/onchange}} is an {{EventHandler}} which is called whenever a new [=sensor reading|reading=] is available.

Issue: Should this be renamed `onreading`?
Should we instead add an `ondata` {{EventHandler}} for continuous data
and use `onchange` when the data changed?

### Sensor.onactivate ### {#sensor-onactivate}

{{Sensor/onactivate}} is an {{EventHandler}} which is called when <emu-val>this</emu-val>.[=[[state]]=] transitions from <a enum-value>"activating"</a> to <a enum-value>"activated"</a>.

### Sensor.onerror ### {#sensor-onerror}

{{Sensor/onerror}} is an {{EventHandler}} which is called whenever an [=exception type|exception=] cannot be handled synchronously.

### Event handlers ### {#event-handlers}

The following are the [=event handlers=]
(and their corresponding [=event handler event types=])
that must be supported as attributes by the objects implementing the [=Sensor=] interface:

<table class="simple">
  <thead>
    <tr>
      <th>event handler</th>
      <th>event handler event type</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong><code>onchange</code></strong></td>
      <td><code>change</code></td>
    </tr>
    <tr>
      <td><strong><code>onactivate</code></strong></td>
      <td><code>activate</code></td>
    </tr>
    <tr>
      <td><strong><code>onerror</code></strong></td>
      <td><code>error</code></td>
    </tr>
  </tbody>
</table>


<h3 id="the-sensor-error-event-interface">The SensorErrorEvent Interface</h3>

<pre class="idl">
[SecureContext, Constructor(DOMString type, SensorErrorEventInit errorEventInitDict)]
interface SensorErrorEvent : Event {
  readonly attribute Error error;
};

dictionary SensorErrorEventInit : EventInit {
  required Error error;
};
</pre>

### SensorErrorEvent.error ### {#sensor-error-event-error}

Gets the {{Error}} object passed to {{SensorErrorEventInit}}.

<h2 id="abstract-operations">Abstract Operations</h2>

<h3 dfn export>Construct Sensor Object</h3>

<div algorithm="construct sensor object">

    : input
    :: |options|, a {{SensorOptions}} object.
    : output
    :: |sensor_instance|, a {{Sensor}} object.

    1.  If the [=incumbent settings object=] is not a [=secure context=], then:
        1.  [=throw=] a {{SecurityError}}.
    1.  If the [=browsing context=] is not a [=top-level browsing context=], then:
        1.  [=throw=] a {{SecurityError}}.
    1.  Let |sensor_instance| be a new {{Sensor}} object,
    1.  If [=sensor=] [=supports periodic reporting mode=] and
        |options|.{{frequency!!dict-member}} is [=present=], then
        1.  Set |sensor_instance|.[=[[desiredPollingFrequency]]=] to |options|.{{frequency!!dict-member}}.

        Note: there is not guarantee that the requested |options|.{{frequency!!dict-member}}
        can be respected. The actual [=frequency=] can be calculated using
        {{Sensor}} {{Sensor/timestamp!!attribute}} attributes.
    1.  If [=identifying parameters=] in |options| are set, then:
        1.  Set |sensor_instance|.[=[[identifyingParameters]]=] to [=identifying parameters=].
    1.  Set |sensor_instance|.[=[[state]]=] to <a enum-value>"unconnected"</a>.
    1.  Return |sensor_instance|.
</div>


<h3 dfn export>Connect to Sensor</h3>

<div algorithm="connect to sensor">

    : input
    :: |sensor_instance|, a {{Sensor} object.
    : output
    :: a boolean.

    1.  If |sensor_instance|.[=[[identifyingParameters]]=] is set and
        |sensor_instance|.[=[[identifyingParameters]]=] allows
        a unique [=sensor=] to be identified, then:
        1.  let |sensor| be that [=sensor=],
        1.  associate |sensor_instance| with |sensor|.
        1.  Return `true`.
    1.  If the [=sensor type=] of |sensor_instance| has an associated [=default sensor=]
        and there is a corresponding [=sensor=] on the device, then
        1.  associate |sensor_instance| with [=default sensor=].
        1.  Return `true`.
    1.  let |e| be the result of [=created|creating=] a
        "{{NotReadableError!!exception}}" {{DOMException}}.
        <!-- Note: user agents may decide to use a
        "{{NotAllowedError!!exception}}" {{DOMException}},
        here instead, possibly after a random but bounded delay,
        to simulate the user denying the permission request,
        rather than giving away physical characteristics of the device
        which might be used for fingerprinting or profiling.
        This would of course prevent the developer from
        correctly diagnosing the reason for the rejection
        and might lead to confusing instructions to the user,
        but it is a tradeoff some User Agent might choose to make. -->
    1.  Invoke the [=Handle Errors=] abstract operation,
        passing it |e| and |sensor_instance| as arguments.
    1.  Return `false`.
</div>


<h3 dfn>Register a Sensor Object</h3>

<div algorithm="register a sensor object">

    : input
    :: |sensor_instance|, a {{Sensor}} object.
    : output
    :: None

    1.  Let |sensor| be the [=sensor=] associated with |sensor_instance|.
    1.  Add |sensor_instance| to |sensor|'s set of [=activated Sensor objects=].
    1.  Invoke the [=Set Sensor Settings=] abstract operation,
        passing it |sensor| as argument.
    <!-- 1.  Let |latest_reading| be |sensor|'s associated [=latest reading=] [ordered map|map].
    1.  If |current_reading|["timestamp"] is not `null` and |sensor_instance|'s state is still <a enum-value>"activating"</a>, then
        1.  invoke the [=Update Observers=] operation, passing it
            |sensor_instance| and |current_reading| as arguments. -->
</div>


<h3 dfn>Unregister a Sensor</h3>

<div algorithm="unregister a sensor">

    : input
    :: |sensor_instance|, a {{Sensor}} object.
    : output
    :: None

    1.  Let |sensor| be the [=sensor=] associated with |sensor_instance|.
    1.  Remove |sensor_instance| from |sensor|'s set of [=activated Sensor objects=].
    1.  If |sensor|'s set of [=activated Sensor objects=] is empty,
        1.  Unset the [=periodic reporting mode flag=].
        1.  Set [=current polling frequency=] to `null`.
        1.  Update the user-agent-specific way in which [=sensor readings=] are obtained from |sensor|
            to no longer provide [=sensor readings|readings=].
        1.  Abort these steps.
    1.  Invoke the [=Set Sensor Settings=] abstract operation,
        passing it |sensor| as argument.
</div>

<h3 dfn>Revoke sensor permission</h3>

<div algorithm="revoke sensor permission">

    : input
    :: |sensor|, a [=sensor=].
    : output
    :: None

    1.  let |activated_sensors| be |sensor|'s associated [=ordered set|set=] of [=activated Sensor objects=].
    1.  [=set/For each=] |s| of |activated_sensors|,
        1.  [=set/Remove=] |s| from |activated_sensors|.
        1.  let |e| be the result of [=created|creating=]
            a "{{NotAllowedError!!exception}}" {{DOMException}}.
        1.  Invoke the [=Handle Errors=] abstract operation,
            passing it |e| and |s| as arguments.
    1.  Unset |sensor|'s [=periodic reporting mode flag=].
    1.  Set |sensor|'s [=current polling frequency=] to `null`.
    1.  Update the user-agent-specific way in which [=sensor readings=] are obtained from |sensor|
        to no longer provide [=sensor readings|readings=].

</div>


<h3 dfn>Set Sensor Settings</h3>

<div algorithm="set sensor settings">

    : input
    :: |sensor|, a [=sensor=].
    : output
    :: None

    1.  Let |settings_changed| be `false`.
    1.  Let |is_periodic| be the result of invoking
        the [=Is Current Reporting Mode Periodic=] abstract operation,
        with |sensor| as argument.
    1.  If |is_periodic| is `false` and the [=periodic reporting mode flag=] is set, then
        1.  set |settings_changed| to `true`.
        1.  Unset the [=periodic reporting mode flag=].
    1.  Otherwise if |is_periodic| is `true` and the [=periodic reporting mode flag=] is unset, then
        1.  set |settings_changed| to `true`.
        1.  Set the [=periodic reporting mode flag=].
    1.  Let |frequency| be the result of invoking
        the [=Find the polling frequency of a Sensor=] abstract operation,
        with |sensor| as argument.
    1.  If |frequency| is different from |sensor|'s [=current polling frequency=],
        1.  set |settings_changed| to `true`.
        1.  Set [=current polling frequency=] to |frequency|.
    1.  If |settings_changed| is `true`
        1.  Invoke the [=Observe a Sensor=] abstract operation,
            passing it |sensor| as argument.

    Issue: This abstract operation needs to return |settings_changed|
    instead of the [=Observe a Sensor=] abstract operation itself.
</div>


<h3 dfn>Observe a Sensor</h3>

<div algorithm="observe a sensor">

    Issue: This needs to be refactored in an abstract operation
    that has access to the {{Sensor}} instance |sensor_instance|
    that just got started.

    : input
    :: |sensor|, a [=sensor=].
    : output
    :: None

    <!-- 1.  Immediately invoke the [=Update latest reading=] abstract operation
        to report fresh [=sensor readings|readings=],
        passing it |sensor| and [=latest reading=]["timestamp"] as arguments. -->
    1.  If |sensor|'s |latest reading|["timestamp"] is not `null`,
        invoke the [=update observers=] abstract operation passing it |sensor_instance|
        and |latest reading|["timestamp"] as arguments.
    1.  Otherwise, poll |sensor| immediately.

        Issue: How do we handle this for [=sensors=] that
        do not provide values immediately?
        Fire a dedicated event to signal brokenness?

    1.  If |sensor|'s [=periodic reporting mode flag=] is set,
        1.  let |frequency| be the [=current polling frequency=],
            capped by the upper and lower bounds of the underlying hardware.

            Issue: Should this max polling frequency be reflected in the {{Sensor}} interface?
            E.g. Through a dedicated attribute?

            Issue: Does the max polling frequency affect the reporting frequency?
            If so, should we advise the developer of this issue?
            E.g. via a dedicated event?
        1.  Poll |sensor| at |frequency|.
        1.  Issue: Hook into the `requestAnimationFrame` framework [[HTML]]
            to invoke the [=update latest reading=] abstract operation
            with every new frame passing it |sensor| and
            the latest [=sensor reading=] as arguments.

            Issue: Relying on `requestAnimationFrame` gives us a perfect point
            to buffer readings > 60Hz and to pass them to together with every new frame.
            That's a level 2 feature.

            Issue: Figure out how to handle sensors/platforms that push the data
            rather than wait for it to be polled.
    1.  If the [=periodic reporting mode flag=] is unset,
        1.  the user-agent can decide on the best reporting strategy
            for this particular |sensor| and [=sensor type=].

            Issue: This needs to be defined better.
</div>


<h3 dfn>Is Current Reporting Mode Periodic</h3>

<div algorithm="is current reporting mode periodic">

    : input
    :: |sensor|, a [=sensor=].
    : output
    :: |result|, a boolean.

    1.  Let |result| be `false`.
    1.  [=list/For each=] |sensor_instance| in |sensor|'s set of [=activated Sensor objects=]:
        1. if |sensor_instance|.[=[[desiredPollingFrequency]]=] is set,
            1. set |result| to `true`, then [=break=].
    1. return |result|.
</div>


<h3 dfn>Find the polling frequency of a Sensor</h3>

<div algorithm="find the polling frequency of a sensor">

    : input
    :: |sensor|, a [=sensor=].
    : output
    :: |frequency|, a [=frequency=].

    1.  Let |frequency| be `null`.
    1.  [=set/For each=] |sensor_instance| in |sensor|'s set of [=activated Sensor objects=]:
        1. let |f| be |sensor_instance|.[=[[desiredPollingFrequency]]=].
        1. if |f| is set and |f| is greater than |frequency|,
            1. set |frequency| to |f|.
    1. return |frequency|.
</div>


<h3 dfn>Update latest reading</h3>

<div algorithm="update latest reading">

    : input
    :: |sensor|, a [=sensor=].
    :: |reading|, a [=sensor reading=].
    :: |reading_timestamp|, the timestamp at which [=sensor=] was polled.

    Issue: The timestamp needs to be specified more precisely,
    see [issue #155](https://github.com/w3c/sensors/issues/155).
    : output
    :: None

    1.  If |sensor|’s [=reporting flag=] is set,
        1. abort these steps.
    1.  If |reading_timestamp| is equal [=latest reading=]["timestamp"],
        1. abort these steps.
    1.  Set |sensor|’s [=reporting flag=].
    1.  [=map/Set=] [=latest reading=]["timestamp"] to |reading_timestamp|.
    1.  [=map/For each=] |key| → |value| of [=latest reading=].
        1.  If |key| is "timestamp", [=continue=].
        1.  [=map/Set=] [=latest reading=][|key|] to the corresponding
            value of |reading|.

        Issue: Maybe compare |value| with corresponding
        value of |reading| to see if there's a change
        that needs to be propagated.
    1.  Unset |sensor|’s [=reporting flag=].
</div>


<h3 dfn>Update Observers</h3>

<div algorithm="update observers">

    : input
    :: |sensor_instance|, a {{Sensor}} object.
    :: |timestamp|, a high resolution timestamp.
    : output
    :: None

    1.  If |sensor_instance|.[=[[state]]=] is <a enum-value>"activating"</a>:
        1.  Set |sensor_instance|.[=[[state]]=] <a enum-value>"activated"</a>.
        1.  [=Fire an event=] named "activate" at |sensor_instance|.
    1.  If |sensor_instance|.[=[[waitingForUpdate]]=] is true, then

        Issue: Should we fire delayed readings? Or should we just drop readings instead?

        1.  Set |sensor_instance|.[=[[waitingForUpdate]]=] to `false`.
        1.  [=Fire an event=] named "reading" at |sensor_instance|.
        1.  Set |sensor_instance|.[=[[lastEventFiredAt]]=] to |timestamp|.

        Issue: Should these last steps be done from within a new task?
</div>


<h3 dfn>Handle Errors</h3>

<div algorithm="handle errors">

    : input
    :: |sensor_instance|, a {{Sensor}} object.
    :: |error|, an [=exception=].
    : output
    :: None

    1.  Set |sensor_instance|.[=[[state]]=] to <a enum-value>"errored"</a>.
    1.  [=Fire an event=] named "error" at |sensor_instance| using {{SensorErrorEvent}}
        with its {{SensorErrorEvent/error!!attribute}} attribute initialized to |error|.
</div>


<h3 dfn>Request Sensor Access</h3>

<div algorithm="request sensor access">

    : input
    :: |sensor_instance|, a {{Sensor}} object.
    : output
    :: |state|, a [=permission state=].

    1.  Let |sensor| be the [=sensor=] associated with |sensor_instance|.
    1.  Let |permission_name| be the {{PermissionName}} associated with |sensor|.
    1.  Let |state| be the result of [=request permission to use|requesting permission to use=] |permission_name|.
    1.  Return |state|.
</div>


<h2 id="extensibility">Extensibility</h2>

<em>This section is non-normative.</em>

Its purpose is to describe
how this specification can be extended to specify APIs for
different [=sensor types=].

Extension specifications are encouraged to focus on a single [=sensor type=],
exposing both [=high-level|high=] and [=low-level|low=] level
as appropriate.




<h3 id="security">Security</h3>

All interfaces defined by extension specifications
should only be available within a [=secure context=].


<h3 id="naming">Naming</h3>

{{Sensor}} interfaces for [=low-level=] sensors should be
named after their associated [=sensor=].
So for example, the interface associated with a gyroscope
should be simply named `Gyroscope`.
{{Sensor}} interfaces for [=high-level=] sensors should be
named by combining the physical quantity the [=sensor=] measures
with the "Sensor" suffix.
For example, a [=sensor=] measuring
the distance at which an object is from it
may see its associated interface called `ProximitySensor`.

Attributes of the {{Sensor}} subclass that
hold [=sensor readings=] values
should be named after the full name of these values.
For example, the `Thermometer` interface should hold
the [=sensor reading=]'s value in
a `temperature` attribute (and not a `value` or `temp` attribute).
A good starting point for naming are the
Quantities, Units, Dimensions and Data Types Ontologies [[QUDT]].


<h3 id="unit">Unit</h3>

Extension specification must specify the unit of [=sensor readings=].

As per the Technical Architecture Group's (TAG) API Design Principles [[API-DESIGN-PRINCIPLES]],
all time measurement should be in milliseconds.
All other units should be specified using,
in order of preference,
and with the exception of temperature (for which Celsius should be favored over Kelvin),
the International System of Units (SI),
SI derived units, and
Non-SI units accepted for use with the SI,
as described in the SI Brochure [[SI]].


<h3 id="high-vs-low-level">Exposing High-Level vs. Low-Level Sensors</h3>

So far, specifications exposing sensors to the Web platform
have focused on [=high-level=] sensors APIs. [[GEOLOCATION-API]] [[ORIENTATION-EVENT]]

This was a reasonable approach for a number of reasons.
Indeed, [=high-level=] sensors:

-   convey developer intent clearly,
-   do not require intimate knowledge of how the underlying hardware sensors functions,
-   are easy to use,
-   may enable the User Agent to make significant
    performance and battery life improvements,
-   help avoid certain privacy and security issues by
    decreasing the amount and type of information exposed.

However, an increasing number of use cases
such as virtual and augmented reality
require [=low-level=] access to sensors,
most notably for performance reasons.

Providing [=low-level=] access
enables Web application developers to leverage domain-specific constraints
and design more performant systems.

Following the precepts of the Extensible Web Manifesto [[EXTENNNNSIBLE]],
extension specifications should focus primarily on
exposing [=low-level=] sensor APIs, but should also expose
[=high-level=] APIs when they are clear benefits in doing so.


<h3 id="multiple-sensors">When is Enabling Multiple Sensors of the Same Type Not the Right Choice?</h3>

TODO: provide guidance on when to:

- allow multiple sensors of the same type to be instantiated,
- create different interfaces that inherit from {{Sensor}},
- add constructor parameters to tweak sensors settings (e.g. setting required accuracy).


<h3 id="definition-reqs">Definition Requirements</h3>

The following definitions must be specified for
each [=sensor type=] in extension specifications:

-   An [=interface=] whose [=inherited interfaces=] contains {{Sensor}}.
    This interface must be constructible.
    Its [{{Constructor!!extended-attribute}}] must take, as argument,
    an optional [=dictionary=] whose [=inherited dictionaries=] contains {{SensorOptions}}.
    Its attributes which expose [=sensor readings=] are readonly and
    have getters must return the  if disturbed, and `null` otherwise.
-   A {{PermissionName}}.

An extension specification may specify the following definitions
for each [=sensor types=]:

-   A [=dictionary=] whose [=inherited dictionaries=] contains {{SensorOptions}}.
-   A [=default sensor=]. Generally, devices are equipped with a single [=sensor=]
    of each [=sensor types|type=],
    so defining a [=default sensor=] should be straightforward.
    For [=sensor types=] where multiple [=sensors=] are common,
    extension specifications may choose not to define a [=default sensor=],
    especially when doing so would not make sense.
-   A set of [=identifying parameters=]. TODO: replace that by an abstract operation.


<h3 id="permission-api">Extending the Permission API</h3>

Provide guidance on how to extend the Permission API [[PERMISSIONS]]
for each [=sensor types=].


<h3 id="example-webidl">Example WebIDL</h3>

Here's example WebIDL for a possible extension of this specification
for proximity [=sensors=].

<pre class=example>
    [SecureContext, Constructor(optional ProximitySensorOptions proximitySensorOptions)]
    interface ProximitySensor : Sensor {
        readonly attribute unrestricted double distance;
    };

    dictionary ProximitySensorOptions : SensorOptions {
        double? min = -Infinity;
        double? max = Infinity;
        ProximitySensorPosition? position;
        ProximitySensorDirection? direction;
    };

    enum ProximitySensorPosition {
        "top-left",
        "top",
        "top-right",
        "middle-left",
        "middle",
        "middle-right",
        "bottom-left",
        "bottom",
        "bottom-right"
    };

    enum ProximitySensorDirection {
        "front",
        "rear",
        "left",
        "right",
        "top",
        "bottom"
    };
</pre>


<h2 id="acknowledgements">Acknowledgements</h2>

First and foremost, I would like to thank Anssi Kostiainen
for his continuous and dedicated support and input throughout
the development of this specification.

Special thanks to Rick Waldron for
driving the discussion around a generic sensor API design for the Web,
sketching the original API on which this is based,
providing implementation feedback from his work on Johnny-Five,
and continuous input during the development of this specification.

Special thanks to Boris Smus, Tim Volodine, and Rich Tibbett
for their initial work on exposing sensors to the web with consistency.

Thanks to Anne van Kesteren
for his tireless help both in person and through IRC.

Thanks to Domenic Denicola and Jake Archibald for their help.

Thanks also to Frederick Hirsch and Dominique Hazaël-Massieux (via the HTML5Apps project)
for both their administrative help and technical input.

Thanks to Tab Atkins for making Bikeshed and taking the time to explain its subtleties.

Thanks to Lukasz Olejnik and Maryam Mehr for their contributions around privacy and security.

The following people have greatly contributed to this specification through extensive discussions on GitHub:
Anssi Kostiainen,
Boris Smus,
chaals,
Claes Nilsson,
Dave Raggett,
David Mark Clements,
Domenic Denicola,
Dominique Hazaël-Massieux (via the HTML5Apps project),
Francesco Iovine,
Frederick Hirsch,
gmandyam,
Jafar Husain,
Johannes Hund,
Kris Kowal,
Lukasz Olejnik,
Marcos Caceres,
Marijn Kruisselbrink,
Mark Foltz,
Mats Wichmann,
Matthew Podwysocki,
pablochacin,
Remy Sharp,
Rich Tibbett,
Rick Waldron,
Rijubrata Bhaumik,
robman,
Sean T. McBeth,
smaug----,
Tab Atkins Jr.,
Virginie Galindo,
zenparsing,
and Zoltan Kis.

We'd also like to thank
Anssi Kostiainen,
Dominique Hazaël-Massieux,
Erik Wilde,
and
Michael[tm] Smith
for their editorial input.

<h2 id="conformance" class="no-ref no-num">Conformance</h2>

<h3 id="conventions" class="no-ref no-num">Document conventions</h3>

    <p>Conformance requirements are expressed with a combination of
    descriptive assertions and RFC 2119 terminology. The key words "MUST",
    "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
    "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this
    document are to be interpreted as described in RFC 2119.
    However, for readability, these words do not appear in all uppercase
    letters in this specification.

    <p>All of the text of this specification is normative except sections
    explicitly marked as non-normative, examples, and notes. [[!RFC2119]]</p>

    <p>Examples in this specification are introduced with the words "for example"
    or are set apart from the normative text with <code>class="example"</code>,
    like this:

    <div class="example">
        <p>This is an example of an informative example.</p>
    </div>

    <p>Because this document doesn't itself define APIs for specific [=sensor types=]--
    that is the role of extensions to this specification--
    all examples are inevitably (wishful) fabrications.
    Although all of the [=sensors=] used a examples
    would be great candidates for building atop the Generic Sensor API,
    their inclusion in this document does not imply that the relevant Working Groups
    are planning to do so.

    <p>Informative notes begin with the word "Note" and are set apart from the
    normative text with <code>class="note"</code>, like this:

    <p class="note">Note, this is an informative note.</p>

<h3 id="conformant-algorithms" class="no-ref no-num">Conformant Algorithms</h3>

    <p>Requirements phrased in the imperative as part of algorithms (such as
    "strip any leading space characters" or "return false and abort these
    steps") are to be interpreted with the meaning of the key word ("must",
    "should", "may", etc) used in introducing the algorithm.</p>

    <p>Conformance requirements phrased as algorithms or specific steps can be
    implemented in any manner, so long as the end result is <dfn>equivalent</dfn>. In
    particular, the algorithms defined in this specification are intended to
    be easy to understand and are not intended to be performant. Implementers
    are encouraged to optimize.</p>

<h3 id="conformance-classes" class="no-ref no-num">Conformance Classes</h3>

    <p>A <dfn>conformant user agent</dfn> must implement all the requirements
    listed in this specification that are applicable to user agents.</p>

<style>
    #toc .current,
    #toc .current-parent {
      border-right-width: 3px;
      border-right-style: solid;
      border-right-color: #3980B5;
    }

    #toc .current {
      background: rgba(75%, 75%, 75%, .25);
      border-right-color: #054572;
    }
</style>
<script>
    // Scrollspy
    var createScrollSpy = (function() {

        function targetId(element) {
            return (element.href || "").split("#")[1] || null;
        }

        function getScrollTop() {
            return (window.pageYOffset !== undefined)
                ? window.pageYOffset
                : (document.documentElement || document.body.parentNode || document.body).scrollTop;
        }

        function addClassToParents(element, className, parentClassName) {
            do {
                element = element.parentNode;
            } while (element && element.tagName != "LI")
            if (element) {
                var a = element.querySelector("a");
                if (a) a.className = className;
                addClassToParents(element, parentClassName ? parentClassName : className);
            }
        }

        function getPosition(element, container) {
            var eR = element.getBoundingClientRect();
            var cR = container.getBoundingClientRect();
            if (eR.bottom < cR.top) return "above";
            if (eR.top > cR.bottom) return "below";
            return "visible";
        }

        function createScrollSpy(options) {
            options = options || {};

            var OFFSET = 80,
                needsUpdate = false,
                previous = null,
                current = null,
                currentNav = null,
                tocContainer,
                toc,
                sections;

            tocContainer = document.querySelector(options.id);
            toc = [].slice.call(tocContainer.querySelectorAll("a"), 0);
            sections = toc.reduce(function(sections, a) {
                var id = targetId(a);
                var section = id ? document.getElementById(id) : null;
                if (section) { sections.push(section); }
                return sections;
            }, []);

            function onscroll() {
                if (!needsUpdate) {
                    needsUpdate = true;
                    requestAnimationFrame(updatePosition);
                }
            }

            function updatePosition() {
                needsUpdate = false;
                var scrollTop = (options.offset || 0) + getScrollTop();
                current = sections.filter(function(section){
                    return section.offsetTop < scrollTop;
                }).pop();
                current = current ? current.id : null;

                if (previous !== current) {
                    previous = current;
                    toc.forEach(function(a) {
                        if (targetId(a) == current) {
                            currentNav = a;
                        } else {
                            a.className = "";
                        }
                    });
                    if (options.markParents) {
                        addClassToParents(currentNav, options.className, options.parentClassName)
                    } else {
                        currentNav.className = options.className;
                    }
                    if (options.scrollIntoView && typeof currentNav.scrollIntoView == "function") {
                        var p = getPosition(currentNav, tocContainer);
                        if (p == "above") {
                            currentNav.scrollIntoView(true);
                        } else if (p == "below") {
                            currentNav.scrollIntoView(false);
                        }
                    }
                }
            }

            return {
                start: function() {
                    window.addEventListener("scroll", onscroll, false);
                },

                stop: function() {
                    window.removeEventListener("scroll", onscroll, false);
                    toc.forEach(function(a) {
                        a.className = "";
                    });
                }
            }
        }

        return createScrollSpy;
    })();

    (function() {
        var spy = createScrollSpy({
            offset: 80,
            id: "#toc",
            className: "current",
            parentClassName: "current-parent",
            markParents: true,
            scrollIntoView: true
        });

        var mm = window.matchMedia('screen and (min-width: 78em)');
        if (mm.matches) {
            spy.start();
        }
        mm.addListener(function(m) {
            if (m.matches) spy.start();
            else spy.stop();
        });
    })();
</script>