feat: add webContents.fromDevToolsTargetId()

[samuelmaddock]

Description of Change

Playwright has experimental support for Electron which works pretty well for single BrowserWindow use cases. However, there are currently issues when multiple BrowserWindows are involved (microsoft/playwright#6760).

The proposed changes introduce the static method webContents.fromDevToolsTargetId(targetId) which allows for looking up a WebContents based on the stable DevTools TargetID.

Using this method will allow Playwright to properly lookup WebContents instances and get their associated BrowserWindows.

Since this enables use cases in a third-party application, it'd be great to be backported to all actively supported versions of Electron (>=11).

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation is 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 webContents.fromDevToolsTargetId(targetId) to lookup a WebContents instance from an associated Chrome DevTools Protocol TargetID.

[pavelfeldman]

It might be easier to expose https://source.chromium.org/chromium/chromium/src/+/main:content/browser/renderer_host/frame_tree_node.h;l=118;bpv=0;bpt=1 instead.

[zcbenz]

API Looks good to me.

[nornagon]

API LGTM

[codebytere]

API LGTM here as well, and agree with @nornagon above about webcontents creation.

[samuelmaddock]

It might be easier to expose https://source.chromium.org/chromium/chromium/src/+/main:content/browser/renderer_host/frame_tree_node.h;l=118;bpv=0;bpt=1 instead.

@pavelfeldman Just so this doesn't go unaddressed, I'll look into binding this in another PR if I find it's needed for debugging specific frames. FrameTreeNode is not a public API which we want to try to avoid. If later it's found to be needed, we can bind the public API RenderFrameHost::GetDevToolsFrameToken() for Electron's WebFrameMain.

[samuelmaddock]

Discussion came up as to whether this is the right way forward for this API.

DevToolsAgentHost is an interface which is implemented for multiple contexts (see overrides for DevToolsAgentHost::GetType()). Some contexts are associated with a specific WebContents while others are not.

For this specific use case, we want to get the associated WebContents for a DevToolsAgentHost currently attached to a frame. We do so by looking up the DevToolsAgentHost by its unique TargetID. If it exists and is of the expected DevToolsAgentHost subclass, it will have a WebContents accessible from DevToolsAgentHost::GetWebContents().

This approach is sufficient for the problem being solved.

---

One alternative design would be to expand the capabilities of the Debugger API, currently only accessible from a WebContents.

interface Debugger {
  /** Get a debugger from an existing, attached DevTools host ID. */
  static fromTargetId(id: string): Debugger | undefined;

  /** An alternative to webContents.fromDevToolsTargetId() */
  webContents?: WebContents;

  /**
    * The type of DevToolsAgentHost.
    * https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_agent_host_impl.cc;l=43-50;drc=2205e9942d2fc0ef177f6802683345a1822da88e
    */
  type: 'page' | 'iframe' | 'worker' | 'shared_worker' | /* etc. */;
}

With this approach, we could create a Debugger instance by looking up an existing DevToolsAgentHost's ID (Target ID). Then its associated WebContents would be accessible via a getter.

This is more complex and would involve careful memory considerations with a likely needed introduction of the Pinnable interface to Debugger.

I'm not currently aware of another use case that this design would solve so the complexity might not be worth it. Another exported module would be needed as well for the static method introduced to Debugger.

[nornagon]

re-✅ , I think this approach is fine.

[release-clerk]

Release Notes Persisted

Added webContents.fromDevToolsTargetId(targetId) to lookup a WebContents instance from an associated Chrome DevTools Protocol TargetID.

[trop]

I have automatically backported this PR to "12-x-y", please check out #30730

[trop]

I have automatically backported this PR to "13-x-y", please check out #30731

[trop]

I have automatically backported this PR to "14-x-y", please check out #30732

[trop]

I have automatically backported this PR to "15-x-y", please check out #30733