@vizzly-testing/cli 0.35.3-beta.1 → 0.35.3-beta.3

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,83 +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.
-
-Local context reads persisted `.vizzly` artifacts. Confirm that their build,
-branch, timestamp, and baseline match the task before treating them as current.
+Confirm the stored build, branch, timestamp, and baseline are current enough
+for the task.
 
-## Generate Fresh Local Evidence
+## Generate Fresh 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.
+`tdd run` and `tdd start` are alternatives. Stop only a daemon started for the
+current task.
 
-## Inspect Cloud Evidence
-
-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> --agent --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
 
-When a build has more than 10 actionable records, run its returned next-page
-command. The command uses `--offset` to preserve API order without pulling the
-full build context into the agent handoff.
+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. Use diff regions only to locate changed pixels; they do not approve a
+   comparison or explain why it changed.
+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.

package/skills/vizzly/references/setup-ci.md

@@ -1,10 +1,10 @@
 # Setup And CI
 
-Use this reference only when the user asks to initialize Vizzly, change CI, or
-troubleshoot configuration. These workflows mutate project files or external
-build state.
+Use this reference only when the task includes initialization, CI changes, or
+configuration troubleshooting. These workflows mutate files or external build
+state.
 
-## Local Setup
+## Initialize
 
 Initialize only with authorization:
 
@@ -12,57 +12,33 @@ Initialize only with authorization:
 vizzly init
 ```
 
-After setup, choose one local execution mode:
-
-```bash
-vizzly tdd run "<existing visual test command>" --no-open
-```
-
-or:
-
-```bash
-vizzly tdd start --json
-<existing visual test command>
-vizzly tdd stop --json
-```
-
-Do not run `tdd start` before `tdd run`; both own a local TDD server lifecycle.
+Use [CLI context](cli-context.md) for local evidence and TDD lifecycle commands.
 
 ## Cloud CI
 
-Use a project-scoped token supplied by the user's existing secret-management
-system. Never print it, write it into the repository, or replace working
-credentials while debugging.
-
-Wrap the CI job's existing visual test command:
+Use a project-scoped token from the repository's existing secret system. Never
+print it or write it into the repository.
 
 ```bash
 vizzly run "<existing visual test command>" --wait --json
 ```
 
-## Parallel CI
-
-Give every shard in one build the same parallel ID, unique to that workflow
-attempt. Run all shards without `--wait`, then finalize that shared ID once
-after every shard finishes:
+For parallel CI, give every shard the same workflow-specific parallel ID. Run
+shards without `--wait`, then finalize once after all shards finish:
 
 ```bash
 vizzly run "<shard test command>" --parallel-id "<shared-ci-run-id>" --json
 vizzly finalize "<shared-ci-run-id>" --json
 ```
 
-Do not create a different parallel ID per shard, and do not wait for a parallel
-build to complete before it has been finalized. Use one finalizer rather than
-having every shard race to finalize the build.
-
 ## Troubleshoot
 
-- Run `vizzly doctor` for local configuration checks.
-- Run `vizzly tdd status --json` for a local daemon started by the task.
-- Run `vizzly status <build-id> --json` for cloud lifecycle facts.
-- Run `vizzly context build <build-id> --source cloud --agent --json` for visual
-  evidence.
-- If screenshots are absent, verify the existing SDK or integration, the test
-  path that should capture them, and the active local or cloud session.
-- If authentication is absent, report it rather than initiating login unless
-  setup is explicitly in scope.
+- `vizzly doctor`: local configuration
+- `vizzly tdd status --json`: a local daemon started by the task
+- `vizzly status <build-id> --json`: cloud lifecycle
+- `vizzly context build <build-id> --source cloud --agent --json`: visual
+  evidence
+
+If screenshots are absent, verify the existing integration, the test path that
+should capture them, and the active session. If authentication is absent,
+report it rather than logging in unless setup is in scope.

package/dist/tdd/core/hotspot-coverage.js

@@ -1,112 +0,0 @@
-/**
- * Hotspot Coverage Calculation
- *
- * Pure functions for calculating how much of a visual diff falls within
- * "hotspot" regions - areas of the UI that frequently change due to dynamic
- * content (timestamps, animations, etc.).
- *
- * Uses 1D Y-coordinate matching (same algorithm as cloud).
- */
-
-/**
- * Calculate what percentage of diff falls within hotspot regions
- *
- * @param {Array} diffClusters - Array of diff clusters from honeydiff
- * @param {Object} hotspotAnalysis - Hotspot data with regions array
- * @returns {{ coverage: number, linesInHotspots: number, totalLines: number }}
- */
-export function calculateHotspotCoverage(diffClusters, hotspotAnalysis) {
-  if (!diffClusters || diffClusters.length === 0) {
-    return {
-      coverage: 0,
-      linesInHotspots: 0,
-      totalLines: 0
-    };
-  }
-  if (!hotspotAnalysis?.regions || hotspotAnalysis.regions.length === 0) {
-    return {
-      coverage: 0,
-      linesInHotspots: 0,
-      totalLines: 0
-    };
-  }
-
-  // Extract Y-coordinates (diff lines) from clusters
-  // Each cluster has a boundingBox with y and height
-  let diffLines = [];
-  for (let cluster of diffClusters) {
-    if (cluster.boundingBox) {
-      let {
-        y,
-        height
-      } = cluster.boundingBox;
-      // Add all Y lines covered by this cluster
-      for (let line = y; line < y + height; line++) {
-        diffLines.push(line);
-      }
-    }
-  }
-  if (diffLines.length === 0) {
-    return {
-      coverage: 0,
-      linesInHotspots: 0,
-      totalLines: 0
-    };
-  }
-
-  // Remove duplicates and sort
-  diffLines = [...new Set(diffLines)].sort((a, b) => a - b);
-
-  // Check how many diff lines fall within hotspot regions
-  let linesInHotspots = 0;
-  for (let line of diffLines) {
-    let inHotspot = hotspotAnalysis.regions.some(region => line >= region.y1 && line <= region.y2);
-    if (inHotspot) {
-      linesInHotspots++;
-    }
-  }
-  let coverage = linesInHotspots / diffLines.length;
-  return {
-    coverage,
-    linesInHotspots,
-    totalLines: diffLines.length
-  };
-}
-
-/**
- * Determine if a comparison should be filtered as "passed" based on hotspot coverage
- *
- * A diff is filtered when:
- * 1. Coverage is >= 80% (most diff in hotspot regions)
- * 2. Confidence is "high" or confidence score > 0.7
- *
- * @param {Object} hotspotAnalysis - Hotspot data with confidence info
- * @param {{ coverage: number }} coverageResult - Result from calculateHotspotCoverage
- * @returns {boolean} True if diff should be filtered as hotspot noise
- */
-export function shouldFilterAsHotspot(hotspotAnalysis, coverageResult) {
-  if (!hotspotAnalysis || !coverageResult) {
-    return false;
-  }
-  let {
-    coverage
-  } = coverageResult;
-
-  // Need at least 80% of diff in hotspot regions
-  if (coverage < 0.8) {
-    return false;
-  }
-
-  // Need high confidence in the hotspot analysis
-  let {
-    confidence,
-    confidenceScore
-  } = hotspotAnalysis;
-  if (confidence === 'high') {
-    return true;
-  }
-  if (confidenceScore !== undefined && confidenceScore > 0.7) {
-    return true;
-  }
-  return false;
-}