Determining the chosen display mode

The following steps are added to the [=application manifest/processing extension-point=] in determining the web app's chosen display mode, which now also takes an optional [=URL=] |document URL|:

1. [=list/For each=] |entry:display override entry| of |manifest:ordered map|'s [=manifest/display_override=] member:
   1. Let |candidate display mode| be null.
   2. If |entry| is a [=display mode=]:
      1. Set |candidate display mode| to |entry|.
   3. Else if |entry| is a [=DisplayOverrideEntryObject=]:
      1. If |entry|'s [=DisplayOverrideEntryObject/url_patterns=] [=list/is empty=]:
         1. Set |candidate display mode| to |entry|'s [=DisplayOverrideEntryObject/display=].
      2. Else if |document URL| is not null:
         1. [=list/For each=] |pattern| of |entry|'s [=DisplayOverrideEntryObject/url_patterns=]:
            1. If |pattern| [=URL pattern/matches=] |document URL|, set |candidate display mode| to |entry|'s [=DisplayOverrideEntryObject/display=] and [=iteration/break=].
   4. If |candidate display mode| is null, [=iteration/continue=].
   5. If display modes list contains |candidate display mode|, return that |candidate display mode|.
   6. If |candidate display mode| is [=display mode/window-controls-overlay=] and the [=user agent=] supports this, then return that |candidate display mode|.
   7. If |candidate display mode| is [=display mode/tabbed=] and the [=user agent=] supports this, then return that |candidate display mode|.
   8. If |candidate display mode| is [=display mode/unframed=], the [=user agent=] supports this, and the application is an Isolated Web Application [[isolated-web-apps]], then return that |candidate display mode|.

Processing the `display_override` member

