feat: add navigationHistory.getEntryAtIndex(int index) method

[alicelovescake]

Description of Change

Problem

Currently, Electron does not expose APIs that provide a list of navigation history. As a result, developers have no way to implement features such as:

• Cmd/Ctrl click on the back/forward button to open the last or next entry in a new tab
• Restoring tab history when tabs are restored

Proposed solution

In Chromium, a Navigation Controller manages session history. There are Chromium APIs that expose NavigationEntry, a data structure that captures all the information required to recreate a browsing state. In particular, NavigationEntry* GetEntryAtIndex(int index) allows us to fetch the navigation entry at a particular index.

NavigationEntry and NavigationController are both currently being used in the Electron codebase so there is no additional upkeep to expose new APIs that involve the same data structures.

Advantages of exposing a new API:

• Developers don’t need to manually bookkeep navigation states, which has the risk of going out of sync with Chromium’s navigation history entries.
• Enhance functionality of Electron for long term usability and DX.

This PR:

• Adds a new endpoint getEntryAtIndex to surface the title and url of a navigation entry at a particular index.
• Refactors WebContents to add a new instance property navigationHistory to store all navigation related methods (on the javascript side, see web-contents.ts)
• Exposes exiting getActiveIndex and length methods on navigationHistory .
• Partially fixes [Feature Request]: View and modify navigation history of webcontents (and by extension webviews) #33899 and [Feature Request]: List webContents history entries  #41250 with the following:

1. Developers can get current navigation index with .getActiveIndex() and entire length of navigation history with .length() These APIs exist but are not included in the documentation. This PR adds them to public docs.
2. With current indexes available, developers can fetch url and title of any navigation entry to save/ recreate history or cmd click back button to open in a new tab

• Developers can't get an entire list of the navigation entries in a single API, but the available APIs should provide enough support to recreate the entire navigation history for every tab.
• Updates documentation and adds tests

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added a new instance property navigationHistory on webContents API with navigationHistory.getEntryAtIndex method, enabling applications to retrieve the URL and title of any navigation entry within the browsing history.

[welcome]

💖 Thanks for opening this pull request! 💖

We use semantic commit messages to streamline the release process. Before your pull request can be merged, you should update your pull request title to start with a semantic prefix.

Examples of commit messages with semantic prefixes:

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

Things that will help get your PR across the finish line:

• Follow the JavaScript, C++, and Python coding style.
• Run npm run lint locally to catch formatting errors earlier.
• Document any user-facing changes you've made following the documentation styleguide.
• Include tests when adding/changing behavior.
• Include screenshots and animated GIFs whenever possible.

We get a lot of pull requests on this repo, so please be patient and we will get back to you as soon as we can.

[alicelovescake]

FYI, the failing tests (returns a Promise with a NativeImage in the rendere) in CI are not from my tests, and pass locally on my machine. I don't have the permission to retry the failed tests. So let me know if this is a blocker!

[codebytere]

@alicelovescake if you rebase the tests have since been disabled!

[erickzhao]

Hey @alicelovescake, can you add API documentation to the PR? We generally do API review via the Markdown API documentation (which also is used to generate the TypeScript types).

[alicelovescake]

Hey @alicelovescake, can you add API documentation to the PR? We generally do API review via the Markdown API documentation (which also is used to generate the TypeScript types).

Will do! If it's ok with everyone, I'm going to include API documentation for some existing APIs that were not exposed before as well as my new one:

• "getActiveIndex", &WebContents::GetActiveIndex
• "length", &WebContents::GetHistoryLength
• "getNavigationEntryForIndex", &WebContents::GetNavigationEntryForIndex

[MarshallOfSound]

I don't love the overloading of the webContents namespace, I think especially if we're documenting a few internal APIs too this might make sense to live on it's own webContents.navigationHistory property or something.

So it would be webContents.navigationHistory.length() etc.

Would make naming make more sense too, like "length" of a webContents doesn't make sense independent of more context, where as the length of a "history" thing does make sense

+1 on the concept
-0.5 on the API location

[alicelovescake]

I don't love the overloading of the webContents namespace, I think especially if we're documenting a few internal APIs too this might make sense to live on it's own webContents.navigationHistory property or something.

So it would be webContents.navigationHistory.length() etc.

Would make naming make more sense too, like "length" of a webContents doesn't make sense independent of more context, where as the length of a "history" thing does make sense

+1 on the concept -0.5 on the API location

Great point Sam! I agree that we can better organize these endpoints, especially the ones all related to navigationHistory.

What I can do is:

1. In this PR, create new navigationHistory namespace to store getActiveIndex, length, and GetEntryAtIndex.
2. In a separate PR, duplicate and move other navigationHistory related endpoints like CanGoBack, GoBack, CanGoForward, GoForward, CanGoToOffset, GoToOffset, CanGoToIndex, GoToIndex to the new namespace after the first PR merges.
3. Deprecate the old endpoints later and highlight the change in release notes.

Let me know what you think and if you have other ideas! Appreciate the feedback!

[MarshallOfSound]

Let me know what you think and if you have other ideas! Appreciate the feedback!

1. Sounds great 💯
2. Sounds great too 👍 We already did this from BrowserWindow -> WebContents many years ago, moving things another layer deep seems fine as long as we maintain the existing API surface as aliases to avoid the breaking change
3. Other folks can comment on this, but maintaining the old aliases isn't that big of a maintenance burden. Happy leaving those in for a while. Deprecating and noting is fine, just like, there's no actual timeline to remove what is effectively webContents.foo = () => webContents.nav.foo() 😄

I'll take a look at the actual code / docs here next week (or at least try too 😅)

[trop]

I was unable to backport this PR to "30-x-y" cleanly;
you will need to perform this backport manually.

[trop]

I was unable to backport this PR to "29-x-y" cleanly;
you will need to perform this backport manually.

[trop]

@alicelovescake has manually backported this PR to "29-x-y", please check out #41661

[trop]

@alicelovescake has manually backported this PR to "30-x-y", please check out #41662

[panther7]

These is missing in changelog (v29.3.0 and 30.x)

[alicelovescake]

These is missing in changelog (v29.3.0 and 30.x)

Thanks for the callout! This is being updated!