From fd64928680c7cb943566a7d4f319fbe8ed7dbae8 Mon Sep 17 00:00:00 2001
From: courtney918 <312600173+courtney918@users.noreply.github.com>
Date: Wed, 2 Sep 2026 15:24:39 +0000
Subject: [PATCH] Document that display-based capture is unavailable on
 headless

Live view and replays are already documented as headless limitations, but
the screenshot telemetry category and computer-controls screenshots share
the same display dependency without saying so. Name the common cause on
the headless page, warn on the screenshot category row, and point at the
framework-level screenshot call that does work without a display.

Also make replay opt-in explicit, so "headful supports replays" isn't
read as "headful records automatically."
---
 browsers/headless.mdx             | 4 +++-
 browsers/replays.mdx              | 4 ++++
 browsers/telemetry/categories.mdx | 6 +++++-
 introduction/create.mdx           | 2 +-
 4 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/browsers/headless.mdx b/browsers/headless.mdx
index b2bb1d94..366db0fd 100644
--- a/browsers/headless.mdx
+++ b/browsers/headless.mdx
@@ -53,5 +53,7 @@ func main() {
 </CodeGroup>
 
 <Info>
-    [Live View](/browsers/live-view) and [Replays](/browsers/replays) are not available in headless mode.
+    [Live View](/browsers/live-view) and [Replays](/browsers/replays) are not available in headless mode. Both capture the browser's display, which headless doesn't have. The same applies to the `screenshot` [telemetry category](/browsers/telemetry/categories) and to [computer controls](/browsers/computer-controls) screenshots.
+
+    To capture what a headless page looked like, take screenshots through your automation framework — Playwright's `page.screenshot()` renders in the page and works without a display. Every other telemetry category works headless.
 </Info>
diff --git a/browsers/replays.mdx b/browsers/replays.mdx
index 1e341f27..ee02d4ee 100644
--- a/browsers/replays.mdx
+++ b/browsers/replays.mdx
@@ -5,6 +5,10 @@ description: "Record and view browser sessions as mp4 videos"
 
 Replays capture browser sessions as video recordings that you can view or download later. You have full control over when replays start and stop, allowing you to capture specific interactions or workflows.
 
+<Note>
+Recording is opt-in per session. A browser doesn't record until you call `replays.start()`, so a session you never started a replay on produces no video.
+</Note>
+
 ## Starting and stopping recordings
 
 To start recording a browser session, use the replays API on an active browser:
diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx
index 4098d4c9..d2b80a8f 100644
--- a/browsers/telemetry/categories.mdx
+++ b/browsers/telemetry/categories.mdx
@@ -107,12 +107,16 @@ These categories report what's happening in the page. Capturing any of them atta
 | `network` | Network requests, responses, and failures | `network_request`, `network_response`, `network_loading_failed`, `network_idle`, `proxy_error` |
 | `page` | Navigation and page lifecycle, including performance signals and renderer crashes | `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_tab_opened`, `page_crashed`, `page_layout_shift`, `page_lcp`, `page_layout_settled`, `page_navigation_settled` |
 | `interaction` | Browser-native input in the page (clicks, keys, scroll) | `interaction_click`, `interaction_key`, `interaction_scroll_settled` |
-| `screenshot` | Periodic screenshots of the session | `monitor_screenshot` |
+| `screenshot` | Periodic screenshots of the session. Headful only | `monitor_screenshot` |
 
 <Note>
 `interaction` events are browser-native DOM events observed in the page, not calls to the [computer-control](/browsers/computer-controls) API (those are reported by the `control` category).
 </Note>
 
+<Warning>
+`screenshot` captures the browser's display, so it can't capture the page on a [headless](/browsers/headless) session. Enabling it there is accepted but won't give you usable frames. To capture frames headless, take them through your automation framework instead — Playwright's `page.screenshot()` renders in the page and needs no display.
+</Warning>
+
 ### The monitor category
 
 `monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`.
diff --git a/introduction/create.mdx b/introduction/create.mdx
index 8437edf3..e51a5803 100644
--- a/introduction/create.mdx
+++ b/introduction/create.mdx
@@ -72,7 +72,7 @@ Most of what you'll tune at creation time falls into four buckets:
 
 <Columns cols={2}>
   <Card title="Headless vs headful" href="/browsers/headless">
-    headful (default) supports live view, replays, and better stealth — ideal for agent workflows on bot-detected sites. headless is lighter (1 gb vs 8 gb), good for simple scraping.
+    headful (default) supports live view, [replays](/browsers/replays) (opt-in per session), and better stealth — ideal for agent workflows on bot-detected sites. headless is lighter (1 gb vs 8 gb), good for simple scraping.
   </Card>
   <Card title="Stealth and proxies" href="/browsers/bot-detection/overview">
     Turn on stealth mode and route through residential, ISP, or datacenter proxies when you're hitting sites with bot detection.