mirror of
https://github.com/webstudio-is/webstudio.git
synced 2026-11-03 10:37:48 +09:00
Oleg Isonen
f2cece41ee
## Summary Reconnect the reusable browser capture session and retry once when a managed screenshot reports that its Browser DevTools connection closed. The active generated-site preview remains running, so the retry recreates only the failed browser session and replays the requested single or multi-viewport capture. ## Root cause Vision already performs a bounded recovery inside its browser runtime. If that recovery still surfaced a DevTools session closure, the MCP preview handler reset the failed session during error cleanup but returned the failure to the caller. The next manual screenshot call could succeed, but the first screenshot after a preview restart still failed. ## Technical choices - Give browser-session closure errors a stable typed code at the Vision boundary. - Detect that typed failure in the MCP preview handler. - Close and recreate only the reusable browser capture session. - Retry the complete capture once against the existing active preview. - Apply the same recovery to one-viewport and responsive batch captures. - Report the reconnect as a screenshot lifecycle progress checkpoint. ## Impact A one-viewport responsive screenshot after preview restart now recovers automatically from a closed DevTools connection. Other screenshot errors retain their existing behavior, and repeated connection failure remains bounded. ## Checklist - [x] Add a fail-first regression for preview restart followed by a one-viewport responsive capture - [x] Recreate the failed browser session without restarting the active preview - [x] Retry the complete screenshot request once - [x] Preserve existing behavior for non-session errors - [x] Verify the recovery through a real preview server, Chrome, CDP, rendering, and PNG output - [x] Review fixture impact: no fixture inputs or generated fixture outputs are affected - [x] Review documentation impact: no update is required because this restores documented automatic screenshot behavior - [ ] Run agent evaluations (requires separate explicit approval) ## Verification - Regression failed before the implementation with `Browser DevTools connection closed.` and passed after it - Real-browser harness with Google Chrome: - restarted a real local HTTP preview and captured a full-page `1440×900` PNG successfully on the first call - forcibly closed the real CDP socket during `Page.captureScreenshot` twice and confirmed the lower browser retry surfaced the typed session-closed failure - confirmed the MCP handler created a new browser session, replayed the full capture successfully, and emitted `tool screenshot reconnecting browser session` - confirmed browser recovery did not restart the active preview - closed all Chrome processes, preview resources, temporary profiles, and screenshot artifacts - `pnpm --filter webstudio exec vitest run src/commands/mcp-preview.test.ts` — 44 tests passed - `pnpm --filter @webstudio-is/vision test` — 13 files, 81 tests passed - `pnpm --filter webstudio typecheck` - `pnpm --filter @webstudio-is/vision typecheck` - `pnpm exec oxlint --deny-warnings packages/vision/src/screenshot-browser-cdp.ts packages/cli/src/commands/mcp-preview.ts packages/cli/src/commands/mcp-preview.test.ts` - `pnpm exec oxfmt packages/vision/src/screenshot-browser-cdp.ts packages/cli/src/commands/mcp-preview.ts packages/cli/src/commands/mcp-preview.test.ts` - `git diff --check` The DevTools failures were injected deterministically at the screenshot command. The ordinary post-restart capture used the same real preview and Chrome path without fault injection. Agent evaluations were not run because repository policy requires separate explicit approval. Closes #6200
Vision
@webstudio-is/vision provides source-agnostic browser capture, screenshot
comparison, OCR analysis, caching primitives, and portable visual reports.
Import the smallest relevant entry point:
import { createBrowserScreenshotSession } from "@webstudio-is/vision/browser";
import { captureVisualEntries } from "@webstudio-is/vision/capture";
import { diffPngFiles } from "@webstudio-is/vision/diff";
import {
classifyScreenshotComparisonReport,
writeScreenshotComparisonReport,
} from "@webstudio-is/vision/report";
import { selectRepresentativeViewports } from "@webstudio-is/vision/viewports";
Consumers own their source-specific orchestration. The visual regression runner, for example, handles Git revisions and Storybook CSF rendering while this package handles capture batches, image comparison, and reports.