pixeljury-vision

pixeljury-vision is the provider-adapter package behind PixelJury's model-backed visual scoring: it sends screenshots, static findings, and the rubric to OpenAI, Anthropic, Gemini, Ollama, Claude Code, Codex, or a deterministic mock adapter.

• Scores PixelJury screenshots against the public visual QA rubric.
• Supports openai, anthropic, gemini, ollama, claude-code, codex, and mock.
• Validates model output against the expected { dimensions, visionTropes } contract.
• Lets integrations use model-backed scoring without reimplementing provider calls.

Install

npm install pixeljury-vision
pnpm add pixeljury-vision
yarn add pixeljury-vision
bun add pixeljury-vision

Most developers should install the CLI instead:

npx pixeljury review http://localhost:3000

Quickstart

import { score } from "pixeljury-vision";

const vision = await score({
  provider: "mock",
  rubricText: "PixelJury rubric text",
  staticSummary: "Static findings summary",
  screenshots: {
    desktop: "pixeljury/screenshot.png",
    mobile: "pixeljury/screenshot-390.png",
  },
});

console.log(vision.dimensions);

Use a real provider by passing provider and credentials:

const vision = await score({
  provider: "openai",
  apiKey: process.env.OPENAI_API_KEY,
  rubricText,
  staticSummary,
  screenshots,
});

What You Can Build With It

• A custom PixelJury integration that keeps the core renderer but chooses a specific provider.
• An internal visual scoring service that validates every model response into a stable shape.
• Local experiments with ollama, claude-code, codex, or mock before switching to API-key providers.

Why pixeljury-vision?

• Provider calls are isolated. Rendering and static-signal code stay in pixeljury-core; this package only handles model scoring.
• The output contract is validated. Invalid model responses are parsed, retried once with stricter instructions, then surfaced clearly.
• It supports local and subscription workflows. ollama, claude-code, and codex avoid a separate API key for local use; passthrough CLI runs use staged screenshot files in a temporary working directory.
• The mock adapter is deterministic. Tests and demos can run without network access.

Compared To Alternatives

| Need | pixeljury-vision | Common alternative | |---|---|---| | PixelJury-compatible vision scoring | Returns the exact dimensions and trope shape consumed by the score composer. | Direct provider SDK calls require your own prompt, schema, retries, and parsing. | | Local/no-key development | Includes mock, ollama, claude-code, and codex adapters. | Hosted-only wrappers usually require API credentials for every run. | | Provider switching | Keeps a single score() API across supported providers. | Separate SDK integrations drift in options and response shape. |

API

import { PROVIDERS, VisionParseError, parseVision, resolveKey, score } from "pixeljury-vision";

Key exports:

• PROVIDERS: supported provider names.
• score({ provider, rubricText, staticSummary, screenshots, apiKey, model }): calls the selected adapter and returns validated dimensions.
• resolveKey(provider, explicit): reads explicit keys, PIXELJURY_KEY, or provider-specific environment variables.
• parseVision(raw): validates raw provider output against the PixelJury score schema.
• VisionParseError: thrown when model output cannot be parsed.

Compatibility And Limitations

• Requires Node.js 18 or newer.
• Expects screenshots generated by PixelJury or compatible PNG files.
• Does not render pages or compose final scores. Use pixeljury-core for rendering/static signals or pixeljury for the full CLI.
• claude-code and codex shell out to local CLIs and are intended for individual local use. PixelJury stages screenshots in a temporary working directory for those passthrough runs instead of pointing the local agent at the caller's project checkout. Use API-key providers for public CI or shared automation.
• The package exports JavaScript modules; TypeScript declaration files are not currently published.

Links

• Repository
• CLI package
• Rubric
• Security policy

License

MIT