Adding field `display_override` to the manifest #932

dmurph · 2020-07-28T18:19:35Z

Status

Since there were no other implementers that could comment on this, it has been moved into the manifest-incubations spec location.

Pull Request

Closes #???
I'm not sure there is one, but it is related to #856 and could close that - but that issue also goes over some other pieces that this change doesn't solve for yet.

This change (choose at least one, delete ones that don't apply):

Adds new normative recommendations or optional items

Implementation commitment (delete if not making normative changes):

Safari (link to issue)
Chrome (link to issue): https://bugs.chromium.org/p/chromium/issues/detail?id=1092667
Firefox (link to issue)
Edge (public signal): https://bugs.chromium.org/p/chromium/issues/detail?id=1092667 (they are doing the implementation work)

If change is normative, and it adds or changes a member:

updated JSON schema

I have not done this yet - should I do this before this request is filed?

Commit message:

Adds the "display_override" manifest field.

This field allows the developer to override the "display" field with a custom fallback chain. It is designed to be both future- and backwards-compatible, and is basically just a logic/algorithm change on how a user agent should determine the requested display mode.

This change also creates an explicit algorithm for determining the display mode, and provides a few new examples using "display_override".

See explainer here:
https://github.com/WICG/display-override/blob/master/explainer.md

TAG Review:
w3ctag/design-reviews#530

Webkit position request:
https://lists.webkit.org/pipermail/webkit-dev/2020-October/031435.html

Mozilla position request:
mozilla/standards-positions#447

Person merging, please make sure that commits are squashed with one of the following as a commit message prefix:

chore:
editorial:
BREAKING CHANGE:
And use none if it's a normative change

Preview | Diff

dmurph · 2020-07-28T18:45:07Z

@mgiuca can you PTAL?

Note - this is definitely a 'draft' in the sense that I've never done a spec pull request here - sorry if there are a bunch of mistakes here! I would love guidance

index.html

mgiuca

Hi Daniel,

Great! Thanks for submitting this PR and getting your feet wet!

I've put a number of comments. My review was somewhat hasty so I didn't give you the precise syntax or wording in a lot of my suggestions, but I think you can figure it out and ping me if you need exact suggested wording or syntax advice.

Apologies: As I said in one of the comments, it's a bit hard to cargo-cult the syntax from elsewhere in this file, since Respec changed the syntax since this was written.

Also I think you already found this, but the language that these algorithms is written in is HTML Infra; it's a semi-formal language and we should try to follow those conventions rather than just writing English pseudo-code.

Cheers!

Matt

mgiuca · 2020-07-29T07:44:06Z

index.html

+              "sizes": "128x128"
+            }],
+            "start_url": "/index.html",
+            "display_override": ["minimal-ui", "standalone"],


I'm not quite clear on what this site's intentions are (maybe make that more clear in the description above).

They want minimal-ui, but if that's not supported fall back to standalone, but if display-override isn't supported, fall back to browser? I don't really see why you'd ever want this.

Wouldn't they either want display-override: minimal, standalone, and display: minimal, or display-override: minimal, display: standalone?

ah, yes you're right

Please resolve :-)

Thanks for pinging, fixed.

index.html

dmurph · 2020-07-29T22:41:38Z

Thanks for the reviews!

I'm not exactly sure how to use github pull request tool to respond to comments, hopefully I did that in an acceptable way

Can you please take a look again?

mgiuca · 2020-07-30T06:38:18Z

Hi,

Yeah GitHub review tool is a big mess; I find it very hard to reply to everything and very easy to lose comments.

I'll do a full review tomorrow; for now just responded to your direct question.

dmurph · 2020-08-03T19:43:25Z

Gentle ping on this request - @mgiuca do you mind giving this another review?

mgiuca

Thanks Daniel. Looking great now.

A few minor comments, and then a suggestion to rewrite the algorithm which you can either accept or reject. Not sure which is cleaner, so have a think about it.

And a good weekend!

index.html

mgiuca · 2020-08-07T06:28:59Z

index.html

+            [=iteration/while=] |considering_display_mode| is not {{browser}}
+            <ol>
+              <li>
+                If the user agent supports the |candidate_display_mode|, then


