fix(playwright): document video-start --size and correct the frame-size guidance

plugins/playwright/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "playwright",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Live E2E browser automation via Microsoft's @playwright/cli — named sessions, accessibility-ref snapshots, click/fill by ref, screenshots, console and network capture, mocking, tracing, video, and auth state, with artifacts written to disk so only paths enter context, plus a vendored upstream baseline and maintainer drift-check update flow.",
   "author": {
     "name": "Melodic Software",

plugins/playwright/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to the `playwright` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.5.0]
+
+### Added
+
+- `reference/tracing-and-video.md` gains a **Frame size (two levers, not one)**
+  section documenting `playwright-cli video-start --size "<W>x<H>"`, which the
+  skill had never mentioned. Video frame size is derived from the viewport at
+  browser-context creation and fitted into an 800×800 box, so the previously
+  canonical bare `video-start demo.webm` recorded at 800×450 regardless of
+  viewport intent, and `resize` afterwards did not change it. A correct
+  recording needs two matched levers — `PLAYWRIGHT_MCP_VIEWPORT_SIZE` prefixed
+  on `open` for what the page renders at, and `--size` for the output frame —
+  and the section tabulates the measured outcome of each partial combination.
+  Also notes that the config file's `saveVideo` block is whole-session
+  auto-save, a different mechanism from on-demand `video-start`.
+
+### Changed
+
+- The canonical video example now carries both size levers, with a neutral
+  illustrative resolution, and the capture checklist points at the new section.
+- `SKILL.md`'s "Defaults (accept, don't override)" section gains an explicit
+  video-recording exception. The `1280×720` viewport row stays — it is the
+  correct CLI default — and so does the "don't put `PLAYWRIGHT_MCP_*` in
+  project settings" posture; what was missing was the documented carve-out that
+  video needs a per-command viewport prefix on `open`. Skill frontmatter is
+  untouched.
+
+### Fixed
+
+- "Known costs" no longer claims "1280×720 WebM is ~5 MB/minute". The CLI never
+  emits 1280×720 by default, and the figure was unsourced — it appears in no
+  upstream or official Playwright documentation. Replaced with a qualitative
+  statement that size scales with frame area and on-screen motion, rather than
+  re-anchoring an invented number to a different resolution.
+
 ## [0.4.0]
 
 ### Added

plugins/playwright/skills/playwright/SKILL.md

@@ -75,6 +75,8 @@ Microsoft's defaults are right for autonomous E2E work. Don't add `PLAYWRIGHT_MC
 | Console level | `info` | Actionable errors/warnings without debug noise |
 | Viewport | 1280×720 | Standard laptop — matches most users' view |
 
+**One exception — video recording.** The video frame size is derived from the viewport at browser-context creation, then fitted into an 800×800 box, so a bare `video-start` records at 800×450 no matter what you do afterwards; `resize` does not change it. Recording at any other size takes two matched levers — `PLAYWRIGHT_MCP_VIEWPORT_SIZE=<W>x<H>` prefixed on the `open` command *plus* `video-start --size "<W>x<H>"`. That is a per-command prefix, not a project-settings entry, so it does not contradict the guidance above. Details and measured outcomes: [reference/tracing-and-video.md](reference/tracing-and-video.md).
+
 The full env var / config file schema lives in Microsoft's upstream README at `$(npm root -g)/@playwright/cli/README.md` — not duplicated here.
 
 ## Actions

plugins/playwright/skills/playwright/reference/tracing-and-video.md

@@ -38,30 +38,75 @@ find .playwright-cli/traces -mtime +7 -delete
 ## Video — basic
 
 ```bash
-playwright-cli open
-playwright-cli video-start demo.webm
-playwright-cli goto https://example.com
-playwright-cli click e1
-playwright-cli video-stop
+PLAYWRIGHT_MCP_VIEWPORT_SIZE=1440x900 playwright-cli -s=demo open
+playwright-cli -s=demo video-start demo.webm --size "1440x900"
+playwright-cli -s=demo goto https://example.com
+playwright-cli -s=demo click e1
+playwright-cli -s=demo video-stop
 ```
 
+Both size arguments are deliberate — see [Frame size](#frame-size-two-levers-not-one) below. Pick
+whatever resolution your evidence needs; `1440x900` here is only an illustration.
+
 Add chapter markers for section transitions:
 
 ```bash
-playwright-cli video-chapter "Login" --description="Entering credentials" --duration=2000
+playwright-cli -s=demo video-chapter "Login" --description="Entering credentials" --duration=2000
 ```
 
 Auto-annotate subsequent actions (click, type, ...) with a callout naming the action and highlighting the target — cheaper than hand-building overlays via `run-code` for simple demos:
 
 ```bash
