vref

Visual reference CLI for curated put.io screenshots.

Build and serve static galleries from repo-local manifests so agents can inspect UI evidence before they edit.

Installation

Install in an app repo that owns visual references:

pnpm add -D @putdotio/vref

Quick Start

Create a repo-local manifest and screenshots:

.vref/
  manifest.json
  screenshots/

Build the gallery:

vref build

Validate without writing index.html:

vref validate --output json
vref build --check --output json

After the owning app repo captures or updates screenshots, rebuild the gallery:

vref build

Open the gallery locally:

vref serve

Agents should inspect the command schema before automating:

vref describe --output json

Manifest

vref reads .vref/manifest.json by default and writes .vref/index.html. Screenshot file paths are relative to .vref/ and must stay inside that directory.

{
  "version": 1,
  "title": "put.io Roku visual reference",
  "description": "Curated Roku screenshots for review and design comparison.",
  "updatedAt": "2026-05-19T13:35:00.000Z",
  "screenshots": [
    {
      "id": "home",
      "title": "Home",
      "group": "Main pages",
      "platform": "Roku",
      "device": "Roku 720p",
      "viewport": { "width": 1280, "height": 720 },
      "file": "screenshots/roku-720p/home.jpg",
      "capturedAt": "2026-05-19T13:34:00.000Z",
      "sizeBytes": 22788,
      "tags": ["home", "navigation"],
      "notes": ["Home menu with Files, Search, and Settings visible."]
    }
  ]
}

Docs

• Visual Reference Guide
• Plan
• Distribution
• Agent guide
• Security

Contributing

See Contributing for setup, validation, and pull request expectations.

License

MIT, see License