From 4b38bb13b22969f4210e5e26dfae94fc0e0f6851 Mon Sep 17 00:00:00 2001
From: Raphael Kubo da Costa <raphael.kubo.da.costa@intel.com>
Date: Tue, 13 Dec 2022 16:23:31 +0100
Subject: [PATCH] editorial: Define a "pre-activation checks algorithm".

Related to w3c/ambient-light#79, where we want to replace the
"ambient-light" powerful feature with an integration with the Media Capture
and Streams spec by only providing illuminance readouts if the same page has
an active local video source.

Part of it requires checking the above condition when `Sensor.start()` is
called; the new algorithm introduced here does it in the "activate a sensor
object" abstract operation.

Additionally, `Sensor.start()` is now invoking "activate a sensor object" as
a queued task, as we want it to run in the main event loop rather than in
parallel since at least the Ambient Light Sensor implementation of the
"pre-activation checks algorithm" needs access to the relevant global object
and its internal slots.
---
 index.bs | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 16b65a6..a3c15b2 100644
--- a/index.bs
+++ b/index.bs
@@ -810,6 +810,10 @@ A [=sensor type=] may have an associated <dfn export>reading quantization
 algorithm</dfn>, which takes a [=sensor reading=] and returns a less accurate
 [=sensor reading=].
 
+A [=sensor type=] may have an associated <dfn export>pre-activation checks
+algorithm</dfn>, which takes a {{Sensor}} instance and returns a boolean, to
+perform extra checks before activating the given {{Sensor}} instance.
+
 <h3 id="model-sensor">Sensor</h3>
 
 The current [=browsing context=]'s [=platform sensor=] must have:
@@ -1169,7 +1173,7 @@ It represents a [=reading timestamp=].
                 but it is a tradeoff some User Agent might choose to make. -->
             1.  Queue a task to run [=notify error=] with [=this=] and |e| as arguments.
             1.  Return.
-        1.  Invoke [=activate a sensor object=] with [=this=] as argument.
+        1.  Queue a task to run [=activate a sensor object=] with [=this=] as argument.
 </div>
 
 
@@ -1330,6 +1334,14 @@ to {{SensorErrorEventInit}}.
     :: None
 
     1.  Let |sensor| be the [=platform sensor=] associated with |sensor_instance|.
+    1.  Let |type| be |sensor|'s associated [=sensor type=].
+    1.  If |type|'s [=pre-activation checks algorithm=] is defined:
+        1.  Let |result| be the result of invoking |type|'s [=pre-activation checks algorithm=] with |sensor_instance|.
+        1.  If |result| is false:
+            1.  Let |e| be the result of [=created|creating=] a "{{NotReadableError}}" {{DOMException}}.
+            <!-- Or a NotAllowedError exception, see the comment in Sensor.start(). -->
+            1.  Queue a task to run [=notify error=] with |sensor_instance| and |e|.
+            1.  Return.
     1.  [=set/Append=] |sensor_instance| to |sensor|'s set of [=activated sensor objects=].
     1.  Invoke [=set sensor settings=] with |sensor| as argument.
     1.  Queue a task to run [=notify activated state=] with |sensor_instance|
@@ -2071,6 +2083,8 @@ for each [=sensor types=]:
     be updated.
 -   A [=reading quantization algorithm=], which may return a sensor reading
     with reduced accuracy.
+-   A [=pre-activation checks algorithm=] with extra steps that are run
+    before a {{Sensor}} instance is activated.
 
 <h3 id="extend-automation">Automation</h3>