Diagram relation of WebView2 control, SDK, & Runtime

microsoft-edge/toc.yml

@@ -1328,6 +1328,9 @@
             - name: Overview of WebView2 APIs
               href: ./webview2/concepts/overview-features-apis.md
 
+            - name: Overview of the components of the WebView2 platform
+              href: webview2/concepts/platform-components.md
+
             - name: "Main classes for WebView2: Environment, Controller, and Core"
               href: ./webview2/concepts/environment-controller-core.md
 

microsoft-edge/webview2/concepts/browser-features.md

@@ -109,6 +109,8 @@ The following Microsoft Edge and Google Chrome settings webpages aren't availabl
 Google has disabled Google Authentication in embedded webviews, which includes WebView2, due to a security policy they have set.  See [Upcoming security changes to Google's OAuth 2.0 authorization endpoint in embedded webviews](https://developers.googleblog.com/2021/06/upcoming-security-changes-to-googles-oauth-2.0-authorization-endpoint.html).
 
 To stay up-to-date on the latest discussion, in the WebView2Feedback repo, see [Google Auth Flows and WebView2](https://github.com/MicrosoftEdge/WebView2Feedback/issues/1647).
+
+
 <!-- ====================================================================== -->
 ## Additional keyboard shortcuts information
 
@@ -214,3 +216,10 @@ If you set `AreBrowserAcceleratorKeysEnabled` to `FALSE`, the following addition
 #### Customizing an individual key
 
 To customize any of the keys individually, use the [AcceleratorKeyPressed](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.acceleratorkeypressed) event.
+
+
+<!-- ====================================================================== -->
+## See also
+
+* [List of Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches)
+* [AcceleratorKeyPressed](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.acceleratorkeypressed?view=webview2-dotnet-1.0.774.44&preserve-view=true) event

microsoft-edge/webview2/concepts/distribution.md

@@ -294,6 +294,13 @@ To use the new version of the WebView2 Runtime, you need to either release all r
 
 In the Evergreen distribution mode, the WebView2 Runtime is automatically kept up to date on the client to provide the latest features and security fixes.  If you use Evergreen distribution, to ensure that your WebView2 app stays compatible with the web, you should set up testing infrastructure.
 
+Microsoft Edge preview channels (Beta, Dev, and Canary) provide a sneak peek into what is coming next in the WebView2 Runtime.  Test your WebView2 app regularly against a Microsoft Edge preview channel, and update your app or [report issues](https://github.com/MicrosoftEdge/WebViewFeedback) if issues arise.  See [Test upcoming APIs and features](../how-to/set-preview-channel.md).
+  Canary is the recommended preview channel, because it ships at the fastest cadence and has the newest APIs.
+
+To help you decide which channel is right, see [Overview of the Microsoft Edge channels](/deployedge/microsoft-edge-channels).  You can [Download Microsoft Edge Insider Channels](https://www.microsoft.com/edge/download/insider) on your test environment, and use `regkey` or environment variables to indicate the channel preference for your testing app.
+
+See [CreateCoreWebView2EnvironmentWithOptions](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environmentwithoptions).  You can also use WebDriver to automate WebView2 testing, as described in [Automate, and test WebView2 with Microsoft Edge WebDriver](../how-to/webdriver.md).
+
 For best practices about how to test your app for forward-compatibility, see [Prerelease testing using preview channels](../how-to/prerelease-testing.md) and [Self-host by deploying preview channels](../how-to/self-hosting.md).
 
 
@@ -418,3 +425,9 @@ Example managed app folder structure:
         \win-x64\native\WebView2Loader.dll (x64)
         \win-x86\native\WebView2Loader.dll (x86)
 ```
+
+
+<!-- ====================================================================== -->
+## See also
+
+* [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-section) - a section of the **Microsoft Edge WebView2** page, which links to the present article.

microsoft-edge/webview2/how-to/context-menus.md

@@ -728,7 +728,7 @@ When the user selects a WebView2 context menu command (a default menu item that'
 ---
 
 
-<!-- ---------------------------------- -->
+<!-- ------------------------------ -->
 #### Custom menu items
 
 If your host app reports a custom menu item as the selected menu item, then the `CustomMenuItemSelected` event will be fired for the custom menu item.

microsoft-edge/webview2/how-to/debug-visual-studio-code.md

@@ -99,7 +99,7 @@ Open `launch.json` and complete the following actions to use targeted WebView2 d
 When debugging your app, you might need to step through the code from the beginning of the rendering process.  If you are rendering webpages on sites and you don't have access to the source code, you can use the `?=value` option, because webpages ignore unrecognized parameters.
 
 
-<!-- ---------------------------------- -->
+<!-- ------------------------------ -->
 #### Cannot debug two WebView2 controls at the same time
 
 After the first match is found in the URL, the debugger stops.  You cannot debug two WebView2 controls at the same time, because the CDP port is shared by all WebView2 controls, and uses a single port number.
@@ -257,15 +257,15 @@ WebView2 doesn't load source maps that are referenced by content which was loade
 You might encounter these scenarios when using the debugger.
 
 
-<!-- ---------------------------------- -->
+<!-- ------------------------------ -->
 #### Doesn't stop at breakpoint
 
 If the debugger doesn't stop at the breakpoint, and you have debug output: 
 
 To solve the issue, confirm that the file with the breakpoint is the same file that's used by the WebView2 control.  The debugger doesn't perform source path mapping.
 
 
-<!-- ---------------------------------- -->
+<!-- ------------------------------ -->
 #### Can't attach to running process
 
 If you can't attach to a running process, and you get a timeout error:

microsoft-edge/webview2/how-to/javascript.md

@@ -23,7 +23,7 @@ This article assumes that you already have a working project. If you don't have
 <!-- ====================================================================== -->
 ## Basic WebView2 functions
 
-Use the following functions to begin embedding JavaScript in your WebView2 app.
+Use the following functions to embed JavaScript in the native-side code of your WebView2 app:
 
 | API | Description |
 | --- | --- |
@@ -34,27 +34,27 @@ Use the following functions to begin embedding JavaScript in your WebView2 app.
 <!-- ====================================================================== -->
 ## Scenario: ExecuteScript JSON-encoded results
 
-Because the result of `ExecuteScriptAsync` is JSON-encoded, if the result of evaluating the JavaScript is a string, you will receive a JSON-encoded string and not the value of the string.
+Because the result of `ExecuteScriptAsync` is JSON-encoded, if the result of evaluating the JavaScript is a string, your native-side code will receive a JSON-encoded string, not the value of the string.
 
-For example, the following code executes script that results in a string.  The resulting string includes a quote at the start, a quote at the end, and escaping slashes:
+For example, the following native-side code executes script that results in a string.  The resulting string includes a quote at the start, a quote at the end, and escaping slashes:
 
 ```csharp
 string result = await coreWebView2.ExecuteScriptAsync(@"'example'");
 Debug.Assert(result == "\"example\"");
 ```
 
-The script returns a string that `ExecuteScript` JSON-encodes for you.  If you call `JSON.stringify` from your script, then the result is doubly encoded as a JSON string the value of which is a JSON string.
+The script returns a string that `ExecuteScript` JSON-encodes for you.  If you call `JSON.stringify` from your script (in your web-side code), then the result is doubly encoded, as a JSON string the value of which is a JSON string.
 
-Only the properties that are directly in the result are included in the JSON-encoded object; inherited properties aren't included in the JSON-encoded object.  Most DOM objects inherit all properties, so you'll need to explicitly copy their values into another object to return.  For example:
+Only the properties that are directly in the result are included in the JSON-encoded object; inherited properties aren't included in the JSON-encoded object.  Most DOM objects inherit all properties, so your web-side code must explicitly copy the properties' values into another object and return that object to your native-side code.  For example:
 
 Script              | Result
 ---                 | ---
 `performance.memory`  | `{}`
 `(() => { const {totalJSHeapSize, usedJSHeapSize} = performance.memory; return {totalJSHeapSize, usedJSHeapSize}; })();` |  `{"totalJSHeapSize":4434368,"usedJSHeapSize":2832912}`
 
-When we return just `performance.memory` we don't see any of its properties in the result because all properties are inherited.  If instead, we copy particular property values from `performance.memory` into our own new object to return, then we see those properties in the result.
+When we return just `performance.memory`, we don't see any of its properties in the result, because all properties are inherited.  If instead, the web-side code copies particular property values from `performance.memory` into a new object and returns that object, then the native-side code sees those properties in the result.
 
-When executing script via `ExecuteScriptAsync` that script is run in the global context.  It helps to have your script in an anonymous function so that any variables you define aren't polluting the global context.
+When executing script via `ExecuteScriptAsync`, that script is run in the global context.  It helps to have your script in an anonymous function, so that any variables you define aren't polluting the global context.
 
 For example:
 
@@ -67,11 +67,14 @@ For example:
 ## Scenario: Running a dedicated script file
 
 In this section, you access a dedicated JavaScript file from your WebView2 control.
+<!-- todo: clarify the scenario.  from native code? "from" is ambiguous.  is the file a web-side file?
+what does "dedicated" mean? -->
+
 
 > [!NOTE]
 > Although writing JavaScript inline may be efficient for quick JavaScript commands, you lose JavaScript color themes and line formatting that makes it difficult to write large sections of code in Visual Studio.
 
-To solve the problem, create a separate JavaScript file with your code, and then pass a reference to that file using the `ExecuteScriptAsync` parameters.
+To solve the problem, create a separate JavaScript file that contains your code, and then pass a reference to that file by using the `ExecuteScriptAsync` parameters.
 
 1. Create a `.js` file in your project, and add the JavaScript code that you want to run.  For example, create a file called `script.js`.
 

microsoft-edge/webview2/how-to/publish-uwp-app-store.md

@@ -89,7 +89,7 @@ Once you're satisfied that your packaged app works, run the Windows App Certific
 1. After a few minutes, the Windows App Certification Kit (WACK) shows a results page.  If the app failed, click the link to review the results.
 
 
-<!-- ---------------------------------- -->
+<!-- ------------------------------ -->
 #### Resolving tests
 
 The results page of the Windows App Certification Kit (WACK) app shows any tests that need to be resolved.

microsoft-edge/webview2/how-to/webresourcerequested.md

@@ -108,7 +108,6 @@ Another example is if the host app is only interested in all requests that are u
 
 ---
 
-
 For details about how the URL filter works, see [CoreWebView2.AddWebResourceRequestedFilter Method > Remarks](/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter#remarks)
 
 
@@ -143,6 +142,7 @@ Intercepting requests sent from WebView2 enables you to further configure your r
 
 <!-- ------------------------------ -->
 #### Example: Intercepting a request, to monitor or modify it
+<!-- ## Example: Header modification when making a request -->
 
 <!-- this example doesn't exist in the sample repo -->
 
@@ -484,7 +484,6 @@ m_webView->add_WebResourceResponseReceived(
 
 ##### [.NET](#tab/dotnet)
 
-
 **Request:**
 
 * [CoreWebView2.AddWebResourceRequestedFilter Method](/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter)

microsoft-edge/webview2/index.md

@@ -33,7 +33,7 @@ The following diagram shows the spectrum of apps, from maximum reach, to maximum
 
 *  Wide **reach** includes websites and Progressive Web Apps.
 
-*  In the middle are hybrid apps, such as WebViews and Electron.
+*  In the middle are hybrid apps, such as WebViews and [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)).
 
 *  Maximum **power** is native apps.
 
@@ -62,9 +62,33 @@ Hybrid apps, in the middle of this spectrum, allow you to enjoy the best of both
 *  **Incremental adoption**.  Add web components piece-by-piece to your app.
 
 
+<!-- ====================================================================== -->
+## Overview of the components of the WebView2 platform
+
+To add WebView2 to your app, you use the WebView2 SDK on your development machine, and distribute the WebView2 Runtime to user machines.  The following diagram shows the high-level WebView2 components on your development machine and user machines.
+
+![Full diagram of WebView2](./index-images/full-diagram.png)
+<!-- .png is owned by index.md, also linked to by platform-components.md -->
+
+Developing a WebView2 app involves software residing in the following places:
+
+| Location | Description |
+|---|---|
+| Dev machine | You use a Visual Studio project that includes the WebView2 SDK.  The SDK includes the WebView2 Runtime, which is an embedded web browser component used for the WebView2 control instances in your host app. |
+| Distributing the app and Runtime | There are several ways to deliver the always up-to-date Evergreen version of the WebView2 Runtime to user machines, with several levels of Internet connectivity supported.  Some scenarios benefit from distributing a specific, fixed-version WebView2 Runtime. |
+| User machine | Your host app on user machines includes instances of the WebView2 control, which uses the WebView2 Runtime. |
+| Resources | The product documentation; the WebView2Samples repo including basic Getting Started WebView2 projects and more full-featured Sample projects; the WebView2Announcements repo; and the WebView2Feedback repo. |
+
+For details, see [Overview of the components of the WebView2 platform](./concepts/platform-components.md).
+
+
 <!-- ====================================================================== -->
 ## Supported platforms
 
+
+<!-- ------------------------------ -->
+#### Frameworks and coding languages supported
+
 The following programming environments are supported:
 
 *  Win32 C/C++
@@ -74,6 +98,10 @@ The following programming environments are supported:
 *  [WinUI 2.0](/windows/apps/winui/winui2/)
 *  [WinUI 3.0](/windows/apps/winui/winui3/)
 
+
+<!-- ------------------------------ -->
+#### Windows versions supported
+
 WebView2 apps can run on the following versions of Windows:
 
 *  Windows 11
@@ -125,6 +153,7 @@ After your environment is set up and the samples build and run on your machine,
 <!-- ====================================================================== -->
 ## See also
 
+* [Overview of the components of the WebView2 platform](./concepts/platform-components.md)
 * [Overview of WebView2 APIs](concepts/overview-features-apis.md)
 * [Distribute your app and the WebView2 Runtime](concepts/distribution.md)
 

microsoft-edge/webview2/samples/webview2browser.md

@@ -314,7 +314,7 @@ We're setting up a few things here. The [ICoreWebView2Settings](/microsoft-edge/
 <!-- ------------------------------ -->
 #### Navigate to web page
 
-You can navigate to a web page by entering its URI in the address bar. When pressing Enter, the controls WebView will post a web message to the host app so it can navigate the active tab to the specified location. Code below shows how the host Win32 application will handle that message.
+You can navigate to a webpage by entering its URI in the address bar. When pressing Enter, the controls WebView will post a web message to the host app so it can navigate the active tab to the specified location. Code below shows how the host Win32 application will handle that message.
 
 ```cpp
         case MG_NAVIGATE:
@@ -525,9 +525,9 @@ function reloadActiveTabContent() {
 <!-- ------------------------------ -->
 #### Communicating the WebViews
 
-We need to communicate the WebViews that power the tabs and UI, so that user interactions in one tab's WebView have the desired effect in the other WebView.  WebView2Browser makes use of set of very useful WebView2 APIs for this purpose, including [PostWebMessageAsJson](/microsoft-edge/webview2/reference/win32/icorewebview2#postwebmessageasjson), [add_WebMessageReceived](/microsoft-edge/webview2/reference/win32/icorewebview2#add_webmessagereceived) and [ICoreWebView2WebMessageReceivedEventHandler](/microsoft-edge/webview2/reference/win32/icorewebview2webmessagereceivedeventhandler).
+We need to communicate the WebViews that power the tabs and UI, so that user interactions in one tab's WebView have the desired effect in the other WebView.  To do this,  WebView2Browser uses WebView2 APIs, including [PostWebMessageAsJson](/microsoft-edge/webview2/reference/win32/icorewebview2#postwebmessageasjson), [add_WebMessageReceived](/microsoft-edge/webview2/reference/win32/icorewebview2#add_webmessagereceived) and [ICoreWebView2WebMessageReceivedEventHandler](/microsoft-edge/webview2/reference/win32/icorewebview2webmessagereceivedeventhandler).
 
-On the JavaScript side, we're making use of the `window.chrome.webview` object exposed to call the `postMessage` method and add an event lister for received messages.
+On the JavaScript side, we use the exposed `window.chrome.webview` object to call the `postMessage` method and add an event lister for received messages.
 
 ```cpp
 HRESULT BrowserWindow::CreateBrowserControlsWebView()
@@ -592,7 +592,7 @@ function reloadActiveTabContent() {
 <!-- ------------------------------ -->
 #### Tab handling
 
-A new tab will be created whenever the user clicks on the **new tab** button to the right of the open tabs. The control's WebView will post a message to the host application to create the WebView for that tab and create an object tracking its state.
+A new tab is created whenever the user clicks the **New tab** button to the right of the open tabs. The control's WebView will post a message to the host application to create the WebView for that tab and create an object tracking its state.
 
 ```javascript
 function createNewTab(shouldBeActive) {