I'm thinking about this while loop. I think it's correct but it's still a bit messy to do a loop with a switch in it when essentially you're just doing a linear scan through a list.

How's this (thinking out loud ... this might be messier, feel free to ignore this and keep the while loop).

First, some definitions:

The fallback chain for browser is [browser].

The fallback chain for minimal-ui is [minimal-ui] + the fallback chain for browser.

The fallback chain for standalone is [standalone] + the fallback chain for minimal-ui.

The fallback chain for fullscreen is [fullscreen] + the fallback chain for standalone.

(Or you could explicitly spell out the full fallback chain for each mode.)

Then, in the algorithm:

First thing you do is go "the display fallback chain is display_override + the fallback chain for display".

For each candidate of display fallback chain, if the user agent supports candidate, return it.

(Effectively, you combine the entire fallback chain into a single list combining both fields, just like you do in the explainer, and scan over it in one general iteration.)

WDYT?

Let me know what you think of the changes :)

dmurph · 2020-08-10T21:10:19Z

Thanks for the review! Please take a look again at the changes :)

index.html

mgiuca · 2020-08-12T23:56:07Z

index.html

+            </ol>
+          </li>
+          <li>
+            Define the |fallback_chain| for {{browser}} to be [{{browser}}]


Don't make fallback_chain a variable, since it doesn't act like a variable, it's more like a concept (strictly speaking, you could think of it as a function, fallback_chain(display_mode) = ..., but I think it's not worth being so formal about it).

So I think move these definitions outside of this algorithm, and express them just in plain English: "The fallback chain for browser is «browser»"., etc. (Note: Use «» to denote a literal list, not, [], per Infra.)

Then down below, replace "the fallback_chain of" with "the fallback chain of" and you're good.

I put this above in the text - hopefully it reads ok?

index.html

mgiuca · 2020-08-13T00:16:53Z

@marcoscaceres I think this is close to being ready from a technical standpoint. Can we get a commitment to implement it in Firefox?

@hober I'm not sure if you or anyone from Safari has reviewed this proposal yet. (See the WICG proposal; TAG review). This is just a change to the manifest parser, and doesn't directly involve implementation of new features (though it enables a path to adding new display modes). Do you have any objections, and would Safari be able to commit to implementing this parser change?

(Daniel, could you link to the TAG review from the PR description?)

dmurph · 2020-09-09T22:17:44Z

Updated patch with Matt's comments. It looks like there is an error with something unrelated to my change, but hopefully it is still reviewable?

@hober, @marcoscaceres, can you PTAL? This change is required for future display modes, like tabbed & custom window overlay.

dmurph · 2020-09-09T22:32:24Z

as you can see, I'm struggling with rebasing my fork with changes from here. Any advice appreciated lol. It seems to really want to apply those chore changes in my patch 🤷

mgiuca

Great work, Daniel! Sorry this has been so long in the making.

I've approved but added some minor comments. One is a type problem we're going to have in the future, but isn't currently a problem, so I've added a long comment but the effect of it is just to add a note about it, for now.

index.html

mgiuca · 2020-09-18T04:20:30Z

index.html

+          </li>
+          <li>
+            [=list/For each=] |fallback_mode:DisplayModeType| of the
+            fallback_chain of |manifest|.{{WebAppManifest/display}}:


Remove the underscore in "fallback_chain" since this is a prose term defined above without an underscore.

And link to the above definition (see above comment to use <dfn>). I think you can use {{fallback chain}} for this. Or maybe [=fallback chain=]. I usually guess until it works :)

index.html

mgiuca · 2020-09-18T04:28:34Z

index.html

@@ -1044,6 +1110,7 @@ <h2>
             DOMString iarc_rating_id;
             USVString start_url;
             DisplayModeType display = "browser";
+             sequence&lt;DisplayModeType&gt; display_override;


I just thought of a problem (which is not a problem right now, but will be as soon as we add a new display mode): we need a way to say for new display modes that they are allowed in display_override but not display.

