@vizzly-testing/cli 0.30.0 → 0.31.0

package/README.md

@@ -1,23 +1,23 @@
 # Vizzly CLI
 
-> Visual proof that your UI works
+> Visual review for agents and teams
 
 [![npm version](https://img.shields.io/npm/v/@vizzly-testing/cli.svg)](https://www.npmjs.com/package/@vizzly-testing/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Visual bugs slip through code review. They hide in pixel-perfect mockups, sneak past unit tests, and show up right when you're about to ship. Vizzly catches them first.
+Vizzly keeps the visual truth behind your UI: approved baselines, meaningful diffs, review state, comments, and preview links in one place. That makes it useful for humans reviewing product changes and for LLM agents that need to understand what the UI is supposed to look like before they edit it.
 
-Unlike tools that re-render components in isolation, Vizzly captures screenshots directly from your functional tests—the *real thing*. Whether you're validating AI-generated code or testing manual changes, you get visual proof before anything hits production.
+Unlike tools that re-render components in isolation, Vizzly captures screenshots directly from your functional tests: the real thing. Whether you're validating AI-generated code or testing manual changes, you get reviewed visual evidence before anything hits production.
 
 ## Why Vizzly?
 
-**Local TDD workflow.** See changes as you type, not after CI. The `vizzly tdd` command runs a local dashboard that compares screenshots instantly—no cloud roundtrip, no waiting.
+**Local TDD workflow.** See changes as you type, not after CI. The `vizzly tdd` command runs a local dashboard that compares screenshots instantly and exposes the current workspace as local context.
 
-**Smart diffing with Honeydiff.** Our Rust-based comparison engine is 12x faster than alternatives and ignores the noise: timestamps, ads, font rendering differences. It finds real changes.
+**Meaningful diff metadata.** Vizzly stores rich diff evidence: changed regions, cluster metadata, fingerprints, hotspots, confirmed regions, and image URLs. Agents can inspect what changed instead of guessing from a pass/fail label.
 
 **Any screenshot source.** Playwright, Cypress, Puppeteer, Selenium, native mobile apps, or even design mockups. If you can capture it, Vizzly can compare it.
 
-**Team-based pricing.** Pay for your team, not your screenshots. Test everything without budget anxiety.
+**Approved baselines as truth.** Cloud context carries human review state. Local context carries the downloaded or generated baseline metadata. That is the bridge between TDD locally and collaborative review in Vizzly.
 
 ## Quick Start
 
@@ -60,7 +60,7 @@ vizzly run "npm test" --wait
 
 ### Visual Context For Agents
 
-Use `vizzly context` when you want Vizzly to act more like visual context than a test runner.
+Use `vizzly context` when you want Vizzly to act like a visual context store, not just a test runner.
 
 This is especially useful for LLM agents, automation, and quick debugging loops. Instead of
 making a bunch of narrow API calls, you can ask for one build, comparison, screenshot, or review
@@ -73,11 +73,11 @@ vizzly context comparison def456 --json
 
 # Local workspace context from .vizzly/
 vizzly context build current --source local
+vizzly context build current --source local --agent
 vizzly context screenshot build-detail-screenshots --source local --json
 ```
 
-`--json` is the main automation path. Human-readable output is there for quick terminal use, but
-JSON is what you want for scripts, agents, and prompt assembly.
+`--json` is the durable automation path. `--agent` gives a compact handoff for prompt assembly and local dogfooding. Add `--full` when an agent really needs the complete build context payload, or `--include screenshots,diffs,comments` when the compact JSON needs selected detail.
 
 Local context is read-only and file-backed. It reads your existing `.vizzly` workspace state from
 TDD runs, including screenshots, diffs, and any saved hotspot or region metadata.

package/dist/api/client.js

@@ -14,6 +14,9 @@ import { buildApiUrl, buildRequestHeaders, buildUserAgent, extractErrorBody, isA
  * Default API URL
  */
 export const DEFAULT_API_URL = 'https://app.vizzly.dev';
+function isProjectToken(token) {
+  return typeof token === 'string' && token.startsWith('vzt_');
+}
 
 /**
  * Create an API client with the given configuration
@@ -63,7 +66,7 @@ export function createApiClient(options = {}) {
       let errorBody = await extractErrorBody(response);
 
       // Handle 401 with token refresh
-      if (shouldRetryWithRefresh(response.status, isRetry, await hasRefreshToken())) {
+      if (shouldRetryWithRefresh(response.status, isRetry, !isProjectToken(token) && (await hasRefreshToken()))) {
         let refreshed = await attemptTokenRefresh();
         if (refreshed) {
           token = refreshed;
@@ -73,7 +76,7 @@ export function createApiClient(options = {}) {
 
       // Auth error
       if (isAuthError(response.status)) {
-        throw new AuthError('Invalid or expired API token. Link a project via "vizzly project:select" or set VIZZLY_TOKEN.');
+        throw new AuthError('Invalid or expired API token. Run "vizzly project link <org>/<project>" or set VIZZLY_TOKEN.');
       }
 
       // Other errors
@@ -119,7 +122,7 @@ export function createApiClient(options = {}) {
       await saveAuthTokens({
         accessToken: data.accessToken,
         refreshToken: data.refreshToken,
-        expiresAt: data.expiresAt,
+        expiresAt: data.expiresAt || new Date(Date.now() + data.expiresIn * 1000).toISOString(),
         user: auth.user
       });
       return data.accessToken;

package/dist/cli.js

@@ -14,18 +14,20 @@ import { loginCommand, validateLoginOptions } from './commands/login.js';
 import { logoutCommand, validateLogoutOptions } from './commands/logout.js';
 import { orgsCommand, validateOrgsOptions } from './commands/orgs.js';
 import { previewCommand, validatePreviewOptions } from './commands/preview.js';
+import { projectLinkCommand, validateProjectLinkOptions } from './commands/project.js';
 import { projectsCommand, validateProjectsOptions } from './commands/projects.js';
 import { approveCommand, commentCommand, rejectCommand, validateApproveOptions, validateCommentOptions, validateRejectOptions } from './commands/review.js';
 import { runCommand, validateRunOptions } from './commands/run.js';
 import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.js';
-import { runDaemonChild, tddListCommand, tddStartCommand, tddStatusCommand, tddStopCommand } from './commands/tdd-daemon.js';
+import { runDaemonChild, tddListCommand, tddStartCommand, tddStatusCommand, tddStopCommand, validateTddStartOptions } from './commands/tdd-daemon.js';
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 import { validateWhoamiOptions, whoamiCommand } from './commands/whoami.js';
 import { createPluginServices } from './plugin-api.js';
 import { loadPlugins } from './plugin-loader.js';
 import { createServices } from './services/index.js';
 import { generateStaticReport, getReportFileUrl } from './services/static-report-generator.js';
+import { withTimeout } from './utils/async-utils.js';
 import { openBrowser } from './utils/browser.js';
 import { colors } from './utils/colors.js';
 import { loadConfig } from './utils/config-loader.js';
@@ -47,7 +49,7 @@ const formatHelp = (cmd, helper) => {
     // Cute grizzly bear mascot with square eyes (like the Vizzly logo!)
     lines.push(c.brand.amber('   ʕ□ᴥ□ʔ'));
     lines.push(`   ${c.brand.amber(c.bold('vizzly'))} ${c.dim(`v${version}`)}`);
-    lines.push(`   ${c.gray('Visual regression testing for UI teams')}`);
+    lines.push(`   ${c.gray('Visual review for agents and teams')}`);
   } else {
     // Compact header for subcommands
     lines.push(`  ${c.brand.amber(c.bold('vizzly'))} ${c.white(cmd.name())}`);
@@ -171,7 +173,7 @@ const formatHelp = (cmd, helper) => {
   if (isRootCommand) {
     lines.push(`  ${c.brand.amber('▸')} ${c.bold('Quick Start')}`);
     lines.push('');
-    lines.push(`      ${c.dim('# Local visual testing')}`);
+    lines.push(`      ${c.dim('# Local visual review')}`);
     lines.push(`      ${c.gray('$')} ${c.white('vizzly tdd start')}`);
     lines.push('');
     lines.push(`      ${c.dim('# CI pipeline')}`);
@@ -250,7 +252,7 @@ function normalizeJsonArgv(argv, commandNames) {
   }
   return normalizedArgv;
 }
-program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json [fields]', 'JSON output, optionally specify fields (e.g., --json id,status,branch)').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
+program.name('vizzly').description('Vizzly CLI for visual review').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json [fields]', 'JSON output, optionally specify fields (e.g., --json id,status,branch)').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
   formatHelp
 });
 
@@ -284,18 +286,15 @@ const pluginServices = createPluginServices(services);
 let plugins = [];
 try {
   plugins = await loadPlugins(configPath, config);
-  for (const plugin of plugins) {
+  for (let plugin of plugins) {
     try {
       // Add timeout protection for plugin registration (5 seconds)
-      const registerPromise = plugin.register(program, {
+      let registerPromise = plugin.register(program, {
         config,
         services: pluginServices,
-        output,
-        // Backwards compatibility alias for plugins using old API
-        logger: output
+        output
       });
-      const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Plugin registration timeout (5s)')), 5000));
-      await Promise.race([registerPromise, timeoutPromise]);
+      await withTimeout(registerPromise, 5000, 'Plugin registration timeout (5s)');
       output.debug(`Registered plugin: ${plugin.name}`);
     } catch (error) {
       output.warn(`Failed to register plugin ${plugin.name}: ${error.message}`);
@@ -312,7 +311,7 @@ program.command('init').description('Initialize Vizzly in your project').option(
     plugins
   });
 });
-program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', v => parseInt(v, 10)).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', v => parseInt(v, 10)).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
+program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -327,11 +326,11 @@ program.command('upload').description('Upload screenshots to Vizzly').argument('
   await uploadCommand(path, options, globalOptions);
 });
 
-// TDD command with subcommands - Local visual testing with interactive dashboard
-const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual comparisons');
+// TDD command with subcommands - local visual review with an interactive dashboard
+const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual review');
 
 // TDD Start - Background server
-tddCmd.command('start').description('Start background TDD server with dashboard').option('--port <port>', 'Port for TDD server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--token <token>', 'API token override').option('--daemon-child', 'Internal: run as daemon child process').action(async options => {
+tddCmd.command('start').description('Start background TDD server with dashboard').option('--port <port>', 'Port for TDD server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--token <token>', 'API token override').option('--daemon-child', 'Internal: run as daemon child process').action(async options => {
   const globalOptions = program.opts();
 
   // If this is a daemon child process, run the server directly
@@ -339,6 +338,14 @@ tddCmd.command('start').description('Start background TDD server with dashboard'
     await runDaemonChild(options, globalOptions);
     return;
   }
+  let validationErrors = validateTddStartOptions(options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
   await tddStartCommand(options, globalOptions);
 });
 
@@ -361,7 +368,7 @@ tddCmd.command('list').description('List all running TDD servers').action(async
 });
 
 // TDD Run - One-off test run with ephemeral server (generates static report)
-tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual comparisons').option('--port <port>', 'Port for TDD server', '47392').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {
+tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual review').option('--port <port>', 'Port for TDD server', '47392').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -422,7 +429,7 @@ tddCmd.command('run <command>').description('Run tests once in TDD mode with loc
   await handleCleanup();
   process.exit(result?.exitCode || 0);
 });
-program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (command, options) => {
+program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (command, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -458,7 +465,7 @@ program.command('status').description('Check the status of a build').argument('<
   }
   await statusCommand(buildId, options, globalOptions);
 });
-program.command('builds').description('List and query builds').option('-b, --build <id>', 'Get a specific build by ID').option('--branch <branch>', 'Filter by branch').option('--status <status>', 'Filter by status (created, pending, processing, completed, failed)').option('--environment <env>', 'Filter by environment').option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', val => parseInt(val, 10), 20).option('--offset <n>', 'Skip first N results', val => parseInt(val, 10), 0).option('--comparisons', 'Include comparisons when fetching a specific build').addHelpText('after', `
+program.command('builds').description('List and query builds').option('-b, --build <id>', 'Get a specific build by ID').option('--branch <branch>', 'Filter by branch').option('--status <status>', 'Filter by status (created, pending, processing, completed, failed)').option('--environment <env>', 'Filter by environment').option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', Number, 20).option('--offset <n>', 'Skip first N results', Number, 0).option('--comparisons', 'Include comparisons when fetching a specific build').addHelpText('after', `
 Examples:
   $ vizzly builds                          # List recent builds
   $ vizzly builds --branch main            # Filter by branch
@@ -482,7 +489,7 @@ Examples:
   }
   await buildsCommand(options, globalOptions);
 });
