Re: [w3c/manifest] First pass as adding a Client Hint for Display Mode (#977)

@marcoscaceres commented on this pull request.

Thanks for crafting this @aarongustafson! Looking pretty good.  

I'm wondering if we need to say exactly when this hint is sent (I imagine that must be part of client-hints-infrastructure spec)? Like, how does the user agent know to send it on page load or whatever... 

Once we clean this up a little bit, might be great to have @yoavweiss take a look at it and make sure we have all the right machinery in place.   

> @@ -2409,6 +2409,45 @@ <h4>
         </section>
       </section>
     </section>
+    <section>
+      <h2>
+        Client Hints
+      </h2>
+      <p>
+        Developers often need to know details about how their web app is being
+        rendered in order to make content-negotiation decisions. Though this
+        information is accessible via JavaScript, when sent as part of a
+        {{Request}}, servers are empowered to do the content-negotiation

Request "concept" here: 

```suggestion
       [=request=], servers are empowered to do the content-negotiation
```

> @@ -2409,6 +2409,45 @@ <h4>
         </section>
       </section>
     </section>
+    <section>
+      <h2>
+        Client Hints
+      </h2>
+      <p>

```suggestion
      <p class="note">
```

> +        provides for the following <a data-cite=
+        "client-hints-infrastructure#client-hint-token">client hint token</a>:

```suggestion
        provides for the `Sec-CH-Display-Mode` [=client hint token=]:
```

If client hint token is not exported, we might need to ask that sped to do that. 


> +        rendered in order to make content-negotiation decisions. Though this
+        information is accessible via JavaScript, when sent as part of a
+        {{Request}}, servers are empowered to do the content-negotiation
+        earlier in the process of setting up the web app, before JavaScript
+        execution takes place. To convey this information, this document
+        provides for the following <a data-cite=
+        "client-hints-infrastructure#client-hint-token">client hint token</a>:
+      </p>
+      <ul>
+        <li>`Sec-CH-Display-Mode` whose value is a suitable [=display modes
+        value=]
+        </li>
+      </ul>
+      <section>
+        <h3>
+          The 'Sec-CH-Display-Mode' Header Field

Why "Sec-"? I presume "Sec-" stands for "Security", but I'm not sure how display mode relates to security? Maybe it should just be `CH-Display-Mode` or is that not how client hints are specified?  

> +          The <dfn data-export="" data-lt=
+          "display mode client hint">Sec-CH-Display-Mode</dfn> request header

Let's not export it until someone needs it: 

```suggestion
          The <dfn data-local-lt=
          "display mode client hint">Sec-CH-Display-Mode</dfn> request header
```


> +        <h3>
+          The 'Sec-CH-Display-Mode' Header Field
+        </h3>
+        <p>
+          The <dfn data-export="" data-lt=
+          "display mode client hint">Sec-CH-Display-Mode</dfn> request header
+          field gives a server information about the [=display mode=] in which
+          the user agent plans to display the web app. It is a <a data-cite=
+          "rfc8941#section-3">Structured Header</a> whose value MUST be a valid
+          <a data-cite="rfc8941#section-3.3.3">string</a>.
+        </p>
+        <p>
+          The header's ABNF is:
+        </p>
+        <pre>
+          Sec-CH-Display-Mode = sf-string

This should probably be
```suggestion
          Sec-CH-Display-Mode = "fullscreen" / "standalone" / "minimal-ui" / "browser"
```

> +        </li>
+      </ul>
+      <section>
+        <h3>
+          The 'Sec-CH-Display-Mode' Header Field
+        </h3>
+        <p>
+          The <dfn data-export="" data-lt=
+          "display mode client hint">Sec-CH-Display-Mode</dfn> request header
+          field gives a server information about the [=display mode=] in which
+          the user agent plans to display the web app. It is a <a data-cite=
+          "rfc8941#section-3">Structured Header</a> whose value MUST be a valid
+          <a data-cite="rfc8941#section-3.3.3">string</a>.
+        </p>
+        <p>
+          The header's ABNF is:

```suggestion
          The header's <abbr title="Augmented BNF for Syntax">ABNF</abbr>, as per [[rfc5234]], is:
```

> +      <section>
+        <h3>
+          The 'Sec-CH-Display-Mode' Header Field
+        </h3>
+        <p>
+          The <dfn data-export="" data-lt=
+          "display mode client hint">Sec-CH-Display-Mode</dfn> request header
+          field gives a server information about the [=display mode=] in which
+          the user agent plans to display the web app. It is a <a data-cite=
+          "rfc8941#section-3">Structured Header</a> whose value MUST be a valid
+          <a data-cite="rfc8941#section-3.3.3">string</a>.
+        </p>
+        <p>
+          The header's ABNF is:
+        </p>
+        <pre>

```suggestion
        <pre class="abnf">
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/pull/977#pullrequestreview-656212093