@vizzly-testing/cli 0.22.1 → 0.23.0

package/dist/api/endpoints.js

@@ -311,4 +311,47 @@ export async function finalizeParallelBuild(client, parallelId) {
       'Content-Type': 'application/json'
     }
   });
+}
+
+// ============================================================================
+// Preview Endpoints
+// ============================================================================
+
+/**
+ * Upload preview ZIP file for a build
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {Buffer} zipBuffer - ZIP file contents
+ * @returns {Promise<Object>} Upload result with preview URL
+ */
+export async function uploadPreviewZip(client, buildId, zipBuffer) {
+  // Create form data with the ZIP file
+  let FormData = (await import('form-data')).default;
+  let formData = new FormData();
+  formData.append('file', zipBuffer, {
+    filename: 'preview.zip',
+    contentType: 'application/zip'
+  });
+  return client.request(`/api/sdk/builds/${buildId}/preview/upload-zip`, {
+    method: 'POST',
+    body: formData,
+    headers: formData.getHeaders()
+  });
+}
+
+/**
+ * Get preview info for a build
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @returns {Promise<Object>} Preview info or null if not found
+ */
+export async function getPreviewInfo(client, buildId) {
+  try {
+    return await client.request(`/api/sdk/builds/${buildId}/preview`);
+  } catch (error) {
+    if (error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
 }

package/dist/api/index.js

@@ -16,4 +16,4 @@ export { createApiClient, DEFAULT_API_URL } from './client.js';
 export { buildApiUrl, buildAuthHeader, buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildRequestHeaders, buildScreenshotCheckObject, buildScreenshotPayload, buildShaCheckPayload, buildUserAgent, computeSha256, extractErrorBody, findScreenshotBySha, isAuthError, isRateLimited, parseApiError, partitionByShaExistence, shaExists, shouldRetryWithRefresh } from './core.js';
 
 // Endpoint functions
-export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuilds, getComparison, getScreenshotHotspots, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadScreenshot } from './endpoints.js';
+export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuilds, getComparison, getPreviewInfo, getScreenshotHotspots, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';

package/dist/cli.js

@@ -6,6 +6,7 @@ import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js
 import { init } from './commands/init.js';
 import { loginCommand, validateLoginOptions } from './commands/login.js';
 import { logoutCommand, validateLogoutOptions } from './commands/logout.js';
+import { previewCommand, validatePreviewOptions } from './commands/preview.js';
 import { projectListCommand, projectRemoveCommand, projectSelectCommand, projectTokenCommand, validateProjectOptions } from './commands/project.js';
 import { runCommand, validateRunOptions } from './commands/run.js';
 import { statusCommand, validateStatusOptions } from './commands/status.js';
@@ -411,6 +412,20 @@ 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').action(async (path, options) => {
+  const globalOptions = program.opts();
+
+  // Validate options
+  const validationErrors = validatePreviewOptions(path, options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await previewCommand(path, options, globalOptions);
+});
 program.command('doctor').description('Run diagnostics to check your environment and configuration').option('--api', 'Include API connectivity checks').action(async options => {
   const globalOptions = program.opts();
 

package/dist/client/index.js

@@ -188,7 +188,9 @@ function createSimpleClient(serverUrl) {
       try {
         // If it's a string, assume it's a file path and send directly
         // Otherwise it's a Buffer, so convert to base64
-        const image = typeof imageBuffer === 'string' ? imageBuffer : imageBuffer.toString('base64');
+        let isFilePath = typeof imageBuffer === 'string';
+        let image = isFilePath ? imageBuffer : imageBuffer.toString('base64');
+        let type = isFilePath ? 'file-path' : 'base64';
         const {
           status,
           json
@@ -196,6 +198,7 @@ function createSimpleClient(serverUrl) {
           buildId: getBuildId(),
           name,
           image,
+          type,
           properties: options,
           fullPage: options.fullPage || false
         }, DEFAULT_TIMEOUT_MS);

package/dist/commands/finalize.js

@@ -6,6 +6,7 @@
 import { createApiClient as defaultCreateApiClient, finalizeParallelBuild as defaultFinalizeParallelBuild } from '../api/index.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
+import { writeSession as defaultWriteSession } from '../utils/session.js';
 
 /**
  * Finalize command implementation
@@ -20,6 +21,7 @@ export async function finalizeCommand(parallelId, options = {}, globalOptions =
     createApiClient = defaultCreateApiClient,
     finalizeParallelBuild = defaultFinalizeParallelBuild,
     output = defaultOutput,
+    writeSession = defaultWriteSession,
     exit = code => process.exit(code)
   } = deps;
   output.configure({
@@ -61,6 +63,14 @@ export async function finalizeCommand(parallelId, options = {}, globalOptions =
     });
     let result = await finalizeParallelBuild(client, parallelId);
     output.stopSpinner();
+
+    // Write session for subsequent commands (like preview)
+    if (result.build?.id) {
+      writeSession({
+        buildId: result.build.id,
+        parallelId
+      });
+    }
     if (globalOptions.json) {
       output.data(result);
     } else {

package/dist/commands/preview.js

@@ -0,0 +1,439 @@
+/**
+ * Preview command implementation
+ *
+ * Uploads static files as a preview for a Vizzly build.
+ * The build is automatically detected from session file or environment.
+ */
+
+import { exec, execSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, statSync } from 'node:fs';
+import { readFile, realpath, stat, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { createApiClient as defaultCreateApiClient, uploadPreviewZip as defaultUploadPreviewZip } from '../api/index.js';
+import { openBrowser as defaultOpenBrowser } from '../utils/browser.js';
+import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
+import { detectBranch as defaultDetectBranch } from '../utils/git.js';
+import * as defaultOutput from '../utils/output.js';
+import { formatSessionAge as defaultFormatSessionAge, readSession as defaultReadSession } from '../utils/session.js';
+let execAsync = promisify(exec);
+
+/**
+ * Validate path for shell safety - prevents command injection
+ * @param {string} path - Path to validate
+ * @returns {boolean} true if path is safe for shell use
+ */
+function isPathSafe(path) {
+  // Reject paths with shell metacharacters that could enable command injection
+  let dangerousChars = /[`$;&|<>(){}[\]\\!*?'"]/;
+  return !dangerousChars.test(path);
+}
+
+/**
+ * Check if a command exists on the system
+ * @param {string} command - Command to check
+ * @returns {boolean}
+ */
+function commandExists(command) {
+  try {
+    let checkCmd = process.platform === 'win32' ? 'where' : 'which';
+    execSync(`${checkCmd} ${command}`, {
+      stdio: 'ignore'
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the appropriate zip command for the current platform
+ * @returns {{ command: string, available: boolean }}
+ */
+function getZipCommand() {
+  // Check for standard zip command (macOS, Linux, Windows with Git Bash)
+  if (commandExists('zip')) {
+    return {
+      command: 'zip',
+      available: true
+    };
+  }
+
+  // Windows: Check for PowerShell Compress-Archive
+  if (process.platform === 'win32') {
+    return {
+      command: 'powershell',
+      available: true
+    };
+  }
+  return {
+    command: null,
+    available: false
+  };
+}
+
+/**
+ * Create a ZIP file from a directory using system commands
+ * @param {string} sourceDir - Directory to zip
+ * @param {string} outputPath - Path for output ZIP file
+ * @returns {Promise<void>}
+ */
+async function createZipWithSystem(sourceDir, outputPath) {
+  let {
+    command,
+    available
+  } = getZipCommand();
+  if (!available) {
+    throw new Error('No zip command found. Please install zip or use PowerShell on Windows.');
+  }
+
+  // Validate paths to prevent command injection
+  // Note: outputPath is internally generated (tmpdir + random), so always safe
+  // sourceDir comes from user input, so we validate it
+  if (!isPathSafe(sourceDir)) {
+    throw new Error('Path contains unsupported characters. Please use a path without special shell characters.');
+  }
+  if (command === 'zip') {
+    // Standard zip command - create ZIP from directory contents
+    // Using cwd option is safe as it's not part of the command string
+    // -r: recursive, -q: quiet
+    await execAsync(`zip -r -q "${outputPath}" .`, {
+      cwd: sourceDir,
+      maxBuffer: 1024 * 1024 * 100 // 100MB buffer
+    });
+  } else if (command === 'powershell') {
+    // Windows PowerShell - use -LiteralPath for safer path handling
+    // Escape single quotes in paths by doubling them
+    let safeSrcDir = sourceDir.replace(/'/g, "''");
+    let safeOutPath = outputPath.replace(/'/g, "''");
+    await execAsync(`powershell -Command "Compress-Archive -LiteralPath '${safeSrcDir}\\*' -DestinationPath '${safeOutPath}' -Force"`, {
+      maxBuffer: 1024 * 1024 * 100
+    });
+  }
+}
+
+/**
+ * Count files in a directory recursively
+ * Skips symlinks to prevent path traversal attacks
+ * @param {string} dir - Directory path
+ * @returns {Promise<{ count: number, totalSize: number }>}
+ */
+async function countFiles(dir) {
+  let {
+    readdir
+  } = await import('node:fs/promises');
+  let count = 0;
+  let totalSize = 0;
+
+  // Resolve the base directory to an absolute path for traversal checks
+  let baseDir = await realpath(resolve(dir));
+  async function walk(currentDir) {
+    let entries = await readdir(currentDir, {
+      withFileTypes: true
+    });
+    for (let entry of entries) {
+      let fullPath = join(currentDir, entry.name);
+
+      // Skip symlinks to prevent traversal attacks
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        // Skip hidden directories and common non-content directories
+        if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === '__pycache__') {
+          continue;
+        }
+
+        // Verify we're still within the base directory (prevent traversal)
+        let realSubDir = await realpath(fullPath);
+        if (!realSubDir.startsWith(baseDir)) {
+          continue;
+        }
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        // Skip hidden files
+        if (entry.name.startsWith('.')) {
+          continue;
+        }
+        count++;
+        let fileStat = await stat(fullPath);
+        totalSize += fileStat.size;
+      }
+    }
+  }
+  await walk(baseDir);
+  return {
+    count,
+    totalSize
+  };
+}
+
+/**
+ * Format bytes for display
+ * @param {number} bytes - Bytes to format
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/**
+ * Preview command implementation
+ * @param {string} path - Path to static files
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ * @param {Object} deps - Dependencies for testing
+ */
+export async function previewCommand(path, options = {}, globalOptions = {}, deps = {}) {
+  let {
+    loadConfig = defaultLoadConfig,
+    createApiClient = defaultCreateApiClient,
+    uploadPreviewZip = defaultUploadPreviewZip,
+    readSession = defaultReadSession,
+    formatSessionAge = defaultFormatSessionAge,
+    detectBranch = defaultDetectBranch,
+    openBrowser = defaultOpenBrowser,
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    // Load configuration
+    let allOptions = {
+      ...globalOptions,
+      ...options
+    };
+    let config = await loadConfig(globalOptions.config, allOptions);
+
+    // Validate API token
+    if (!config.apiKey) {
+      output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+      exit(1);
+      return {
+        success: false,
+        reason: 'no-api-key'
+      };
+    }
+
+    // Validate path exists and is a directory
+    if (!existsSync(path)) {
+      output.error(`Path does not exist: ${path}`);
+      exit(1);
+      return {
+        success: false,
+        reason: 'path-not-found'
+      };
+    }
+    let pathStat = statSync(path);
+    if (!pathStat.isDirectory()) {
+      output.error(`Path is not a directory: ${path}`);
+      exit(1);
+      return {
+        success: false,
+        reason: 'not-a-directory'
+      };
+    }
+
+    // Resolve build ID
+    let buildId = options.build;
+    let buildSource = 'flag';
+    if (!buildId && options.parallelId) {
+      // TODO: Look up build by parallel ID
+      output.error('Parallel ID lookup not yet implemented. Use --build to specify build ID directly.');
+      exit(1);
+      return {
+        success: false,
+        reason: 'parallel-id-not-implemented'
+      };
+    }
+    if (!buildId) {
+      // Try to read from session
+      let currentBranch = await detectBranch();
+      let session = readSession({
+        currentBranch
+      });
+      if (session?.buildId && !session.expired) {
+        if (session.branchMismatch) {
+          output.warn(`Session build is from different branch (${session.branch})`);
+          output.hint(`Use --build to specify a build ID, or run tests on this branch first.`);
+          exit(1);
+          return {
+            success: false,
+            reason: 'branch-mismatch'
+          };
+        }
+        buildId = session.buildId;
+        buildSource = session.source;
+        if (globalOptions.verbose) {
+          output.info(`Using build ${buildId} from ${buildSource} (${formatSessionAge(session.age)})`);
+        }
+      }
+    }
+    if (!buildId) {
+      output.error('No build found');
+      output.blank();
+      output.print('  Run visual tests first, then upload your preview:');
+      output.blank();
+      output.print('    vizzly run "npm test"');
+      output.print('    vizzly preview ./dist');
+      output.blank();
+      output.print('  Or specify a build explicitly:');
+      output.blank();
+      output.print('    vizzly preview ./dist --build <build-id>');
+      output.blank();
+      exit(1);
+      return {
+        success: false,
+        reason: 'no-build'
+      };
+    }
+
+    // Check for zip command availability
+    let zipInfo = getZipCommand();
+    if (!zipInfo.available) {
+      output.error('No zip command found. Please install zip (macOS/Linux) or ensure PowerShell is available (Windows).');
+      exit(1);
+      return {
+        success: false,
+        reason: 'no-zip-command'
+      };
+    }
+
+    // Count files and calculate size
+    output.startSpinner('Scanning files...');
+    let {
+      count: fileCount,
+      totalSize
+    } = await countFiles(path);
+    if (fileCount === 0) {
+      output.stopSpinner();
+      output.error(`No files found in ${path}`);
+      exit(1);
+      return {
+        success: false,
+        reason: 'no-files'
+      };
+    }
+    output.updateSpinner(`Found ${fileCount} files (${formatBytes(totalSize)})`);
+
+    // Create ZIP using system command
+    output.updateSpinner('Compressing files...');
+    // Use timestamp + random bytes for unique temp file (prevents race conditions)
+    let randomSuffix = randomBytes(8).toString('hex');
+    let zipPath = join(tmpdir(), `vizzly-preview-${Date.now()}-${randomSuffix}.zip`);
+    let zipBuffer;
+    try {
+      await createZipWithSystem(path, zipPath);
+      zipBuffer = await readFile(zipPath);
+    } catch (zipError) {
+      output.stopSpinner();
+      output.error(`Failed to create ZIP: ${zipError.message}`);
+      await unlink(zipPath).catch(() => {});
+      exit(1);
+      return {
+        success: false,
+        reason: 'zip-failed',
+        error: zipError
+      };
+    } finally {
+      // Always clean up temp file
+      await unlink(zipPath).catch(() => {});
+    }
+    let compressionRatio = ((1 - zipBuffer.length / totalSize) * 100).toFixed(0);
+    output.updateSpinner(`Compressed to ${formatBytes(zipBuffer.length)} (${compressionRatio}% smaller)`);
+
+    // Upload
+    output.updateSpinner('Uploading preview...');
+    let client = createApiClient({
+      baseUrl: config.apiUrl,
+      token: config.apiKey,
+      command: 'preview'
+    });
+    let result = await uploadPreviewZip(client, buildId, zipBuffer);
+    output.stopSpinner();
+
+    // Success output
+    if (globalOptions.json) {
+      output.data({
+        success: true,
+        buildId,
+        previewUrl: result.previewUrl,
+        files: result.uploaded,
+        totalBytes: result.totalBytes,
+        newBytes: result.newBytes,
+        deduplicationRatio: result.deduplicationRatio
+      });
+    } else {
+      output.complete('Preview uploaded');
+      output.blank();
+      let colors = output.getColors();
+      output.print(`  ${colors.brand.textTertiary('Files')}       ${colors.white(result.uploaded)} (${formatBytes(result.totalBytes)} compressed)`);
+      if (result.reusedBlobs > 0) {
+        let savedBytes = result.totalBytes - result.newBytes;
+        output.print(`  ${colors.brand.textTertiary('Deduped')}     ${colors.green(result.reusedBlobs)} files (saved ${formatBytes(savedBytes)})`);
+      }
+      if (result.basePath) {
+        output.print(`  ${colors.brand.textTertiary('Base path')}   ${colors.dim(result.basePath)}`);
+      }
+      output.blank();
+      output.print(`  ${colors.brand.textTertiary('Preview')}     ${colors.cyan(colors.underline(result.previewUrl))}`);
+
+      // Open in browser if requested
+      if (options.open) {
+        let opened = await openBrowser(result.previewUrl);
+        if (opened) {
+          output.print(`  ${colors.dim('Opened in browser')}`);
+        }
+      }
+    }
+    output.cleanup();
+    return {
+      success: true,
+      result
+    };
+  } catch (error) {
+    output.stopSpinner();
+
+    // Handle specific error types
+    if (error.status === 404) {
+      output.error(`Build not found: ${options.build || 'from session'}`);
+    } else if (error.status === 403) {
+      if (error.message?.includes('Starter')) {
+        output.error('Preview hosting requires Starter plan or above');
+        output.hint('Upgrade your plan at https://app.vizzly.dev/settings/billing');
+      } else {
+        output.error('Access denied', error);
+      }
+    } else {
+      output.error('Preview upload failed', error);
+    }
+    exit(1);
+    return {
+      success: false,
+      error
+    };
+  } finally {
+    output.cleanup();
+  }
+}
+
+/**
+ * Validate preview options
+ * @param {string} path - Path to static files
+ * @param {Object} options - Command options
+ */
+export function validatePreviewOptions(path, _options) {
+  let errors = [];
+  if (!path || path.trim() === '') {
+    errors.push('Path to static files is required');
+  }
+  return errors;
+}

package/dist/commands/run.js

@@ -13,6 +13,7 @@ import { finalizeBuild as defaultFinalizeBuild, runTests as defaultRunTests } fr
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
+import { writeSession as defaultWriteSession } from '../utils/session.js';
 
 /**
  * Run command implementation
@@ -41,6 +42,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
     generateBuildNameWithGit = defaultGenerateBuildNameWithGit,
     spawn = defaultSpawn,
     output = defaultOutput,
+    writeSession = defaultWriteSession,
     exit = code => process.exit(code),
     processOn = (event, handler) => process.on(event, handler),
     processRemoveListener = (event, handler) => process.removeListener(event, handler)
@@ -239,6 +241,14 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
           onBuildCreated: data => {
             buildUrl = data.url;
             buildId = data.buildId;
+
+            // Write session for subsequent commands (like preview)
+            writeSession({
+              buildId: data.buildId,
+              branch,
+              commit,
+              parallelId: runOptions.parallelId
+            });
             if (globalOptions.verbose) {
               output.info(`Build created: ${data.buildId}`);
             }

package/dist/commands/status.js

@@ -3,7 +3,7 @@
  * Uses functional API operations directly
  */
 
-import { createApiClient, getBuild } from '../api/index.js';
+import { createApiClient, getBuild, getPreviewInfo } from '../api/index.js';
 import { loadConfig } from '../utils/config-loader.js';
 import { getApiUrl } from '../utils/environment-config.js';
 import * as output from '../utils/output.js';
@@ -42,6 +42,9 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}) {
       command: 'status'
     });
     let buildStatus = await getBuild(client, buildId);
+
+    // Also fetch preview info (if exists)
+    let previewInfo = await getPreviewInfo(client, buildId);
     output.stopSpinner();
 
     // Extract build data from API response
@@ -68,7 +71,13 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}) {
         approvalStatus: build.approval_status,
         executionTime: build.execution_time_ms,
         isBaseline: build.is_baseline,
-        userAgent: build.user_agent
+        userAgent: build.user_agent,
+        preview: previewInfo ? {
+          url: previewInfo.preview_url,
+          status: previewInfo.status,
+          fileCount: previewInfo.file_count,
+          expiresAt: previewInfo.expires_at
+        } : null
       };
       output.data(statusData);
       output.cleanup();
@@ -139,6 +148,15 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}) {
       output.labelValue('View', output.link('Build', buildUrl));
     }
 
+    // Show preview URL if available
+    if (previewInfo?.preview_url) {
+      output.labelValue('Preview', output.link('Preview', previewInfo.preview_url));
+      if (previewInfo.expires_at) {
+        let expiresDate = new Date(previewInfo.expires_at);
+        output.hint(`Preview expires ${expiresDate.toLocaleDateString()}`);
+      }
+    }
+
     // Show additional info in verbose mode
     if (globalOptions.verbose) {
       output.blank();

package/dist/commands/upload.js

@@ -3,6 +3,7 @@ import { createUploader as defaultCreateUploader } from '../services/uploader.js
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
+import { writeSession as defaultWriteSession } from '../utils/session.js';
 
 /**
  * Construct proper build URL with org/project context
@@ -60,6 +61,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     detectPullRequestNumber = defaultDetectPullRequestNumber,
     generateBuildNameWithGit = defaultGenerateBuildNameWithGit,
     output = defaultOutput,
+    writeSession = defaultWriteSession,
     exit = code => process.exit(code),
     buildUrlConstructor = constructBuildUrl
   } = deps;
@@ -158,6 +160,16 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     const result = await uploader.upload(uploadOptions);
     buildId = result.buildId; // Ensure we have the buildId
 
+    // Write session for subsequent commands (like preview)
+    if (buildId) {
+      writeSession({
+        buildId,
+        branch,
+        commit,
+        parallelId: config.parallelId
+      });
+    }
+
     // Mark build as completed
     if (result.buildId) {
       output.progress('Finalizing build...');

package/dist/sdk/index.js

@@ -247,6 +247,7 @@ export class VizzlySDK extends EventEmitter {
       buildId,
       name,
       image: imageBase64,
+      type: 'base64',
       properties: options.properties || {}
     };
 

package/dist/server/handlers/api-handler.js

@@ -47,7 +47,7 @@ export const createApiHandler = (client, {
   let vizzlyDisabled = false;
   let screenshotCount = 0;
   let uploadPromises = [];
-  const handleScreenshot = async (buildId, name, image, properties = {}) => {
+  const handleScreenshot = async (buildId, name, image, properties = {}, type) => {
     if (vizzlyDisabled) {
       output.debug('upload', `${name} (disabled)`);
       return {
@@ -73,8 +73,11 @@ export const createApiHandler = (client, {
     }
 
     // Support both base64 encoded images and file paths
+    // Use explicit type from client if provided (fast path), otherwise detect (slow path)
+    // Only accept valid type values to prevent invalid types from bypassing detection
     let imageBuffer;
-    const inputType = detectImageInputType(image);
+    let validTypes = ['base64', 'file-path'];
+    const inputType = type && validTypes.includes(type) ? type : detectImageInputType(image);
     if (inputType === 'file-path') {
       // It's a file path - resolve and read the file
       const filePath = resolve(image.replace('file://', ''));

package/dist/server/handlers/tdd-handler.js

@@ -267,7 +267,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       output.debug('tdd', `baseline: ${baseline.buildName}`);
     }
   };
-  const handleScreenshot = async (_buildId, name, image, properties = {}) => {
+  const handleScreenshot = async (_buildId, name, image, properties = {}, type) => {
     // Validate and sanitize screenshot name
     let sanitizedName;
     try {
@@ -306,8 +306,11 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
 
     // Support both base64 encoded images and file paths
     // Vitest browser mode returns file paths, so we need to handle both
+    // Use explicit type from client if provided (fast path), otherwise detect (slow path)
+    // Only accept valid type values to prevent invalid types from bypassing detection
     let imageBuffer;
-    const inputType = detectImageInputType(image);
+    let validTypes = ['base64', 'file-path'];
+    const inputType = type && validTypes.includes(type) ? type : detectImageInputType(image);
     if (inputType === 'file-path') {
       // It's a file path - resolve and read the file
       const filePath = resolve(image.replace('file://', ''));

package/dist/server/routers/screenshot.js

@@ -31,7 +31,8 @@ export function createScreenshotRouter({
           buildId,
           name,
           properties,
-          image
+          image,
+          type
         } = body;
         if (!name || !image) {
           sendError(res, 400, 'name and image are required');
@@ -40,7 +41,7 @@ export function createScreenshotRouter({
 
         // Use buildId from request body, or fall back to server's buildId
         const effectiveBuildId = buildId || defaultBuildId;
-        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, properties);
+        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, properties, type);
         sendJson(res, result.statusCode, result.body);
         return true;
       } catch (error) {

package/dist/utils/image-input-detector.js

@@ -81,41 +81,46 @@ export function looksLikeFilePath(str) {
     return false;
   }
 
-  // 0. Explicitly reject data URIs first (they contain : and / which would match path patterns)
+  // 0. Length check - file paths are short, base64 screenshots are huge
+  // Even the longest realistic file path is < 500 chars
+  // This makes detection O(1) for large base64 strings
+  // Use same threshold (1000) as detectImageInputType for consistency
+  if (str.length > 1000) {
+    return false;
+  }
+
+  // 1. Explicitly reject data URIs (they contain : and / which would match path patterns)
   if (str.startsWith('data:')) {
     return false;
   }
 
-  // 1. Check for file:// URI scheme
+  // 2. Check for file:// URI scheme
   if (str.startsWith('file://')) {
     return true;
   }
 
-  // 2. Check for absolute paths (Unix or Windows)
-  // Unix: starts with /
-  // Windows: starts with drive letter like C:\ or C:/
-  if (str.startsWith('/') || /^[A-Za-z]:[/\\]/.test(str)) {
+  // 3. Windows absolute paths (C:\ or C:/) - base64 never starts with drive letter
+  if (/^[A-Za-z]:[/\\]/.test(str)) {
     return true;
   }
 
-  // 3. Check for relative path indicators
-  // ./ or ../ or .\ or ..\
+  // 4. Relative path indicators (./ or ../) - base64 never starts with dot
   if (/^\.\.?[/\\]/.test(str)) {
     return true;
   }
 
-  // 4. Check for path separators (forward or back slash)
-  // This catches paths like: subdirectory/file.png or subdirectory\file.png
-  if (/[/\\]/.test(str)) {
-    return true;
-  }
-
   // 5. Check for common image file extensions
-  // This catches simple filenames like: screenshot.png
-  // Common extensions: png, jpg, jpeg, gif, webp, bmp, svg, tiff, ico
+  // This is the safest check - base64 never ends with .png/.jpg/etc
+  // Catches: /path/file.png, subdir/file.png, file.png
   if (/\.(png|jpe?g|gif|webp|bmp|svg|tiff?|ico)$/i.test(str)) {
     return true;
   }
+
+  // Note: We intentionally don't check for bare "/" prefix or "/" anywhere
+  // because JPEG base64 starts with "/9j/" which would false-positive
+  // File paths without extensions are rare for images and will fall through
+  // to base64 detection, which is acceptable for backwards compat
+
   return false;
 }
 
@@ -127,14 +132,13 @@ export function looksLikeFilePath(str) {
  * - 'file-path': A file path (relative or absolute)
  * - 'unknown': Cannot determine (ambiguous or invalid)
  *
- * Strategy:
- * 1. First check if it's valid base64 (can contain / which might look like paths)
- * 2. Then check if it looks like a file path (more specific patterns)
- * 3. Otherwise return 'unknown'
+ * Strategy (optimized for performance):
+ * 1. Check for data URI prefix first (O(1), definitive)
+ * 2. Check file path patterns (O(1) prefix/suffix checks)
+ * 3. For large non-path strings, assume base64 (skip expensive validation)
+ * 4. Only run full base64 validation on small ambiguous strings
  *
- * This order prevents base64 strings (which can contain /) from being
- * misidentified as file paths. Base64 validation is stricter and should
- * be checked first.
+ * This avoids O(n) regex validation on large screenshot buffers.
  *
  * @param {string} str - String to detect
  * @returns {'base64' | 'file-path' | 'unknown'} Detected input type
@@ -151,15 +155,26 @@ export function detectImageInputType(str) {
     return 'unknown';
   }
 
-  // Check base64 FIRST - base64 strings can contain / which looks like paths
-  // Base64 validation is stricter and more deterministic
-  if (isBase64(str)) {
+  // 1. Data URIs are definitively base64 (O(1) check)
+  if (str.startsWith('data:')) {
     return 'base64';
   }
 
-  // Then check file path - catch patterns that aren't valid base64
+  // 2. Check file path patterns (O(1) prefix/suffix checks)
   if (looksLikeFilePath(str)) {
     return 'file-path';
   }
+
+  // 3. For large strings that aren't file paths, assume base64
+  // Screenshots are typically 100KB+ as base64, file paths are <1KB
+  // Skip expensive O(n) validation for large strings
+  if (str.length > 1000) {
+    return 'base64';
+  }
+
+  // 4. Full validation only for small ambiguous strings
+  if (isBase64(str)) {
+    return 'base64';
+  }
   return 'unknown';
 }

package/dist/utils/session.js

@@ -0,0 +1,185 @@
+/**
+ * Session management for build context
+ *
+ * Tracks the current build ID so subsequent commands (like `vizzly preview`)
+ * can automatically attach to the right build without passing IDs around.
+ *
+ * Two mechanisms:
+ * 1. Session file (.vizzly/session.json) - for local dev and same CI job
+ * 2. GitHub Actions env ($GITHUB_ENV) - for cross-step persistence in GHA
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+let SESSION_DIR = '.vizzly';
+let SESSION_FILE = 'session.json';
+let SESSION_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Get the session file path
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @returns {string} Path to session file
+ */
+export function getSessionPath(cwd = process.cwd()) {
+  return join(cwd, SESSION_DIR, SESSION_FILE);
+}
+
+/**
+ * Write build context to session file and GitHub Actions env
+ *
+ * @param {Object} context - Build context
+ * @param {string} context.buildId - The build ID
+ * @param {string} [context.branch] - Git branch
+ * @param {string} [context.commit] - Git commit SHA
+ * @param {string} [context.parallelId] - Parallel build ID
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory
+ * @param {Object} [options.env] - Environment variables (defaults to process.env)
+ */
+export function writeSession(context, options = {}) {
+  let {
+    cwd = process.cwd(),
+    env = process.env
+  } = options;
+  let session = {
+    buildId: context.buildId,
+    branch: context.branch || null,
+    commit: context.commit || null,
+    parallelId: context.parallelId || null,
+    createdAt: new Date().toISOString()
+  };
+
+  // Write session file
+  let sessionPath = getSessionPath(cwd);
+  let sessionDir = dirname(sessionPath);
+  if (!existsSync(sessionDir)) {
+    mkdirSync(sessionDir, {
+      recursive: true
+    });
+  }
+  writeFileSync(sessionPath, `${JSON.stringify(session, null, 2)}\n`, {
+    mode: 0o600
+  });
+
+  // Write to GitHub Actions environment
+  if (env.GITHUB_ENV) {
+    appendFileSync(env.GITHUB_ENV, `VIZZLY_BUILD_ID=${context.buildId}\n`);
+  }
+
+  // Also write to GitHub Actions output if we're in a step
+  if (env.GITHUB_OUTPUT) {
+    appendFileSync(env.GITHUB_OUTPUT, `build-id=${context.buildId}\n`);
+  }
+}
+
+/**
+ * Read build context from session file or environment
+ *
+ * Priority:
+ * 1. VIZZLY_BUILD_ID environment variable
+ * 2. Session file (if recent and optionally matching branch)
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory
+ * @param {string} [options.currentBranch] - Current git branch (for validation)
+ * @param {Object} [options.env] - Environment variables
+ * @param {number} [options.maxAgeMs] - Max session age in ms
+ * @returns {Object|null} Session context or null if not found/invalid
+ */
+export function readSession(options = {}) {
+  let {
+    cwd = process.cwd(),
+    currentBranch = null,
+    env = process.env,
+    maxAgeMs = SESSION_MAX_AGE_MS
+  } = options;
+
+  // Check environment variable first
+  if (env.VIZZLY_BUILD_ID) {
+    return {
+      buildId: env.VIZZLY_BUILD_ID,
+      source: 'environment'
+    };
+  }
+
+  // Try session file
+  let sessionPath = getSessionPath(cwd);
+  if (!existsSync(sessionPath)) {
+    return null;
+  }
+  try {
+    let content = readFileSync(sessionPath, 'utf-8');
+    let session = JSON.parse(content);
+
+    // Validate required field
+    if (!session.buildId) {
+      return null;
+    }
+
+    // Check age
+    let createdAt = new Date(session.createdAt);
+    let age = Date.now() - createdAt.getTime();
+    if (age > maxAgeMs) {
+      return {
+        ...session,
+        source: 'session_file',
+        expired: true,
+        age
+      };
+    }
+
+    // Check branch match (if current branch provided)
+    let branchMismatch = false;
+    if (currentBranch && session.branch && session.branch !== currentBranch) {
+      branchMismatch = true;
+    }
+    return {
+      ...session,
+      source: 'session_file',
+      expired: false,
+      branchMismatch,
+      age
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clear the session file
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory
+ */
+export function clearSession(options = {}) {
+  let {
+    cwd = process.cwd()
+  } = options;
+  let sessionPath = getSessionPath(cwd);
+  try {
+    if (existsSync(sessionPath)) {
+      writeFileSync(sessionPath, '');
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Format session age for display
+ *
+ * @param {number} ageMs - Age in milliseconds
+ * @returns {string} Human-readable age
+ */
+export function formatSessionAge(ageMs) {
+  let seconds = Math.floor(ageMs / 1000);
+  let minutes = Math.floor(seconds / 60);
+  let hours = Math.floor(minutes / 60);
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m ago`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ago`;
+  }
+  return `${seconds}s ago`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -88,7 +88,6 @@
   },
   "dependencies": {
     "@vizzly-testing/honeydiff": "^0.8.0",
-    "@vizzly-testing/static-site": "^0.0.11",
     "ansis": "^4.2.0",
     "commander": "^14.0.0",
     "cosmiconfig": "^9.0.0",