@vizzly-testing/cli 0.35.3-beta.0 → 0.35.3-beta.2

package/dist/server/routers/events.js

@@ -19,7 +19,7 @@ let defaultTimers = {
 /**
  * Read and parse JSON from disk, returning null on missing or invalid files.
  */
-export function readJsonFile(path) {
+function readJsonFile(path) {
   if (!existsSync(path)) {
     return null;
   }
@@ -33,7 +33,7 @@ export function readJsonFile(path) {
 /**
  * Read report data and attach baseline metadata for the stats view.
  */
-export function readReportDataFile({
+function readReportDataFile({
   reportDataPath,
   baselineMetadataPath
 }) {
@@ -84,7 +84,7 @@ function summaryChanged(oldData, newData) {
 /**
  * Build incremental SSE events by diffing old vs new report data.
  */
-export function buildReportDataEvents(oldData, newData) {
+function buildReportDataEvents(oldData, newData) {
   if (!oldData) {
     return [{
       type: 'reportData',
@@ -129,7 +129,7 @@ export function buildReportDataEvents(oldData, newData) {
 /**
  * Watch report-data.json with fs.watch plus a lightweight mtime fallback.
  */
-export function watchReportDataFile({
+function watchReportDataFile({
   workingDir,
   reportDataPath,
   onReportDataChanged,

package/dist/tdd/services/comparison-service.js

@@ -4,7 +4,7 @@
  * Wraps honeydiff for image comparison and builds comparison result objects.
  */
 
-import { compare } from '@vizzly-testing/honeydiff';
+import { analyze } from '@vizzly-testing/honeydiff';
 import { calculateHotspotCoverage } from '../core/hotspot-coverage.js';
 import { calculateRegionCoverage, shouldAutoApproveFromRegions } from '../core/region-coverage.js';
 import { generateComparisonId } from '../core/signature.js';
@@ -26,17 +26,41 @@ export async function compareImages(baselinePath, currentPath, diffPath, options
     threshold = 2.0,
     minClusterSize = 2
   } = options;
-  return compare(baselinePath, currentPath, {
+  let analysis = await analyze(baselinePath, currentPath, {
     threshold,
     antialiasing: true,
+    minimumRegionPixels: minClusterSize
+  }, {
     diffPath,
-    overwrite: true,
-    includeClusters: true,
-    includeSSIM: true,
-    includeGMSD: true,
-    clusterMerge: true,
-    minClusterSize
+    overwrite: true
   });
+  let comparison = analysis.comparison;
+  let perception = analysis.perception;
+  let changedPixels = comparison.pixels.changed.total;
+  let totalPixels = comparison.pixels.total;
+  let heightChange = comparison.heightChange;
+  return {
+    isDifferent: comparison.different,
+    diffPercentage: totalPixels > 0 ? changedPixels / totalPixels * 100 : 0,
+    diffPixels: changedPixels,
+    totalPixels,
+    aaPixelsIgnored: comparison.pixels.suppressed.antialiasing.count,
+    aaPercentage: totalPixels > 0 ? comparison.pixels.suppressed.antialiasing.count / totalPixels * 100 : 0,
+    boundingBox: comparison.difference.spatial?.bounds || null,
+    heightDiff: heightChange ? heightChange.direction === 'added' ? heightChange.rowCount : -heightChange.rowCount : 0,
+    intensityStats: comparison.difference.appearance,
+    diffClusters: comparison.difference.regions.map(region => ({
+      boundingBox: region.spatial.bounds,
+      pixelCount: region.spatial.pixelCount,
+      visualPixels: region.visualPixels,
+      addedPixels: region.addedPixels,
+      removedPixels: region.removedPixels,
+      appearance: region.appearance
+    })),
+    perceptualScore: perception?.ssim,
+    ssimScore: perception?.ssim,
+    gmsdScore: perception?.gmsd
+  };
 }
 
 /**

package/dist/utils/visual-context-normalizers.js

@@ -145,9 +145,11 @@ function getBaselineScreenshot(comparison = {}) {
 /**
  * Project compact Honeydiff facts without making raw geometry the default.
  *
- * Agents need stable counts, fingerprints, URLs, and the API projection for
- * first-pass diagnosis. Raw regions and scoring details stay behind an
- * explicit include because they can dominate an otherwise bounded handoff.
+ * Agents need stable counts, fingerprints, URLs, the API projection, and the
+ * server's authoritative artifact manifest for first-pass diagnosis. Keeping
+ * that manifest intact prevents the CLI from becoming less authoritative than
+ * the API. Raw regions and scoring details stay behind an explicit include
+ * because they can dominate an otherwise bounded handoff.
  *
  * @param {Object} comparison - Comparison record from the API.
  * @param {boolean} includeDiffs - Whether to include raw Honeydiff diagnostics.
@@ -158,6 +160,7 @@ function getComparisonDiff(comparison = {}, includeDiffs = false) {
   let analysis = comparison.analysis || {};
   let regions = diff.regions || diff.diff_regions || analysis.diff_regions || comparison.diff_regions;
   let projection = diff.projection || diff.analysis_projection || analysis.projection || analysis.analysis_projection || comparison.analysis_projection || comparison.projection || null;
+  let artifacts = diff.artifacts ?? analysis.artifacts ?? comparison.artifacts ?? null;
   let compact = {
     percentage: diff.percentage ?? analysis.percentage ?? analysis.diff_percentage ?? comparison.diff_percentage ?? null,
     changed_pixels: diff.changed_pixels ?? analysis.changed_pixels ?? comparison.changed_pixels ?? null,
@@ -168,6 +171,12 @@ function getComparisonDiff(comparison = {}, includeDiffs = false) {
     projection,
     image_url: diff.image_url || diff.url || analysis.diff_image_url || comparison.diff_url || comparison.diff_image_url || null
   };
+
+  // Preserve server-owned evidence exactly so agents can verify and download
+  // artifacts without the CLI recreating identities, digests, or availability.
+  if (artifacts != null) {
+    compact.artifacts = artifacts;
+  }
   if (includeDiffs) {
     compact.regions = regions || [];
     compact.cluster_metadata = diff.cluster_metadata || analysis.cluster_metadata || comparison.cluster_metadata || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.35.3-beta.0",
+  "version": "0.35.3-beta.2",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -60,7 +60,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "cli": "source .envrc && node bin/vizzly.js",
+    "cli": "node scripts/run-development-cli.js production",
+    "cli:local": "node scripts/run-development-cli.js local",
     "start": "node src/index.js",
     "build": "pnpm run clean && pnpm run compile && pnpm run build:reporter && pnpm run build:reporter-ssr && pnpm run copy-types",
     "clean": "rimraf dist",
@@ -93,7 +94,7 @@
   },
   "dependencies": {
     "@vizzly-testing/bear-den": "0.1.4",
-    "@vizzly-testing/honeydiff": "^0.11.1",
+    "@vizzly-testing/honeydiff": "^0.16.0",
     "ansis": "^4.2.0",
     "commander": "^15.0.0",
     "cosmiconfig": "^9.0.0",
@@ -115,18 +116,18 @@
     }
   },
   "devDependencies": {
-    "@babel/cli": "^7.28.0",
-    "@babel/core": "^7.23.6",
-    "@babel/preset-env": "^7.23.6",
-    "@babel/preset-react": "^7.27.1",
-    "@babel/preset-typescript": "^7.23.6",
-    "@biomejs/biome": "^2.3.8",
+    "@babel/cli": "^8.0.1",
+    "@babel/core": "^8.0.1",
+    "@babel/preset-env": "^8.0.2",
+    "@babel/preset-react": "^8.0.1",
+    "@babel/preset-typescript": "^8.0.1",
+    "@biomejs/biome": "^2.5.10",
     "@heroicons/react": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "@playwright/test": "^1.55.1",
     "@tailwindcss/postcss": "^4.1.13",
     "@tanstack/react-query": "^5.90.11",
-    "@types/node": "^25.0.2",
+    "@types/node": "^26.0.0",
     "@vitejs/plugin-react": "^6.0.1",
     "autoprefixer": "^10.4.21",
     "babel-plugin-react-compiler": "^1.0.0",
@@ -136,8 +137,8 @@
     "tailwindcss": "^4.1.13",
     "tsd": "^0.33.0",
     "tui-driver": "github:vizzly-testing/tui-driver",
-    "typescript": "^6.0.3",
-    "vite": "^8.0.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
     "wouter": "^3.7.1"
   }
 }

package/skills/vizzly/SKILL.md

@@ -1,74 +1,64 @@
 ---
 name: vizzly
-description: "Inspect, explain, and debug Vizzly visual regression evidence; use an existing Vizzly workflow before and after UI changes; add or adjust screenshot capture; troubleshoot local TDD or cloud builds; or configure Vizzly CI. Use when a task mentions Vizzly, screenshot baselines, comparisons, Honeydiff, visual review, dynamic regions, or a repository's Vizzly setup."
+description: Inspect and explain Vizzly visual regression evidence, verify UI changes, troubleshoot local or cloud builds, adjust screenshot capture, or configure Vizzly CI. Use when a task mentions Vizzly, screenshot baselines, comparisons, Honeydiff, visual review, dynamic regions, or an existing Vizzly workflow.
 ---
 
 # Vizzly
 
-Use Vizzly as visual evidence for user-facing changes. Keep the repository's
-existing test workflow in charge of how the UI is exercised.
+Use Vizzly as evidence for user-facing changes. Keep the repository's existing
+test workflow in charge of how the UI is exercised.
 
-## Start From The Repository
+## Prepare
 
-1. Confirm that the repository uses Vizzly by checking its configuration,
-   dependencies, scripts, or existing `.vizzly` data.
-2. Use the repository's established CLI invocation. The examples in this skill
-   use `vizzly`; substitute its package script, `pnpm exec vizzly`, or
-   `npx vizzly` when that is how the repository runs local binaries.
-3. Do not install, initialize, log in, or change credentials unless the task
-   explicitly includes setup. Never print or persist a token.
+1. Confirm the repository uses Vizzly by checking its config, dependencies,
+   scripts, or `.vizzly` data.
+2. Use the repository's established CLI invocation exactly. Otherwise, replace
+   `vizzly` in these examples with `pnpm exec vizzly`; use `npx vizzly` when the
+   repository uses npm.
+3. Do not install, initialize, log in, or change credentials unless setup is in
+   scope. Never print or persist a token.
 
-## Follow The Evidence Loop
+## Inspect And Verify
 
-1. Choose the most relevant source:
-   - Use a supplied cloud build or comparison ID when the task names one.
-   - Use existing local context when `.vizzly` contains the run under review.
-   - Generate fresh evidence through the repository's existing visual test
-     workflow when stored evidence may be stale or absent.
-2. Request the bounded, machine-readable build context:
+1. Choose the supplied cloud build or comparison when one is named. Otherwise,
+   use current local evidence or find the relevant cloud build.
+2. Request bounded JSON:
 
    ```bash
    vizzly context build current --source local --agent --json
    vizzly context build <build-id> --source cloud --agent --json
    ```
 
-3. Check the build identity, source, branch, timestamps, baseline selection,
-   review state, and truncation fields before interpreting the evidence. Treat
-   omitted fields as unknown.
-4. Inspect the current, baseline, and diff images together using whatever
-   image, browser, URL, or local-file capability is available. If an image is
-   inaccessible, say so and do not infer its visual contents from metadata.
-5. Read viewport, browser, screenshot metadata, review state, and Honeydiff
-   facts alongside the images. Follow the returned `suggested_commands` for
-   exact comparison or screenshot drill-downs. Request raw diff regions only
-   when the compact summary is insufficient.
-6. Separate observations from explanations. State what the evidence shows,
-   then label any proposed cause with appropriate confidence.
-7. Make the smallest justified UI or test change, rerun the owning user
-   workflow, and inspect the resulting evidence again.
+3. Confirm the build, source, branch, timestamps, baseline, review state, and
+   pagination before drawing conclusions. If `has_more` is true, run the
+   returned next-page command before concluding. Missing fields remain unknown.
+4. Follow `suggested_commands` to inspect a comparison. View its baseline,
+   current, and diff images together. If an image cannot be opened, label the
+   result metadata-only; do not call it visual verification.
+5. Read image dimensions, viewport, browser, diff regions, fingerprint, and
+   relevant history alongside the images. A prior approval is supporting
+   evidence, not permission to approve the current comparison.
+6. State observations before possible causes. Make the smallest justified
+   change, rerun the owning workflow, and inspect the new evidence.
 
 ## Guardrails
 
-- Treat an approved baseline as the accepted reference for that comparison,
-  not infallible truth. Check its identity and selection reason.
-- Do not invent progress, counts, review state, visual causes, or missing API
+- Do not invent progress, ranking, review state, visual causes, or missing API
   values.
-- Do not approve, reject, comment on, publish, or replace visual evidence
-  unless the user explicitly asks for that mutation.
-- Preserve existing thresholds, cluster sizes, signature properties, and
-  dynamic-region behavior unless the task and evidence justify changing them.
-- Prefer deterministic fixtures and existing end-to-end journeys over hiding a
-  diff with broader tolerances or a new screenshot-only test.
-- Report the screenshot or comparison identity, the relevant build or link,
-  the observed evidence, any access limitations, and the command used.
+- Do not approve, reject, comment on, publish, or replace evidence unless the
+  task explicitly asks for that mutation.
+- Preserve thresholds, cluster sizes, signature properties, and dynamic-region
+  behavior unless repeated evidence justifies a change.
+- Prefer deterministic fixtures and existing user journeys over hiding a diff
+  with broader tolerances or a new screenshot-only test.
+- Report the comparison or screenshot identity, observed evidence, access
+  limitations, and the command or link used.
 
-## Load References Only When Needed
+## Load A Reference When Needed
 
-- Read [references/cli-context.md](references/cli-context.md) for local and
-  cloud inspection commands, TDD lifecycle, and evidence drill-downs.
-- Read [references/sdks.md](references/sdks.md) only when adding or changing
-  screenshot capture code.
-- Read [references/dynamic-content.md](references/dynamic-content.md) when a
-  diff may involve unstable content, hotspots, or confirmed regions.
-- Read [references/setup-ci.md](references/setup-ci.md) only when the task asks
-  to initialize Vizzly, change CI, or troubleshoot configuration.
+- [CLI context](references/cli-context.md): local and cloud evidence, build
+  discovery, drill-downs, images, and TDD lifecycle.
+- [SDK capture](references/sdks.md): add or change screenshot capture code.
+- [Dynamic content](references/dynamic-content.md): investigate unstable
+  content, hotspots, or confirmed regions.
+- [Setup and CI](references/setup-ci.md): initialize Vizzly or change CI.

package/skills/vizzly/references/cli-context.md

@@ -1,16 +1,25 @@
-# CLI And Context
+# CLI Context
 
-Use the repository's existing CLI invocation. The examples use `vizzly` for
-brevity; substitute the repository's package script or package-manager command
-when needed.
+Use the repository's established CLI invocation and existing authentication.
+If cloud authentication is unavailable, report the blocker. Do not start an
+interactive login unless setup is in scope.
 
-Use existing authentication and project configuration. If cloud authentication
-is missing, report the blocker. Do not start an interactive login or change
-credentials unless the task includes setup.
+## Choose The Evidence
 
-## Inspect Existing Local Evidence
+Use an ID supplied by the task. If no cloud build is supplied, list recent
+builds and select the one matching the branch, commit, or pull request:
 
-Request structured local evidence with both `--agent` and `--json`:
+```bash
+vizzly builds --branch <branch> --limit 5 --json
+vizzly status <build-id> --json
+vizzly context build <build-id> --source cloud --agent --json
+```
+
+Use status for lifecycle facts and build context for visual evidence. Do not
+assume the first returned comparison is the most important; preserve API order
+and inspect the records relevant to the task.
+
+For saved local evidence:
 
 ```bash
 vizzly context build current --source local --agent --json
@@ -18,79 +27,71 @@ vizzly context screenshot "<screenshot-name>" --source local --json
 vizzly context review-queue --source local --json
 ```
 
-Pin hand-written local drill-downs with `--source local`. Without it, automatic
-source resolution may fall back to cloud data when a local item is unavailable.
+Confirm the stored build, branch, timestamp, and baseline are current enough
+for the task.
 
-Local context reads persisted `.vizzly` artifacts. Confirm that their build,
-branch, timestamp, and baseline match the task before treating them as current.
+## Generate Fresh Evidence
 
-## Generate Fresh Local Evidence
-
-For a one-off run, let Vizzly own the complete local session:
+For one run, let Vizzly own the local session:
 
 ```bash
 vizzly tdd run "<existing visual test command>" --no-open
-vizzly context build current --source local --agent --json
 ```
 
-For repeated test runs, start the detached daemon once:
+For repeated runs, start the detached daemon once:
 
 ```bash
 vizzly tdd start --json
 vizzly tdd status --json
 <existing visual test command>
-vizzly context build current --source local --agent --json
 vizzly tdd stop --json
 ```
 
-Treat `tdd run` and `tdd start` as alternatives. Do not shell-background
-`tdd start`; it already launches a detached daemon. Stop only a server started
-for the current task, and reuse the printed port for status or stop commands
-when Vizzly selects a non-default port.
-
-## Inspect Cloud Evidence
+`tdd run` and `tdd start` are alternatives. Stop only a daemon started for the
+current task.
 
-When the task already has a build ID:
+When a cloud build is in scope:
 
 ```bash
-vizzly status <build-id> --json
+vizzly run "<existing visual test command>" --wait --json
 vizzly context build <build-id> --source cloud --agent --json
 ```
 
-Use status for server-owned lifecycle, processing, comparison, and review
-facts. Use build context for visual debugging.
+## Inspect A Comparison
 
-When creating a cloud build is in scope, wrap the repository's existing test
-command:
+Follow the build response's `suggested_commands`. The direct form is:
 
 ```bash
-vizzly run "<existing visual test command>" --wait --json
-vizzly context build <build-id> --source cloud --agent --json
+vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --json
+vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --include diffs --json
 ```
 
-## Read And Drill Into Evidence
+Open all three images together. Prefer `original_url` and fall back to `url`:
 
-For each evidence record:
+- Current: `comparison.screenshot.original_url` or
+  `comparison.screenshot.url`
+- Baseline: `comparison.baseline.original_url` or `comparison.baseline.url`
+- Diff: `comparison.analysis.diff_image_url`
 
-1. Inspect the current, baseline, and diff images with an available harness
-   capability. State the limitation if an image cannot be accessed.
-2. Read render metadata, review state, and compact Honeydiff diagnostics next
-   to the images.
-3. Run the returned `suggested_commands` instead of reconstructing identifiers
-   or URLs.
-4. Add `--include diffs` only when raw Honeydiff region geometry is needed.
-   Request comments only when human review context matters.
+Then compare the visible change with diff regions, fingerprint, and the
+separate `similar_by_fingerprint` and `recent_by_name` history streams.
+Previous review decisions help explain recurring evidence but do not decide the
+current review.
 
-Useful manual drill-downs are:
+Useful supporting commands:
 
 ```bash
-vizzly context comparison <comparison-id> --source <local-or-cloud> --json
 vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
 vizzly context similar <fingerprint-hash> --source cloud --json
 vizzly context review-queue --source <local-or-cloud> --json
 ```
 
-Use the source from the evidence you are inspecting in place of
-`<local-or-cloud>`. `context similar` is cloud-only. Keep missing values
-unknown, and do not turn metadata into a visual conclusion when the underlying
-images are unavailable.
+Use `--include diffs` only when compact diagnostics are insufficient. Request
+comments only when human review context matters.
+
+## Continue Without Guessing
+
+Run returned `suggested_commands` rather than reconstructing IDs, sources, or
+pagination. When more evidence exists, the next-page command carries the API's
+opaque `--cursor`; do not edit or interpret it. Keep follow-up commands pinned
+to the source that produced the evidence.

package/skills/vizzly/references/dynamic-content.md

@@ -1,39 +1,28 @@
 # Dynamic Content
 
-Treat dates, timers, randomized data, API-backed content, generated images, and
-responsive text as possible causes of change, not automatic explanations.
+Dates, timers, random data, API content, generated images, and responsive text
+can cause a diff. They are possible explanations, not conclusions.
 
 ## Diagnose Before Tuning
 
-1. Inspect screenshot history and the actual image evidence:
+1. Inspect the actual images and screenshot history:
 
    ```bash
    vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
    ```
 
-2. Replace `<local-or-cloud>` with the source of the evidence being diagnosed.
-   Record the observed region, recurrence, render metadata, and whether the
-   same change appears across builds or variants.
-3. Check whether deterministic fixtures can remove irrelevant variation.
-4. Treat hotspots and confirmed regions as server- or user-owned evidence.
-   They can affect comparison results, but this CLI exposes them for inspection
-   rather than authoring.
-5. Preserve existing per-screenshot `threshold` and `minClusterSize` values
-   unless the task and repeated evidence justify a change. Do not invent new
-   tolerance values from one diff.
-
-## Avoid
-
-- Raising a global threshold for one unstable area.
-- Masking a whole page when only a small region changes.
-- Assuming a recurring change is harmless without inspecting it.
-- Ignoring structural movement because a region contains dynamic content.
-- Claiming a cause when only metadata, rather than images or history, is
-  available.
-
-## Report Findings
-
-State the observed change first. Then distinguish a likely explanation—such as
-fixture drift, content disappearance, layout shift, capture timing, or baseline
-mismatch—from unresolved alternatives. Include the screenshot identity and the
-context command or link used.
+2. Record the visible region, recurrence, render metadata, and whether the same
+   change appears across builds or variants.
+3. Prefer deterministic fixtures when they can remove irrelevant variation.
+4. Treat hotspots and confirmed regions as server- or user-authored evidence.
+   This CLI exposes them for inspection, not authoring.
+5. Preserve `threshold` and `minClusterSize` unless repeated evidence
+   justifies a change.
+
+Avoid broad masks, global threshold changes for one region, and claims based on
+metadata alone. A recurring change can still be a bug, especially when content
+movement affects nearby layout.
+
+Report the observed change first. Label fixture drift, layout shift, capture
+timing, or baseline mismatch as a possible cause until the evidence establishes
+it.

package/skills/vizzly/references/sdks.md

@@ -1,9 +1,10 @@
-# SDK Capture Patterns
+# SDK Capture
 
-Prefer the repository's existing Vizzly integration and user journey. Add a new
-capture path only when the task requires it.
+Use the repository's existing Vizzly integration and user journey. The
+JavaScript example applies only when no framework-specific capture path already
+owns the workflow.
 
-## JavaScript Client
+## JavaScript
 
 ```javascript
 import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
@@ -13,37 +14,28 @@ await vizzlyScreenshot('settings-profile-edit-mode', screenshot);
 ```
 
 `vizzlyScreenshot(name, image, options)` accepts PNG bytes or a file path.
-Available options include:
+Options include `properties`, `threshold`, `minClusterSize`, and
+`fullPage`. Preserve existing tuning unless visual evidence justifies changing
+it.
 
-- `properties`: metadata attached to the screenshot.
-- `threshold`: per-screenshot CIEDE2000 Delta E tolerance.
-- `minClusterSize`: minimum changed-pixel cluster size.
-- `fullPage`: whether the screenshot represents a full-page capture.
+## Keep Identity Stable
 
-Do not add arbitrary tuning values. Preserve the repository's existing values
-unless visual evidence justifies changing them.
+Use a descriptive name. Identity always includes the name, viewport width, and
+browser. Configured `signatureProperties` add custom identity fields; other
+properties are metadata.
 
-## Screenshot Identity
+Do not assume theme, locale, or state creates a separate baseline unless the
+configuration says so. Avoid generic names such as `screenshot1` and names
+with slashes.
 
-Use a stable, descriptive name. Vizzly's signature always includes the name,
-viewport width, and browser. Only properties named in the project's
-`signatureProperties` configuration participate in baseline identity.
+## Follow Existing Integrations
 
-Treat other `properties` as metadata. Do not assume values such as theme,
-locale, or state create separate baselines unless the configuration says so.
-
-## Existing Integrations
-
-- Use the Vizzly Vitest matcher when the project already configures the plugin:
+- Keep the Vizzly Vitest matcher when it is already configured:
 
   ```javascript
   await expect(page).toMatchScreenshot('hero-section.png');
   ```
 
-- Prefer existing Storybook, static-site, or Ember capture flows over adding a
-  parallel Playwright path.
-- For Swift/XCTest, inspect the repository's Vizzly Swift package documentation
-  and existing `VizzlyXCTest` usage before changing capture code.
-
-Use properties for searchable metadata and configured variants. Avoid generic
-names such as `screenshot1` or `test`, and avoid names with slashes.
+- Prefer existing Storybook, static-site, Ember, or Swift capture flows over a
+  parallel test path.
+- Inspect the repository's integration setup before changing capture code.