Intent to Ship: Navigation API

883 views
Skip to first unread message

Domenic Denicola

unread,
Apr 12, 2022, 12:08:42 PMApr 12
to blink-dev

Contact emails

dom...@chromium.org, jap...@chromium.org


Explainer

https://github.com/WICG/navigation-api/blob/main/README.md


Specification

https://wicg.github.io/navigation-api/


Summary

The window.navigation API provides the ability to intercept and initiate navigations, as well as introspect an application's history entries. This provides a more useful alternative to window.history and window.location, specifically aimed at the needs of single-page web applications.


(Note: this API was formerly known as the app history API.)


Blink component

Blink>History


TAG review

https://github.com/w3ctag/design-reviews/issues/605

https://github.com/w3ctag/design-reviews/issues/717


TAG review status

Issues addressed


Link to origin trial feedback summary

https://docs.google.com/document/d/1oDtVhNJaDyEAqsthe07wJaGNVpt-g4TLB4A0-lU2lr4/edit?usp=sharing


Risks


Interoperability

The biggest interoperability risk with this API is that it is building on a rocky foundation. The existing session history spec does not match browsers very well, and browsers do not match each other. Since this new API layers on top of the existing model, this could cause issues.


We have attempted to address this via a solid and well-tested specification for the new API, as well as ongoing efforts in whatwg/html PR #6315 and elsewhere on the HTML Standard issue tracker to reform the foundational parts of the specification. For example, although the navigation API's new events, such as currententrychange, are fired at well-specified times, there is an existing interop problem regarding the timing of popstate vs. hashchange events, which makes it difficult to write tests for the ordering of currententrychange vs. hashchange/popstate. Working on such existing interop issues and specification problems, and then expanding the navigation API test suite to cover any such interactions, is our team's top priority after this launch. See also this tracking issue.


Regarding whether this new API will be implemented in other browsers, we have been encouraged by the consistent and positive collaboration with Gecko engineers, which has led to several API changes and a good amount of review. (We have no signal from WebKit.)


Compatibility

This has been the team's main focus for the last few months, as we burned through the list of potentially-compat-impacting issues. In collaboration with Gecko this led to several improvements, such as the API rename (from app history), a change in how replacement navigations are requested, and the addition of an indicator for when a download is requested. We believe the remaining issues (3 at the time of writing) are manageable:


  • #72: this will result in firing an event more often during extreme edge case scenarios involving replacement navigations, or in less-rare-but-still-rare scenarios involving the user clearing their history. Neither case should prove problematic.

  • #207: the most likely solution will either be leaving things as they are, or changing the timing of an event in a way that will not disturb "normal" usage of the API. Although such a timing change could be risky if this API had wide deployment, we believe that changing the timing within a milestone or three would not be problematic if it ends up being desirable.

  • #202: this issue is about the default for how focus is managed following a navigation API-intercepted navigation. We believe the currently-chosen default is probably the best, especially given testaments on that thread from the accessibility community and from web framework authors. However we have not yet closed the issue as we haven't concluded the discussion with Gecko engineers. Similar to #207, this would probably be changeable within a few milestones if necessary, without significant impact to sites using the API. And if we did change it, early-adopter sites could easily restore the previous behavior by changing the value of an option.


Signals

Gecko: No signal. Initial positive opinions on the issue, and continued engagement on the design, but not yet an official position.


WebKit: No signal.


