Use permissions API for XR feature requests

index.bs

@@ -23,6 +23,9 @@ Abstract: This specification describes support for accessing virtual reality (VR
 <pre class="link-defaults">
 spec:infra;
     type:dfn; text:string
+    type:dfn; text:tuple
+spec:permissions-1;
+    type:dfn; text:powerful feature
 </pre>
 
 <pre class="anchors">
@@ -346,11 +349,15 @@ When this method is invoked, the user agent MUST run the following steps:
             1. Abort these steps.
         1. Let |session| be a new {{XRSession}} object.
         1. [=Initialize the session=] with |session|, |mode|, and |device|.
-        1. [=Resolve the requested features=] given by |options|' {{XRSessionInit/requiredFeatures}} and |options|' {{XRSessionInit/optionalFeatures}} values for |session|, and let |resolved| be the returned value.
-        1. If |resolved| is <code>false</code>, run the following steps:
+        1. Let |descriptor| be an {{XRPermissionDescriptor}} initialized with |session|, |options|' {{XRSessionInit/requiredFeatures}}, and |options|' {{XRSessionInit/optionalFeatures}}.
+        1. Let |descriptor| be an {{XRPermissionDescriptor}} initialized with |session|, |options|' {{XRSessionInit/requiredFeatures}}, and |options|' {{XRSessionInit/optionalFeatures}}.
+        1. Let |status| be an {{XRPermissionStatus}}, initially <code>null</code>
+        1. [=Request the xr permission=] with |descriptor| and |status|.
+        1. If |status|' {{PermissionStatus/state}} is {{PermissionState/"denied"}} run the following steps:
             1. [=Reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}}.
             1. If |immersive| is <code>true</code>, set [=pending immersive session=] to <code>false</code>.
             1. Abort these steps.
+        1. Set |session|'s [=list of enabled features=] to |status|' {{XRPermissionStatus/granted}}.
         1. Potentially set the [=active immersive session=] as follows:
             <dl class="switch">
               <dt> If |immersive| is <code>true</code>
