docs: explain contact sheet frame sampling

Author: Pete Hunt

README.md

@@ -469,6 +469,8 @@ agent-browser state clean --older-than <days>  # Delete old states
 
 With recording `--cursor`, the pointer and click ripple render with the page, keeping drags synchronized in every captured frame. The temporary overlay is inert, hidden from accessibility snapshots, and removed when recording stops. Screenshots taken during the recording include it.
 
+Contact sheets sample candidate frames at the rate set by `--fps`, so brief UI states between samples may not appear. The final captured frame is always considered.
+
 ### Navigation
 
 ```bash

cli/src/mcp.rs

@@ -1396,7 +1396,7 @@ fn parity_tools() -> Vec<Value> {
                     "description": "Capture rate in frames per second (default 30, max 60).",
                 },
                 "cursor": { "type": "boolean", "description": "Render a pointer and click ripple with the page so drags stay synchronized. The inert overlay is hidden from accessibility snapshots, included in screenshots while recording, and removed on stop." },
-                "contactSheet": { "type": "boolean", "description": "Export first, changed, and final frames as a timestamped PNG beside the video." },
+                "contactSheet": { "type": "boolean", "description": "Export first, changed, and final frames as a timestamped PNG beside the video. Candidate frames are sampled at fps, and the final captured frame is always considered." },
                 "contactSheetThreshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Changed-pixel ratio required to select a contact-sheet frame (default 0.05). Implies contactSheet." },
             }),
             &["path"],
@@ -1425,7 +1425,7 @@ fn parity_tools() -> Vec<Value> {
                     "description": "Capture rate in frames per second (default 30, max 60).",
                 },
                 "cursor": { "type": "boolean", "description": "Render a pointer and click ripple with the page so drags stay synchronized. The inert overlay is hidden from accessibility snapshots, included in screenshots while recording, and removed on stop." },
-                "contactSheet": { "type": "boolean", "description": "Export first, changed, and final frames as a timestamped PNG beside the video." },
+                "contactSheet": { "type": "boolean", "description": "Export first, changed, and final frames as a timestamped PNG beside the video. Candidate frames are sampled at fps, and the final captured frame is always considered." },
                 "contactSheetThreshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Changed-pixel ratio required to select a contact-sheet frame (default 0.05). Implies contactSheet." },
             }),
             &["path"],
@@ -4913,6 +4913,19 @@ mod tests {
                 tool["inputSchema"]["properties"]["contactSheet"]["type"],
                 "boolean"
             );
+            let contact_sheet_description = tool["inputSchema"]["properties"]["contactSheet"]
+                ["description"]
+                .as_str()
+                .unwrap();
+            for needle in ["sampled at fps", "final captured frame"] {
+                assert!(
+                    contact_sheet_description.contains(needle),
+                    "{} contact-sheet description should mention {}: {}",
+                    name,
+                    needle,
+                    contact_sheet_description
+                );
+            }
             let threshold = &tool["inputSchema"]["properties"]["contactSheetThreshold"];
             assert_eq!(threshold["minimum"], json!(0));
             assert_eq!(threshold["maximum"], json!(1));

cli/src/output.rs

@@ -2942,6 +2942,10 @@ With --cursor, an inert overlay renders the pointer and page together so
 drags stay synchronized. It is hidden from accessibility snapshots and
 removed on stop. Screenshots taken while recording include the overlay.
 
+Contact sheets sample candidates at the requested recording rate. Brief UI
+states between samples may not appear; the final captured frame is always
+considered.
+
 Operations:
   start <path> [url]     Start recording the active page (navigates first if url given)
   stop                   Stop recording and save video

docs/src/app/recording/page.mdx

@@ -60,7 +60,7 @@ agent-browser record start ./checkout.webm --contact-sheet
 agent-browser record start ./checkout.webm --contact-sheet-threshold 0.02
 ```
 
-The threshold accepts `0` to `1`, defaults to `0.05`, and implies `--contact-sheet`. Contact sheets contain at most 100 frames.
+The threshold accepts `0` to `1`, defaults to `0.05`, and implies `--contact-sheet`. Candidate frames are sampled at the rate set by `--fps`, so brief UI states between samples may not appear. The final captured frame is always considered. Contact sheets contain at most 100 frames.
 
 ![Example contact sheet with timestamps and highlighted change regions](/recording/contact-sheet-example.png)
 

skill-data/core/SKILL.md

@@ -386,7 +386,7 @@ agent-browser click @e3
 agent-browser record stop
 ```
 
-Recording uses the active tab. Use `--cursor` for an animated pointer, `--contact-sheet` for a visual summary, and `--fps 60` for motion-heavy recordings. The cursor renders with the page so drags stay synchronized. Its inert overlay is hidden from accessibility snapshots, included in screenshots while recording, and removed on stop.
+Recording uses the active tab. Use `--cursor` for an animated pointer, `--contact-sheet` for a visual summary, and `--fps 60` for motion-heavy recordings. The cursor renders with the page so drags stay synchronized. Its inert overlay is hidden from accessibility snapshots, included in screenshots while recording, and removed on stop. Contact sheets sample candidate frames at the rate set by `--fps`, and the final captured frame is always considered.
 
 See [references/video-recording.md](references/video-recording.md) for frame rate guidance, codec options, and more.
 

skill-data/core/references/video-recording.md

@@ -109,7 +109,7 @@ agent-browser record start ./checkout.webm --contact-sheet
 agent-browser record start ./checkout.webm --contact-sheet-threshold 0.02
 ```
 
-The threshold accepts values from `0` to `1` and defaults to `0.05`. Passing `--contact-sheet-threshold` implies `--contact-sheet`. At most 100 frames are included.
+The threshold accepts values from `0` to `1` and defaults to `0.05`. Passing `--contact-sheet-threshold` implies `--contact-sheet`. Candidate frames are sampled at the rate set by `--fps`, so brief UI states between samples may not appear. The final captured frame is always considered. At most 100 frames are included.
 
 ## Use Cases