Add user activation interface.

Describe the interface and augment PostMessage options to contain the
required fields.

Fixes #4008

Author: dtapuska

source

@@ -73335,7 +73335,7 @@ END:VCARD</pre>
   seconds, so that the user can possibly perceive the link between an interaction with the page and
   the page calling the activation-gated API.</p>
 
-  <p>These two values imply two boolean user activation states for <var>W</var>:</p>
+  <p>These two values imply two boolean <dfn>user activation states</dfn> for <var>W</var>:</p>
 
   <dl>
    <dt><dfn data-export="">Sticky activation</dfn></dt>
@@ -73481,6 +73481,74 @@ END:VCARD</pre>
   </dl>
 
 
+  <h4>The <code>UserActivation</code> interface</h4>
+
+  <p>The <span>user activation states</span> are exposed via the <code>UserActivation</code>
+  interface. <code>UserActivation</code> objects can be created either as a live or snapshot object,
+  it depends on how the object was referenced. Objects accessed via <code>navigator</code>'s <code
+  data-x="dom-Navigator-userActivation">userActivation</code> attribute are live, in that changes
+  will in the <span>user activation states</span> will be reflected in the attributes of the object.
+  <code>UserActivation</code> objects retrieved via <code>MessageEvent</code>'s <code
+  data-x="dom-MessageEvent-userActivation">userActivation</code> attribute will be snapshot objects,
+  that is a snapshot of the source's state.</p>
+
+  <pre><code class="idl" data-x="">[Exposed=(Window,Worker,AudioWorklet)]
+interface <dfn>UserActivation</dfn> {
+  readonly attribute boolean <span data-x="dom-UserActivation-hasBeenActive">hasBeenActive</span>;
+  readonly attribute boolean <span data-x="dom-UserActivation-isActive">isActive</span>;
+};
+
+partial interface <span id="NavigatorUserActivation-partial">Navigator</span> {
+  [SameObject] readyonly attribute <code>UserActivation</code> <span data-x="dom-Navigator-userActivation">userActivation</span>;
+};</code></pre>
+
+  <dl class="domintro">
+
+   <dt><var>navigator</var> . <code subdfn
+   data-x="dom-Navigator-userActivation">userActivation</code></dt>
+
+   <dd>
+
+    <p>Returns the a live object representing the current <span>user activation states</span>.</p>
+
+   </dd>
+
+   <dt><var>userActivation</var> . <code subdfn
+   data-x="dom-UserActivation-hasBeenActive">hasBeenActive</code></dt>
+
+   <dd>
+
+    <p>Returns the state of the <span>sticky activation</span>.</p>
+
+   </dd>
+
+   <dt><var>userActivation</var> . <code subdfn
+   data-x="dom-UserActivation-isActive">isActive</code></dt>
+
+   <dd>
+
+    <p>Returns the state of the <span>transient activation</span>.</p>
+
+   </dd>
+
+  </dl>
+
+  <div w-nodev>
+
+  <p>The <dfn><code data-x="dom-UserActivation-hasBeenActive">hasBeenActive</code></dfn> attribute
+  must return the state of the <span>sticky activation</span>. If the object is live it must
+  always reflect the current state. If the object is a snapshot it must reflect the state at which
+  the time the object was created.</p>
+
+  <p>The <dfn><code data-x="dom-UserActivation-isActive">isActive</code></dfn> attribute must return
+  the state of the <span>transient activation</span>. If the object is live it must always
+  reflect the current state. If the object is a snapshot it must reflect the state at which the time
+  the object was created.</p>
+
+  <p>The <dfn><code data-x="dom-Navigator-userActivation">userActivation</code></dfn> attribute must
+  return a live representation of the <span>user activation states</span>.</p>
+
+  </div>
 
   <h3 id="activation">Activation behavior of elements</h3>
 
@@ -96717,6 +96785,7 @@ interface <dfn>MessageEvent</dfn> : <span>Event</span> {
   readonly attribute DOMString <span data-x="dom-MessageEvent-lastEventId">lastEventId</span>;
   readonly attribute <span>MessageEventSource</span>? <span data-x="dom-MessageEvent-source">source</span>;
   readonly attribute FrozenArray&lt;<span>MessagePort</span>&gt; <span data-x="dom-MessageEvent-ports">ports</span>;
+  readonly attribute <span>UserActivation</span>? <span data-x="dom-MessageEvent-userActivation">userActivation</span>;
 
   void <span data-x="dom-MessageEvent-initMessageEvent">initMessageEvent</span>(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false, optional any data = null, optional USVString origin = "", optional DOMString lastEventId = "", optional <span>MessageEventSource</span>? source = null, optional sequence&lt;<span>MessagePort</span>&gt; ports = []);
 };
@@ -96727,6 +96796,7 @@ dictionary <dfn>MessageEventInit</dfn> : <span>EventInit</span> {
   DOMString lastEventId = "";
   <span>MessageEventSource</span>? source = null;
   sequence&lt;<span>MessagePort</span>&gt; ports = [];
+  <span>UserActivation</span>? userActivation = null;
 };
 
 typedef (<span>WindowProxy</span> or <span>MessagePort</span> or <span>ServiceWorker</span>) <dfn>MessageEventSource</dfn>;</code></pre>
