Add iframe/window "navigated" event

[jakearchibald]

iframe.src = url;

Right now, it's difficult to know when the iframe commits its navigation. There's the 'load' event, but that waits on inner resources to load, so it can be long after the navigation is committed.

I think this timing information is already available, as you can poll iframe.contentDocument until it changes or starts throwing. At which point you know the navigation has commited.

A callback for this would solve #2161, as you could add a DOMContentLoaded listener at this point if the iframe is same-origin.

---

Suggested API:

iframe.addEventListener('navigated', () => {
  // Fired when a navigation commits.
});

await iframe.navigated;
// Resolves when the iframe's navigation commits.
// This promise changes each time src is set.

It's unclear if 'navigated' should fire on a failed navigation, and if .navigated should reject, due to #125, #1230, and #4247 (h/t @domenic).

I'm not sure how you'd do the same thing for WindowProxy. Would we be able to hang a .navigated promise off WindowProxy?

[domenic]

I'm not sure how you'd do the same thing for WindowProxy. Would we be able to hang a .navigated promise off WindowProxy?

Why would we want to do this for WindowProxy?

[jakearchibald]

If we come up with a solution for iframes, it feels like we should also solve it for window.open windows, which have the same limitations.

[annevk]

Hmm, but once it starts throwing you wouldn't know if the user navigated further to another origin until you get another load event, right? I think we have to be quite careful here, especially since the I don't think the navigation algorithm is implemented as-is across the board.

[jakearchibald]

That's fair. Maybe this makes the promise more attractive, where the promise only changes when the src is set – it doesn't change when navigations are triggered within the iframe itself.

I'm not sure if this would work with WindowProxy.

[annevk]

As a signal for when initial about:blank has been replaced? That could work on Window I suppose as that's the only case where its associated document is changed. (Again though, there's a lot of non-interop in that area around events.)

[jakearchibald]

Yeah, I suppose it could apply only to the very first navigation that happens to an iframe/window. For subsequent navigations it might make more sense to have something like windowProxy.location.navigate which returns a promise.

[Jamesernator]

Would this also allowing cancelling the navigation, or would this fire just after the navigation has started fetching?

For me I've been recently wanting to be able to intercept and capture navigations to insert a "Are your sure you want to go to blah?". e.g. Being able to do this would be great:

iframe.addEventListener("navigated", () => {
  if (!isSafe(iframe.contentWindow.location.href)) {
    const confirmNavigationURL = new URL("/confirmNavigation", location.href);
    confirmNavigationURL.searchParams.set("url", iframe.contentWindow.location.href);
    iframe.contentWindow.location.href = confirmNavigationURL.href;
  }
});

[domenic]

@Jamesernator I think your particular use case is better served by https://github.com/WICG/app-history. Although that's for your own window, not for an iframe, so maybe not...

[Jamesernator]

@Jamesernator I think your particular use case is better served by https://github.com/WICG/app-history. Although that's for your own window, not for an iframe, so maybe not...

Actually yes the cancellation behaviour of that proposal is fine for my case as I can inject scripts into the iframe, outside control would be slightly less awkward, but admittedly my use case is super super niche and appHistory would be more than sufficient.