We either need to do this in the type system (so it is type-impossible to use, say, "display": "tabbed", but you can use "display_override": ["tabbed"]), or have steps in the algorithm to fail if you use a "new" display mode in display. My preference is the former.

I think what we should do is have two enums, for now let's just call them "DisplayModeType" and "EnhancedDisplayModeType". The IDL should have:

DisplayModeType display = "browser"; sequence<DisplayModeType or EnhancedDisplayModeType> display_override;

And never put a new value in DisplayModeType.

That allows you to use the new ones in display_override but not display, and we don't need to mention this in the algorithms at all. Does that sound good? We could also rename the old one to LegacyDisplayModeType or something, I don't really mind.

If we do that now, EnhancedDisplayModeType will be empty, so maybe we just add a note to do that in the future? Let's add a note just under the listing of DisplayModeType's possible values, that no new values will be added to this, and future display modes will be added to a new enum that can only be used with display_override but not display, for forwards-compatibility reasons.

Sound good, I'll add a note about this under the DisplayModeType's possible values, saying:

No new values will be added to this enum, and instead future display modes will be added to a new enum that can only be used with display_override but not display, for forwards-compatibility reasons. display_override will then be defined as sequence<DisplayModeType or EnhancedDisplayModeType>, assuming the new enum is named EnhancedDisplayModeType.

Sounds good. Maybe reword it so it reads more easily: "will be added to a new enum, tentatively named EnhancedDisplayModeType, ..." and then you can remove the "assuming" qualifier to the last sentence.

Based on internal implementation experience, it will be much easier to present this as the other option, where the algorithm fails for any 'new' display mode in display. What do you think about that?

I made a note under the algorithm:

In the future, new values added to {{DisplayModeType}} will not be added to the fallback chain, and the algorithm should treat the a {{WebAppManifest/display}} field set to a new value as {{browser}}.

And a note in DisplayModeType:

index.html

Feedback provided in a different CL (2375597: dpwas: Add window-controls-overlay as a new display mode | https://chromium-review.googlesource.com/c/chromium/src/+/2375597) and in w3c/manifest#932 is that we need a way to say new display modes are allowed in display_override but not display. The plan is to introduce a new enum EnhancedDisplayMode, and display_override should be: sequence<DisplayModeType or EnhancedDisplayModeType>. To support that, this CL deprecates the existing display_override field, and renames it. Renaming here should be fine, as long as we don't use JSON serialization. Once the new field has landed, we will remove this field, and mark it reserved so that future users don't reuse the field. Explainer: https://github.com/WICG/display-override/blob/master/explainer.md Design document: https://docs.google.com/document/d/1hEmbGVHMN38q1YTaaGccQ-Y5CHr7xIURYPRWXTuvZLo/edit?usp=sharing I2P: https://groups.google.com/a/chromium.org/d/topic/blink-dev/WvIeZT8uSzw/discussion Manifest w3c PR: w3c/manifest#932 Bug: 1092667 Change-Id: Ifbc0160a88263d4994d138f99921371ceea2bcb8 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2436417 Commit-Queue: Mike Jackson <mjackson@microsoft.com> Reviewed-by: Alexey Baskakov <loyso@chromium.org> Reviewed-by: Daniel Murphy <dmurph@chromium.org> Cr-Commit-Position: refs/heads/master@{#811932}

This reverts commit 3ce0075. Reason for revert: Keeping single enum Original change's description: > dpwas: deprecate existing display_overrides field in proto > > Feedback provided in a different CL (2375597: dpwas: Add > window-controls-overlay as a new display mode | > https://chromium-review.googlesource.com/c/chromium/src/+/2375597) > and in w3c/manifest#932 is that we need a > way to say new display modes are allowed in display_override but > not display. > > The plan is to introduce a new enum EnhancedDisplayMode, and > display_override should be: > sequence<DisplayModeType or EnhancedDisplayModeType>. > > To support that, this CL deprecates the existing display_override field, > and renames it. Renaming here should be fine, as long as we don't use > JSON serialization. Once the new field has landed, we will remove > this field, and mark it reserved so that future users don't reuse > the field. > > Explainer: https://github.com/WICG/display-override/blob/master/explainer.md > Design document: https://docs.google.com/document/d/1hEmbGVHMN38q1YTaaGccQ-Y5CHr7xIURYPRWXTuvZLo/edit?usp=sharing > I2P: https://groups.google.com/a/chromium.org/d/topic/blink-dev/WvIeZT8uSzw/discussion > Manifest w3c PR: w3c/manifest#932 > > Bug: 1092667 > Change-Id: Ifbc0160a88263d4994d138f99921371ceea2bcb8 > Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2436417 > Commit-Queue: Mike Jackson <mjackson@microsoft.com> > Reviewed-by: Alexey Baskakov <loyso@chromium.org> > Reviewed-by: Daniel Murphy <dmurph@chromium.org> > Cr-Commit-Position: refs/heads/master@{#811932} TBR=dmurph@chromium.org,loyso@chromium.org,mjackson@microsoft.com Change-Id: Ie953a019c6c9d0dc7e90ea2fcf639325460e8e11 No-Presubmit: true No-Tree-Checks: true No-Try: true Bug: 1092667 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2441147 Reviewed-by: Daniel Murphy <dmurph@chromium.org> Commit-Queue: Daniel Murphy <dmurph@chromium.org> Cr-Commit-Position: refs/heads/master@{#812127}

dmurph · 2020-10-29T19:14:21Z

I just responded to all comments, ready for review :)

