Expose information about last activation/cross-document navigation

[noamr]

Following up on this idea from @domenic.

In some cases, like in view transition, developers want to customize the page/style/what not based on the last/current navigation: which URL did it come from, was it a back navigation, etc. For example, show a welcome message but not if it's a back navigation, or run a different animation if coming from the home page.

To use with CSS view transitions, the developer would listen to the proposed readytorender event (#9315) or some such, and then customize or skip the transition based on that info.

My current thought about this right now is that this should be about activation rather than navigation - navigations can be same-document, and in the case of prerender the interesting point in time for this is when the document is activated rather than when it's prerendered.

Strawman API:

interface ActivationInfo {
  /* The URL of the previous document (if same origin), at time of activation. `about:blank` if first page/unaccessible */previousURL;
  readonly attribute USVString? previousURL;

  /* The URL of the this document, at time of activation */
  readonly attribute USVString activationURL;

  /* push/replace/traverse/reload*/
  readonly attribute NavigationType navigationType;

  /* if available. -1 means this is a back navigation. */
  readonly attribute double? traversalOffset;
  
  /* True for bfcache-restore and prerender activation */
  readonly attribute boolean persisted;
}

partial interface Document {
 readonly attribute ActivationInfo activationInfo;
}

An alternative would be to expose info about the most recent cross-document navigation rather than activation. The difference would only be meaningful for prerendering, where the previous URL at time of activation is more meaningful than the URL at time of prerendering.

[noamr]

An alternative API could be more consistent with the navigation API, specifically [NavigationDestination](https://html.spec.whatwg.org/multipage/nav-history-apis.html#navigationhistoryentry:

interface ActivationInfo {
  /* push/replace/traverse/reload*/
  readonly attribute NavigationType navigationType;

  readonly attribute NavigationDestination? previous;
  readonly attribute NavigationDestination current;
}

partial interface Document {
 readonly attribute ActivationInfo activationInfo;
}

[khushalsagar]

A few questions for the proposal above, I like the direction its headed!

• readonly attribute NavigationDestination current;
  Why is this needed? Seems like the page should already know its current info.

• We'll need some event for the bfcache case when this information is guaranteed to be updated. readytorender seems like the right spot for VT (or any other case which needs to set visual state based on this). But I'm not sure if there are use-case for which this would be too late.
  Same for pre-render activation.
• For pre-render, do we just not provide this info while the Document is pre-rendering? So it only comes through at activation time. Or are there use-cases where it would make sense to start off with the URL of the Document that initiated the pre-render, since that will most likely be the URL after activation.
  One use-case that comes to my mind is pre-render initiated when the user hovers over a link. The page might want to fetch resources and tag which ones are render-blocking during pre-rendering based on the previous URL.

@jeremyroman for the pre-rendering stuff.

[noamr]

A few questions for the proposal above, I like the direction its headed!

• readonly attribute NavigationDestination current;
  Why is this needed? Seems like the page should already know its current info.

You have this data when you activate the page, but afterwards this info might change with soft navigations. It's an optional convenience. If we don't want it we don't have to have it.

• We'll need some event for the bfcache case when this information is guaranteed to be updated. readytorender seems like the right spot for VT (or any other case which needs to set visual state based on this). But I'm not sure if there are use-case for which this would be too late.

pageshow is good enough I believe.

Same for pre-render activation.

prerenderingchange

• For pre-render, do we just not provide this info while the Document is pre-rendering? So it only comes through at activation time. Or are there use-cases where it would make sense to start off with the URL of the Document that initiated the pre-render, since that will most likely be the URL after activation.
  One use-case that comes to my mind is pre-render initiated when the user hovers over a link. The page might want to fetch resources and tag which ones are render-blocking during pre-rendering based on the previous URL.

@jeremyroman for the pre-rendering stuff.

I think it would work to have it be the previous page, and change on prerenderingchange.

[khushalsagar]

+1 to everything above.

[domenic]

This direction seems good to me. A few minor surface concerns:

---

NavigationDestination or NavigationHistoryEntry? I think we can provide the full NavigationHistoryEntry in this case. (Assuming we leave it as null if it's cross-origin.) In particular, I'd expect something like

// after a cross-document back traversal, either bfcache or not:
console.assert(document.activationInfo.previous === navigation.entries()[navigation.currentEntry.index + 1]);

// always the case on page load, although it'd change after a same-document navigation of any sort:
console.assert(navigation.currentEntry === document.activationInfo.current);

---

It's an interesting question whether we want to expose the "activation" vocabulary in the API, or how "activation" vs. "navigation" impacts things.

Clearly, we want to expose bfcache reactivation. But that is a navigation, too. (Specifically a cross-document traversal.)

I'm not sure I see how prerender activation vs. the original navigation that started the prerender would play into this API. Given the proposals so far, nothing seems to expose this difference. Were you thinking this would be null during prerendering? That seems bad, as it would make it unnecessarily difficult to make your page pre-renderable. (You'd need to move anything that accesses this property until after prerenderingchange.)

So, I'd rather phrase this in terms of something like "this cross-document navigation". And maybe place it under navigation. I'm not sure exactly what a good name is, but I feel like navigation.crossDocumentLoad or something is better than document.activationInfo? I still don't love that name, but basically I'm wondering if we can avoid introducing "activation" here...

---

For the previous name, I think from might be good since it aligns with currentEntryChangeEvent.from and navigation.transition.from.

For the current name, I think something more like entry might be good since it will stop being current after any same-document navigations. (I.e., it will stop matching navigation.currentEntry.) So then it's something like navigation.crossDocumentLoad.entry? Kind of reasonable...

[noamr]

This direction seems good to me. A few minor surface concerns:

NavigationDestination or NavigationHistoryEntry? I think we can provide the full NavigationHistoryEntry in this case. (Assuming we leave it as null if it's cross-origin.) In particular, I'd expect something like

// after a cross-document back traversal, either bfcache or not:
console.assert(document.activationInfo.previous === navigation.entries()[navigation.currentEntry.index + 1]);

// always the case on page load, although it'd change after a same-document navigation of any sort:
console.assert(navigation.currentEntry === document.activationInfo.current);

I can see that. I went with NavigationDestination because we're never sameDocument.

It's an interesting question whether we want to expose the "activation" vocabulary in the API, or how "activation" vs. "navigation" impacts things.

Clearly, we want to expose bfcache reactivation. But that is a navigation, too. (Specifically a cross-document traversal.)

Perhaps crossDocumentNavigationInfo? We have sameDocument concept in the navigation API so it's consistent.

I'm not sure I see how prerender activation vs. the original navigation that started the prerender would play into this API. Given the proposals so far, nothing seems to expose this difference. Were you thinking this would be null during prerendering? That seems bad, as it would make it unnecessarily difficult to make your page pre-renderable. (You'd need to move anything that accesses this property until after prerenderingchange.)

Thinking it would be the prerender navigation during prerendering, and the activation navigation on prerenderingchange and after.

So, I'd rather phrase this in terms of something like "this cross-document navigation". And maybe place it under navigation. I'm not sure exactly what a good name is, but I feel like navigation.crossDocumentLoad or something is better than document.activationInfo? I still don't love that name, but basically I'm wondering if we can avoid introducing "activation" here...

Sounds good. Especially if we expose the prerendering navigation.

For the previous name, I think from might be good since it aligns with currentEntryChangeEvent.from and navigation.transition.from.

For the current name, I think something more like entry might be good since it will stop being current after any same-document navigations. (I.e., it will stop matching navigation.currentEntry.) So then it's something like navigation.crossDocumentLoad.entry? Kind of reasonable...

Not sure about the word "load" because when we activate from bfcache/prerender the document is already "loaded" (as in the load event has potentially fired).

So something like:

interface CrossDocumentNavigation {
  readonly attribute NavigationHistoryEntry entry;
  readonly attribute NavigationHistoryEntry? from;
  NavigationType type;
};

partial interface Navigation {
  attribute CrossDocumentNavigation crossDocument;
}

The following doesn't seem too bad:

navigation.crossDocument.entry;
navigation.crossDocument.from;
navigation.crossDocument.type;

[domenic]

Thinking it would be the prerender navigation during prerendering, and the activation navigation on prerenderingchange and after.

We've so far been treating prerendering activation as more of a "visual" event, not an actual navigation. So I think it could stay the same across both.

So something like:

Looks pretty good to me! The navigation.crossDocument name isn't the most clear thing ever, but I have no better ideas, and at least it's nice and short. So I'm supportive of it, at least until we get any clearly-better suggestions.

[noamr]

Thinking it would be the prerender navigation during prerendering, and the activation navigation on prerenderingchange and after.

We've so far been treating prerendering activation as more of a "visual" event, not an actual navigation. So I think it could stay the same across both.

How would that work for the view-transitions case, and potentially other cases, if there were soft navigations in the initiating page? We want from to match the actual relevant entry and URL that we came from, to match the UI etc. The URL that initiated the prerender is less relevant for that.

[domenic]

Hmm, I'm not sure I understand the problem. Is this the scenario you're talking about?

1. /a.html prerenders /b.html
2. In /b.html during the prerender, .from is the /a.html entry, and .entry is the /b.html entry.
3. /b.html, while prerendered, does a same-document navigation to /b.html#2. This does not update .from or .entry. (Also, all same-document navigations during prerender are forced to be "replace".)
4. a.html activates the prerender, causing /b.html#2 to become the active document.
5. During prerenderingchange and/or readytorender (Proposal: fire an event before the first rendering opportunity after activation #9315), the code in /b.html#2 looks at navigation.crossDocument.from and sees /a.html, which is indeed where the user is coming from and what was previously displayed in the UI.

[noamr]

Hmm, I'm not sure I understand the problem. Is this the scenario you're talking about?

More like this:

1. /a1.html prerenders /b.html
2. /a1.html soft-navigates (pushState?) to /a2.html
3. The user clicks a link to /b.html#foo at the original document (which is now /a2.html)
4. This activates the prerendered /b.html and performs a same-document (anchor) nav
5. I want access to something like {from: "/a2.html" to: "/b.html#foo"}

I don't totally buy that prerender activation is merely a visibility thing. It also tinkers with the history, and from the point of view of the old page it's a proper navigation.

[domenic]

I see! That is indeed tricky. OK, now I understand why you wanted to focus on activation, and maybe we should reconsider the naming in light of that...

I guess there is also the following tricky case:

1. /a.html prerenders /B.html
2. /B.html, while prerendered, cross-document navigates to /C.html. This is forced to be a "replace" navigation.
3. What does navigation.crossDocument return while in /C.html? In particular, is navigation.crossDocument.from about /B.html, or about /A.html?

(And you can mix in your example too, so that /a.html updates itself to /a2.html while /B.html or /C.html are prerendered.)

So I can see the following possible paths:

1. navigation.crossDocument is null during prerendering
2. navigation.crossDocument.from (and type) is null during prerendering.
   • navigation.crossDocument.entry updates naturally on cross-document navigations during prerendering, e.g. from /B.html to /C.html
   • But there's no way for /C.html to ever see information about /B.html
   • Once prerendering activation happens, from becomes an entry for the activator, e.g. /a.html or /a2.html.
3. Two properties, e.g. navigation.crossDocument.from and navigation.crossDocument.activator.
   • activator behaves like from in the previous path, null until activation.
   • from is null initially, on /B.html (because prerenders are new traversable navigables with no history, initially). On /C.html, it is a reference to /B.html.
   • type is still null during prerendering
4. Magically-updating from and type, activation-focused
   • They track basically our "current best guess" on how the activation will happen, e.g. /a.html and "push", but can update over time.
5. Hide this whole object behind a promise, which only resolves after prerendering activation.

Any other possibilities?

Only (4) or (5) makes it easy for prerendered pages to mostly-ignore the fact that they're being prerendered. At the cost that they might be slightly buggy (for (4)), or delayed (for (5)). The others, to varying degrees, can lead to unexpected nulls when you start prerendering pages on your site, and thus making introducing prerendering costly. That's unfortunate.

Despite that, I'm leaning toward (2) or (3) as the most conceptually clean. Maybe this is just one of those things which we can't make transparent to prerendered pages.

For most pages, which are not prerendered, (1), (2), or (4) are most convenient. (3) is reasonable but could be a bit confusing, in that you'd get two properties with the same value and so people might write their code sloppily not thinking about which one is actually correct for their potential prerendering future.

If we go down (2) or (3), then maybe it's fine to make developers learn about the activation concept after all? navigation.activation, maybe with some remixed property names?

[noamr]

I see! That is indeed tricky. OK, now I understand why you wanted to focus on activation, and maybe we should reconsider the naming in light of that...

I guess there is also the following tricky case:

1. /a.html prerenders /B.html
2. /B.html, while prerendered, cross-document navigates to /C.html. This is forced to be a "replace" navigation.
3. What does navigation.crossDocument return while in /C.html? In particular, is navigation.crossDocument.from about /B.html, or about /A.html?

/B.html IMO.

(And you can mix in your example too, so that /a.html updates itself to /a2.html while /B.html or /C.html are prerendered.)

So I can see the following possible paths:

1. navigation.crossDocument is null during prerendering
2. navigation.crossDocument.from (and type) is null during prerendering.

That's not bad

• navigation.crossDocument.entry updates naturally on cross-document navigations during prerendering, e.g. from /B.html to /C.html
• But there's no way for /C.html to ever see information about /B.html
• Once prerendering activation happens, from becomes an entry for the activator, e.g. /a.html or /a2.html.

3. Two properties, e.g. navigation.crossDocument.from and navigation.crossDocument.activator.

• activator behaves like from in the previous path, null until activation.
• from is null initially, on /B.html (because prerenders are new traversable navigables with no history, initially). On /C.html, it is a reference to /B.html.
• type is still null during prerendering

4. Magically-updating from and type, activation-focused

• They track basically our "current best guess" on how the activation will happen, e.g. /a.html and "push", but can update over time.

5. Hide this whole object behind a promise, which only resolves after prerendering activation.

Any other possibilities?

Yes! To expose it only in events where it makes sense, like in the pagereveal/readytorender event, maybe in prerenderingchange. Not have it at all as something globally accessible.
Treat it as something transient rather than stationary.

Despite that, I'm leaning toward (2) or (3) as the most conceptually clean. Maybe this is just one of those things which we can't make transparent to prerendered pages.

I like (2) if we don't go the event route.

For most pages, which are not prerendered, (1), (2), or (4) are most convenient. (3) is reasonable but could be a bit confusing, in that you'd get two properties with the same value and so people might write their code sloppily not thinking about which one is actually correct for their potential prerendering future.

If we go down (2) or (3), then maybe it's fine to make developers learn about the activation concept after all? navigation.activation, maybe with some remixed property names?

Sure. Let's see if we're going with that. I definitely prefer (2) to the rest, because it's the simplest in the non-prerender case.

[domenic]

Hmm, yeah, I can see how only exposing it in events is simplest. That does prevent us from accomplishing the other use cases (around the loading spinner and detecting stops during the navigation) in WICG/navigation-api#256 (comment), at least in the same API. Maybe that's fine? But it'd be kind of a shame if we later decide they should have been together in the same API.

[noamr]

Hmm, yeah, I can see how only exposing it in events is simplest. That does prevent us from accomplishing the other use cases (around the loading spinner and detecting stops during the navigation) in WICG/navigation-api#256 (comment), at least in the same API. Maybe that's fine? But it'd be kind of a shame if we later decide they should have been together in the same API.

What's wrong with listening to reveal in this use-case?

[noamr]

@domenic Oh I see you're talking about the use cases in the comment rather than the original issue. Out of these use cases, several are already covered by existing events like DOMContentLoaded and load, no?

Perhaps at some point we could have an activation-info thing that's actually for the initial load (not including activate/restore) with the added things like controlling the load indicator.

[khushalsagar]

One use-case for exposing it sooner would be tagging appropriate resources and DOM nodes as render-blocking. By design reveal and pageshow are too late for that. Having it globally accessible for the lifetime of the Document means authors can use the info in scripts in head to set up the render-blocking stuff. It particularly matters as we reduce the lead time between triggering pre-rendering and activation. Such that the optimal render-blocking step would matter for performance, and the from info will likely stay unchanged on activation.

Out of the options Domenic mentioned, I like 4. The browser automagically updates the value and if needed later, we can add an event to notify when the value changes.

[noamr]

One use-case for exposing it sooner would be tagging appropriate resources and DOM nodes as render-blocking. By design reveal and pageshow are too late for that. Having it globally accessible for the lifetime of the Document means authors can use the info in scripts in head to set up the render-blocking stuff. It particularly matters as we reduce the lead time between triggering pre-rendering and activation. Such that the optimal render-blocking step would matter for performance, and the from info will likely stay unchanged on activation.

Out of the options Domenic mentioned, I like 4. The browser automagically updates the value and if needed later, we can add an event to notify when the value changes.

Yea I see the point in this use case. (4) handles it pretty well, and perhaps (2) is confusing when prerendering.

[noamr]

4. Magically-updating from and type, activation-focused

Note that entry might also magically update with the right amount of soft navigations. Perhaps instead of magically updating the contents of navigation.crossDocument, that getter would return something new after each activation, and the object itself can remain consti-sh? It would be more "conceptually clean" than a mutating object.

So I think:

navigation.crossDocument
    .entry
    .from
    .type

and navigation.crossDocument is a getter rather than a constant. WDYT?

[domenic]

How can entry update with soft navigations? I thought it was supposed to represent the first entry after a cross-document navigation, thus the name navigation.crossDocument.entry meaning something like "the cross-document navigation's resulting entry".

[noamr]

How can entry update with soft navigations? I thought it was supposed to represent the first entry after a cross-document navigation, thus the name navigation.crossDocument.entry meaning something like "the cross-document navigation's resulting entry".

A prerender activation after a soft navigation in the prerendered page would be to the lastest entry.
A BFCache restore after a soft navigation would be a cross-document navigation to an entry that's not the original cross-document entry.

[domenic]

OK, so it's not supposed to represent the original cross-document navigation. So crossDocument is not a good name.

I think I'd prefer the properties updating, instead of the object; since they can vary independently, that seems more clear.

[noamr]

OK, so it's not supposed to represent the original cross-document navigation. So crossDocument is not a good name.

Right, it's the most recent cross document navigation rather than the original one.

If "activation" doesn't feel 100%, perhaps we should call this a page transition? We already have a PageTransitionEvent for page-show/page-hide. btw activation is already web-exposed in navigation timing - the timestamp when a prerendered page was activation.

So if we don't like navigation.crossDocument, I suggest document.lastActivation or navigation.lastPageTransition or navigation.lastActivation (perhaps my favorite), with entry, from, type, and potentially a change event.

I think I'd prefer the properties updating, instead of the object; since they can vary independently, that seems more clear.

I'm OK with that.

[domenic]

I'm good with something related to "activation". I apologize for not realizing from the start that this would need to be more connected to activation, and we couldn't just hide it under the concept of "navigation" or "cross-document navigation".

last seems tricky since for prerendering code, it won't actually have happened yet? So maybe just navigation.activation?

[noamr]

I'm good with something related to "activation". I apologize for not realizing from the start that this would need to be more connected to activation, and we couldn't just hide it under the concept of "navigation" or "cross-document navigation".

last seems tricky since for prerendering code, it won't actually have happened yet? So maybe just navigation.activation?

Works for me!

[noamr]

@zcorpan how do you feel about this? Do we need a new standards position on this or is the one for navigation API enough?

[khushalsagar]

last seems tricky since for prerendering code, it won't actually have happened yet? So maybe just navigation.activation?

What will activation be set to for a prerendering page? I want to make sure the prerendering page has access to the speculative "from" entry to configure render-blocking.

[noamr]

last seems tricky since for prerendering code, it won't actually have happened yet? So maybe just navigation.activation?

What will activation be set to for a prerendering page? I want to make sure the prerendering page has access to the speculative "from" entry to configure render-blocking.

It would be null. I think that's good.
Note that the activator page might soft-navigate and change the URL before it activates the prerendered page.

[khushalsagar]

It would be null. I think that's good.
Note that the activator page might soft-navigate and change the URL before it activates the prerendered page.

I'd be curious to hear @jeremyroman @domenic's take on this. It could put pre-render at a disadvantage. For example, a page could set up parser blocking only when there is a morph transition which requires a DOM node on the other side. Like list->details page needs that but home->details page doesn't. A pre-rendered page won't be able to do that. Again this only matters if the delay between starting pre-rendering and activation is small but that's the direction we seem to be headed in.

The fact that activator page's URL can change is a concern but seems reasonable to start the pre-rendered page with the value from the Document that initiated the pre-render. And update if that changes. We're already adding the concept that this value can update for BFCache.

[noamr]

It would be null. I think that's good.
Note that the activator page might soft-navigate and change the URL before it activates the prerendered page.

I'd be curious to hear @jeremyroman/@domenic's take on this. It could put pre-render at a disadvantage. For example, a page could set up parser blocking only when there is a morph transition which requires a DOM node on the other side. Like list->details page needs that but home->details page doesn't. A pre-rendered page won't be able to do that. Again this only matters if the delay between starting pre-rendering and activation is small but that's the direction we seem to be headed in.

A prerendered page can do this at prerenderingchange. I think it makes much more sense than doing it in the head, when you don't know your activating from entry.

Note that the prerendered page also has access to the referrer, which is the same as from in this case.

[domenic]

In prototyping an interesting case came up. After the replace navigation from the initial about:blank, what should navigation.activation.from be?

Currently in #9856 we construct a new NavigationHistoryEntry for it, because of this clause:

Otherwise, if navigationType is "replace" and previousEntryForActivation's document state's origin is same origin with document's origin, then set activation's old entry to a new NavigationHistoryEntry in navigation's relevant realm, whose session history entry is previousEntryForActivation.

However, generally the philosophy of the navigation API is that it "doesn't work" on the initial about:blank, and tries not to expose the initial about:blank's existence. So, I am wondering if instead we want to censor it to navigation.activation.from === null?

[khushalsagar]

I assumed a navigation from about:blank would be considered cross-origin. Is that not how the navigation API treats it? For the VT use-case this treatment would work because there can't possibly be a transition when navigating away from about:blank.

[domenic]

I assumed a navigation from about:blank would be considered cross-origin.

Not necessarily. The initial about:blank inherits the origin from its creator, and its creator might be same-origin to the page that replaces the initial about:blank.

Is that not how the navigation API treats it?

The navigation API currently doesn't expose it one way or another, since you can't observe replaced entries, and the navigation API itself is disabled while on the initial about:blank. So this feature is the first time we'd have to answer the question.

[khushalsagar]

The initial about:blank inherits the origin from its creator, and its creator might be same-origin to the page that replaces the initial about:blank.

Ah TIL. In that case your statement here sounds good to me: "I am wondering if instead we want to censor it to navigation.activation.from === null". The initial about:blank seems like an internal detail of how navigation works.

[noamr]

I'm OK with not exposing the initial about:blank here.
I do wonder about same-origin history jumps - they don't appear in the session history, but I don't see why they can't be orphan entries like replace. This info is anyway otherwise observable.

I think in general we should allow orphan entries for same-origin navigations rather than special-case replace, and opt-out the initial about:blank from this.

@domenic WDYT?

[domenic]

I'm OK with that.

[noamr]

I'm OK with that.

Revised the PR.