Web developers: Strongly positive. The initial public proposal, as well as the issue tracker and Twitter, has had great engagement and enthusiasm from developers. Origin trial feedback was also encouraging. In addition, we have several conversations going on with frameworks, libraries, and larger websites to ensure that we're solving the problems they see with today's history API. So far reactions have been either positive, or requesting that we add additional functionality (most notably #32).


Ergonomics

Although this API layers onto the same underlying model as window.history, and will have well-specified interactions with it, the exact integrations may be confusing. (For example, navigation.navigate() will behave differently from history.pushState().) We've done our best to smooth over these rough edges where possible, but have favored making the navigation API pleasant to use over making it perfectly align with window.history.


Activation

This feature is hard to polyfill, but developers have managed to produce something that works in many cases: frehner/appHistory is one, and virtualstate/navigation another.


We've also seen a pattern where developers have existing history/navigation wrappers (e.g. router libraries or app-specific history and navigation code) which they can adapt with a new navigation API-based backend for browsers that support it.


Security

We believe the security risks of this feature are minimal because of how it is scoped to same-origin contiguous history entries, and similarly only allows interception of same-origin navigations. We also need to ensure that we don't allow "trapping" the user by preventing them from using their back button; the API is designed to prevent this.


See the specification's security and privacy discussion for more.


WebView Application Risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?


This feature does not introduce any changes to existing APIs.


Debuggability

This feature mostly has no need for extended tooling. crbug.com/1252940 tracked adding the newly-introduced events to the Event Listener Breakpoints panel.


Is this feature fully tested by web-platform-tests?

Yes.


These results show a strange number of failures for Chromium. We suspect this is due to the test runner on wpt.fyi, as running the tests locally, or in a live Chrome browser, does not exhibit the issue. See web-platform-tests/wpt#33590.


Flag name

NavigationApi


Requires code in //chrome?

False


Tracking bug

https://bugs.chromium.org/p/chromium/issues/detail?id=1183545


Launch bug

https://bugs.chromium.org/p/chromium/issues/detail?id=1252954


Measurement

https://chromestatus.com/metrics/feature/timeline/popularity/4056


Non-OSS dependencies

Does the feature depend on any code or APIs outside the Chromium open source repository and its open-source dependencies to function?

No.


Sample links

https://gigantic-honored-octagon.glitch.me/

https://selective-heliotrope-dumpling.glitch.me/


Estimated milestones

We plan to land this API in M102.


Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/6232287446302720


Links to previous Intent discussions

Intent to Prototype

Intent to Experiment



This intent message was generated by Chrome Platform Status and then cleaned up a good bit.

Mike Taylor

unread,
Apr 18, 2022, 10:49:16 AMApr 18
to Domenic Denicola, blink-dev
On 4/12/22 12:08 PM, Domenic Denicola wrote:
(Aside: This explainer is a master-class in writing explainers. Incredibly well done - I really appreciate the effort that went into this).


Specification

https://wicg.github.io/navigation-api/


Summary

The window.navigation API provides the ability to intercept and initiate navigations, as well as introspect an application's history entries. This provides a more useful alternative to window.history and window.location, specifically aimed at the needs of single-page web applications.


(Note: this API was formerly known as the app history API.)


Blink component

Blink>History


TAG review

https://github.com/w3ctag/design-reviews/issues/605

https://github.com/w3ctag/design-reviews/issues/717


TAG review status

Issues addressed


Link to origin trial feedback summary

https://docs.google.com/document/d/1oDtVhNJaDyEAqsthe07wJaGNVpt-g4TLB4A0-lU2lr4/edit?usp=sharing


Risks


Interoperability

The biggest interoperability risk with this API is that it is building on a rocky foundation. The existing session history spec does not match browsers very well, and browsers do not match each other. Since this new API layers on top of the existing model, this could cause issues.


We have attempted to address this via a solid and well-tested specification for the new API, as well as ongoing efforts in whatwg/html PR #6315 and elsewhere on the HTML Standard issue tracker to reform the foundational parts of the specification. For example, although the navigation API's new events, such as currententrychange, are fired at well-specified times, there is an existing interop problem regarding the timing of popstate vs. hashchange events, which makes it difficult to write tests for the ordering of currententrychange vs. hashchange/popstate. Working on such existing interop issues and specification problems, and then expanding the navigation API test suite to cover any such interactions, is our team's top priority after this launch. See also this tracking issue.

I do have slight concerns over the popstate/hashchange event change - I fear that might result in more back button traps for Chromium users (that sadly Gecko users experience today). But I could be wrong - do you have any plans to measure and monitor abuse? Or do we have existing metrics?

Regarding whether this new API will be implemented in other browsers, we have been encouraged by the consistent and positive collaboration with Gecko engineers, which has led to several API changes and a good amount of review. (We have no signal from WebKit.)


Compatibility

This has been the team's main focus for the last few months, as we burned through the list of potentially-compat-impacting issues. In collaboration with Gecko this led to several improvements, such as the API rename (from app history), a change in how replacement navigations are requested, and the addition of an indicator for when a download is requested. We believe the remaining issues (3 at the time of writing) are manageable:


  • #72: this will result in firing an event more often during extreme edge case scenarios involving replacement navigations, or in less-rare-but-still-rare scenarios involving the user clearing their history. Neither case should prove problematic.

  • #207: the most likely solution will either be leaving things as they are, or changing the timing of an event in a way that will not disturb "normal" usage of the API. Although such a timing change could be risky if this API had wide deployment, we believe that changing the timing within a milestone or three would not be problematic if it ends up being desirable.

  • #202: this issue is about the default for how focus is managed following a navigation API-intercepted navigation. We believe the currently-chosen default is probably the best, especially given testaments on that thread from the accessibility community and from web framework authors. However we have not yet closed the issue as we haven't concluded the discussion with Gecko engineers. Similar to #207, this would probably be changeable within a few milestones if necessary, without significant impact to sites using the API. And if we did change it, early-adopter sites could easily restore the previous behavior by changing the value of an option.

I agree that these issues seem tractable in the near-term.

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAM0wra8BD%2Bea9fSiRGyPJeAZ2KknQe6c9Xmza5BS7O94ktjXiA%40mail.gmail.com.


Domenic Denicola

unread,
Apr 18, 2022, 11:39:47 AMApr 18
to Mike Taylor, Domenic Denicola, blink-dev
To make sure we are on the same page: at this point we are discussing a future Intent to Ship about a separate behavior change, and we are not discussing the Navigation API.

Our plan for that future Intent to Ship does indeed involve careful monitoring. However I don't think it has any chance of increasing back-trapping. Deterministically firing the events in the order (sync popstate, async hashchange) like Gecko does, instead of Chrome's version where sometimes it's (async popstate, async hashchange) and sometimes it's (async hashchange, async popstate) depending on network conditions and page size, should not increase back-trapping.

Mike Taylor

unread,
Apr 18, 2022, 11:47:45 AMApr 18
to Domenic Denicola, blink-dev
LGTM1 - I'm excited about this API, and hopeful we can smooth over the subtle interop issues that you've documented. But I see this as a huge ergonomics win over the status quo, and am encouraged by the careful work y'all have done.

Correct - and to be extra clear, any potential future I2S is not influencing this I2S in my mind.

Our plan for that future Intent to Ship does indeed involve careful monitoring. However I don't think it has any chance of increasing back-trapping. Deterministically firing the events in the order (sync popstate, async hashchange) like Gecko does, instead of Chrome's version where sometimes it's (async popstate, async hashchange) and sometimes it's (async hashchange, async popstate) depending on network conditions and page size, should not increase back-trapping.
OK, I'm very happy to be wrong here. :)

Yoav Weiss

unread,
Apr 20, 2022, 7:57:48 AMApr 20
to blink-dev, Mike Taylor, blink-dev, Domenic Denicola
LGTM2

I share MikeT's excitement about this API, and hopeful it can provide both ergonomics wins for developers as well as predictability wins for browsers when it comes to SPAs and navigations.

I agree with your assessment on the manageability of those issues, and agree they should not be blockers here. 
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

Mike West

unread,
Apr 20, 2022, 9:44:27 AMApr 20
to blink-dev, Yoav Weiss, Mike Taylor, blink-dev, Domenic Denicola
LGTM3.

-mike
Reply all
Reply to author
Forward
0 new messages