feat(record): raise the default recording viewport to 1280x1600

[kevinccbsg]

Phase 1 of docs/spec-record-viewport.md, and only Phase 1 — no record.fullPage option, as agreed.

The change

DEFAULT_RECORD.viewport goes from 1280x720 to 1280x1600.

That is the whole behaviour change. The rest is the comment explaining why the number is what it is, so the next person does not "tidy" it back down.

Why it matters

The viewport decides what the video contains. Puppeteer captures exactly it — no scrolling, no letterboxing — so anything below the fold is simply absent. Its own filter says so:

-vf crop='min(1280,iw):min(800,ih):0:0',pad=1280:800:0:0

Measured on twd-vue-example: at 720 the recording cut the todos page just below the filter buttons, which put the list the tests assert on off-frame. The clip looked fine and showed none of the behaviour under test.

The expensive part is that nothing in the run mentions it. The frame is cropped silently, and only a human watching the video finds out.

What this does not fix

Worth being straight about, since the spec is: 1600 is still a guess. It is the height that was reached for by hand after watching that video, and it will be wrong for some app. For an app that fits, it now wastes encoder time on empty space — the cheaper mistake than a clip that documents nothing, but a mistake.

The spec's own recommendation was to ship Phase 2 (record.fullPage, measuring the document) instead, which would make the number unnecessary. You've called that out of scope for now, so this is the stopgap it describes.

The cheap middle option, if you ever want it: compare scrollHeight against the capture height after navigation and log one warning when content is being cropped. That would have turned an afternoon of watching videos into a line of output, and it does not need the fullPage machinery. Not built here.

Also in this PR

Two stale claims in the docs, both left from before 1.6.0 gave every run an explicit viewport. README and CLAUDE.md each said a normal run inherits Puppeteer's implicit 800x600; it gets config.viewport, 1280x800 by default. Corrected while editing the same sentences.

Notes

• Both axes stay even, which the H.264 conversion added in fix(record): stop a dead ffmpeg from hanging the run, and make the output playable #24 needs for yuv420p.
• record.viewport set explicitly still wins, so existing configs are unaffected.
• The top-level viewport (layout snapshots) is untouched at 1280x800 — committed .snap references stay valid.
• 559 tests passing.

🤖 Generated with Claude Code

[github-actions]

TWD Contract Validation

Spec	Passed	Failed	Warnings	Mode
./contracts/users-3.0.json	2	3	1	warn
./contracts/posts-3.1.json	2	2	0	warn
./contracts/products-3.0.json	13	23	2	warn
./contracts/events-3.1.json	6	13	0	warn

23 passed · 41 failed · 3 warnings · 1 skipped

Failed validations

./contracts/users-3.0.json

• GET /users/{userId} (200) — mock getUserNoAddress — in "Contract Validation - Mismatches > should fail: missing nested address field"
  • response.address: missing required property "address"
• GET /users/{userId} (200) — mock getUserBadAddress — in "Contract Validation - Mismatches > should fail: nested address missing required city"
  • response.address.city: missing required property "city"
  • response.address.country: missing required property "country"
• GET /users/{userId} (200) — mock getUserBadRole — in "Contract Validation - Mismatches > should fail: oneOf role with invalid variant"
  • response.role: oneOf best match (branch 2 of 2) failed: must be one of: "viewer"

./contracts/posts-3.1.json

• GET /posts/{postId} (200) — mock getPostNoAuthor — in "Contract Validation - Mismatches > should fail: post missing nested author object"
  • response.author: missing required property "author"
• GET /posts/{postId} (200) — mock getPostBadMeta — in "Contract Validation - Mismatches > should fail: post oneOf metadata matches neither variant"
  • response.metadata: oneOf best match (branch 1 of 2) failed: missing required property "category", unexpected property "duration", must be one of: "article"

./contracts/products-3.0.json

• GET /products (200) — mock getProductEmptyName — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: empty name violates minLength"
  • response[0].name: must NOT have fewer than 1 characters
• GET /products (200) — mock getProductBadSku — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid SKU pattern"
  • response[0].sku: must match pattern "^[A-Z]{2,4}-\d{4,8}$"
• GET /products (200) — mock getProductBadUuid — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid uuid format for id"
  • response[0].id: must match format "uuid"
• GET /products (200) — mock getProductBadDateTime — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid date-time format"
  • response[0].createdAt: must match format "date-time"
• GET /products (200) — mock getProductBadDate — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid date format"
  • response[0].releaseDate: must match format "date"
