✨ Align Storybook and static-site SDKs

[Robdel12]

Why

This PR aligns the browser-driven SDKs: Storybook and static-site. These are not just wrappers around the CLI. They discover stories/pages, launch browsers, capture screenshots, create cloud builds, attach metadata, send screenshots, and finalize the build.

That makes them easy places for option drift to hide. A user can set comparison, browser, request, build, or metadata options and reasonably expect the same contract as the core CLI. Before this pass, those options were too blended together. Some values affected Playwright capture, some affected Vizzly requests, some became screenshot metadata, and some could be dropped before build creation.

The goal is that these SDKs behave like first-class capture runners. Browser options stay with the browser. Vizzly routing/comparison options go to Vizzly. User metadata goes into the metadata bag. Cloud builds get finalized into an honest state.

What changed

Shared web SDK behavior

• Builds cloud run options through small helpers that combine Vizzly config and git metadata into the same shape the core runner expects.
• Preserves threshold, minClusterSize, parallelId, PR number, branch, commit, message, environment, eager mode, and build name when creating cloud builds.
• Finalizes empty cloud runs instead of leaving builds open.
• Finalizes failed capture runs as unsuccessful.
• Reads plugin package versions from package.json so metadata cannot drift from the published package.
• Uses SDK config schema helpers for concurrency defaults.

Storybook

• Validates positive integer concurrency.
• Supports explicit browser/capture controls including --no-headless, --timeout, and --request-timeout.
• Separates Playwright screenshot timeout from Vizzly request timeout.
• Produces stable screenshot metadata for story ID, story title, story name, viewport name, viewport dimensions, browser, URL, threshold, min cluster size, full-page mode, and user properties.
• Documents the sanitized Component-Story@viewport naming format the code actually uses.
• Moves stale utility coverage into the active Node test suites.

Static-site

• Validates positive integer concurrency.
• Supports explicit browser/capture controls including --no-headless, --request-timeout, and --no-use-sitemap.
• Preserves per-page overrides when merging page config.
• Matches page config paths with or without a leading slash.
• Produces stable screenshot metadata for browser, viewport, viewport dimensions, URL, full-page mode, and user properties.
• Passes Vizzly request timeout to the Vizzly client without mixing it into Playwright capture timeout.
• Updates sample pages/config/docs to show the supported shape.

Properties and options

This PR sits on top of the core contract from #283: properties is user metadata, while SDK/config options stay top-level. The web SDKs still add framework-generated metadata needed for stable baselines, but user-supplied properties are treated as the user’s bag and merged intentionally rather than acting as an untyped option tunnel.

The reason that distinction matters is practical: threshold, minClusterSize, requestTimeout, buildId, and similar values change behavior. They should be parsed and validated as options, not accidentally stored as metadata.

Testing

• Cloud run option construction from Vizzly config and git metadata.
• Finalizing empty cloud runs and failed capture runs.
• Storybook/static-site screenshot metadata generation.
• Request timeout versus screenshot timeout behavior.
• CLI option parsing and validation.
• Config merge behavior, page pattern matching, crawler/task behavior, package exports, plugin metadata, and SDK integration paths.

These are mostly integration-style tests around the SDK boundary. A later E2E visual-diff matrix should still exercise a real fixture site and assert actual diff outcomes through the CLI/API/dashboard path.

Verification

• pnpm --dir clients/storybook test: 181 passed.
• pnpm --dir clients/static-site test: 211 passed.
• Covered by the full preservation branch verification before the stack was split.
• Stack cleanup verification: git diff --check and PR file-list checks for ✨ Align core SDK option contracts #283 through 📝 Document aligned SDK workflows #287.

[vizzly-testing]

Vizzly - Visual Test Results

CLI Reporter - Waiting for build

No builds received yet for this pull request.

CLI TUI - Approved

5 comparisons, no changes detected.

View build

---

_{rd/sdk-web-plugins · 7adc3dde}