-program.command('comparisons').description('Query and search comparisons').option('-b, --build <id>', 'Get comparisons for a specific build').option('--id <id>', 'Get a specific comparison by ID').option('--name <pattern>', 'Search comparisons by name (supports wildcards)').option('--status <status>', 'Filter by status (identical, new, changed)').option('--branch <branch>', 'Filter by branch (for name search)').option('--limit <n>', 'Maximum results to return (1-250)', val => parseInt(val, 10), 50).option('--offset <n>', 'Skip first N results', val => parseInt(val, 10), 0).option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').addHelpText('after', `
+program.command('comparisons').description('Query and search comparisons').option('-b, --build <id>', 'Get comparisons for a specific build').option('--id <id>', 'Get a specific comparison by ID').option('--name <pattern>', 'Search comparisons by name (supports wildcards)').option('--status <status>', 'Filter by status (identical, new, changed)').option('--branch <branch>', 'Filter by branch (for name search)').option('--limit <n>', 'Maximum results to return (1-250)', Number, 50).option('--offset <n>', 'Skip first N results', Number, 0).option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').addHelpText('after', `
 Examples:
   $ vizzly comparisons -b abc123           # List comparisons for a build
   $ vizzly comparisons --id def456         # Get specific comparison by ID
@@ -505,13 +512,15 @@ Examples:
   }
   await comparisonsCommand(options, globalOptions);
 });