-playwright-cli video-show-actions --duration=600 --position=top-right --cursor=pointer
-playwright-cli click e1
-playwright-cli fill e2 "test"
-playwright-cli video-hide-actions
+playwright-cli -s=demo video-show-actions --duration=600 --position=top-right --cursor=pointer
+playwright-cli -s=demo click e1
+playwright-cli -s=demo fill e2 "test"
+playwright-cli -s=demo video-hide-actions
 ```
 
 `--position` accepts `top-left|top|top-right|bottom-left|bottom|bottom-right` (default `top-right`); `--cursor=pointer` (default) animates a mouse pointer between action points, `--cursor=none` disables it.
 
+## Frame size (two levers, not one)
+
+**A bare `video-start <name>.webm` does not record at your viewport size.** Upstream's default is
+"the size of the recorded video will fit 800x800" (`playwright-cli video-start --help`), so the CLI's
+default 1280×720 viewport records as **800×450**. Playwright's own docs say the same thing and give
+the same fallback number ([recordVideo.size](https://playwright.dev/docs/api/class-browser#browser-new-context),
+[Videos](https://playwright.dev/docs/videos): *"You may need to set the viewport size to match your
+desired video size."*).
+
+Two independent levers control the result. A full-resolution recording needs **both**, matched:
+
+| Lever | Where it goes | What it governs |
+|---|---|---|
+| Context viewport | `PLAYWRIGHT_MCP_VIEWPORT_SIZE=<W>x<H>` prefixed on the `open` command | What the page actually renders at |
+| Video frame | `video-start <name>.webm --size "<W>x<H>"` | The output file's pixel dimensions |
+
+The viewport must be set on `open`, because that is the command that creates the browser context the
+recorder derives its geometry from.
+
+The `VAR=value <command>` prefix shown here is POSIX shell syntax (Git Bash, WSL, macOS, Linux).
+PowerShell has no inline env prefix — set `$env:PLAYWRIGHT_MCP_VIEWPORT_SIZE = '<W>x<H>'` on its own
+line before the `open`, then clear it afterwards if later sessions should use the default.
+
+Measured outcomes (ffprobe on the resulting `.webm`, `@playwright/cli` 0.1.14):
+
+| What you do | What you get |
+|---|---|
+| `open`, then bare `video-start` | 800×450 — the default viewport fitted into an 800 box |
+| `open`, `resize <w> <h>`, then bare `video-start` | still 800×450 — **`resize` does not change the video frame size** |
+| `PLAYWRIGHT_MCP_VIEWPORT_SIZE=1920x1200 open`, bare `video-start` | 800×500 — a bigger viewport is still fitted into 800 |
+| `open`, `video-start --size "1920x1200"` | a 1920×1200 file, but the 1280×720 render sits in the top-left corner and the rest is padded grey |
+| both levers, matched | the size you asked for |
+
+`resize` is for exercising responsive layout; it is not a video lever. If a recording came back
+smaller than expected, the fix is at `open` time, not after it.
+
+**Not the same thing as `saveVideo`.** The config file (`.playwright/cli.config.json`) has a
+top-level `saveVideo: { width, height }` that auto-saves a video of the *whole session* to the output
+directory, and a `browser.contextOptions` block that accepts a `viewport` — per the `@playwright/cli`
+README schema. That is a different mechanism from on-demand `video-start`/`video-stop`; treat the
+config route as unverified until you have measured it yourself.
+
 ## Video — hero scripts (via `run-code`)
 
 For polished recordings (demos, PR evidence), build a single `run-code` script with typing delays, overlays, and chapter cards. See [running-code.md](running-code.md) for execution mechanism. Upstream ships a detailed pattern at `../vendor/references/video-recording.md` covering:
@@ -79,13 +124,16 @@ When capturing for a PR or bug report:
 
 1. **Plan the flow first** — know exactly which commands and element refs you'll hit
 2. **Open browser, take initial snapshot** to get refs
-3. **Start capture** (`tracing-start` or `video-start <name>.webm`)
+3. **Start capture** — `tracing-start`, or `video-start <name>.webm --size "<W>x<H>"` with the
+   viewport already set on `open` (see [Frame size](#frame-size-two-levers-not-one))
 4. **Perform the flow** using refs from snapshot
 5. **Stop capture** (`tracing-stop` or `video-stop`)
 6. **Move output to a meaningful location** — don't leave artifacts named `page-<timestamp>.png` in `.playwright-cli/`; use `--filename=` or `mv` to something like `<artifact-dir>/<descriptive-name>.webm`
 
 ## Known costs
 
 - Tracing adds ~50-150ms/action overhead
-- Video adds real-time encoding overhead; 1280×720 WebM is ~5 MB/minute
+- Video adds real-time encoding overhead. WebM file size scales with frame area and with how much of
+  the screen moves, so raising `--size` raises cost roughly in proportion — measure your own flow
+  rather than budgeting from a rule of thumb
 - Both grow `.playwright-cli/` unboundedly — clean up old runs