Make viewport optional

Author: hiroTamada

browsers/viewport.mdx

@@ -3,39 +3,57 @@ title: "Viewport Configuration"
 description: "Configure browser viewport size and refresh rate for your automations"
 ---
 
-Kernel browsers allow you to configure the viewport size and refresh rate when creating a browser session. The viewport configuration determines the initial browser window dimensions and display refresh rate.
+Kernel browsers allow you to configure the viewport size and refresh rate when creating a browser session. The viewport configuration determines the initial browser window dimensions and display refresh rate. The refresh rate can be explicitly specified or automatically determined based on the width and height if they match a supported configuration.
 
 ## Setting viewport configuration
 
-You can configure the viewport when creating a browser by specifying the `viewport` parameter with `width`, `height`, and `refresh_rate`:
+You can configure the viewport when creating a browser by specifying the `viewport` parameter with `width` and `height`. The `refresh_rate` is optional and will be automatically determined from the dimensions if they match a supported configuration:
 
 <CodeGroup>
 
 ```typescript Typescript/Javascript
+// Explicitly specify refresh rate
 const kernelBrowser = await kernel.browsers.create({
     viewport: {
         width: 1920,
         height: 1080,
         refresh_rate: 25
     }
 });
+
+// Auto-determine refresh rate from dimensions (25Hz for 1920x1080)
+const kernelBrowserAuto = await kernel.browsers.create({
+    viewport: {
+        width: 1920,
+        height: 1080
+    }
+});
 ```
 
 ```python Python
+# Explicitly specify refresh rate
 kernel_browser = client.browsers.create(
     viewport={
         "width": 1920,
         "height": 1080,
         "refresh_rate": 25
     }
 )
+
+# Auto-determine refresh rate from dimensions (25Hz for 1920x1080)
+kernel_browser_auto = client.browsers.create(
+    viewport={
+        "width": 1920,
+        "height": 1080
+    }
+)
 ```
 
 </CodeGroup>
 
 ## Supported viewport configurations
 
-Kernel supports specific viewport configurations. The server will reject unsupported combinations. The following resolutions are supported:
+Kernel supports specific viewport configurations. The server will reject unsupported combinations. When you provide width and height without specifying refresh_rate, it will be automatically determined if the dimensions match one of the supported resolutions exactly. The following resolutions are supported:
 
 | Resolution | Width | Height | Refresh Rate |
 |------------|-------|--------|--------------|
@@ -54,7 +72,7 @@ Higher resolutions may affect the responsiveness of [live view](/browsers/live-v
 <CodeGroup>
 
 ```typescript Typescript/Javascript
-// Full HD (1920x1080) at 25Hz
+// Full HD (1920x1080) at 25Hz - explicit refresh rate
 const fullHD = await kernel.browsers.create({
     viewport: {
         width: 1920,
@@ -63,25 +81,32 @@ const fullHD = await kernel.browsers.create({
     }
 });
 
-// QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness
+// Full HD (1920x1080) - auto-determined 25Hz
+const fullHDAuto = await kernel.browsers.create({
+    viewport: {
+        width: 1920,
+        height: 1080
+    }
+});
+
+// QHD (2560x1440) - auto-determined 10Hz
+// Note: May affect live view responsiveness
 const qhd = await kernel.browsers.create({
     viewport: {
         width: 2560,
-        height: 1440,
-        refresh_rate: 10
+        height: 1440
     }
 });
 
-// XGA (1024x768) at 60Hz - Default configuration
+// XGA (1024x768) - auto-determined 60Hz (Default configuration)
 const xga = await kernel.browsers.create({
     viewport: {
         width: 1024,
-        height: 768,
-        refresh_rate: 60
+        height: 768
     }
 });
 
-// WUXGA (1920x1200) at 25Hz
+// WUXGA (1920x1200) at 25Hz - explicit refresh rate
 const wuxga = await kernel.browsers.create({
     viewport: {
         width: 1920,
@@ -92,7 +117,7 @@ const wuxga = await kernel.browsers.create({
 ```
 
 ```python Python
-# Full HD (1920x1080) at 25Hz
+# Full HD (1920x1080) at 25Hz - explicit refresh rate
 full_hd = await client.browsers.create(
     viewport={
         "width": 1920,
@@ -101,25 +126,32 @@ full_hd = await client.browsers.create(
     }
 )
 
-# QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness
+# Full HD (1920x1080) - auto-determined 25Hz
+full_hd_auto = await client.browsers.create(
+    viewport={
+        "width": 1920,
+        "height": 1080
+    }
+)
+
+# QHD (2560x1440) - auto-determined 10Hz
+# Note: May affect live view responsiveness
 qhd = await client.browsers.create(
     viewport={
         "width": 2560,
-        "height": 1440,
-        "refresh_rate": 10
+        "height": 1440
     }
 )
 
-# XGA (1024x768) at 60Hz - Default configuration
+# XGA (1024x768) - auto-determined 60Hz (Default configuration)
 xga = await client.browsers.create(
     viewport={
         "width": 1024,
-        "height": 768,
-        "refresh_rate": 60
+        "height": 768
     }
 )
 
-# WUXGA (1920x1200) at 25Hz
+# WUXGA (1920x1200) at 25Hz - explicit refresh rate
 wuxga = await client.browsers.create(
     viewport={
         "width": 1920,
@@ -152,12 +184,12 @@ default_viewport = await client.browsers.create()
 ## Viewport constraints
 
 The viewport configuration has the following constraints:
-- **Width**: Minimum 320px, Maximum 7680px
-- **Height**: Minimum 240px, Maximum 4320px
-- **Refresh Rate**: Must match the supported configurations listed above
+- **Width** (required): Minimum 320px, Maximum 7680px
+- **Height** (required): Minimum 240px, Maximum 4320px
+- **Refresh Rate** (optional): If provided, must match the supported configurations listed above. If omitted, automatically determined from width and height.
 
 <Note>
-While the API accepts width and height values within the min/max ranges, only the specific resolution and refresh rate combinations listed in the supported configurations table are actually supported. The server will reject any unsupported combinations.
+While the API accepts width and height values within the min/max ranges, only the specific resolution and refresh rate combinations listed in the supported configurations table are actually supported. When refresh_rate is omitted, it will be automatically determined if the width and height match a supported configuration exactly. The server will reject any unsupported combinations.
 </Note>
 
 ## Considerations