-let contextCmd = program.command('context').description('Fetch visual context bundles for agents and reviewers');
-contextCmd.command('build').description('Fetch a build context bundle').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').addHelpText('after', `
+let contextCmd = program.command('context').description('Fetch build context for agents and reviewers');
+contextCmd.command('build').description('Fetch build context for agents and reviewers').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full build context payload with --agent --json').option('--include <items>', 'Add detail to compact agent JSON: screenshots,diffs,comments').addHelpText('after', `
 Examples:
   $ vizzly context build abc123
   $ vizzly context build current --source local
-  $ vizzly context build abc123 --json
-  $ vizzly context build abc123 --json build.id,summary.comparisons
+  $ vizzly context build current --source local --agent
+  $ vizzly context build abc123 --agent --json
+  $ vizzly context build abc123 --agent --json --include diffs,comments
+  $ vizzly context build abc123 --agent --json --full
 `).action(async (buildId, options) => {
   const globalOptions = program.opts();
   const validationErrors = validateContextBuildOptions(options);
@@ -524,7 +533,7 @@ Examples:
   }
   await contextBuildCommand(buildId, options, globalOptions);
 });
-contextCmd.command('comparison').description('Fetch a comparison context bundle').argument('<comparison-id>', 'Comparison ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--similar-limit <n>', 'Maximum similar fingerprint matches to return (1-50)', val => parseInt(val, 10)).option('--recent-limit <n>', 'Maximum recent same-name comparisons to return (1-50)', val => parseInt(val, 10)).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', val => parseInt(val, 10)).addHelpText('after', `
+contextCmd.command('comparison').description('Fetch a comparison context bundle').argument('<comparison-id>', 'Comparison ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--similar-limit <n>', 'Maximum similar fingerprint matches to return (1-50)', Number).option('--recent-limit <n>', 'Maximum recent same-name comparisons to return (1-50)', Number).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', Number).addHelpText('after', `
 Examples:
   $ vizzly context comparison def456
   $ vizzly context comparison def456 --source local
