@vizzly-testing/cli 0.35.3-beta.4 → 0.37.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.37.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -72,17 +72,18 @@
     "dev:reporter": "cd src/reporter && vite --config vite.dev.config.js",
     "test:types": "tsd",
     "prepublishOnly": "pnpm run build",
-    "test": "node --experimental-test-coverage --test --test-concurrency=1 --test-reporter=spec $(find tests -name '*.test.js')",
+    "test": "node --experimental-test-coverage --test --test-concurrency=1 --test-reporter=spec $(find tests clients/swift/tests-js -name '*.test.js')",
     "test:watch": "node --test --test-reporter=spec --watch $(find tests -name '*.test.js')",
     "test:reporter": "playwright test --config=tests/reporter/playwright.config.js",
     "test:reporter:visual": "node bin/vizzly.js tdd run \"pnpm run test:reporter\" --no-open",
     "test:swift:e2e": "pnpm run build && node clients/swift/scripts/run-e2e.js",
+    "test:swift:previews:e2e": "node clients/swift/scripts/run-preview-e2e.js",
     "test:tui": "node --test --test-reporter=spec tests/tui/*.test.js",
     "test:tui:docker": "./tests/tui/run-tui-tests.sh",
-    "lint": "biome check src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
-    "lint:fix": "biome check --write --unsafe src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
-    "format": "biome format --write src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
-    "format:check": "biome format src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin",
+    "lint": "biome check src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
+    "lint:fix": "biome check --write --unsafe src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
+    "format": "biome format --write src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
+    "format:check": "biome format src tests clients/storybook/src clients/storybook/tests clients/static-site/src clients/static-site/tests clients/vitest/src clients/vitest/tests clients/ember/src clients/ember/tests clients/ember/bin clients/swift/src clients/swift/tests-js clients/swift/scripts",
     "fix": "pnpm run format && pnpm run lint:fix"
   },
   "engines": {
@@ -94,7 +95,7 @@
   },
   "dependencies": {
     "@vizzly-testing/bear-den": "0.1.4",
-    "@vizzly-testing/honeydiff": "^0.16.0",
+    "@vizzly-testing/honeydiff": "^0.17.0",
     "ansis": "^4.2.0",
     "commander": "^15.0.0",
     "cosmiconfig": "^9.0.0",

package/skills/vizzly/SKILL.md

@@ -20,21 +20,29 @@ test workflow in charge of how the UI is exercised.
 
 ## Inspect And Verify
 
+For cloud API queries, selectable fields, or an authorized review decision,
+start with `vizzly api schema --json` and follow
+[schema discovery](references/cli-context.md#query-the-cloud-api).
+Discover request details as needed instead of loading the entire OpenAPI document.
+Use `vizzly context ... --json` for local evidence and human-readable `context`
+output for guided inspection.
+
 1. Choose the supplied cloud build or comparison when one is named. Otherwise,
    use current local evidence or find the relevant cloud build.
-2. Request bounded JSON:
+2. For cloud data, discover the relevant API operations. For locally saved data,
+   request JSON context:
 
    ```bash
-   vizzly context build current --source local --agent --json
-   vizzly context build <build-id> --source cloud --agent --json
+   vizzly api schema --json
+   vizzly context build current --source local --json
    ```
 
 3. Confirm the build, source, branch, timestamps, baseline, review state, and
-   pagination before drawing conclusions. If `has_more` is true, run the
-   returned next-page command before concluding. Missing fields remain unknown.
-4. Follow `suggested_commands` to inspect a comparison. View its baseline,
-   current, and diff images together. If an image cannot be opened, label the
-   result metadata-only; do not call it visual verification.
+   pagination before drawing conclusions. Follow the schema's page instructions
+   for cloud data. Missing fields remain unknown.
+4. For cloud data, discover the comparison and image operations from the schema.
+   View the baseline, current, and diff images together. If an image cannot be
+   opened, label the result metadata-only; do not call it visual verification.
 5. Read image dimensions, viewport, browser, diff regions, fingerprint, and
    relevant history alongside the images. A prior approval is supporting
    evidence, not permission to approve the current comparison.
@@ -57,7 +65,7 @@ test workflow in charge of how the UI is exercised.
 ## Load A Reference When Needed
 
 - [CLI context](references/cli-context.md): local and cloud evidence, build
-  discovery, drill-downs, images, and TDD lifecycle.
+  discovery, schema queries, review decisions, images, and TDD lifecycle.
 - [SDK capture](references/sdks.md): add or change screenshot capture code.
 - [Dynamic content](references/dynamic-content.md): investigate unstable
   content and screenshot-specific tolerances.

package/skills/vizzly/references/cli-context.md

@@ -4,6 +4,41 @@ Use the repository's established CLI invocation and existing authentication.
 If cloud authentication is unavailable, report the blocker. Do not start an
 interactive login unless setup is in scope.
 
+## Query The Cloud API
+
+Discover the live review API instead of guessing endpoints or adding command flags:
+
+```bash
+vizzly api schema --json
+vizzly api schema <operation-id> --json
+vizzly api schema <operation-id> -q view=fields --json
+vizzly api schema <operation-id> -q view=response --json
+```
+
+The index lists available operations. The default operation view describes the
+method, path, parameters, authentication, and example arguments. Request field
+choices or response types only when needed. API JSON payloads are under
+`data.response`.
+
+Call the discovered path using `vizzly api <path>`, `-X` for its method, `-H`
+for headers, and `-q` for query parameters. Send the discovered API version
+header on data requests. Use `fields` to select just the evidence needed.
+Follow the response's pagination values explicitly; the CLI fetches one page
+per request. Keep cursors opaque and preserve the query they belong to.
+
+For a review, discover projects/builds, then inspect the build's screenshots,
+comparisons, and image endpoints. Download images with `--output <new-file>`
+and view baseline, current, and diff together. Use file output for large analysis
+responses too. Existing files are not overwritten. Export the full schema only
+when needed: `vizzly api schema --full --output <new-file> --json`.
+
+Review decisions require an authorized task, user credentials, and the documented
+organization header. Discover the decision operation's body before sending it
+with `-d @<file>` or `-d @-` for stdin. Generate a fresh `commandId` for each
+intended decision, then read back the review state. Generic writes are not
+automatically replayed; after an uncertain result, inspect state before retrying.
+Treat schema examples as argument arrays, not shell scripts.
+
 ## Choose The Evidence
 
 Use an ID supplied by the task. If no cloud build is supplied, list recent
@@ -12,17 +47,18 @@ builds and select the one matching the branch, commit, or pull request:
 ```bash
 vizzly builds --branch <branch> --limit 5 --json
 vizzly status <build-id> --json
-vizzly context build <build-id> --source cloud --agent --json
+vizzly api schema sdk.getBuildContext --json
 ```
 
-Use status for lifecycle facts and build context for visual evidence. Do not
-assume the first returned comparison is the most important; preserve API order
-and inspect the records relevant to the task.
+Use status for lifecycle facts, then follow the discovered build-context
+operation for visual evidence. Do not assume the first returned comparison is
+the most important; preserve API order and inspect the records relevant to the
+task.
 
 For saved local evidence:
 
 ```bash
-vizzly context build current --source local --agent --json
+vizzly context build current --source local --json
 vizzly context screenshot "<screenshot-name>" --source local --json
 vizzly context review-queue --source local --json
 ```
@@ -54,16 +90,16 @@ When a cloud build is in scope:
 
 ```bash
 vizzly run "<existing visual test command>" --wait --json
-vizzly context build <build-id> --source cloud --agent --json
+vizzly api schema --json
 ```
 
 ## Inspect A Comparison
 
-Follow the build response's `suggested_commands`. The direct form is:
+Discover comparison and image operations from the schema:
 
 ```bash
-vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --json
-vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --include diffs --json
+vizzly api schema getComparisonContext --json
+vizzly api schema sdk.getComparisonImage --json
 ```
 
 Open all three images together. Prefer `original_url` and fall back to `url`:
@@ -86,12 +122,10 @@ vizzly context similar <fingerprint-hash> --source cloud --json
 vizzly context review-queue --source <local-or-cloud> --json
 ```
 
-Use `--include diffs` only when compact diagnostics are insufficient. Request
-comments only when human review context matters.
+Use the documented response and pagination fields to request only the evidence
+needed. Request comments only when human review context matters.
 
 ## Continue Without Guessing
 
-Run returned `suggested_commands` rather than reconstructing IDs, sources, or
-pagination. When more evidence exists, the next-page command carries the API's
-opaque `--cursor`; do not edit or interpret it. Keep follow-up commands pinned
-to the source that produced the evidence.
+Use IDs and pagination values from API responses. Keep cursors opaque and
+preserve the query they belong to when requesting the next page.

package/skills/vizzly/references/setup-ci.md

@@ -36,8 +36,8 @@ vizzly finalize "<shared-ci-run-id>" --json
 - `vizzly doctor`: local configuration
 - `vizzly tdd status --json`: a local daemon started by the task
 - `vizzly status <build-id> --json`: cloud lifecycle
-- `vizzly context build <build-id> --source cloud --agent --json`: visual
-  evidence
+- `vizzly api schema --json`: discover supported cloud review operations and
+  their request and response schemas.
 
 If screenshots are absent, verify the existing integration, the test path that
 should capture them, and the active session. If authentication is absent,