mgiuca · 2020-10-30T05:10:01Z

FYI this was discussed at TPAC 2020, minuted here:

https://www.w3.org/2020/10/26-webapps-minutes.html#t07

(I wasn't present.)

Just wanted to address:

@slightlyoff : to @NotWoods point, supporting a valid value in either location seems like a good "v2" solution

There is a detailed discussion on this here.

We explicitly didn't want to support non-legacy values in display, because that would not be backwards compatible with older browsers. Two options we considered:

Allow display to have the new modes as an option. e.g., "display": "window_controls_overlay". But if you're a browser that doesn't know about "tabbed", you have to interpret this as "browser", which means developers may accidentally create an experience that has a fancy overlay on supported browsers, and literally doesn't show any window at all on browsers that don't support WCO.
Allow display to have either a string or an array, allowing you to specify the fallback chain directly in there. Again, a legacy browser won't know what to do with the array, so it will just fall back to browser.

If we let developers put the new values in either display or display_override, then they can work around this backwards compatibility problem by always putting the new values in display_override, and never in display. But we're providing a footgun by letting them put new values in display: if you ever use it, you will see the correct behaviour on your shiny new browser, but incorrect behaviour on the older browser you forgot to test in.

That is why we're proposing to only allow the new values in display_override, and not allow any new values to be allowed in display.

NotWoods · 2020-10-30T05:59:33Z

I'm OK with not allowing new values in display. The resolution from TPAC was that implementors would allow display to be omitted if display_override is present, allowing it to work like a display v2. I'm concerned about how to teach this to a new dev who isn't concerned about the backwards compat, and requiring two separate display fields makes it more confusing.

dmurph · 2020-10-30T16:19:25Z

FYI @marcoscaceres today is the last day for us to bikeshed on the name :)

mgiuca · 2020-11-13T02:59:07Z

The resolution from TPAC was that implementors would allow display to be omitted if display_override is present, allowing it to work like a display v2.

I think that wouldn't be good for compat until all browsers are implementing display_override (which is why we designed it as an override, not as a v2). Otherwise, a developer tests against, say, Chrome, uses display_override without considering browsers that aren't implementing it, and it doesn't behave properly on those other browsers. I think we should make it mandatory now, and we can address it again in a year or so, removing the need to have a display which would be backwards-compatible.

This isn't getting a lot of attention, and I'd like to set a deadline to land it in the Manifest spec. If not, I think we should move this into a WICG repo so that we can point to it without having to refer to this PR. @NotWoods are you planning to implement this in Gecko? If so, I think we can take that as a sign of multi-vendor interest, and land this as-is.

If we only have Chromium on board, then we should move it into WICG.

Should we set a deadline of EOD Friday November 20, to get approvals on this PR?

