saccade

[![CI](https://img.shields.io/github/actions/workflow/status/Tavrin/saccade/ci.yml?branch=main&label=CI)](https://github.com/Tavrin/saccade/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/saccade.svg)](https://crates.io/crates/saccade)
[![docs.rs](https://img.shields.io/docsrs/saccade)](https://docs.rs/saccade)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](#license)
[![MSRV](https://img.shields.io/badge/MSRV-1.89-blue)](Cargo.toml)
[MCP Registry: io.github.Tavrin/saccade](https://registry.modelcontextprotocol.io/?q=io.github.Tavrin%2Fsaccade)

# saccade

saccade is a visual and performance evidence tool for humans, CI and AI agents.
It measures perceptual differences, locates them in measured regions (with
optional advisory observations), and checks them against the thresholds and
policies you declare. It writes offline HTML reports and versioned JSON.
Performance conclusions require comparable captures, timing provenance and
repeat evidence. Only a human can approve a baseline.

![Report with image differences and numbered hotspots](docs/images/report.png)

## Quickstart

```sh
saccade demo --out saccade-demo
saccade view saccade-demo
```

The demo exits 1 on purpose: it contains changed and missing captures.
Open `saccade-demo/report/index.html` to see the result. The
[quickstart walkthrough](docs/quickstart.md) has copyable examples for
comparison, exact identity, configuration, evidence export and local review.
Not sure which command fits? Use the [task map](docs/quickstart.md#which-command-for-which-task)
and the five tested guides: [visual CI](docs/guides/visual-ci.md),
[controlled rendering](docs/guides/controlled-rendering.md),
[document export](docs/guides/document-export.md),
[media intake](docs/guides/media-intake.md) and
[delivery tuning](docs/guides/delivery-tuning.md). `saccade doctor` shows what your
install can run.

## Use cases

### Visual verification for coding agents

The local MCP server reads registered capture roots and writes reports under a
separate output root. Its tools cannot approve baselines. Agents can inspect
bounded results and follow recorded next actions.

```sh
saccade mcp --root captures --out-root agent-reports
saccade compare captures/before captures/after --out agent-reports/change --json
```

See the [agent guide](docs/agents.md) and [MCP and plugin setup](docs/plugins.md).

### CI visual regression

The local Playwright package provides `toMatchSaccade` and capture stabilization.
A sweep groups page pairs and records capture failures as failures.

```sh
node integrations/playwright/sweep.cjs sweep.json captures capture-options.json
saccade sweep compare sweep.json --captures captures/captures.json --out sweep-report --json
```

See the [Playwright matcher](docs/playwright-matcher.md), [sweep](docs/sweep.md)
and [CI integration](docs/ci.md). Sweep needs the optional `products` feature.

### Render and engine evidence

Declared spatial policies distinguish `texture_noise_only` from
`systematic_shift`. Required-effect checks can fail on an empty footprint;
capture layers restrict measurement scope and fixed-camera sequences measure
temporal stability. Supply the policies and capture provenance with your inputs.

```sh
saccade compare before after --config render-evidence.toml --out render-report --json
saccade experiment sequence before-frames after-frames --fixed-camera --out temporal-report --json
```

See [rendering evidence](docs/render-evidence.md) and
[engine capture ingestion](docs/engine-ingest.md),
[temporal settling](docs/experiments-wave11.md#event-relative-visual-settling)
and [one-flag masks](docs/experiments-wave11.md#one-flag-native-scopes-and-occupancy).

### Image delivery tuning

Audit served formats and search declared encodings for a perceptual target.
Local and URL-template adapters record bytes and content types and do not modify originals.

```sh
saccade imgtune audit --urls images.txt --accept 'image/avif,image/webp,image/*' --out audit.json --json
saccade imgtune search tuning.json --out tuning-report.json --json
```

See [image tuning](docs/imgtune.md). Enable `products`, plus `imgtune-avif` for AVIF.

### Media analysis records

A media record keeps status and provenance for metadata, quality, fingerprints
and optional model sections. Disabled or failed sections are recorded as such.
The Python package and local HTTP API use the same analysis path.

```sh
saccade analyze-media image.jpg --profile cpu-lite --output-size 1200x800 --json
saccade keyframes video.mp4 --out frames --json
```

See [media analysis](docs/media.md), [Python](docs/python.md) and [HTTP API](docs/api.md).
Install with `pip install saccade-vision` (Python 3.10+); the import stays `import saccade`.

### Single-image provenance and integrity

Inspect C2PA credentials, metadata and compression-history indicators without a
baseline. Heuristics have stated limits and do not establish a real/fake verdict.
GPS disclosure is opt-in; C2PA validation needs `credentials`.

```sh
saccade inspect-image received.jpg --output-size 1600x900 --out inspection --json
saccade inspect-image received.png --hash-index hashes/saccade-hash.v1.json --out indexed-inspection --json
```

See [single-image inspection](docs/inspect-image.md).

### General comparison

Pick registration, hashes, embedding similarity/search, OCR text differences,
no-reference quality or document rasterization to fit the question.
Model workflows require supplied pinned artifacts and the relevant features.

```sh
saccade compare before.png after.png --align similarity --out aligned-report --json
saccade text before.png after.png --out text-report --json
saccade assess image.jpg --out quality-report --json
```

See [choosing a comparison](docs/choosing-a-comparison.md),
[registration](docs/registration.md), [hashing](docs/hashing.md),
[embeddings and search](docs/embeddings.md), [OCR](docs/text.md),
[quality](docs/assessment.md) and [documents](docs/documents.md).

### Performance evidence

Compare supplied timing sidecars using paired statistics and uncertainty
intervals, or locate changes in a sequence. Saccade does not run the benchmark;
missing or rejected provenance cannot qualify a speedup.

```sh
saccade compare before after --out perf-report --json
saccade history onset --store history --json
```

See [paired statistics](docs/paired-performance.md),
[change points](docs/wave1.md), [identity/performance](docs/identity-and-performance.md),
[timing verdicts](docs/experiments-wave11.md#timing-ab),
[ablation tables](docs/experiments-wave11.md#multi-arm-repeat-tables)
and [report linking](docs/experiments-wave11.md#external-report-links-and-indexes).
The [performance sidecar kit](docs/perf-kit.md) has fixtures and recipes for producers.
Label images can be scored with [mask metrics](docs/mask-metrics.md), boxes exchanged
as COCO or YOLO ([box interchange](docs/box-interchange.md)), and extracted video
frames described by a [frame map](docs/frame-map.md).

## Install

Install with Rust 1.89 or newer:

```sh
cargo install saccade --version 0.3.0 --locked
saccade doctor --json
```

To build this checkout, use `cargo install --locked --path crates/saccade`.
[Release archives](https://github.com/Tavrin/saccade/releases) include checksums,
licences and third-party notices. See [release instructions](docs/releasing.md).

| Cargo features | Default? | Purpose and requirements |
| --- | --- | --- |
| `compression`, `parallel`, `graphics` | Yes | FLIP, compression scores, graphics and temporal measurements; CPU processing. |
| `ai`, `evaluation` | Yes | Provider review adapters and evaluation; calls require explicit authorization and budgets. |
| `workbench`, `mcp` | Yes | Local report browsing and bounded agent tools. |
| `assist` | No | Experimental explain, mask audit, visible-condition checks and batch advice. |
| `products` | No | Sweep, image tuning, design-source and notifier adapters. Browser captures separately need Node.js and Playwright. |
| `imgtune-avif` | No | AVIF encoding/decoding; system dav1d >=1.3.0 development library and pkg-config. |
| `semantic-regions`, `embeddings`, `local-models` | No | Pinned CPU model artifacts and dynamically loaded ONNX Runtime 1.22 (API 22). Runtime/model pulls are explicit provisioning operations; analysis never downloads them. |
| `ocr`, `ocr-provider` | No | Local PP-OCRv5 Latin with pinned models/runtime; separately opt-in hosted document OCR with spend/egress controls. |
| `documents`, `credentials` | No | SVG/PDF rasterization and offline C2PA validation. |
| `media-http` | No | Bounded URL inputs for media analysis; network fetches require an explicit URL input. |
| `local-vlm`, `vision-providers` | No | Configured local/hosted vision adapters; observations remain advice. |
| `geometry`, `dense-motion`, `prechecks`, `schema` | No | Mesh measurements, dense motion, experimental safety/accessibility checks and schema generation. |

Video extraction invokes external `ffmpeg` and `ffprobe`; neither is bundled.
See [model/runtime provisioning](docs/wave7.md) and [AVIF prerequisites](docs/imgtune.md#system-prerequisites).
Default comparisons need no provider account or GPU. Add optional features with
`cargo install ... --features products,ocr`, for example.

## Crates

| Crate | Purpose |
| --- | --- |
| `saccade-core` | Shared image measurements, evidence contracts and Rust workflows. |
| `saccade-print` | ICC-managed print raster comparisons and diagnostics. |
| `saccade-geo` | Native TIFF measurements with grid and nodata metadata. |
| `saccade-a11y` | Accessibility pre-checks on declared regions or on regions it finds itself. |
| `saccade` | Command-line interface and MCP server. |
| `saccade-py` | Python bindings for shared measurements. |

With the `prechecks` feature, `a11y auto` finds text and UI regions in an image
and checks them, offline:

```sh
saccade a11y auto screenshot.png --out accessibility-report
```

## Metric