@@ -542,7 +551,7 @@ Examples:
   }
   await contextComparisonCommand(comparisonId, options, globalOptions);
 });
-contextCmd.command('screenshot').description('Fetch screenshot context and historical memory').argument('<name>', 'Screenshot name').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--recent-limit <n>', 'Maximum recent comparisons to return (1-50)', val => parseInt(val, 10)).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', val => parseInt(val, 10)).addHelpText('after', `
+contextCmd.command('screenshot').description('Fetch screenshot context and historical memory').argument('<name>', 'Screenshot name').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--recent-limit <n>', 'Maximum recent comparisons to return (1-50)', Number).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', Number).addHelpText('after', `
 Examples:
   $ vizzly context screenshot Dashboard
   $ vizzly context screenshot Dashboard --source local
@@ -560,7 +569,7 @@ Examples:
   }
   await contextScreenshotCommand(name, options, globalOptions);
 });
-contextCmd.command('similar').description('Fetch project-scoped matches for a fingerprint hash').argument('<fingerprint-hash>', 'Fingerprint hash to search for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum matches to return (1-50)', val => parseInt(val, 10)).addHelpText('after', `
+contextCmd.command('similar').description('Fetch project-scoped matches for a fingerprint hash').argument('<fingerprint-hash>', 'Fingerprint hash to search for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum matches to return (1-50)', Number).addHelpText('after', `
 Examples:
   $ vizzly context similar fp-dashboard
   $ vizzly context similar fp-dashboard --project storybook --org acme
@@ -577,7 +586,7 @@ Examples:
   }
   await contextSimilarCommand(fingerprintHash, options, globalOptions);
 });