@@ -496,36 +503,6 @@ Note: {{XRReferenceSpaceType/"local"}} is always included in the [=requested fea
 
 Note: For example, several VR devices support either configuring a safe boundary for the user to move around within or skipping boundary configuration and operating in a mode where the user is expected to stand in place. Such a device can be considered to be [=capable of supporting=] {{"bounded-floor"}} {{XRReferenceSpace}}s even if they are currently not configured with safety boundaries, because it's expected that the user could configure the device appropriately if the experience required it. This is to allow user agents to avoid fully initializing the [=XRSession/XR device=] or waiting for the user's environment to be recognized prior to [=resolve the requested features|resolving the requested features=] if desired. If, however, the user agent knows that the boundary state at the time the session is requested without additional initialization it may choose to reject the {{"bounded-floor"}} feature if the safety boundary not already configured.
 
-<div class="algorithm" data-algorithm="resolve-features">
-
-To <dfn>resolve the requested features</dfn> given |requiredFeatures| and |optionalFeatures| for an {{XRSession}} |session|, the user agent MUST run the following steps:
-
-  1. Let |consentRequired| be an empty [=/list=] of {{DOMString}}.
-  1. Let |consentOptional| be an empty [=/list=] of {{DOMString}}.
-  1. Add every [=feature descriptor=] in the [=default features=] table associated with |session|'s [=XRSession/mode=] to the indicated feature list if it is not already present.
-  1. For each |feature| in |requiredFeatures| perform the following steps:
-    1. If |feature| is not a valid [=feature descriptor=], return <code>false</code>.
-    1. If the requesting document's origin is not allowed to use any [[#feature-policy|feature policy]] required by |feature| as indicated by the [=feature requirements=] table, return <code>false</code>.
-    1. If |session|'s [=XRSession/XR device=] is not [=capable of supporting=] the functionality described by |feature| or the user agent has otherwise determined to reject the feature, return <code>false</code>.
-    1. If the functionality described by |feature| requires [=explicit consent=], append it to |consentRequired|.
-    1. Else append |feature| to |session|'s [=list of enabled features=].
-  1. For each |feature| in |optionalFeatures| perform the following steps:
-    1. If |feature| is not a valid [=feature descriptor=], continue to the next entry.
-    1. If the requesting document's origin is not allowed to use any [[#feature-policy|feature policy]] required by |feature| as indicated by the [=feature requirements=] table, continue to the next entry.
-    1. If |session|'s [=XRSession/XR device=] is not [=capable of supporting=] the functionality described by |feature| or the user agent has otherwise determined to reject the feature, continue to the next entry.
-    1. If the functionality described by |feature| requires [=explicit consent=], append it to |consentOptional|.
-    1. Else append |feature| to |session|'s [=list of enabled features=].
-  1. If |consentRequired| or |consentOptional| are not empty, request [=explicit consent=] to use the functionality described by those features.
-  1. For each |feature| in |consentRequired| perform the following steps:
-    1. If a clear signal of [=user intent=] to enable |feature| has not been given, return <code>false</code>.
-    1. Else append |feature| to |session|'s [=list of enabled features=].
-  1. For each |feature| in |consentOptional| perform the following steps:
-    1. If a clear signal of [=user intent=] to enable |feature| has not been given, continue to the next entry.
-    1. Else append |feature| to |session|'s [=list of enabled features=].
-  1. Return <code>true</code>
-
-</div>
-
 Session {#session}
 =======
 
@@ -2334,6 +2311,117 @@ The [=default allowlist=] for this feature is <code>["self"]</code>.
 
 Note: If the document's origin is not allowed to use the <code>"xr-spatial-tracking"</code> feature policy any [=immersive sessions=] will be blocked, because all [=immersive sessions=] require some use of spatial tracking. [=Inline sessions=] will still be allowed, but restricted to only using the {{XRReferenceSpaceType/"viewer"}} {{XRReferenceSpace}}.
 
+
+Permissions API Integration {#permissions}
+---------
+
+The [[!permissions]] API provides a uniform way for websites to request permissions from users and query which permissions they have. 
+
+The <dfn enum-value for="PermissionName">"xr"</dfn> [=powerful feature=]’s permission-related algorithms and types are defined as follows: 
+
+
+<dl>
+<dt>[=permission descriptor type=]</dt>
+<dd>
+
+<pre class="idl">
+dictionary XRPermissionDescriptor: PermissionDescriptor {
+  XRSession session;
+  sequence&lt;any&gt; requiredFeatures;
+  sequence&lt;any&gt; optionalFeatures;
+};
+</pre>
+
+where {{PermissionDescriptor/name}} is {{PermissionName/"xr"}}.
+
+
+</dd>
+
+<dt>[=permission result type=]</dt>
+<dd>
+<pre class=idl>
+dictionary XRPermissionStatus: PermissionStatus {
+  sequence&lt;any&gt; granted;
+};
+</pre>
+
+</dd>
+
+
+<dt>[=permission request algorithm=]</dt>
+<dd>
+<div class=algorithm data-algorithm="xr-permission-request-algorithm">
+To <dfn lt="request the xr permission">request the "xr" permission</dfn> with an {{XRPermissionDescriptor}} |descriptor| and a {{XRPermissionStatus}} |status|, the UA MUST run the following steps:
+
+  1. Let |result| be the result of [=resolve the requested features|resolving the requested features=] given |descriptor|'s {{XRPermissionDescriptor/requiredFeatures}}, {{XRPermissionDescriptor/optionalFeatures}}, and {{XRPermissionDescriptor/session}}.
+  1. If |result| is <code>null</code>, run the following steps:
+    1. Set |status|'s {{XRPermissionStatus/granted}} to an empty {{FrozenArray}}.
+    1. Set |status|'s {{PermissionStatus/state}} to {{PermissionState/"denied"}}.
+    1. Abort these steps.
+  1. Let <code>(|consentRequired|, |consentOptional|, |granted|)</code> be the fields of |result|.
+  1. For each |feature| in |consentRequired| perform the following steps:
+      1. If a clear signal of [=user intent=] to enable |feature| has not been given, set |status|'s   {{PermissionStatus/state}} to {{PermissionState/"denied"}} and abort these steps.
+      1. If |feature| is not in |granted|, append |feature| to |granted|.
+  1. For each |feature| in |consentOptional| perform the following steps:
+      1. If a clear signal of [=user intent=] to enable |feature| has not been given, continue to the next entry.
+      1. If |feature| is not in |granted|, append |feature| to |granted|.
+  1. Set |status|'s {{XRPermissionStatus/granted}} to |granted|.
+  1. Set |status|'s {{PermissionStatus/state}} to {{PermissionState/"granted"}}.
+
+Note: The user agent may choose to batch up permissions prompts for all requested features when gauging if there is a clear signal of [=user intent=].
+
+</div>
+
+
+<dt>[=permission query algorithm=]</dt>
+<dd>
+<div class=algorithm data-algorithm="xr-permission-query-algorithm">
+To query the "xr" permission with an {{XRPermissionDescriptor}} |descriptor| and a {{XRPermissionStatus}} |status|, the UA MUST run the following steps:
+
+  1. Set |status|'s {{PermissionStatus/state}} to |descriptor|'s [=permission state=].
+  1. If |status|'s {{PermissionStatus/state}} is {{PermissionState/"denied"}}, set |status|'s {{XRPermissionStatus/granted}} to an empty {{FrozenArray}} and abort these steps.
+  1. Let |result| be the result of [=resolve the requested features|resolving the requested features=] given |descriptor|'s {{XRPermissionDescriptor/requiredFeatures}}, {{XRPermissionDescriptor/optionalFeatures}}, and {{XRPermissionDescriptor/session}}.
+  1. If |result| is <code>null</code>, run the following steps:
+    1. Set |status|'s {{XRPermissionStatus/granted}} to an empty {{FrozenArray}}.
+    1. Set |status|'s {{PermissionStatus/state}} to {{PermissionState/"denied"}}.
+    1. Abort these steps.
+  1. Let <code>(|consentRequired|, |consentOptional|, |granted|)</code> be the fields of |result|.
+  1. Set |status|'s {{XRPermissionStatus/granted}} to |granted|.
+  1. If |consentRequired| [=list/is empty=] and |consentOptional| [=list/is empty=], set |status|'s {{PermissionStatus/state}} to {{PermissionState/"granted"}} and abort these steps
+  1. Set |status|'s {{PermissionStatus/state}} to {{PermissionState/"prompt"}}.
+
+</div>
+
+</dd>
+
+</dl>
+
+<div class="algorithm" data-algorithm="resolve-features">
+
+To <dfn>resolve the requested features</dfn> given |requiredFeatures| and |optionalFeatures| for an {{XRSession}} |session|, the user agent MUST run the following steps:
+
+  1. Let |consentRequired| be an empty [=/list=] of {{DOMString}}.
+  1. Let |consentOptional| be an empty [=/list=] of {{DOMString}}.
+  1. Let |granted| be a [=/list=] of {{DOMString}} initialized to |session|'s [=list of enabled features=].
+  1. Add every [=feature descriptor=] in the [=default features=] table associated with |session|'s [=XRSession/mode=] to the indicated feature list if it is not already present.
+  1. For each |feature| in |requiredFeatures| perform the following steps:
+    1. If |feature| is not a valid [=feature descriptor=], return <code>null</code>.
+    1. If |feature| is already in |granted|, continue to the next entry.
+    1. If the requesting document's origin is not allowed to use any [[#feature-policy|feature policy]] required by |feature| as indicated by the [=feature requirements=] table, return <code>null</code>.
+    1. If |session|'s [=XRSession/XR device=] is not [=capable of supporting=] the functionality described by |feature| or the user agent has otherwise determined to reject the feature, return <code>null</code>.
+    1. If the functionality described by |feature| requires [=explicit consent=], append it to |consentRequired|.
+    1. Else append |feature| to |granted|.
+  1. For each |feature| in |optionalFeatures| perform the following steps:
+    1. If |feature| is not a valid [=feature descriptor=], continue to the next entry.
+    1. If |feature| is already in |granted|, continue to the next entry.
+    1. If the requesting document's origin is not allowed to use any [[#feature-policy|feature policy]] required by |feature| as indicated by the [=feature requirements=] table, continue to the next entry.
+    1. If |session|'s [=XRSession/XR device=] is not [=capable of supporting=] the functionality described by |feature| or the user agent has otherwise determined to reject the feature, continue to the next entry.
+    1. If the functionality described by |feature| requires [=explicit consent=], append it to |consentOptional|.
+    1. Else append |feature| to |granted|.
+  1. Return the [=tuple=] <code>(|consentRequired|, |consentOptional|, |granted|)</code>
+
+</div>
+
 Acknowledgements {#ack}
 ================