docs: add info about adding popups exception and remove jank on load

.vitepress/theme/styles/content.scss

@@ -91,3 +91,8 @@
 .content-container .VPDocFooter {
   margin-top: 30px;
 }
+
+.mx-auto {
+  margin-left: auto !important;
+  margin-right: auto !important;
+}

.vitepress/theme/styles/fixes.scss

@@ -220,6 +220,10 @@
   margin-top: 40px !important;
 }
 
+.vp-doc h2 .header-anchor {
+  top: 16px;
+}
+
 .vp-doc p > strong > a,
 .vp-doc p > a,
 .vp-doc li > strong > a,

docs/platform/webcontainers/browser-config.md

@@ -22,15 +22,30 @@ With Chrome's defaults, starting with version 118 or later, you should get a pre
 
 Read on if you run into issues or want an even smoother experience.
 
-Previews opened in a separate tab will require you to connect them to the editor. You usually get prompted to click on a button to do that. However, you might do that more frequently than expected with Chrome's [memory saver][CHROME_MEMORY_SAVER]. To avoid it, you can add the following exception in [chrome://settings/performance](chrome://settings/performance):
+### Previews in a separate tab {#chrome-preview-separate-tab}
+
+Previews opened in a separate tab are not connected by default to the editor and require an extra step. To complete this step, you are usually prompted to click a button.
+
+This can happen automatically if your popups settings, [chrome://settings/content/popups](chrome://settings/content/popups), are adjusted with the following exception:
+
+```
+https://[*.]webcontainer.io
+```
+
+<img class="mx-auto" alt="Chrome popups settings showing the *.webcontainer.io origins as exceptions" src="./assets/chrome-settings-popups.png" width="800" height="502.37" />
+
+Once done, whenever the preview needs to reconnect to the editor, it will open a popup that gets immediately closed.
+
+Lastly, if Chrome's [memory saver][CHROME_MEMORY_SAVER] is turned on, this step might be necessary more often than required. To avoid it, you can add the following exception in [chrome://settings/performance](chrome://settings/performance):
 
 ```
+https://webcontainer.io
 https://stackblitz.com
 ```
 
-Once done, you should see something similar to this:
+Your performance settings should be similar to this:
 
-<img alt="Chrome performance settings showing the memory saver section with an exception for stackblitz.com" src="./assets/chrome-memory-saver.png" width="800" />
+<img class="mx-auto" alt="Chrome performance settings showing the memory saver section with an exception for stackblitz.com" src="./assets/chrome-memory-saver.png" width="800" height="502.37" />
 
 ### Enabling Service Workers {#chrome-service-workers}
 
@@ -45,7 +60,7 @@ The first option should be preferred because this is a [new feature][GOOGLE_SP]
 
 Visit `chrome://flags/#third-party-storage-partitioning` and choose `Enabled` in the drop down. In recent version of Chrome, choosing the `Default` value should work too.
 
-<img alt="Chrome flags showing the third-party Storage Partitioning option enabled." src="./assets/chrome-enable-sp.png" width="800" />
+<img alt="Chrome flags showing the third-party Storage Partitioning option enabled." src="./assets/chrome-enable-sp.png" width="800" height="234.56" />
 
 
 #### Or add exceptions for Stackblitz
@@ -59,11 +74,11 @@ https://[*.]webcontainer.io
 
 For instance, in Chrome, go to `chrome://settings/cookies` and add those exceptions in the “Sites that can always use cookies” section.
 
-<img alt="Chrome cookie settings with an empty list of “Sites that can always use cookies”." src="./assets/chrome-settings-cookies-1.png" width="800" />
+<img alt="Chrome cookie settings with an empty list of “Sites that can always use cookies”." src="./assets/chrome-settings-cookies-1.png" width="800" height="600" />
 
-<img alt="Chrome cookie settings showing a modal dialog for adding a site to list of third-party cookie exceptions." src="./assets/chrome-settings-cookies-2.png" width="800" />
+<img alt="Chrome cookie settings showing a modal dialog for adding a site to list of third-party cookie exceptions." src="./assets/chrome-settings-cookies-2.png" width="800" height="600" />
 
-<img alt="Chrome cookie settings with exceptions for stackblitz.io and local.webcontainer.io domains." src="./assets/chrome-settings-cookies-3.png" width="800" />
+<img alt="Chrome cookie settings with exceptions for stackblitz.io and local.webcontainer.io domains." src="./assets/chrome-settings-cookies-3.png" width="800" height="600" />
 
 :::details Advanced: enabling Service Workers for a single project
 
@@ -83,7 +98,9 @@ Note that the list of blocked domains might look different for you. In particula
 
 :::
 
-## Firefox: enabling Service Workers {#firefox-service-workers}
+## Firefox
+
+### Enabling Service Workers {#firefox-service-workers}
 
 When Firefox’s Enhanced Tracking Protection is configured in “Custom” mode with the cookie blocking option set to “All cross-site cookies”, Firefox will block the Service Workers used by WebContainers.
 
@@ -97,7 +114,8 @@ To do so, visit `about:preferences#privacy` to check what your current settings
 <img
   alt="The Firefox “Privacy & Security” settings page showing that Enhanced Tracking Protection is set to “Custom”, and to “Cookies: All cross-site cookies (may cause websites to break)”."
   src="./assets/firefox-settings-cookies-1.png"
-  width="1024"
+  width="820"
+  height="661"
 />
 
 To add exceptions for StackBlitz, scroll down to the “Cookies and Site Data” section, click on “Manage Exceptions…”, and add exceptions for the following sites:
@@ -110,11 +128,25 @@ https://webcontainer.io
 <img
   alt="The Cookies and site data exceptions management window in Firefox settings. It shows a couple entries for stackblitz.io and webcontainer.io, both with the value “Allow”."
   src="./assets/firefox-settings-cookies-2.png"
-  width="1024"
+  width="820"
+  height="645"
 />
 
 Don’t forget to click “Save Changes”. Then you should be able to reload the tab with your StackBlitz project, and hopefully everything should work!
 
+### Previews in a separate tab {#firefox-preview-separate-tab}
+
+Previews opened in a separate tab are not connected by default to the editor and require an extra step. To complete this step, you are usually prompted to click a button.
+
+This can happen automatically if your popups settings, [about:preferences#privacy](about:preferences#privacy), are adjusted with the following exception:
+
+```
+https://webcontainer.io
+```
+
+<img alt="Firefox popups settings showing the webcontainer.io site allowed as an exception" src="./assets/firefox-settings-popups.png" width="800" height="649" />
+
+
 ## Brave: enabling Service Workers {#brave-service-workers}
 
 By default, Brave’s “Shields” feature blocks [Service Workers][MDN_SERVICE_WORKER] and cookies from third-party domains.
@@ -123,19 +155,19 @@ To allow WebContainers to run in Brave, you will need to add an exception for St
 
 1. Visit a WebContainers-based project, for instance https://stackblitz.com/edit/nextjs. The project’s boot sequence might stay stuck on the “Running start command” step:
 
-![Screenshot of Brave on a WebContainers project with the Brave Shields feature on. Loading the project’s web server is stuck on the last step.](./assets/brave-stuck-project.png)
+<img alt="Screenshot of Brave on a WebContainers project with the Brave Shields feature on. Loading the project’s web server is stuck on the last step" src="./assets/brave-stuck-project.png" width="820" height="500"/>
 
 2. Click on the “Shields” icon at the right of the address bar, then click on “Advanced View”.
 
-<img alt="Screenshot showing the Shields configuration popup for stackblitz.com." src="./assets/brave-shields-popup.png" width="380" />
+<img alt="Screenshot showing the Shields configuration popup for stackblitz.com." src="./assets/brave-shields-popup.png" width="380" height="358" />
 
 3. In the advanced view, change the “Cross-site cookies blocked” option to “All cookies allowed”.
 
-![Screenshot showing the advanced view of the Shields configuration popup, with a drop-down selector for cross-site cookie permissions.](./assets/brave-shields-details.png)
+<img alt="Screenshot showing the advanced view of the Shields configuration popup, with a drop-down selector for cross-site cookie permissions." src="./assets/brave-shields-details.png" width="820" height="559" />
 
 Brave will reload the page, and you should get a working project:
 
-![Screenshot of Brave on a WebContainers project with the Brave Shields feature tweaked to allow third-party cookies and Service Workers. Loading the web server works, and shows the default page for Next.js’s starter project.](./assets/brave-working-project.png)
+<img alt="Screenshot of Brave on a WebContainers project with the Brave Shields feature tweaked to allow third-party cookies and Service Workers. Loading the web server works, and shows the default page for Next.js’s starter project." src="./assets/brave-working-project.png" width="820" height="500"/>
 
 ## Edge: enabling WebAssembly {#edge-webassembly}