@@ -96779,6 +96849,15 @@ typedef (<span>WindowProxy</span> or <span>MessagePort</span> or <span>ServiceWo
 
    </dd>
 
+   <dt><var>event</var> . <code subdfn data-x="dom-MessageEvent-userActivation">userActivation</code></dt>
+
+   <dd>
+
+    <p>Returns a snapshot of the <code>UserActivation</code> state in the
+    source at the time of <code data-x="dom-window-postMessage">postMessage()</code>.</p>
+
+   </dd>
+
    <!-- initMessageEvent is deprecated -->
 
   </dl>
@@ -96811,6 +96890,10 @@ typedef (<span>WindowProxy</span> or <span>MessagePort</span> or <span>ServiceWo
   value it was initialized to. It represents, in <span>cross-document messaging</span> and
   <span>channel messaging</span>, the <code>MessagePort</code> array being sent.</p>
 
+  <p>The <dfn><code data-x="dom-MessageEvent-userActivation">userActivation</code></dfn> attribute
+  must return the value it was initialized to. It represents the <span>UserActivation</span> state
+  at the source.</p>
+
   <!-- handwavy, file bugs if there are interop issues -->
   <p>The <dfn><code data-x="dom-MessageEvent-initMessageEvent">initMessageEvent()</code></dfn>
   method must initialize the event in a manner analogous to the similarly-named <code
@@ -98751,6 +98834,12 @@ function receiver(e) {
    window, in same-origin cases. See discussion at
    https://github.com/whatwg/html/issues/1542#issuecomment-233502636 -->
 
+   <li><p>Let userActivationSnapshot be null</p></li>
+
+   <li><p>If <var>options</var>'s <code data-x="">includeUserActivation</code> member is true, set
+   userActivationSnapshot to be <var>incumbent settings</var>'s <span>global object</span>'s (if
+   available) <span>user activation states</span>.</p></li>
+
    <li><p>Let <var>targetOrigin</var> be <var>options</var>["<code
    data-x="">targetOrigin</code>"].</p></li>
 
@@ -98824,8 +98913,10 @@ function receiver(e) {
      attribute initialized to <var>origin</var>, the <code
      data-x="dom-MessageEvent-source">source</code> attribute initialized to <var>source</var>, the
      <code data-x="dom-MessageEvent-data">data</code> attribute initialized to
-     <var>messageClone</var>, and the <code data-x="dom-MessageEvent-ports">ports</code> attribute
-     initialized to <var>newPorts</var>.</p></li>
+     <var>messageClone</var>, the <code data-x="dom-MessageEvent-ports">ports</code> attribute
+     initialized to <var>newPorts</var>, and the <code
+     data-x="dom-MessageEvent-userActivation">userActivation</code> attribute initialized to
+     <var>userActivationSnapshot</var>.</p></li>
     </ol>
    </li>
   </ol>
@@ -99140,6 +99231,7 @@ interface <dfn>MessagePort</dfn> : <span>EventTarget</span> {
 
 dictionary <dfn>PostMessageOptions</dfn> {
   sequence&lt;<span data-x="idl-object">object</span>&gt; transfer = [];
+  boolean includeUserActivation = false;
 };</code></pre>
 
   <dl class="domintro">
@@ -99304,6 +99396,14 @@ dictionary <dfn>PostMessageOptions</dfn> {
    <code>MessagePort</code>, then throw a <span>"<code>DataCloneError</code>"</span>
    <code>DOMException</code>.</p></li>
 
+   <li><p>Let userActivationSnapshot be null.</p></li>
+
+   <li><p>Let <var>incumbent settings</var> be the <span>incumbent settings object</span>.</p></li>
+
+   <li><p>If <var>options</var>'s <code data-x="">includeUserActivation</code> member is true, set
+   userActivationSnapshot to be <var>incumbent settings</var>'s <span>global object</span>'s (if
+   available) <span>user activation states</span>.</p></li>
+
    <li><p>Let <var>doomed</var> be false.</p></li>
 
    <li><p>If <var>targetPort</var> is not null and <var>transfer</var> <span data-x="list
@@ -99358,9 +99458,10 @@ dictionary <dfn>PostMessageOptions</dfn> {
      <li><p><span data-x="concept-event-fire">Fire an event</span> named <code
      data-x="event-message">message</code> at <var>finalTargetPort</var>, using
      <code>MessageEvent</code>, with the <code data-x="dom-MessageEvent-data">data</code> attribute
-     initialized to <var>messageClone</var> and the <code
-     data-x="dom-MessageEvent-ports">ports</code> attribute initialized to
-     <var>newPorts</var>.</p></li>
+     initialized to <var>messageClone</var>, the <code data-x="dom-MessageEvent-ports">ports</code>
+     attribute initialized to <var>newPorts</var>, and the <code
+     data-x="dom-MessageEvent-userActivation">userActivation</code> attribute initialized to
+     <var>userActivationSnapshot</var>.</p></li>
     </ol>
    </li>
   </ol>
@@ -99430,6 +99531,11 @@ dictionary <dfn>PostMessageOptions</dfn> {
   message queue</span> must be enabled, as if the <code data-x="dom-MessagePort-start">start()</code>
   method had been called.</p>
 
+  <p>If a  <code>MessagePort</code> object's <code
+  data-x="handler-MessagePort-onmessage">onmessage</code> IDL attribute is set, the port's <span>port
+  message queue</span> must be enabled, as if the <code data-x="dom-MessagePort-start">start()</code>
+  method had been called.</p>
+
   </div>