• GET /products (200) — mock getProductBadEmail — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid email format"
  • response[0].contactEmail: must match format "email"
• GET /products (200) — mock getProductBadUri — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid uri format"
  • response[0].website: must match format "uri"
• GET /products (200) — mock getProductBadIp — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid ipv4 format"
  • response[0].serverIp: must match format "ipv4"
• GET /products (200) — mock getProductBadIpV6 — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid ipv6 format"
  • response[0].serverIpV6: must match format "ipv6"
• GET /products (200) — mock getProductZeroPrice — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: price of 0 violates exclusiveMinimum"
  • response[0].price: must be > 0
• GET /products (200) — mock getProductNegQty — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: negative quantity violates minimum"
  • response[0].quantity: must be >= 0
• GET /products (200) — mock getProductOverQty — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: quantity exceeds maximum"
  • response[0].quantity: must be <= 999999
• GET /products (200) — mock getProductBadWeight — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: weight not multipleOf 0.01"
  • response[0].weight: must be multiple of 0.01
• GET /products (200) — mock getProductBadRating — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: rating above maximum (5)"
  • response[0].rating: must be <= 5
• GET /products (200) — mock getProductBadCurrency — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid enum value for currency"
  • response[0].currency: must be one of: "USD", "EUR", "GBP", "JPY"
• GET /products (200) — mock getProductBadCategory — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid enum value for category"
  • response[0].category: must be one of: "electronics", "clothing", "food", "books", "toys"
• GET /products (200) — mock getProductBadBool — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: string value for boolean inStock"
  • response[0].inStock: expected boolean, got string
• GET /products (200) — mock getProductDupTags — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: duplicate tags violates uniqueItems"
  • response[0].tags: must NOT have duplicate items (items ## 1 and 0 are identical)
• GET /products (200) — mock getProductTooManyTags — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: tags exceeds maxItems (10)"
  • response[0].tags: must NOT have more than 10 items
• GET /products (200) — mock getProductBadMeta — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: non-string value in metadata additionalProperties"
  • response[0].metadata.count: expected string, got number
• GET /settings (200) — mock getSettingsBadExtra — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: extra property on Settings (additionalProperties: false)"
  • response.extraField: unexpected property "extraField"
• GET /settings (200) — mock getSettingsBadLang — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid language pattern in Settings"
  • response.language: must match pattern "^[a-z]{2}(-[A-Z]{2})?$"
• GET /products (200) — mock getProductBadNullable — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: wrong type for nullable description (number instead of string|null)"
  • response[0].description: expected string,null, got number

./contracts/events-3.1.json

• GET /events (200) — mock getEventsEmpty — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: empty events array violates minItems (1)"
  • response: must NOT have fewer than 1 items
• GET /events (200) — mock getEventShortName — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: event name too short (minLength: 3)"
  • response[0].name: must NOT have fewer than 3 characters
• GET /events (200) — mock getEventBadDate — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid date-time format for startDate"
  • response[0].startDate: must match format "date-time"
• GET /events (200) — mock getEventFloatId — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: float value for integer id"
  • response[0].id: expected integer, got number
  • response[0].id: must match format "int64"
• GET /events (200) — mock getEventBadBool — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: number value for boolean active"
  • response[0].active: expected boolean, got number
• GET /events (200) — mock getEventBadStatus — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid enum value for status"
  • response[0].status: must be one of: "draft", "published", "archived"
• GET /events (200) — mock getEventScoreMax — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: score at exclusiveMaximum boundary (100)"
  • response[0].score: must be < 100
• GET /events (200) — mock getEventLowPriority — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: priority below minimum (1)"
  • response[0].priority: must be >= 1
• GET /events (200) — mock getEventHighPriority — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: priority above maximum (5)"
  • response[0].priority: must be <= 5
• GET /events (200) — mock getEventDupAttendees — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: duplicate attendees violates uniqueItems"
  • response[0].attendees: must NOT have duplicate items (items ## 1 and 0 are identical)
• GET /events (200) — mock getEventNoAttendees — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: empty attendees array violates minItems (1)"
  • response[0].attendees: must NOT have fewer than 1 items
• GET /events (200) — mock getEventBadAttendee — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid email format in attendees"
  • response[0].attendees[0]: must match format "email"
• GET /events/{eventId} (200) — mock getEventBadNullable — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: wrong type for nullable description (number instead of string|null)"
  • response.description: expected string,null, got number

View full report →