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

package/dist/types/client.d.ts

@@ -33,6 +33,8 @@ export function autoDiscoverTddServer(
  */
 export interface ScreenshotResult {
   success: boolean;
+  /** Cloud capture accepted locally; upload completion is reported by flush. */
+  queued?: boolean;
   status?:
     | 'passed'
     | 'failed'
@@ -67,16 +69,17 @@ export interface ScreenshotResult {
  * @example
  * // With properties and comparison settings
  * await vizzlyScreenshot('checkout-form', screenshot, {
- *   properties: { browser: 'chrome', viewport: { width: 1920, height: 1080 } },
+ *   properties: { browser: 'chrome', theme: 'dark', locale: 'en-US' },
  *   threshold: 5,
  *   minClusterSize: 10,
  *   fullPage: true,
  *   requestTimeout: 5000
  * });
  *
- * `properties` is the user metadata bag. Comparison options are normalized
- * into the server metadata payload, while `requestTimeout` stays on the
- * client request and `buildId` only routes the screenshot to a build.
+ * `properties` is the user metadata bag and every key is preserved. Vizzly
+ * reads width and height from the captured image. Comparison options are sent
+ * separately, while `requestTimeout` stays on the client request and `buildId`
+ * only routes the screenshot to a build.
  */
 export function vizzlyScreenshot(
   name: string,
@@ -94,11 +97,15 @@ export function vizzlyScreenshot(
 ): Promise<ScreenshotResult | null>;
 
 /**
- * Flush result summary returned by vizzlyFlush
+ * Results returned by vizzlyFlush. Cloud counts cover the whole run, including
+ * earlier flushes; success is false if any capture failed. Uploaded and reused
+ * counts are separate. TDD mode reports local comparison results instead.
  */
 export interface FlushResult {
   success: boolean;
   uploaded?: number;
+  reused?: number;
+  failures?: Array<{ name: string; error: string }>;
   flushed?: boolean;
   total?: number;
   passed?: number;

package/dist/uploader/core.js

@@ -200,12 +200,13 @@ export function buildFileMetadata(filePath, buffer) {
  * @returns {Object} Screenshot format for SHA check
  */
 export function fileToScreenshotFormat(file) {
+  let browser = extractBrowserFromFilename(file.filename);
   return {
     sha256: file.sha256,
     name: file.filename.replace(/\.png$/, ''),
-    browser: extractBrowserFromFilename(file.filename) || 'chrome',
-    viewport_width: 1920,
-    viewport_height: 1080
+    properties: browser ? {
+      browser
+    } : {}
   };
 }
 

package/dist/utils/screenshot-options.js

@@ -1,82 +1,10 @@
-/**
- * Screenshot option names that are part of the SDK/config contract, not the
- * user's arbitrary metadata bag.
- */
-export let RESERVED_PROPERTY_OPTIONS = Object.freeze({
-  threshold: {
-    message: 'Move "threshold" out of properties; properties is only for user metadata.'
-  },
-  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',
-    option,
-    message: RESERVED_PROPERTY_OPTIONS[option].message
-  };
-}
 
 /**
- * Normalize screenshot SDK options into the local and cloud upload payload.
- * Reserved names found inside properties are discarded instead of being promoted
- * into options.
+ * Keep user properties separate from the Vizzly options sent beside them.
  */
 export function normalizeScreenshotOptions(options = {}) {
   let {
@@ -90,16 +18,7 @@ export function normalizeScreenshotOptions(options = {}) {
     deviceScaleFactor,
     selector
   } = options;
-  let warnings = [];
-  let normalizedProperties = {};
   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));
-      continue;
-    }
-    normalizedProperties[key] = value;
-  }
   return {
     buildId,
     requestTimeout,
@@ -109,8 +28,9 @@ export function normalizeScreenshotOptions(options = {}) {
     captureMode,
     deviceScaleFactor,
     selector,
-    properties: normalizedProperties,
-    warnings
+    properties: {
+      ...sourceProperties
+    }
   };
 }
 export function createScreenshotProperties(options = {}) {

package/dist/utils/security.js

@@ -166,55 +166,40 @@ export function safePath(workingDir, ...pathSegments) {
 }
 
 /**
- * Validates screenshot properties object for safe values
- * @param {Object} properties - Properties to validate
- * @returns {Object} Validated properties object
+ * Validate user metadata without interpreting names as Vizzly options or
+ * rewriting values. Rendering code must escape strings for its output context.
+ * Reject unsafe object keys and values that cannot be represented as JSON.
+ *
+ * @param {Object} [properties={}] - User screenshot metadata.
+ * @returns {Object} A copy preserving the supplied JSON values.
+ * @throws {Error} Metadata contains unsafe keys, cycles, or non-JSON values.
  */
 export function validateScreenshotProperties(properties = {}) {
-  if (properties === null || typeof properties !== 'object') {
+  if (!properties || typeof properties !== 'object' || Array.isArray(properties)) {
     return {};
   }
-  const validated = {};
-
-  // Validate common properties with safe constraints
-  if (properties.browser && typeof properties.browser === 'string') {
-    try {
-      // Extract browser name without version (e.g., "Chrome/139.0.7258.138" -> "Chrome")
-      const browserName = properties.browser.split('/')[0];
-      validated.browser = sanitizeScreenshotName(browserName, 50);
-    } catch (error) {
-      // Skip invalid browser names, don't include them
-      output.warn(`Invalid browser name '${properties.browser}': ${error.message}`);
-    }
-  }
-  if (properties.viewport && typeof properties.viewport === 'object') {
-    const viewport = {};
-    if (typeof properties.viewport.width === 'number' && properties.viewport.width > 0 && properties.viewport.width <= 10000) {
-      viewport.width = Math.floor(properties.viewport.width);
-    }
-    if (typeof properties.viewport.height === 'number' && properties.viewport.height > 0 && properties.viewport.height <= 10000) {
-      viewport.height = Math.floor(properties.viewport.height);
+  let ancestors = new Set();
+  function copy(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+      return value;
     }
-    if (Object.keys(viewport).length > 0) {
-      validated.viewport = viewport;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value !== 'object' || ancestors.has(value)) {
+      throw new Error('Screenshot properties must contain JSON values');
     }
-  }
-
-  // Allow other safe string properties but sanitize them
-  for (const [key, value] of Object.entries(properties)) {
-    if (key === 'browser' || key === 'viewport') continue; // Already handled
-
-    if (typeof key === 'string' && key.length <= 50 && /^[a-zA-Z0-9_-]+$/.test(key)) {
-      if (typeof value === 'string' && value.length <= 200) {
-        // Preserve safe URL/query characters like '&' in metadata values.
-        // Rendering layers should escape for HTML instead of mutating payload data here.
-        validated[key] = value.replace(/[<>"']/g, '');
-      } else if (typeof value === 'number' && !Number.isNaN(value) && Number.isFinite(value)) {
-        validated[key] = value;
-      } else if (typeof value === 'boolean') {
-        validated[key] = value;
+    ancestors.add(value);
+    let result;
+    if (Array.isArray(value)) {
+      result = value.map(copy);
+    } else {
+      let entries = Object.entries(value);
+      if (entries.some(([key]) => ['__proto__', 'constructor', 'prototype'].includes(key))) {
+        throw new Error('Screenshot properties contain an unsafe key');
       }
+      result = Object.fromEntries(entries.map(([key, item]) => [key, copy(item)]));
     }
+    ancestors.delete(value);
+    return result;
   }
-  return validated;
+  return copy(properties);
 }

package/package.json

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