Clarify applying manifest to an existing browsing context

[christianliebel]

Closes #784

This change:

• Adds new normative requirements

Adds normative text to the Applying the manifest section covering the case where a user agent applies a manifest to an existing top-level browsing context (e.g., immediately after installation). The two cases are now specified:

• If the active document's URL is within scope: the browsing context becomes an application context.
• If the active document's URL is not within scope: the behavior is implementation-defined.

An informative note illustrates the implementation-defined case (e.g., Chromium's tab-promotion behavior).

The original note added by this PR has been moved from the navigation scope section to sit adjacent to the new normative text, and revised for consistency (replacing [=launch=] with [=apply=], which correctly describes applying to an existing context rather than creating a new one).

Implementation commitment: no implementation changes required — the normative text formalizes existing behavior and explicitly leaves the out-of-scope case as implementation-defined.

Commit message:

Add normative text for applying manifest to existing browsing context

---

Preview | Diff

[Copilot]

Pull request overview

This PR adds an editorial note documenting user agent behavior when launching an installed web application from the browsing context that initiated installation, specifically addressing the case where that context's URL is outside the manifest's scope. This addresses part of issue #784 regarding clarification of manifest behavior with out-of-scope pages.

Changes:

• Adds a non-normative note in the navigation scope section describing potential user agent behavior when launching installed apps from out-of-scope URLs

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dmurph]

LGTM

[marcoscaceres]

After discussion with @marcoscaceres, we think this PR's note needs to be paired with normative text, and the note itself revised to be consistent with it.

Proposed normative text

Add the following to the "Applying the manifest" section, after the sentence "the user agent MAY [=apply=] a manifest to it before [=navigate|navigation=] begins":

<p>
  A user agent MAY also [=apply=] a manifest to an existing [=top-level
  browsing context=]. If the [=navigable/active document=]'s
  [=Document/URL=] is [=manifest/within scope=] of the manifest, the
  existing [=top-level browsing context=] becomes an [=application
  context=]. If the [=Document/URL=] is not [=manifest/within scope=],
  the resulting behavior is implementation-defined.
</p>

Revised note

Replace the current <aside> added by this PR with the following (and move it to sit directly after the normative text above):

<aside class="note">
  <p>
    Some user agents might [=apply=] a manifest to the existing
    [=top-level browsing context=] from which installation was
    initiated. If the [=navigable/active document=]'s [=Document/URL=]
    is not [=manifest/within scope=] of the manifest's
    [=manifest/navigation scope=], one possible behavior is that the
    [=application context=] initially exists at an out-of-scope
    [=Document/URL=].
  </p>
</aside>

Rationale

• The note previously used [=launch=], which per the spec creates a new application context — inconsistent with describing the existing-tab-promotion case.
• The normative text clarifies both branches: in-scope (browsing context becomes an application context) and out-of-scope (implementation-defined).
• Together they close Clarify behaviour of a page linking to a manifest that is not within scope of that manifest #784 properly: the informative note illustrates one concrete instance of the implementation-defined behavior.

[marcoscaceres]

LGTM! Nice one.

[christianliebel]

@dmurph @saschanaz Could you please review this change? It should align with the installation behavior of Chromium and Gecko. We wanted to clarify this in the spec to address #784.

[dmurph]

LGTM

[dmurph]

@saschanaz Given that there is alignment between webkit and chromium folks here I'm going to approve & merge to keep velocity up (as we meet to chat about this stuff infrequently)

However! This should also come with the understanding that we should revert if there are other issues or objections where we have made mistakes. So please let us know if you have feedback that we can continue iterating on or revert this change.