Recording docs: video is on by default, and Java gets examples

docs/how-to-guides/record-video.md

@@ -1,9 +1,9 @@
 # Record Video
 
-Recordings can include a video track of the session. Pass `video` to
-`recording.start()` and the browser encodes the viewport to WebM itself,
-using the WebDriver BiDi `browsingContext.startScreencast` command — nothing
-extra to install. The video lands inside the recording zip next to the trace:
+Recordings include a video track wherever the engine supports it — no option
+needed. The browser encodes the viewport to WebM itself, using the WebDriver
+BiDi `browsingContext.startScreencast` command, so there is nothing extra to
+install. The video lands inside the recording zip next to the trace:
 
 ```
 record.zip
@@ -79,6 +79,8 @@ const { firefox } = require('vibium');
 const bro = await firefox.start();
 const vibe = await bro.page();
 
+// video: true because this script exists to produce a video -- fail
+// rather than quietly write a trace without one.
 await vibe.context.recording.start({ video: true, path: 'runs/login.zip' });
 await vibe.go('https://example.com');
 // ... actions to record ...
@@ -102,6 +104,8 @@ from vibium import firefox
 bro = firefox.start()
 vibe = bro.page()
 
+# video=True because this script exists to produce a video -- fail
+# rather than quietly write a trace without one.
 vibe.context.recording.start(video=True, path="runs/login.zip")
 vibe.go("https://example.com")
 # ... actions to record ...

docs/how-to-guides/using-firefox.md

@@ -114,7 +114,7 @@ any of them with `--engine chrome` is an error rather than a silent no-op.
 | Capability | Chrome | Firefox |
 |------------|--------|---------|
 | Navigation, elements, input, pages, screenshots, storage, and trace recording | Supported | Supported and covered by the Firefox core suite |
-| Native video (`recording.start({ video: true })`) | Not implemented by Chrome yet | Firefox 154+; see [Record Video](record-video.md) |
+| Native video (`recording.start()`) | Not implemented by Chrome yet | Firefox 154+; see [Record Video](record-video.md) |
 | Dialog callbacks and `capture.dialog()` | Supported | Supported and covered by the cross-engine suites |
 | Network events and request interception | Supported | Supported and covered by the cross-engine suites |
 | PDF printing (`page.pdf`) | Supported | Output and support may differ |

docs/tutorials/recording.md

@@ -305,15 +305,64 @@ The default format is JPEG at 0.5 quality. Lowering `quality` produces smaller f
 
 ## Video
 
-On engines that support it (Firefox 154+, local browsers), the recording can include a video track — the browser encodes the viewport to WebM and the file lands inside the zip next to the trace:
+On engines that support it (Firefox 154+, local browsers), a recording includes
+a video track automatically — the browser encodes the viewport to WebM and the
+file lands inside the zip next to the trace. You do not have to ask for it:
 
 ```javascript
-await ctx.recording.start({ video: true })
+await ctx.recording.start()
 // ...
-await ctx.recording.stop()   // the zip now contains video/<context>.webm
+await ctx.recording.stop()   // on Firefox the zip contains video/<context>.webm
+```
+
+The `video` option has three settings:
+
+- **omitted** — record video where the engine supports it, and carry on without
+  it where it doesn't. The stop result reports `videoUnavailable` with the
+  engine's reason.
+- **`true`** — video is mandatory. `start()` fails with an explanatory error
+  rather than producing a recording that silently lacks it.
+- **`false`** — no video track.
+
+Video is sized to the viewport and captured at the engine's default frame rate.
+To change either, pass an object instead of a boolean. Every field is optional:
+
+```javascript
+await ctx.recording.start({ video: { height: 480 } })        // scale down
+await ctx.recording.start({ video: { frameRate: 10 } })      // smaller file
+await ctx.recording.start({ video: { height: 480, frameRate: 10 } })
+```
+
+In Python the fields are snake_case:
+
+```python
+vibe.context.recording.start(video={"height": 480, "frame_rate": 10})
+```
+
+Java uses flat setters. `videoSize` takes both dimensions, so pick a pair on the
+viewport's aspect ratio rather than a single side:
+
+```java
+vibe.context().recording().start(new RecordingOptions().videoFrameRate(10));
+vibe.context().recording().start(new RecordingOptions().videoSize(854, 480));
+```
+
+Two things to know about the size. **An object counts as asking for video**, the
+same as `video: true` — you named specific output, so a recording that silently
+skipped it would be a surprise. And **the size is a request**: the engine keeps
+the viewport's aspect ratio and derives the other side, so `{ height: 480 }` on a
+16:9 viewport encodes 854×480, and asking for 640×480 there gets you 640×360. The
+stop result reports what was actually encoded:
+
+```javascript
+const result = await ctx.recording.stop()
+result.videos   // [{ context, durationMs, width: 854, height: 480 }]
 ```
 
-With `video` omitted, video is recorded whenever the engine supports it and skipped otherwise. `video: true` requires it — `start()` fails with an explanatory error on Chrome. `video: false` turns it off. Dimensions default to the viewport (`video: { width, height, frameRate }` to override). Remote browser connections (`--connect`) record every track except video — the stop result says why. For remote hosts you control, `video: { remote: 'keep' }` records anyway and leaves the file there; see the [Record Video](../how-to-guides/record-video.md) guide.
+Remote browser connections (`--connect`) record every track except video, and
+the stop result says why; for a remote host you control,
+`video: { remote: 'keep' }` records anyway and leaves the file there. See the
+[Record Video](../how-to-guides/record-video.md) guide.
 
 Engine requirements, Firefox channel setup, and the zip layout are covered in [Record Video](../how-to-guides/record-video.md).
 

docs/tutorials/remote-browser.md

@@ -145,6 +145,22 @@ print(page.find("h1").text())    # "Example Domain"
 bro.stop()
 ```
 
+### Java
+
+```java
+import com.vibium.Vibium;
+import com.vibium.types.StartOptions;
+
+var bro = Vibium.start(new StartOptions().connectURL("ws://your-server:9515/session"));
+var page = bro.page();
+
+page.go("https://example.com");
+System.out.println(page.title());            // "Example Domain"
+System.out.println(page.find("h1").text());  // "Example Domain"
+
+bro.stop();
+```
+
 ---
 
 ## With Authentication
@@ -198,6 +214,14 @@ bro = browser.start("wss://cloud.example.com/bidi", headers={
 })
 ```
 
+**Java:**
+
+```java
+var bro = Vibium.start(new StartOptions()
+    .connectURL("wss://cloud.example.com/bidi")
+    .connectHeaders(Map.of("Authorization", "Bearer my-token")));
+```
+
 ---
 
 ## Environment Variables