docs: clarify the null value for the viewport (#20333)

Fixes https://github.com/microsoft/playwright/issues/20284

docs/src/api/params.md

@@ -276,7 +276,14 @@ When using [`method: Page.goto`], [`method: Page.route`], [`method: Page.waitFor
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
-Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.
+Use `null` to disable the consistent viewport emulation.
+
+:::note
+The `null` value opts out from the default presets, makes viewport depend on the
+host window size defined by the operating system. It makes the execution of the
+tests non-deterministic.
+:::
 
 ## csharp-context-option-viewport
 * langs: csharp
@@ -285,7 +292,14 @@ Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `n
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
-Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the default viewport.
+Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.
+Use `ViewportSize.NoViewport` to disable the consistent viewport emulation.
+
+:::note
+The `ViewportSize.NoViewport` value opts out from the default presets,
+makes viewport depend on the host window size defined by the operating system.
+It makes the execution of the tests non-deterministic.
+:::
 
 ## context-option-screen
 * langs:

packages/playwright-core/types/types.d.ts

@@ -12514,7 +12514,11 @@ export interface BrowserType<Unused = {}> {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * viewport emulation.
+     *
+     * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+     * by the operating system. It makes the execution of the tests non-deterministic.
      */
     viewport?: null|{
       /**
@@ -13877,7 +13881,11 @@ export interface AndroidDevice {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * viewport emulation.
+     *
+     * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+     * by the operating system. It makes the execution of the tests non-deterministic.
      */
     viewport?: null|{
       /**
@@ -15779,7 +15787,11 @@ export interface Browser extends EventEmitter {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * viewport emulation.
+     *
+     * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+     * by the operating system. It makes the execution of the tests non-deterministic.
      */
     viewport?: null|{
       /**
@@ -18820,7 +18832,11 @@ export interface BrowserContextOptions {
   videosPath?: string;
 
   /**
-   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+   * viewport emulation.
+   *
+   * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+   * by the operating system. It makes the execution of the tests non-deterministic.
    */
   viewport?: null|ViewportSize;
 }

packages/playwright-test/types/test.d.ts

@@ -3523,7 +3523,11 @@ export interface PlaywrightTestOptions {
    */
   userAgent: string | undefined;
   /**
-   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+   * viewport emulation.
+   *
+   * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+   * by the operating system. It makes the execution of the tests non-deterministic.
    */
   viewport: ViewportSize | null | undefined;
   /**