NotWoods · 2020-11-14T06:56:17Z

@marcoscaceres is usually the one who handles Gecko implementation, I'll defer to him.

I'm OK with adjusting the requirements later, especially since installablity criteria is not defined in the spec anyways.

marcoscaceres · 2021-03-05T05:14:10Z

index.html

@@ -1374,6 +1449,25 @@ <h3>
          developer's preferred <a>display mode</a> for the web application.
        </p>
      </section>
+      <section>
+        <h3>
+          <code>display_override</code> member


Suggested change

<code>display_override</code> member

`display_override` member

marcoscaceres · 2021-03-05T05:25:18Z

If this is a multi-os / multi-browser feature, I think it might be ok to take this on. Can someone verify for me that this works across, say, Chrome (OS?) and Edge with Windows integration? For a feature such as this, I think we can probably argue that OS level integration counts enough as an independent implementation... although we should look at if the Edge/Chrome implementations are truly independent.

@dmurph, please note that I've removed all the WebIDL from the spec, so this needs some editorial cleanup to get it align with the new stuff in the spec.

dmurph · 2021-03-08T19:39:07Z

So this patch is a bit old - I've since put the spec language in here:
https://github.com/WICG/manifest-incubations
and then landed an editorial change to put an extension point in the display algorithm.

and it looks like the references there are now broken too lol. Cost of having an incubations spec I guess.

If we feel like this should live in w3c/manifest, then I'm super happy to move it into here. We haven't received signals from FF or Safari, and IDK how Edge is being treated now that they are based on Chromium.

marcoscaceres · 2021-03-09T06:21:40Z

We haven't received signals from FF or Safari, and IDK how Edge is being treated now that they are based on Chromium.

Yeah, it would be good to get another engine onboard before we add this.

diekus · 2021-07-05T19:03:17Z

Hola! Saw this discussion and wanted to ping interested parties as I am looking into adding the "window-controls-overlay" into the display-override, but I am a bit confused as to why this is not in the manifest per se? Should we consider again adding display override to the main spec? What are the parameters that are being taken into account for not allowing it in? I'm thinking it might be confusing to have display in but display-override not, even though their functionalities are highly linked. Also, similar to @NotWoods , it might be confusing for new devs (tbf it is confusing for me atm)?

To followup on @dmurph 's comments, I have checked with FF and Webkit on positions for WCO and have not gotten any signs of life from either, and I am concerned that for many upcoming features related to installed Web apps on desktop everything will be thrown into the 'incubations' bag?