-contextCmd.command('review-queue').description('Fetch pending review context for a project').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum comparisons to return (1-100)', val => parseInt(val, 10)).option('--offset <n>', 'Skip first N comparisons', val => parseInt(val, 10)).addHelpText('after', `
+contextCmd.command('review-queue').description('Fetch pending review context for a project').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum comparisons to return (1-100)', Number).option('--offset <n>', 'Skip first N comparisons', Number).addHelpText('after', `
 Examples:
   $ vizzly context review-queue --project storybook --org acme
   $ vizzly context review-queue --source local
@@ -740,7 +749,7 @@ or the single organization for a project token.
   }
   await orgsCommand(options, globalOptions);
 });
-program.command('projects').description('List projects you have access to').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', val => parseInt(val, 10), 50).option('--offset <n>', 'Skip first N results', val => parseInt(val, 10), 0).addHelpText('after', `
+program.command('projects').description('List projects you have access to').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', Number, 50).option('--offset <n>', 'Skip first N results', Number, 0).addHelpText('after', `
 Examples:
   $ vizzly projects                        # List all projects
   $ vizzly projects --org my-company       # Filter by organization
@@ -762,6 +771,26 @@ Workflow:
   }
   await projectsCommand(options, globalOptions);
 });
+let projectCommand = program.command('project').description('Manage the project linked to this local checkout');
+projectCommand.command('link [selector]').description('Link a Vizzly project for cloud uploads').option('--org <slug>', 'Organization slug').option('--project <slug>', 'Project slug').option('--name <name>', 'Credential name shown in Vizzly').option('--expires-at <iso>', 'Optional token expiration timestamp').addHelpText('after', `
+Examples:
+  $ vizzly project link vizzly/storybook
+  $ vizzly project link --org vizzly --project storybook
+
+Note: run "vizzly login" first. The linked credential is project-scoped and is
+used for cloud uploads; your user login remains separate for review actions.
+`).action(async (selector, options) => {
+  const globalOptions = program.opts();
+  const validationErrors = validateProjectLinkOptions(selector, options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await projectLinkCommand(selector, options, globalOptions);
+});
 program.command('finalize').description('Finalize a parallel build after all shards complete').argument('<parallel-id>', 'Parallel ID to finalize').action(async (parallelId, options) => {
   const globalOptions = program.opts();
 
@@ -776,7 +805,7 @@ program.command('finalize').description('Finalize a parallel build after all sha
   }
   await finalizeCommand(parallelId, options, globalOptions);
 });
-program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('-p, --parallel-id <id>', 'Look up build by parallel ID').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('--public-link', 'Acknowledge that preview URL grants access to anyone with the link (required for private projects)').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
+program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('--public-link', 'Acknowledge that preview URL grants access to anyone with the link (required for private projects)').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
   const globalOptions = program.opts();
 
   // Show helpful error if path is missing

package/dist/client/index.js

@@ -8,16 +8,17 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { dirname, join, parse } from 'node:path';
 import { getBuildId, getServerUrl, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
+import { createScreenshotProperties } from '../utils/screenshot-options.js';
 
 // Internal client state
 let currentClient = null;
 let isDisabled = false;
 
 // Default timeout for screenshot requests (30 seconds)
-const DEFAULT_TIMEOUT_MS = 30000;
+let DEFAULT_TIMEOUT_MS = 30000;
 
 // Log levels for client SDK output control
-export const LOG_LEVELS = {
+export let LOG_LEVELS = {
   debug: 0,
   info: 1,
   warn: 2,
@@ -71,14 +72,14 @@ export function autoDiscoverTddServer(startDir, deps = {}) {
   try {
     // Look for .vizzly/server.json in current directory and parent directories
     let currentDir = startDir || process.cwd();
-    const root = parse(currentDir).root;
+    let root = parse(currentDir).root;
     while (currentDir !== root) {
-      const serverJsonPath = join(currentDir, '.vizzly', 'server.json');
+      let serverJsonPath = join(currentDir, '.vizzly', 'server.json');
       if (exists(serverJsonPath)) {
         try {
-          const serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
+          let serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
           if (serverInfo.port) {
-            const url = `http://localhost:${serverInfo.port}`;
+            let url = `http://localhost:${serverInfo.port}`;
             return url;
           }
         } catch {
@@ -191,14 +192,9 @@ function createSimpleClient(serverUrl) {
         let isFilePath = typeof imageBuffer === 'string';
         let image = isFilePath ? imageBuffer : imageBuffer.toString('base64');
         let type = isFilePath ? 'file-path' : 'base64';
-        let {
-          fullPage,
-          threshold,
-          properties: userProperties,
-          ...rest
-        } = options;
+        let properties = createScreenshotProperties(options);
         let httpStart = Date.now();
-        const {
+        let {
           status,
           json
         } = await httpPost(`${serverUrl}/screenshot`, {
@@ -206,11 +202,7 @@ function createSimpleClient(serverUrl) {
           name,
           image,
           type,
-          properties: {
-            ...rest,
-            ...userProperties
-          },
-          fullPage: fullPage || false
+          properties
         }, DEFAULT_TIMEOUT_MS);
         let httpMs = Date.now() - httpStart;
         if (shouldLogClient('debug')) {
@@ -293,10 +285,11 @@ function createSimpleClient(serverUrl) {
  * @param {Buffer|string} imageBuffer - PNG image data as a Buffer, or a file path to an image
  * @param {Object} [options] - Optional configuration
  * @param {Record<string, any>} [options.properties] - Additional properties to attach to the screenshot
- * @param {number} [options.threshold=0] - Pixel difference threshold (0-100)
- * @param {boolean} [options.fullPage=false] - Whether this is a full page screenshot
+ * @param {number} [options.threshold] - CIEDE2000 Delta E threshold for this screenshot
+ * @param {number} [options.minClusterSize] - Minimum changed cluster size for this screenshot
+ * @param {boolean} [options.fullPage] - Whether this is a full page screenshot
  *
- * @returns {Promise<void>}
+ * @returns {Promise<Object|null>} Screenshot result from the server, or null when capture is skipped
  *
  * @example
  * // Basic usage with Buffer
@@ -319,19 +312,17 @@ function createSimpleClient(serverUrl) {
  *   threshold: 5
  * });
  *
- * @throws {VizzlyError} When screenshot capture fails or client is not initialized
- * @throws {VizzlyError} When file path is provided but file doesn't exist
- * @throws {VizzlyError} When file cannot be read due to permissions or I/O errors
+ * Capture failures are logged and return null so test suites can continue.
  */
 export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
   if (isVizzlyDisabled()) {
-    return; // Silently skip when disabled
+    return null; // Silently skip when disabled
   }
   let client = getClient();
   if (!client) {
     // Silently disable - no server running, nothing to do
     disableVizzly();
-    return;
+    return null;
   }
 
   // Pass through the original value (Buffer or file path)
@@ -342,7 +333,7 @@ export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
 /**
  * Wait for all queued screenshots to be processed
  *
- * @returns {Promise<void>}
+ * @returns {Promise<Object|null>} Flush summary, or null if no server is connected
  *
  * @example
  * afterAll(async () => {
@@ -350,10 +341,11 @@ export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
  * });
  */
 export async function vizzlyFlush() {
-  const client = getClient();
+  let client = getClient();
   if (client) {
     return client.flush();
   }
+  return null;
 }
 
 /**
@@ -401,7 +393,7 @@ export function setEnabled(enabled) {
  * @returns {Object} Client information
  */
 export function getVizzlyInfo() {
-  const client = getClient();
+  let client = getClient();
   return {
     enabled: !isVizzlyDisabled(),
     serverUrl: getServerUrl(),