@vizzly-testing/cli 0.35.3-beta.3 → 0.35.3-beta.4

package/README.md

@@ -153,10 +153,9 @@ test('homepage looks correct', async ({ page }) => {
 
 `properties` is your metadata bag for baseline grouping, filtering, and
 debugging. SDK options such as `threshold`, `minClusterSize`, `fullPage`,
-`requestTimeout`, and `buildId` stay at the top level. If one of those reserved
-SDK options is accidentally placed inside `properties`, Vizzly removes it from
-metadata, applies it as an option when possible, and warns so the call site can
-be cleaned up.
+`requestTimeout`, and `buildId` stay at the top level. Reserved SDK and capture
+fields inside `properties` are ignored and produce a warning; they are never
+interpreted as options or stored as user metadata.
 
 The client SDK is lightweight. It posts screenshots to the local Vizzly server
 or the cloud build wrapper. It works with any test runner.

package/dist/api/core.js

@@ -7,6 +7,7 @@
 
 import crypto from 'node:crypto';
 import { URLSearchParams } from 'node:url';
+import { createScreenshotProperties, getScreenshotOptionsPayload } from '../utils/screenshot-options.js';
 
 // ============================================================================
 // Header Building
@@ -77,11 +78,14 @@ export function buildRequestHeaders({
  * @param {string|null} sha256 - Pre-computed SHA256 hash (optional)
  * @returns {Object} Screenshot upload payload
  */
-export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = null) {
+export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = null, screenshotOptions = {}) {
   let payload = {
     name,
-    properties: metadata ?? {}
+    properties: createScreenshotProperties({
+      properties: metadata
+    })
   };
+  Object.assign(payload, getScreenshotOptionsPayload(screenshotOptions));
   if (buffer) {
     payload.image_data = buffer.toString('base64');
   }
@@ -98,8 +102,8 @@ export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = nul
  * @param {string} sha256 - Pre-computed SHA256 hash
  * @returns {Object} Screenshot resolution payload
  */
-export function buildScreenshotResolvePayload(name, metadata = {}, sha256) {
-  return buildScreenshotPayload(name, null, metadata, sha256);
+export function buildScreenshotResolvePayload(name, metadata = {}, sha256, screenshotOptions = {}) {
+  return buildScreenshotPayload(name, null, metadata, sha256, screenshotOptions);
 }
 
 /**
@@ -180,13 +184,16 @@ export function buildShaCheckPayload(screenshots, buildId) {
  */
 export function buildScreenshotCheckObject(sha256, name, metadata = {}) {
   let meta = metadata || {};
+  let properties = createScreenshotProperties({
+    properties: meta
+  });
   return {
     sha256,
     name,
     browser: meta.browser || 'chrome',
     viewport_width: meta.viewport?.width || meta.viewport_width || 1920,
     viewport_height: meta.viewport?.height || meta.viewport_height || 1080,
-    properties: meta
+    properties
   };
 }
 

package/dist/api/endpoints.js

@@ -179,10 +179,10 @@ function canUploadBytesAfterShaResolveError(error) {
  * @param {boolean} skipDedup - Skip SHA deduplication (uploadAll mode)
  * @returns {Promise<Object>} Upload result
  */
-export async function uploadScreenshot(client, buildId, name, buffer, metadata = {}, skipDedup = false) {
+export async function uploadScreenshot(client, buildId, name, buffer, metadata = {}, skipDedup = false, screenshotOptions = {}) {
   // Skip SHA deduplication if requested
   if (skipDedup) {
-    let payload = buildScreenshotPayload(name, buffer, metadata);
+    let payload = buildScreenshotPayload(name, buffer, metadata, null, screenshotOptions);
     return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
       method: 'POST',
       headers: {
@@ -194,7 +194,7 @@ export async function uploadScreenshot(client, buildId, name, buffer, metadata =
 
   // Normal flow with server-side SHA resolution.
   let sha256 = computeSha256(buffer);
-  let resolvePayload = buildScreenshotResolvePayload(name, metadata, sha256);
+  let resolvePayload = buildScreenshotResolvePayload(name, metadata, sha256, screenshotOptions);
   try {
     let resolveResult = await client.request(`/api/sdk/builds/${buildId}/screenshots`, {
       method: 'POST',
@@ -222,7 +222,7 @@ export async function uploadScreenshot(client, buildId, name, buffer, metadata =
   }
 
   // File doesn't exist, or resolve failed; proceed with upload.
-  let payload = buildScreenshotPayload(name, buffer, metadata, sha256);
+  let payload = buildScreenshotPayload(name, buffer, metadata, sha256, screenshotOptions);
   return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
     method: 'POST',
     headers: {

package/dist/client/index.js

@@ -8,7 +8,7 @@ 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 { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
+import { getScreenshotOptionsPayload, normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 // Internal client state
 let currentClient = null;
@@ -219,6 +219,7 @@ function createSimpleClient(serverUrl, clientOptions = {}) {
           type,
           properties: normalizedOptions.properties
         };
+        Object.assign(screenshotData, getScreenshotOptionsPayload(normalizedOptions));
         if (normalizedOptions.warnings.length > 0) {
           screenshotData.warnings = normalizedOptions.warnings;
         }

package/dist/screenshot-server/core.js

@@ -4,6 +4,8 @@
  * No I/O, no side effects - just data transformations.
  */
 
+import { getScreenshotOptionsPayload } from '../utils/screenshot-options.js';
+
 // ============================================================================
 // Request Validation
 // ============================================================================
@@ -149,9 +151,11 @@ export function buildServerStoppedMessage() {
  * @returns {{ name: string, image: string, properties?: Object }}
  */
 export function extractScreenshotData(body) {
-  return {
+  let screenshotData = {
     name: body.name,
     image: body.image,
     properties: body.properties
   };
+  Object.assign(screenshotData, getScreenshotOptionsPayload(body));
+  return screenshotData;
 }

package/dist/sdk/index.js

@@ -19,7 +19,7 @@ import { createUploader } from '../uploader/index.js';
 import { loadConfig } from '../utils/config-loader.js';
 import { resolveImageBuffer } from '../utils/file-helpers.js';
 import * as output from '../utils/output.js';
-import { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
+import { getScreenshotOptionsPayload, normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 /**
  * Create a new Vizzly instance with custom configuration
@@ -314,6 +314,7 @@ export class VizzlySDK extends EventEmitter {
       type: 'base64',
       properties: normalizedOptions.properties
     };
+    Object.assign(screenshotData, getScreenshotOptionsPayload(normalizedOptions));
     if (normalizedOptions.warnings.length > 0) {
       screenshotData.warnings = normalizedOptions.warnings;
     }

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

@@ -4,6 +4,7 @@ import { resolve } from 'node:path';
 import { uploadScreenshot as defaultUploadScreenshot } from '../../api/index.js';
 import { detectImageInputType } from '../../utils/image-input-detector.js';
 import * as output from '../../utils/output.js';
+import { normalizeScreenshotOptions } from '../../utils/screenshot-options.js';
 
 /**
  * API Handler - Non-blocking screenshot upload
@@ -47,8 +48,23 @@ export const createApiHandler = (client, {
   let vizzlyDisabled = false;
   let screenshotCount = 0;
   let uploadPromises = [];
-  const handleScreenshot = async (buildId, name, image, properties = {}, type, warnings = []) => {
+  const handleScreenshot = async (buildId, name, image, properties = {}, type, warnings = [], screenshotOptions = {}) => {
     let handlerStart = Date.now();
+    let normalizedOptions = normalizeScreenshotOptions({
+      ...screenshotOptions,
+      properties
+    });
+    properties = normalizedOptions.properties;
+    screenshotOptions = {
+      ...screenshotOptions,
+      threshold: normalizedOptions.threshold,
+      minClusterSize: normalizedOptions.minClusterSize,
+      fullPage: normalizedOptions.fullPage,
+      captureMode: normalizedOptions.captureMode,
+      deviceScaleFactor: normalizedOptions.deviceScaleFactor,
+      selector: normalizedOptions.selector
+    };
+    warnings = [...(warnings || []), ...normalizedOptions.warnings];
     output.debug('upload', `${name} received`, {
       buildId: buildId?.slice(0, 8)
     });
@@ -131,7 +147,7 @@ export const createApiHandler = (client, {
     let uploadStart = Date.now();
 
     // Fire upload in background - DON'T AWAIT!
-    let uploadPromise = uploadScreenshot(client, buildId, name, imageBuffer, properties ?? {}).then(result => {
+    let uploadPromise = uploadScreenshot(client, buildId, name, imageBuffer, properties ?? {}, false, screenshotOptions).then(result => {
       let duration = Date.now() - uploadStart;
       if (!result.skipped) {
         output.debug('upload', `${name} completed`, {

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

@@ -5,6 +5,7 @@ import { getDimensionsSync as defaultGetDimensionsSync } from '@vizzly-testing/h
 import { TddService as DefaultTddService } from '../../tdd/tdd-service.js';
 import { detectImageInputType as defaultDetectImageInputType } from '../../utils/image-input-detector.js';
 import * as defaultOutput from '../../utils/output.js';
+import { normalizeScreenshotOptions } from '../../utils/screenshot-options.js';
 import { safePath as defaultSafePath, sanitizeScreenshotName as defaultSanitizeScreenshotName, validateScreenshotProperties as defaultValidateScreenshotProperties } from '../../utils/security.js';
 
 /**
@@ -305,7 +306,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       output.debug('tdd', `baseline: ${baseline.buildName}`);
     }
   };
-  const handleScreenshot = async (_buildId, name, image, properties = {}, type, warnings = []) => {
+  const handleScreenshot = async (_buildId, name, image, properties = {}, type, warnings = [], screenshotOptions = {}) => {
     let handlerStart = Date.now();
     output.debug('tdd', `${name} received`);
 
@@ -324,13 +325,18 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       };
     }
 
-    // Unwrap double-nested properties if needed (client SDK wraps options in properties field)
+    // Preserve the old nested wrapper for older clients, then filter user
+    // properties before local comparison/report serialization.
     let unwrappedProperties = unwrapProperties(properties);
+    let normalizedProperties = normalizeScreenshotOptions({
+      properties: unwrappedProperties
+    });
+    warnings = [...(warnings || []), ...normalizedProperties.warnings];
 
     // Validate and sanitize properties
     let validatedProperties;
     try {
-      validatedProperties = validateScreenshotProperties(unwrappedProperties);
+      validatedProperties = validateScreenshotProperties(normalizedProperties.properties);
     } catch (error) {
       return {
         statusCode: 400,
@@ -419,7 +425,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
 
     // Use the sanitized name as-is (no modification with browser/viewport)
     // Baseline matching uses signature logic (name + viewport_width + browser)
-    const comparison = await tddService.compareScreenshot(sanitizedName, imageBuffer, extractedProperties);
+    const comparison = await tddService.compareScreenshot(sanitizedName, imageBuffer, extractedProperties, screenshotOptions);
 
     // Comparison tracked by tdd.js event handler
 

package/dist/server/routers/screenshot.js

@@ -4,6 +4,7 @@
  */
 
 import * as output from '../../utils/output.js';
+import { normalizeScreenshotOptions } from '../../utils/screenshot-options.js';
 import { parseJsonBody } from '../middleware/json-parser.js';
 import { sendError, sendJson } from '../middleware/response.js';
 
@@ -33,7 +34,13 @@ export function createScreenshotRouter({
           properties,
           image,
           type,
-          warnings
+          warnings,
+          threshold,
+          minClusterSize,
+          fullPage,
+          captureMode,
+          deviceScaleFactor,
+          selector
         } = body;
         if (!name || !image) {
           sendError(res, 400, 'name and image are required');
@@ -42,7 +49,23 @@ 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, type, warnings);
+        const normalizedOptions = normalizeScreenshotOptions({
+          properties,
+          threshold,
+          minClusterSize,
+          fullPage,
+          captureMode,
+          deviceScaleFactor,
+          selector
+        });
+        const result = await screenshotHandler.handleScreenshot(effectiveBuildId, name, image, normalizedOptions.properties, type, [...(warnings || []), ...normalizedOptions.warnings], {
+          threshold: normalizedOptions.threshold,
+          minClusterSize: normalizedOptions.minClusterSize,
+          fullPage: normalizedOptions.fullPage,
+          captureMode: normalizedOptions.captureMode,
+          deviceScaleFactor: normalizedOptions.deviceScaleFactor,
+          selector: normalizedOptions.selector
+        });
         sendJson(res, result.statusCode, result.body);
         return true;
       } catch (error) {

package/dist/tdd/tdd-service.js

@@ -752,7 +752,7 @@ export class TddService {
   /**
    * Compare a screenshot against baseline
    */
-  async compareScreenshot(name, imageBuffer, properties = {}) {
+  async compareScreenshot(name, imageBuffer, properties = {}, screenshotOptions = {}) {
     // Destructure dependencies
     let {
       output,
@@ -850,8 +850,8 @@ export class TddService {
     }
 
     // Baseline exists - compare
-    let effectiveThreshold = typeof validatedProperties.threshold === 'number' && validatedProperties.threshold >= 0 ? validatedProperties.threshold : this.threshold;
-    let effectiveMinClusterSize = Number.isInteger(validatedProperties.minClusterSize) && validatedProperties.minClusterSize >= 1 ? validatedProperties.minClusterSize : this.minClusterSize;
+    let effectiveThreshold = typeof screenshotOptions.threshold === 'number' && screenshotOptions.threshold >= 0 ? screenshotOptions.threshold : this.threshold;
+    let effectiveMinClusterSize = Number.isInteger(screenshotOptions.minClusterSize) && screenshotOptions.minClusterSize >= 1 ? screenshotOptions.minClusterSize : this.minClusterSize;
     try {
       let honeydiffResult = await compareImages(baselineImagePath, currentImagePath, diffImagePath, {
         threshold: effectiveThreshold,

package/dist/types/index.d.ts

@@ -401,7 +401,11 @@ export interface TddService {
   compareScreenshot(
     name: string,
     imageBuffer: Buffer,
-    properties?: Record<string, unknown>
+    properties?: Record<string, unknown>,
+    screenshotOptions?: Pick<
+      ScreenshotOptions,
+      'threshold' | 'minClusterSize' | 'fullPage'
+    >
   ): Promise<ComparisonResult>;
 
   getResults(): TddResults;

package/dist/utils/screenshot-options.js

@@ -9,16 +9,62 @@ export let RESERVED_PROPERTY_OPTIONS = Object.freeze({
   minClusterSize: {
     message: 'Move "minClusterSize" out of properties; properties is only for user metadata.'
   },
+  min_cluster_size: {
+    message: 'Move "min_cluster_size" out of properties; properties is only for user metadata.'
+  },
   fullPage: {
     message: 'Move "fullPage" out of properties; properties is only for user metadata.'
   },
+  full_page: {
+    message: 'Move "full_page" out of properties; properties is only for user metadata.'
+  },
+  captureMode: {
+    message: 'Move "captureMode" out of properties; properties is only for user metadata.'
+  },
+  capture_mode: {
+    message: 'Move "capture_mode" out of properties; properties is only for user metadata.'
+  },
+  deviceScaleFactor: {
+    message: 'Move "deviceScaleFactor" out of properties; properties is only for user metadata.'
+  },
+  device_scale_factor: {
+    message: 'Move "device_scale_factor" out of properties; properties is only for user metadata.'
+  },
+  pixelRatio: {
+    message: 'Move "pixelRatio" out of properties; properties is only for user metadata.'
+  },
+  dpr: {
+    message: 'Move "dpr" out of properties; properties is only for user metadata.'
+  },
+  selector: {
+    message: 'Move "selector" out of properties; properties is only for user metadata.'
+  },
+  component: {
+    message: 'Move "component" out of properties; properties is only for user metadata.'
+  },
+  elementSelector: {
+    message: 'Move "elementSelector" out of properties; properties is only for user metadata.'
+  },
+  element_selector: {
+    message: 'Move "element_selector" out of properties; properties is only for user metadata.'
+  },
   buildId: {
     message: 'Move "buildId" out of properties; properties is only for user metadata.'
   },
+  build_id: {
+    message: 'Move "build_id" out of properties; properties is only for user metadata.'
+  },
   requestTimeout: {
     message: 'Move "requestTimeout" out of properties; properties is only for user metadata.'
+  },
+  request_timeout: {
+    message: 'Move "request_timeout" out of properties; properties is only for user metadata.'
   }
 });
+export let SCREENSHOT_OPTION_NAMES = Object.freeze(['threshold', 'minClusterSize', 'fullPage', 'captureMode', 'deviceScaleFactor', 'selector']);
+export function getScreenshotOptionsPayload(options = {}) {
+  return Object.fromEntries(SCREENSHOT_OPTION_NAMES.filter(option => options[option] !== undefined).map(option => [option, options[option]]));
+}
 function createReservedPropertyWarning(option) {
   return {
     code: 'reserved-property-option',
@@ -28,8 +74,9 @@ function createReservedPropertyWarning(option) {
 }
 
 /**
- * Normalize screenshot SDK options into the properties payload consumed by the
- * local TDD server and cloud-compatible comparison path.
+ * Normalize screenshot SDK options into the local and cloud upload payload.
+ * Reserved names found inside properties are discarded instead of being promoted
+ * into options.
  */
 export function normalizeScreenshotOptions(options = {}) {
   let {
@@ -38,38 +85,30 @@ export function normalizeScreenshotOptions(options = {}) {
     requestTimeout,
     threshold,
     minClusterSize,
-    fullPage
+    fullPage,
+    captureMode,
+    deviceScaleFactor,
+    selector
   } = options;
   let warnings = [];
   let normalizedProperties = {};
-  for (let [key, value] of Object.entries(properties || {})) {
+  let sourceProperties = properties && typeof properties === 'object' && !Array.isArray(properties) ? properties : {};
+  for (let [key, value] of Object.entries(sourceProperties)) {
     if (RESERVED_PROPERTY_OPTIONS[key]) {
       warnings.push(createReservedPropertyWarning(key));
-      if (key === 'threshold' && threshold === undefined) threshold = value;
-      if (key === 'minClusterSize' && minClusterSize === undefined) {
-        minClusterSize = value;
-      }
-      if (key === 'fullPage' && fullPage === undefined) fullPage = value;
-      if (key === 'buildId' && buildId === undefined) buildId = value;
-      if (key === 'requestTimeout' && requestTimeout === undefined) {
-        requestTimeout = value;
-      }
       continue;
     }
     normalizedProperties[key] = value;
   }
-  if (threshold !== undefined) {
-    normalizedProperties.threshold = threshold;
-  }
-  if (minClusterSize !== undefined) {
-    normalizedProperties.minClusterSize = minClusterSize;
-  }
-  if (fullPage !== undefined) {
-    normalizedProperties.fullPage = fullPage;
-  }
   return {
     buildId,
     requestTimeout,
+    threshold,
+    minClusterSize,
+    fullPage,
+    captureMode,
+    deviceScaleFactor,
+    selector,
     properties: normalizedProperties,
     warnings
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.35.3-beta.3",
+  "version": "0.35.3-beta.4",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",