I kinda get that it is because there is no other implementation(-ish?), but oddly enough, unless I am mistaken it seems that shortcuts](https://caniuse.com/?search=shortcut)" is not implemented in other engines either yet is in the manifest spec?

Adding manual WPT tests for new display-override field. PR to add new field to manifest spec is here: w3c/manifest#932 Bug: 1149993 Change-Id: I670c69737e337a4c13e35672daa93e703f97b84e

Adding manual WPT tests for new display-override field. PR to add new field to manifest spec is here: w3c/manifest#932 Bug: 1149993 Change-Id: I670c69737e337a4c13e35672daa93e703f97b84e Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3166014 Commit-Queue: Mike Jackson <mjackson@microsoft.com> Reviewed-by: Daniel Murphy <dmurph@chromium.org> Cr-Commit-Position: refs/heads/main@{#922341}

…sts, a=testonly Automatic update from web-platform-tests dpwas: Add display_override tentative tests Adding manual WPT tests for new display-override field. PR to add new field to manifest spec is here: w3c/manifest#932 Bug: 1149993 Change-Id: I670c69737e337a4c13e35672daa93e703f97b84e Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3166014 Commit-Queue: Mike Jackson <mjackson@microsoft.com> Reviewed-by: Daniel Murphy <dmurph@chromium.org> Cr-Commit-Position: refs/heads/main@{#922341} -- wpt-commits: 351e54723427bcdcf0c1e75bcf10a5d221cf86ce wpt-pr: 30826

Adding manual WPT tests for new display-override field. PR to add new field to manifest spec is here: w3c/manifest#932 Bug: 1149993 Change-Id: I670c69737e337a4c13e35672daa93e703f97b84e Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3166014 Commit-Queue: Mike Jackson <mjackson@microsoft.com> Reviewed-by: Daniel Murphy <dmurph@chromium.org> Cr-Commit-Position: refs/heads/main@{#922341}

Adding manual WPT tests for new display-override field. PR to add new field to manifest spec is here: w3c/manifest#932 Bug: 1149993 Change-Id: I670c69737e337a4c13e35672daa93e703f97b84e Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3166014 Commit-Queue: Mike Jackson <mjackson@microsoft.com> Reviewed-by: Daniel Murphy <dmurph@chromium.org> Cr-Commit-Position: refs/heads/main@{#922341} NOKEYCHECK=True GitOrigin-RevId: 7e650a5a28936cfe05fe9231614f056fd011bc12

marcoscaceres reviewed Jul 29, 2020

View reviewed changes

index.html Outdated Show resolved Hide resolved

marcoscaceres reviewed Jul 29, 2020

View reviewed changes

index.html Outdated Show resolved Hide resolved

mgiuca reviewed Jul 29, 2020

View reviewed changes

mgiuca reviewed Aug 7, 2020

View reviewed changes

mgiuca reviewed Aug 13, 2020

View reviewed changes

dmurph force-pushed the gh-pages branch 3 times, most recently from 7167668 to 99288ca Compare September 9, 2020 22:31

dmurph force-pushed the gh-pages branch from 99288ca to 27f2859 Compare September 17, 2020 17:27

mgiuca approved these changes Sep 18, 2020

View reviewed changes

kenchris mentioned this pull request Sep 22, 2020

Window Controls Overlay for Installed Desktop Web Apps w3ctag/design-reviews#481

Closed

1 task

dmurph mentioned this pull request Oct 2, 2020

Standards position request: display_override in WebManifest mozilla/standards-positions#447

Open

dmurph mentioned this pull request Oct 19, 2020

TPAC planning and specification status report #906

Closed

marcoscaceres self-requested a review October 26, 2020 21:53

dmurph force-pushed the gh-pages branch 2 times, most recently from 6290db1 to 76f5ec1 Compare October 29, 2020 19:13

mwjacksonmsft mentioned this pull request Nov 18, 2020

[appmanifest] add display-override member tests web-platform-tests/wpt#26567

Closed

marcoscaceres reviewed Mar 5, 2021

View reviewed changes

aarongustafson mentioned this pull request May 25, 2021

First pass as adding a Client Hint for Display Mode #977

Open

4 tasks

dmurph closed this Sep 1, 2021

dmurph force-pushed the gh-pages branch from a70561e to e127fd7 Compare September 1, 2021 22:42

chromium-wpt-export-bot mentioned this pull request Sep 16, 2021

dpwas: Add display_override tentative tests web-platform-tests/wpt#30826

Merged

	<code>display_override</code> member
	`display_override` member

Adding field display_override to the manifest #932

Adding field display_override to the manifest #932

Conversation

dmurph commented Jul 28, 2020 • edited by pr-preview bot

Status

Pull Request

dmurph commented Jul 28, 2020

mgiuca left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmurph commented Jul 29, 2020

mgiuca commented Jul 30, 2020

dmurph commented Aug 3, 2020

mgiuca left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmurph commented Aug 10, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mgiuca commented Aug 13, 2020

dmurph commented Sep 9, 2020

dmurph commented Sep 9, 2020

mgiuca left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmurph commented Oct 29, 2020

mgiuca commented Oct 30, 2020

NotWoods commented Oct 30, 2020

dmurph commented Oct 30, 2020

mgiuca commented Nov 13, 2020

NotWoods commented Nov 14, 2020

Choose a reason for hiding this comment

marcoscaceres commented Mar 5, 2021

dmurph commented Mar 8, 2021

marcoscaceres commented Mar 9, 2021

diekus commented Jul 5, 2021

Adding field `display_override` to the manifest #932

Adding field `display_override` to the manifest #932

dmurph commented Jul 28, 2020 •

edited by pr-preview bot