To process the `display_override` member, given [=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|, and [=URL=] |manifest URL:URL|, run the following:

1. Set |manifest|["display_override"] to a new [=list=].
2. If |json|["display_override"] does not [=map/exist=], return.
3. If |json|["display_override"] is not a [=list=], return.
4. Let |processed display override:list| be a new [=list=].
5. [=list/For each=] |entry| of |json|["display_override"]:
   1. If |entry| is a [=string=]:
      1. If the display modes list (including [=display mode extensions|extensions=]) contains |entry|, [=list/append=] |entry| to |processed display override|.
   2. Else if |entry| is an [=ordered map=]:
      1. If |entry|["display"] does not [=map/exist=] or is not a [=string=], [=iteration/continue=].
      2. If the display modes list (including [=display mode extensions|extensions=]) does not contain |entry|["display"], [=iteration/continue=].
      3. If the [=user agent=] does not support URL patterns for |entry|["display"], [=iteration/continue=].
      4. Let |override object| be a new [=DisplayOverrideEntryObject=] with its [=DisplayOverrideEntryObject/display=] set to |entry|["display"].
      5. If |entry|["url_patterns"] [=map/exists=]:
         1. If |entry|["url_patterns"] is not a [=list=], [=iteration/continue=].
         2. [=list/For each=] |pattern entry| of |entry|["url_patterns"]:
            1. Let |pattern:URL pattern| be the result of [=build a URL pattern from an infra value=] given |pattern entry| and |manifest URL|. If this process throws or returns null, [=iteration/continue=].
            2. [=list/append=] |pattern| to |override object|'s [=DisplayOverrideEntryObject/url_patterns=].
      6. [=list/append=] |override object| to |processed display override|.
6. Set |manifest|["display_override"] to |processed display override|.

Concepts

• Window controls: interface elements that the operating system uses consistently across applications to enable the user to perform certain actions to control the application. Common actions in the [=window controls=] include minimize, maximize/restore, and close buttons.
• Window frame: The host-native decorations, including borders, title bar, and window controls, that surround the web contents of an application window.

Display mode extensions

Additionally to the normal display modes, [=manifest/display_override=] also supports certain display mode extensions.

[=display mode/unframed=]

The app window is [=display mode/unframed=], meaning it does not have a [=Window frame=]. It does not have any host-native title bar, and [=window controls=] are not visible. Web contents extend to the entire window area. [=display mode/Unframed=] is restricted to [[[isolated-web-apps]]].

[=display mode/window-controls-overlay=]

The app window has a [=display mode/window-controls-overlay=] instead of regular [=window controls=].

tabbed

The web application can have multiple [=application contexts=] combined in a single operating-system-level window. For example, this could mean the user agent displays a tab strip UI to allow the user to switch between the application contexts.

            {
              "name": "Recipe Zone",
              "description": "All of the recipes!",
              "icons": [{
                "src": "icon/hd_hi",
                "sizes": "128x128"
              }],
              "start_url": "/index.html",
              "display_override": ["minimal-ui"],
              "display": "standalone",
              "theme_color": "yellow",
              "background_color": "red"
            }
          

unframed display mode

The [=display mode/unframed=] display mode enables [[[isolated-web-apps]]] to have full control over the appearance of the app window, including the title bar area.

A window in [=display mode/unframed=] does not have any host-native title bar or [=window controls=] visible, and the web contents are extended to the whole window area. The app can specify [=draggable regions=] in the web contents to create a customized title bar.

[=User agents=] MUST restrict the use of [=display mode/unframed=] to [[[isolated-web-apps]]].

Once an [=display mode/unframed=] window has been created, its display mode is fixed for the lifetime of the window. The [=user agent=] MUST NOT allow navigation to out-of-scope URLs to take place within the unframed window.

Visual Example

The following figures illustrate the visual difference between a standard web application window and one utilizing the [=display mode/unframed=] display mode. The regular app window (left) includes the host-native title bar and standard window controls. In contrast, the unframed app window (right) removes these host-provided frame decorations, allowing the web contents to occupy the entire window area.

            @media (display-mode: unframed) {
              /* styles for unframed mode */
            }
          

Defining draggable regions

The `app-region` property can be used to define with CSS which regions or elements in for example a title bar are draggable.

• To enable dragging an element, shall be set to `drag`.
• To disable dragging an element, shall be set to `no-drag`.

The `app-region` property MUST only take effect when the applied [=display mode=] of the window is [=display mode/unframed=] or [=display mode/window-controls-overlay=].

home_tab member

The `home_tab` member of the [=tab_strip=] object is an ordered map that contains information about a special "home tab" that is intended to serve as the top-level menu for the application. It contains the following members:

• [=home_tab/scope_patterns=]

The scope_patterns member is a list of {{URLPatternInput}}s that define the [=within home tab scope|scope of the home tab=] relative to the [=manifest URL=].

An application has a home tab if the applied [=display mode=] of the application is [=display mode/tabbed=], and the [=Document/processed manifest=] includes a non-null [=home_tab=] member of the [=tab_strip=] member.

The home tab context is an optional [=application context=] that has special properties compared to other application contexts. If the application [=has a home tab=], every application window SHOULD feature a [=home tab context=]. If not, then the application windows SHOULD NOT have a [=home tab context=].

How the [=home tab context=] is presented is at the discretion of the user agent, but it SHOULD have a different appearance to normal application contexts.

A [=URL=] |url:URL| is said to be within home tab scope if and only if:

• the application [=has a home tab=], and
• |url| is [=manifest/within scope=] of the manifest, and
• at least one of the following:
  • |url| [=URL/equals=] the [=start URL=], with [=URL/equals/exclude fragments=] set to true, or
  • Applying [=URL pattern/match=] given any element of the [=scope_patterns=] member of the [=home_tab=] member of the [=tab_strip=] member of the [=Document/processed manifest=] and |url| returns a {{URLPatternResult}}.

A URL is is outside of home tab scope if it is not [=within home tab scope=].

new_tab_button member

The [=tab_strip/new_tab_button=] member is an ordered map that describes the behaviour of a UI affordance (such as a button) which, when clicked/activated, opens a new [=application context=] within the application window. It has the following members:

• [=new_tab_button/url=]

The url member is a string that represents a URL relative to the [=manifest URL=] that is [=manifest/within scope=] of a [=Document/processed manifest=].

An application has a new tab button if the [=Document/processed manifest=]'s [=new_tab_button=]'s [=new_tab_button/url=] member is [=outside of home tab scope=]. If the application does not [=has a new tab button|have a new tab button=], the user agent SHOULD NOT make the "new tab" affordance available to the end user.

When the new tab button is activated by the end user, the following steps are run:

1. [=Create a new application context=] in the current window and focus it.
2. Navigate it to the value of the [=new_tab_button/url=] member of [=new_tab_button=].

Processing the `tab_strip` member

To process the `tab_strip` member, given [=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|, and [=URL=] |manifest URL:URL|, run the following during the extension point in [=processing a manifest=]:

1. Set |manifest|["tab_strip"] to a new [=ordered map=].
2. If |json|["tab_strip"] does not exist or |json|["tab_strip"] is not an [=ordered map=]:
   1. Set |manifest|["tab_strip"]["new_tab_button"]["url"] to |manifest|["start_url"].
   2. Return.
3. [=Process the `home_tab` member=] passing |json|["tab_strip"], |manifest|["tab_strip"], and |manifest URL|.
4. [=Process the `new_tab_button` member=] passing |json|["tab_strip"], |manifest|["tab_strip"], |manifest URL|, and |manifest|["start_url"].

new_note_url member

The [=note_taking=] `new_note_url` member is a [=string=] that represents the URL the developer would prefer the user agent load when the user wants to take a new note using the web application (e.g., from an operating system shortcut icon or keyboard shortcut).

The `new_note_url` member is purely advisory, and a user agent MAY ignore it or provide the end-user the choice of whether to use it. The user agent MAY provide the end-user the choice to modify it.

Processing the `note_taking` member

To process the `note_taking` member, given [=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|, [=URL=] |manifest_URL:URL|, run the following during the extension point in [=processing a manifest=]:

1. If |json|["note_taking"] does not [=map/exist=], return.
2. If the type of |json|["note_taking"] is not [=ordered map=], return.
3. Set |manifest|["note_taking"] to a new [=ordered map=].
4. [=process the `new_note_url` member=] passing |json|["note_taking"], |manifest|["note_taking"], and |manifest URL|.

Processing the `new_note_url` member

To process the `new_note_url` member, given [=ordered map=] |json_note_taking:ordered map|, [=ordered map=] |manifest_note_taking:ordered map|, [=URL=] |manifest_URL:URL|, run the following:

1. If |json_note_taking|["new_note_url"] does not [=map/exist=], return.
2. If the type of |json_note_taking|["new_note_url"] is not [=string=], return.
3. Let |new_note_url:URL| be the result of [=URL Parser|parsing=] |json_note_taking|["new_note_url"] with |manifest URL| as the base URL.
4. If |new_note_url| is failure, return.
5. If |new_note_url| is not [=manifest/within scope=] of |manifest URL|, return.
6. Set manifest_note_taking["new_note_url"] to |new_note_url|.

Launching the `new_note_url`

To launch the `new_note_url`, given processed manifest |manifest:processed manifest|, run the following steps:

1. If |manifest|["note_taking"] does not [=map/exist=], return.
2. If |manifest|["note_taking"]["new_note_url"] does not [=map/exist=], return.
3. If the type of |manifest|["note_taking"]["new_note_url"] is not [=URL=], return.
4. Run the steps to [=launch a web application=] setting |manifest| to |manifest| and |target URL| to |manifest|["note_taking"]["new_note_url"].

The user agent MAY [=launch the `new_note_url`=] for a given [=installed web application=] at any time, typically in response to a user affordance.

Processing the `protocol_handlers` member

To process the `protocol_handlers` member, given [=object=] |json:JSON|, |manifest:ordered map|:

1. Let |processedProtocolHandlers| be a new [=list=] of |json:JSON|["|protocol_handlers|"].
2. Set manifest["|protocol_handlers|"] to |processedProtocolHandlers|.
3. [=list/For each=] |protocol_handler| (protocol handler description):
   1. If |protocol_handler|["protocol"] or |protocol_handler|["url"] is undefined, [=iteration/continue=].
   2. Let (|normalizedProtocol:string|, |normalizedUrl:URL|) be the result of running [=normalize protocol handler parameters=] with |protocol_handler|["protocol"], | protocol_handler|["url"] using |manifest URL| as the base URL, and [=this=]'s relevant [=environment settings object=]. If the result is failure, [=iteration/continue=].
   3. If |normalizedUrl| is not [=manifest/within scope=] of |manifest|, [=iteration/continue=].
   4. If |processedProtocolHandlers| [=list/contains=] the |normalizedUrl|, [=iteration/continue=].
   5. [=List/Append=] |protocol_handler| to |processedProtocolHandlers|.
4. [=list/For each=] |processedProtocolHandlers|, the user agent SHOULD [=register a protocol handler=].

A user agent SHOULD ask users for permission before registering a [=protocol handler description=] protocol_handlers as the default handler for a protocol with the host operating system. A user agent MAY truncate the list of [=protocol handler description=] protocol_handlers presented in order to remain consistent with the conventions or limitations of the host operating system.

Protocol handler items

Each protocol handler description is an [=object=] that represents a protocol that the web application wants to handle, corresponding to the [=manifest/protocol_handlers=] member. It has the following members:

• [=protocol handler description/protocol=]
• [=protocol handler description/url=]

A user agent SHOULD use these values to register the web application as a handler with the operating system. When the user activates a protocol handler URL, the user agent SHOULD run handling a protocol launch.

Privacy consideration: Default protocol handler

Depending on the operating system capabilities, the protocol handler could become a 'default' handler (e.g. handling launches of a given protocol automatically) of a given protocol without the explicit knowledge of the user. To protect against possible misuse, user agents MAY employ protections such as:

• Requiring explicit user consent before executing the process to [=invoke a protocol handler=].
• Removing the web application's OS registration as a protocol handling entity, either in response to the above dialog or by user action.
• Confirming protocol handler registrations on [=installation=].

If a user agent removes the the registration of the protocol handler entity it SHOULD provide UX for the user to re-register the web app and protocol with the operating system.

File Handler Items

Each file handler represents a URL in the scope of the application that can handle launches with [=file types=] it accepts. It has the following members:

• [=file handler/action=]
• [=file handler/name=]
• [=file handler/accept=]
• [=file handler/icons=]

A user agent can use these members to associate the web application with [=file type=] on the operating system.

A file type can be defined by a [=MIME type=] and/or [=file extension=]. A file belongs to a file type if the OS determines it to have a [=MIME type=] and/or its name ends with a certain [=file extension=]. A file extension is a string that start with a "." and only contains valid suffix code points. Additionally, [=file extensions=] are limited to a length of 16 code points.

Processing file handler items

To process a file handler item, given [=ordered map=] |item:ordered map|, [=URL=] |start_url:URL|, [=URL=] |scope:URL|, and [=URL=] |manifest URL:URL|:

1. Return failure if any of the following is true:
   • |item|["action"] doesn't [=map/exist=] or is not a [=string=].
   • |item|["accept"] doesn't [=map/exist=].
   • |item|["accept"] is not a [=dictionary=].
   • |item|["accept"] [=map/is empty=].
2. Let |url:URL| be the result of [=URL Parser|parsing=] |item|["action"] with |manifest_url URL| as the base URL.
3. If |url| is failure, return failure.
4. If |url| is not [=manifest/within scope=] of |scope|, return failure.
5. Let |launch_type:string| be a new [=string=] initialized to "single-client".
6. If |item|["launch_type"] [=map/exists=] and is "multiple-clients", set |launch_type| to |item|["launch_type"].
7. Let |accept:ordered map| be a new [=ordered map=].
8. [=map/for each=] |mime_type_string:string| → |extensions| of |item|["accept"]
   1. If |extensions| is not a [=list=], [=iteration/continue=].
   2. If |extensions| is [=list/empty=], [=iteration/continue=].
   3. If |extensions| [=list/contains=] items that are not [=string=]s, [=iteration/continue=].
   4. If |extensions| [=list/contains=] strings that do not begin with the character `.`, [=iteration/continue=].
   5. If |extensions| [=list/contains=] strings that are greater than 16 characters long, [=iteration/continue=].
   6. Let |mime_type_parsed:mime type| be the result of running the steps of [=parse a mime type=] on |mime_type_string|.
   7. If |mime_type_parsed:mime type| is failure, [=iteration/continue=].
   8. If |mime_type_parsed/type| is not listed as a top-level type in [[IANA-MEDIA-TYPES]], [=iteration/continue=].
   9. Set |accept|[|mime_type_string|] to |extensions|.
9. If |accept:ordered map| is empty, return failure.
10. Let |file_handler:ordered map| be |ordered map| «[ "action" → |url|, "name" → |item|["name"], "launch_type" → |launch_type|, "accept" → |accept| ]».
11. Process image resources passing |item|["icons"], |file_handler|, |manifest URL|, and "icons".
12. Return |file_handler|.

Execute a file handler launch

The steps to execute a file handler launch are given by the following algorithm. The algorithm takes [=list=] |files:list| and a [=ordered map=] |manifest:ordered_map| which holds results from [=processing a manifest=].

1. Let |file_handlers:list| be |manifest|["file_handlers"].
2. If |file_handlers:list| is null, return.
3. Let |launches:ordered map| be an [=ordered map=].
4. [=list/for each=] |filename:string| of |files|
   1. [=list/for each=] |file_handler:ordered_map| of |file_handlers:list|:
      1. [=map/for each=] |mime_type_string:string| → |extensions:list| of |file_handler|["accept"]
         1. [=list/for each=] |extension:string| of |extensions|:
            1. If |filename| does not end in |extension|, [=iteration/continue=].
            2. If |launches|[|file_handler|] [=map/exists=], [=list/append=] |filename| to |launches|[|file_handler|].
            3. Else, set |launches|[|file_handler|] to a [=list=] with the single element |filename|.
            4. [=iteration/Continue=] to next element of |files|.
5. [=map/for each=] |file_handler| → |files:list| of |launches|
   1. If |file_handler|["launch_type"] is equal to "multiple-clients"
      1. [=list/for each=] |file| of |files|
         1. Let |params:LaunchParams| be a new {{LaunchParams}} with {{LaunchParams/targetURL}} set to |file_handler|["action"] and {{LaunchParams/files}} set to a {{FrozenArray}} with a single element that is a {{FileSystemHandle}} corresponding to |file|.
         2. [=Launch a web application with handling=], passing |manifest| and |params|.
   2. Else,
      1. Let |params:LaunchParams| be a new {{LaunchParams}} with {{LaunchParams/targetURL}} set to |file_handler|["action"] and {{LaunchParams/files}} set to a {{FrozenArray}} of {{FileSystemHandle}}s that correspond to the file paths named by |files|.
      2. [=Launch a web application with handling=], passing |manifest| and |params|.

Registering file handlers

A user agent SHOULD register file handlers with the host operating system, consistent with:

• The app is exposed in appropriate OS surfaces such as the native file browser and other surfaces that display lists of apps that can handle a given file or file type.
• The app is a candidate for becoming the system's default handler for associated file types.

A user agent MAY truncate the total set of [=file extensions=] to preserve functionality and prevent abuse. A user agent MAY prevent associations with certain filetypes.

Privacy consideration: Default file handler.

Depending on the operating system capabilities, the [=file handler=] could become a default handler of a given [=file type=] without the explicit knowledge of the user, handling launches of a given file type automatically. To protect against possible mis-use, [=user agents=] MAY require explicit user consent to begin with the process to [=execute a file handler launch=]. If consent is sought, the user agent SHOULD allow the user to specify that the decision is permanent and if so specified SHOULD remove the web application's OS registration as a file handling entity.

Privacy consideration: Name and icon.

The name and icon of each file handler can be sensitive to privacy and security, as there isn't a specified way for the user to see and confirm these. Due to this, [=user agents=] MAY choose to ignore these in favor of alternative strings and icons or fall back on OS defaults.

Processing the `scope_extensions` member

To process the `scope_extensions` member, given [=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|, and [=URL=] |manifest_id:URL|:

1. Let |processedScopeExtensions:list| be a new [=list=].
2. Set |manifest|["scope_extensions"] to |processedScopeExtensions|.
3. If |json|["scope_extensions"] does not [=map/exist=] or is not a [=list=], return.
4. [=list/For each=] |entry:ordered map| of |json|["scope_extensions"]:
   1. If |entry|["type"] or |entry|["origin"] do not [=map/exist=], [=iteration/continue=].
   2. If |entry|["type"] is not "origin", [=iteration/continue=].
   3. If |entry|["origin"] is not a [=string=], [=iteration/continue=].
   4. Let [=URL=] |origin_url:URL| be the result of [=URL Parser|parsing=] |entry|["origin"].
   5. If |origin_url| is a valid |URL| with [=URL/scheme=] "https", set |entry|["origin"] to the [=URL/origin=] of |origin_url|.
   6. Else [=iteration/continue=].
   7. Validate |entry| using the algorithm from [=validate scope extensions=], given [=ordered map=] |entry:ordered map| and [=URL=] |manifest_id:URL|.
   8. If the previous step returned an error, [=iteration/continue=].
   9. Else, set |entry|["scope"] to the returned [=URL=].
   10. [=list/Append=] |entry| to |processedScopeExtensions|.

Validating scope extensions

To validate scope extensions, given [=ordered map=] |extension:ordered map| and [=URL=] |manifest_id:URL|:

1. Let [=URL=] |origin_url:URL| be the [=URL=] of the [=URL/origin=] |extension|["origin"].
2. Let [=URL=] |download_url:URL| be the result of [=URL Parser|parsing=] "/.well-known/web-app-origin-association" using |origin_url| as the base [=URL=].
3. Let [=ordered map=] |json:ordered map| be the result of a [=fetch=] given |download_url|.
4. If the [=fetch=] failed, return an error.
5. If |json|[|manifest_id|] does not [=map/exist=] or is not an [=ordered map=], return an error.
6. Let [=string=] |scope:string| be "/".
7. If |json|[|manifest_id|]["scope"] [=map/exists=] and is a [=string=], set |scope| to |json|[|manifest_id|]["scope"].
8. Let [=URL=] |resolved_scope:URL| be the result of [=URL Parser|parsing=] |scope| with |extension|["origin"] as the base [=URL=].
9. Return |resolved_scope|.

Applying scope extensions

The user agent MAY choose to apply apply extended scope in some scenarios and [=manifest/scope=] in others.

If the [=application context=]'s [=navigable/active document=]'s [=URL=] is not [=manifest/within scope=] but is [=within extended scope=], the user agent SHOULD provide UI that allows the user to determine the [=URL=] or at least its [=origin=], including whether it is served over a secure connection. This UI SHOULD differ from any UI used when the [=URL=] is not [=manifest/within scope=] of the [=application context=]'s [=Document/processed manifest=], in order to make it obvious that the user is still navigating the intended contents of the application but also keep the user informed of the privacy and security implications of navigating to a different [=origin=].

migrate_from member

The [=manifest/migrate_from=] member is a [=list=] of either [=strings=] or [=ordered maps=] that identifies the old web applications that are being migrated from.

If an entry is a [=string=], it is treated as the [=manifest/id=] of the old application.

If an entry is an [=ordered map=], it can have the following members:

• id: A [=string=] representing the [=manifest/id=] of the old application.
• install_url: A [=string=] representing a URL of a page that links to the old application's manifest. A user agent can use this field to fetch the manifest of the old application in order to apply updates even if every other URL that is part of the old application redirects to the new application.
• behavior: A [=string=] that can be either `"suggest"` or `"force"`. This is a hint to the user agent that might influence how forceful the UI is that the user agent presents to the user to tell them about the migration.

migrate_to member

The [=manifest/migrate_to=] member is an optional [=ordered map=] that proactively signals a migration to a new application. It has the following members:

• id: A [=string=] representing the [=manifest/id=] of the new application.
• install_url: A [=string=] representing a URL of a page that links to the new application's manifest. The manifest on this page needs to include a [=manifest/migrate_from=] field that points back at this application for the migration to be processed.

Validating origin migration

To validate origin migration, given [=URL=] |old_manifest_id:URL| and [=URL=] |new_manifest_id:URL|:

1. If |old_manifest_id|'s [=URL/origin=] and |new_manifest_id|'s [=URL/origin=] are not [=same site=], return an error.
2. If |old_manifest_id|'s [=URL/origin=] is [=same origin=] as |new_manifest_id|'s [=URL/origin=], return success.
3. Let [=URL=] |origin_url:URL| be the [=URL/origin=] of |old_manifest_id|.
4. Let [=URL=] |download_url:URL| be the result of [=URL Parser|parsing=] "/.well-known/web-app-origin-association" using |origin_url| as the base [=URL=].
5. Let [=ordered map=] |json:ordered map| be the result of a [=fetch=] given |download_url|.
6. If the [=fetch=] failed, return an error.
7. If |json|[|new_manifest_id|] does not [=map/exist=] or is not an [=ordered map=], return an error.
8. If |json|[|new_manifest_id|]["allow_migration"] is not `true`, return an error.
9. Return success.

Processing the `migrate_from` member

To process the `migrate_from` member, given [=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|, and [=URL=] |manifest URL:URL|:

1. If |json|["id"] does not [=map/exist=] or is not a [=string=], return.
2. If |json|["id"] is the empty string, return.
3. Let |base_origin:origin| be |manifest|["start_url"]'s [=URL/origin=].
4. Let |id_url:URL| be the result of [=URL Parser|parsing=] |json|["id"] with |base_origin| as the base URL.
5. If |id_url| is failure, return.
6. If |id_url| is not [=same origin=] as |manifest|["start_url"], return.
7. Let |processed_migrate_from:list| be a new [=list=].
8. Set |manifest|["migrate_from"] to |processed_migrate_from|.
9. If |json|["migrate_from"] does not [=map/exist=] or is not a [=list=], return.
10. [=list/For each=] |entry| of |json|["migrate_from"]:
    1. Let |processed_entry:ordered map| be a new [=ordered map=].
    2. If |entry| is a [=string=]:
       1. Let |id:URL| be the result of [=URL Parser|parsing=] |entry| with |manifest URL| as the base URL.
       2. If |id| is failure, [=iteration/continue=].
       3. Set |processed_entry|'s [=migrate_from_item/id=] to |id|.
    3. Else if |entry| is an [=ordered map=]:
       1. If |entry|'s [=migrate_from_item/id=] does not [=map/exist=] or is not a [=string=], [=iteration/continue=].
       2. Let |id:URL| be the result of [=URL Parser|parsing=] |entry|'s [=migrate_from_item/id=] with |manifest URL| as the base URL.
       3. If |id| is failure, [=iteration/continue=].
       4. Set |processed_entry|'s [=migrate_from_item/id=] to |id|.
       5. If |entry|'s [=migrate_from_item/install_url=] [=map/exists=] and is a [=string=]:
          1. Let |install_url:URL| be the result of [=URL Parser|parsing=] |entry|'s [=migrate_from_item/install_url=] with |manifest URL| as the base URL.
          2. If |install_url| is not failure, set |processed_entry|'s [=migrate_from_item/install_url=] to |install_url|.
       6. If |entry|'s [=migrate_from_item/behavior=] [=map/exists=] and is a [=string=]:
          1. If |entry|'s [=migrate_from_item/behavior=] is "suggest" or "force", set |processed_entry|'s [=migrate_from_item/behavior=] to |entry|'s [=migrate_from_item/behavior=].
    4. Else, [=iteration/continue=].
    5. Validate |processed_entry|'s [=migrate_from_item/id=] using the algorithm from [=validate origin migration=], given [=URL=] |processed_entry|'s [=migrate_from_item/id=] and [=URL=] |id_url|.
    6. If the previous step returned an error, [=iteration/continue=].
    7. [=list/Append=] |processed_entry| to |processed_migrate_from|.

Processing the `migrate_to` member

To process the `migrate_to` member, given [=ordered map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|, and [=URL=] |manifest URL:URL|:

1. If |json|["migrate_to"] does not [=map/exist=] or is not an [=ordered map=], return.
2. Let |entry:ordered map| be |json|["migrate_to"].
3. If |entry|'s [=migrate_to_item/id=] does not [=map/exist=] or is not a [=string=], return.
4. Let |id:URL| be the result of [=URL Parser|parsing=] |entry|'s [=migrate_to_item/id=] with |manifest URL| as the base URL.
5. If |id| is failure, return.
6. Let |processed_migrate_to:ordered map| be a new [=ordered map=].
7. Set |processed_migrate_to|'s [=migrate_to_item/id=] to |id|.
8. If |entry|'s [=migrate_to_item/install_url=] [=map/exists=] and is a [=string=]:
   1. Let |install_url:URL| be the result of [=URL Parser|parsing=] |entry|'s [=migrate_to_item/install_url=] with |manifest URL| as the base URL.
   2. If |install_url| is not failure, set |processed_migrate_to|'s [=migrate_to_item/install_url=] to |install_url|.
9. Set |manifest|["migrate_to"] to |processed_migrate_to|.

Privacy and Security Considerations

To prevent malicious actors from silently taking over applications (e.g., a simple calculator updating itself to mimic a banking app), the [=validate origin migration=] algorithm enforces a two-way handshake. Both the new and the old application origins must explicitly agree to the migration via the [=web-app-origin-association=] file.

Furthermore, migrations are restricted to be [=same site=] to ensure they are used for legitimate rebranding and architecture changes within an organization's control, rather than transferring ownership to unverified third parties.

User agents should consider including an explicit user confirmation dialog as part of the migration flow, especially if an update to security-sensitive fields (such as the app name and icons) is included.

`platform` member

The platform member represents the [=platform=] this [=external application resource=] is associated with. A platform represents a software distribution ecosystem or possibly an operating system. This specification does not define the particular values for the platform member.

`url` member

An [=external application resource's=] url member is the URL where the application can be found.

To process the `url` member of an application:

1. If application URL is missing, return null.
2. Otherwise, [=URL Parser|parse=] application URL and if the result is not failure, return the result. Otherwise return null.

`id` member

An [=external application resource's=] id member represents the id which is used to represent the application on the platform.

`min_version` member

An [=external application resource's=] min_version member represents the minimum version of the application that is considered related to this web app. This version is a string with platform-specific syntax and semantics.

`fingerprints` member

An [=external application resource's=] fingerprints member represents an [=list=] of [=fingerprints=].

A fingerprint represents a set of cryptographic fingerprints used for verifying the application. A fingerprint has the following two members: type and value. Each of these are strings, but their syntax and semantics are platform-defined.

Installation process

The steps to install the web application are given by the following algorithm:

1. Let manifest be the manifest of an installable document.
2. Perform an unspecified sequence of actions to attempt to register the web application in the user's operating system (e.g., create shortcuts that launch the web application, register the application in the system uninstall menu, etc.). If the installation fails (which can be for any reason, for example, the OS denying permission to the user agent to add an icon to the home screen of the device), abort these steps.
3. Queue a task on the application life-cycle task source to fire an event named `"appinstalled"` at the [=top-level browsing context=]'s [=relevant global object=] for which the installation took place.

BeforeInstallPromptEvent Interface

          [Exposed=Window]
          interface BeforeInstallPromptEvent : Event {
            constructor(DOMString type, optional EventInit eventInitDict = {});
            Promise<PromptResponseObject> prompt();
          };

          dictionary PromptResponseObject {
            AppBannerPromptOutcome userChoice;
          };

          enum AppBannerPromptOutcome {
            "accepted",
            "dismissed"
          };
        

The {{BeforeInstallPromptEvent}} is dispatched when the site is allowed to present a site-triggered install prompt, or prior to the user agent presenting an automated install prompt. It allows the site to cancel the automated install prompt, as well as manually present the site-triggered install prompt.

The PromptResponseObject contains the result of calling {{BeforeInstallPromptEvent/prompt()}}. It contains one member, userChoice, which states the user's chosen outcome.

An instance of a {{BeforeInstallPromptEvent}} has the following internal slots:

[[\didPrompt]]

A boolean, initially `false`. Represents whether this event was used to present an install prompt to the end-user.

[[\userResponsePromise]]

A promise that represents the outcome of presenting an install prompt.

              window.addEventListener("beforeinstallprompt", event => {
                // Suppress automatic prompting.
                event.preventDefault();

                // Show the (disabled-by-default) install button. This button
                // resolves the installButtonClicked promise when clicked.
                installButton.disabled = false;

                // Wait for the user to click the button.
                installButton.addEventListener("click", async e => {
                  // The prompt() method can only be used once.
                  installButton.disabled = true;

                  // Show the prompt.
                  const userChoice = await event.prompt();
                  console.info(`user choice was: ${userChoice}`);
                });
              });
            

Extensions to the `Window` object

          partial interface Window {
            attribute EventHandler onappinstalled;
            attribute EventHandler onbeforeinstallprompt;
          };