@percy/core 1.31.14-beta.0 → 1.31.14-beta.2

package/README.md

@@ -53,6 +53,7 @@ The following options can also be defined within a Percy config file
   - `requestHeaders` — Request headers used when discovering snapshot assets
   - `authorization` — Basic auth `username` and `password` for protected snapshot assets
   - `disableCache` — Disable asset caching (**default** `false`)
+  - `maxCacheRam` — Cap the asset-discovery cache at this many MB (**default** unset/unbounded). When set, least-recently-used resources are evicted to stay within the cap. MB is decimal (1 MB = 1,000,000 bytes), not binary MiB (1,048,576). The cap measures cache body bytes only; process RSS is typically 1.5–2× the cap due to Node's Buffer slab allocator. Values below 25 MB are clamped to 25 MB with a warn log (the per-resource ceiling is 25 MB, so smaller caps would reject every resource). Also settable via the `--max-cache-ram <MB>` CLI flag or the `PERCY_MAX_CACHE_RAM` env var
   - `userAgent` — Custom user-agent string used when requesting assets
   - `cookies` — Browser cookies to use when requesting assets
   - `networkIdleTimeout` — Milliseconds to wait for the network to idle (**default** `100`)

package/dist/api.js

@@ -259,7 +259,7 @@ export function createPercyServer(percy, port) {
     if (cmd === 'reset') {
       // the reset command will reset testing mode and clear any logs
       percy.testing = {};
-      logger.instance.messages.clear();
+      logger.instance.reset();
     } else if (cmd === 'version') {
       // the version command will update the api version header for testing
       percy.testing.version = body;
@@ -304,7 +304,7 @@ export function createPercyServer(percy, port) {
   }))
   // returns an array of raw logs from the logger
   .route('get', '/test/logs', (req, res) => res.json(200, {
-    logs: Array.from(logger.instance.messages)
+    logs: logger.instance.query(() => true)
   }))
   // serves a very basic html page for testing snapshots
   .route('get', '/test/snapshot', (req, res) => {

package/dist/archive.js

@@ -0,0 +1,117 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+const ARCHIVE_VERSION = 1;
+const MAX_FILENAME_LENGTH = 200;
+const UNSAFE_CHARS = /[/\\:*?"<>|]/g;
+
+// Validates the archive dir to prevent path traversal attacks.
+// Returns the resolved absolute path.
+export function validateArchiveDir(archiveDir) {
+  let resolved = path.resolve(archiveDir);
+  let normalized = path.normalize(resolved);
+
+  // Reject if the normalized path still contains '..' segments
+  if (normalized.split(path.sep).includes('..')) {
+    throw new Error(`Invalid archive dir: path traversal detected in "${archiveDir}"`);
+  }
+  return resolved;
+}
+
+// Sanitizes a snapshot name into a safe filename.
+// Strips unsafe characters and appends a hash to prevent collisions.
+export function sanitizeFilename(name) {
+  let safe = name.replace(UNSAFE_CHARS, '_');
+  if (safe.length > MAX_FILENAME_LENGTH) {
+    safe = safe.substring(0, MAX_FILENAME_LENGTH);
+  }
+
+  // Append a short hash of the original name for collision prevention
+  let hash = crypto.createHash('sha256').update(name).digest('hex').substring(0, 8);
+  return `${safe}-${hash}`;
+}
+
+// Serializes a snapshot into a JSON-safe object for archiving.
+// Resources have their binary content base64-encoded.
+export function serializeSnapshot(snapshot) {
+  let {
+    resources,
+    ...snapshotData
+  } = snapshot;
+  return {
+    version: ARCHIVE_VERSION,
+    snapshot: snapshotData,
+    resources: (resources || []).map(r => ({
+      ...r,
+      content: r.content ? Buffer.from(r.content).toString('base64') : null
+    }))
+  };
+}
+
+// Validates and deserializes an archived snapshot from parsed JSON.
+// Decodes base64 resource content back to Buffers.
+export function deserializeSnapshot(data) {
+  if (!data || typeof data !== 'object') {
+    throw new Error('Invalid archive: expected an object');
+  }
+  if (data.version !== ARCHIVE_VERSION) {
+    throw new Error(`Unsupported archive version: ${data.version} (expected ${ARCHIVE_VERSION})`);
+  }
+  if (!data.snapshot || typeof data.snapshot.name !== 'string' || !data.snapshot.name) {
+    throw new Error('Invalid archive: missing snapshot name');
+  }
+  if (!Array.isArray(data.resources) || data.resources.length === 0) {
+    throw new Error('Invalid archive: missing or empty resources');
+  }
+  return {
+    ...data.snapshot,
+    resources: data.resources.map(r => ({
+      ...r,
+      content: r.content ? Buffer.from(r.content, 'base64') : null
+    }))
+  };
+}
+
+// Archives a single snapshot to the archive directory.
+// Creates the directory if it doesn't exist.
+export function archiveSnapshot(archiveDir, snapshot) {
+  fs.mkdirSync(archiveDir, {
+    recursive: true
+  });
+  let filename = sanitizeFilename(snapshot.name);
+  let filepath = path.join(archiveDir, `${filename}.json`);
+  let serialized = serializeSnapshot(snapshot);
+  fs.writeFileSync(filepath, JSON.stringify(serialized));
+}
+
+// Reads all archived snapshots from the given directory.
+// Skips symlinks and invalid files with warnings.
+export function readArchivedSnapshots(archiveDir, log) {
+  let resolved = validateArchiveDir(archiveDir);
+  if (!fs.existsSync(resolved) || !fs.lstatSync(resolved).isDirectory()) {
+    throw new Error(`Archive directory not found: ${archiveDir}`);
+  }
+  let entries = fs.readdirSync(resolved);
+  let snapshots = [];
+  for (let entry of entries) {
+    if (!entry.endsWith('.json')) continue;
+    let filepath = path.join(resolved, entry);
+    let stat = fs.lstatSync(filepath);
+
+    // Skip symlinks for security
+    if (stat.isSymbolicLink()) {
+      log === null || log === void 0 || log.warn(`Skipping symlink: ${entry}`);
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    try {
+      let raw = fs.readFileSync(filepath, 'utf-8');
+      let data = JSON.parse(raw);
+      let snapshot = deserializeSnapshot(data);
+      snapshots.push(snapshot);
+    } catch (error) {
+      log === null || log === void 0 || log.warn(`Skipping invalid archive file "${entry}": ${error.message}`);
+    }
+  }
+  return snapshots;
+}

package/dist/cache/byte-lru.js

@@ -0,0 +1,352 @@
+function _classPrivateMethodInitSpec(e, a) { _checkPrivateRedeclaration(e, a), a.add(e); }
+function _classPrivateFieldInitSpec(e, t, a) { _checkPrivateRedeclaration(e, t), t.set(e, a); }
+function _checkPrivateRedeclaration(e, t) { if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object"); }
+function _classPrivateFieldGet(s, a) { return s.get(_assertClassBrand(s, a)); }
+function _classPrivateFieldSet(s, a, r) { return s.set(_assertClassBrand(s, a), r), r; }
+function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); }
+// Two-tier cache used by asset discovery:
+//   ByteLRU — byte-budget in-memory LRU; Map insertion order = LRU order.
+//   DiskSpillStore — on-disk overflow tier. RAM evictions spill here; lookups
+//   fall back to disk before refetching from origin.
+// All operations are synchronous; callers (network intercept, ByteLRU.set)
+// cannot yield to the event loop mid-op. Per-entry size is capped at 25MB
+// upstream so disk I/O latency is bounded.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+const DEFAULT_PER_ENTRY_OVERHEAD = 512;
+export class ByteLRU {
+  #map = new Map();
+  #bytes = 0;
+  #max;
+  #stats = {
+    hits: 0,
+    misses: 0,
+    evictions: 0,
+    peakBytes: 0
+  };
+  onEvict;
+  constructor(maxBytes, {
+    onEvict
+  } = {}) {
+    this.#max = maxBytes;
+    this.onEvict = onEvict;
+  }
+  get(key) {
+    if (!this.#map.has(key)) {
+      this.#stats.misses++;
+      return undefined;
+    }
+    const rec = this.#map.get(key);
+    this.#map.delete(key);
+    this.#map.set(key, rec);
+    this.#stats.hits++;
+    return rec.value;
+  }
+  set(key, value, size) {
+    if (!Number.isFinite(size) || size < 0) return false;
+
+    // Reject oversize BEFORE touching any existing entry — a failed set on an
+    // existing key must not evict the prior (valid) entry.
+    if (this.#max !== undefined && size > this.#max) {
+      if (this.onEvict) this.onEvict(key, 'too-big', value);
+      return false;
+    }
+    if (this.#map.has(key)) {
+      this.#bytes -= this.#map.get(key).size;
+      this.#map.delete(key);
+    }
+    this.#map.set(key, {
+      value,
+      size
+    });
+    this.#bytes += size;
+    if (this.#bytes > this.#stats.peakBytes) this.#stats.peakBytes = this.#bytes;
+    while (this.#max !== undefined && this.#bytes > this.#max) {
+      const oldestKey = this.#map.keys().next().value;
+      const rec = this.#map.get(oldestKey);
+      this.#bytes -= rec.size;
+      this.#map.delete(oldestKey);
+      this.#stats.evictions++;
+      if (this.onEvict) this.onEvict(oldestKey, 'lru', rec.value);
+    }
+    return true;
+  }
+  has(key) {
+    return this.#map.has(key);
+  }
+  delete(key) {
+    if (!this.#map.has(key)) return false;
+    this.#bytes -= this.#map.get(key).size;
+    return this.#map.delete(key);
+  }
+  clear() {
+    this.#map.clear();
+    this.#bytes = 0;
+  }
+  get size() {
+    return this.#map.size;
+  }
+  get calculatedSize() {
+    return this.#bytes;
+  }
+  get stats() {
+    return {
+      ...this.#stats,
+      currentBytes: this.#bytes
+    };
+  }
+}
+
+// Returns the byte length of a resource's content. Buffer.byteLength is used
+// for strings so that multi-byte UTF-8 (CJK, emoji) is counted in bytes, not
+// JS string units, otherwise the cache budget can drift past its cap.
+function contentBytes(content) {
+  if (content == null) return 0;
+  if (Buffer.isBuffer(content)) return content.length;
+  if (typeof content === 'string') return Buffer.byteLength(content);
+  return content.length ?? 0;
+}
+
+// Handles the two Percy cache-entry shapes: single resource, or array of
+// roots captured at multiple widths (see discovery.js parseDomResources).
+export function entrySize(resource, overhead = DEFAULT_PER_ENTRY_OVERHEAD) {
+  if (Array.isArray(resource)) {
+    return resource.reduce((n, r) => n + contentBytes(r === null || r === void 0 ? void 0 : r.content) + overhead, 0);
+  }
+  return contentBytes(resource === null || resource === void 0 ? void 0 : resource.content) + overhead;
+}
+
+// Multi-width root arrays carry per-element binary content. Encode buffers as
+// base64 inside JSON so the whole array survives a disk roundtrip; null and
+// string content pass through as themselves.
+function encodeArrayElement(r) {
+  if (!r) return r;
+  const {
+    content,
+    ...rest
+  } = r;
+  if (content == null) return {
+    ...rest,
+    content: null
+  };
+  if (Buffer.isBuffer(content)) return {
+    ...rest,
+    content: {
+      __buf: content.toString('base64')
+    }
+  };
+  return {
+    ...rest,
+    content: String(content)
+  };
+}
+function decodeArrayElement(r) {
+  if (!r) return r;
+  const {
+    content,
+    ...rest
+  } = r;
+  if (content && typeof content === 'object' && '__buf' in content) {
+    return {
+      ...rest,
+      content: Buffer.from(content.__buf, 'base64')
+    };
+  }
+  return {
+    ...rest,
+    content
+  };
+}
+var _index = /*#__PURE__*/new WeakMap();
+var _bytes = /*#__PURE__*/new WeakMap();
+var _peakBytes = /*#__PURE__*/new WeakMap();
+var _stats = /*#__PURE__*/new WeakMap();
+var _counter = /*#__PURE__*/new WeakMap();
+var _ready = /*#__PURE__*/new WeakMap();
+var _DiskSpillStore_brand = /*#__PURE__*/new WeakSet();
+export class DiskSpillStore {
+  constructor(dir, {
+    log
+  } = {}) {
+    _classPrivateMethodInitSpec(this, _DiskSpillStore_brand);
+    _classPrivateFieldInitSpec(this, _index, new Map());
+    _classPrivateFieldInitSpec(this, _bytes, 0);
+    _classPrivateFieldInitSpec(this, _peakBytes, 0);
+    _classPrivateFieldInitSpec(this, _stats, {
+      spilled: 0,
+      restored: 0,
+      spillFailures: 0,
+      readFailures: 0
+    });
+    _classPrivateFieldInitSpec(this, _counter, 0);
+    _classPrivateFieldInitSpec(this, _ready, false);
+    this.dir = dir;
+    this.log = log;
+    try {
+      // mode 0o700: spilled bytes are origin-fetchable so the threat model is
+      // small, but on shared-tenant CI hosts other users on the same box
+      // shouldn't be able to read them.
+      fs.mkdirSync(dir, {
+        recursive: true,
+        mode: 0o700
+      });
+      _classPrivateFieldSet(_ready, this, true);
+    } catch (err) {
+      var _this$log, _this$log$debug;
+      (_this$log = this.log) === null || _this$log === void 0 || (_this$log$debug = _this$log.debug) === null || _this$log$debug === void 0 || _this$log$debug.call(_this$log, `disk-spill init failed for ${dir}: ${err.message}`);
+    }
+  }
+
+  // Returns true on success; false on any failure so caller falls back to drop.
+  // Overwrites prior spill for the same URL — a fresh discovery write wins.
+  // Two resource shapes are supported: a single resource with a binary
+  // .content, and a multi-width root array (see entrySize for the array
+  // shape). Arrays are JSON-encoded with base64 buffers so the whole array
+  // survives the disk roundtrip.
+  set(url, resource) {
+    var _this$counter;
+    if (!_classPrivateFieldGet(_ready, this)) return false;
+    let bytes;
+    let meta;
+    let isArray = false;
+    if (Array.isArray(resource)) {
+      isArray = true;
+      try {
+        bytes = Buffer.from(JSON.stringify(resource.map(encodeArrayElement)));
+      } catch {
+        return false;
+      }
+    } else {
+      let content = resource === null || resource === void 0 ? void 0 : resource.content;
+      if (content == null) return false;
+      if (!Buffer.isBuffer(content)) {
+        try {
+          content = Buffer.from(content);
+        } catch {
+          return false;
+        }
+      }
+      bytes = content;
+      meta = {
+        ...resource
+      };
+      delete meta.content;
+    }
+
+    // Counter-based filename keeps URL-derived data out of path.join —
+    // avoids any path-traversal surface even though sha256 would be safe.
+    const filepath = path.join(this.dir, String(_classPrivateFieldSet(_counter, this, (_this$counter = _classPrivateFieldGet(_counter, this), ++_this$counter))));
+    try {
+      fs.writeFileSync(filepath, bytes);
+    } catch (err) {
+      var _this$log2, _this$log2$debug;
+      _classPrivateFieldGet(_stats, this).spillFailures++;
+      (_this$log2 = this.log) === null || _this$log2 === void 0 || (_this$log2$debug = _this$log2.debug) === null || _this$log2$debug === void 0 || _this$log2$debug.call(_this$log2, `disk-spill write failed for ${url}: ${err.message}`);
+      return false;
+    }
+    if (_classPrivateFieldGet(_index, this).has(url)) {
+      const prev = _classPrivateFieldGet(_index, this).get(url);
+      _classPrivateFieldSet(_bytes, this, _classPrivateFieldGet(_bytes, this) - prev.size);
+      try {
+        fs.unlinkSync(prev.path);
+      } catch {/* best-effort */}
+    }
+    _classPrivateFieldGet(_index, this).set(url, {
+      path: filepath,
+      size: bytes.length,
+      isArray,
+      meta
+    });
+    _classPrivateFieldSet(_bytes, this, _classPrivateFieldGet(_bytes, this) + bytes.length);
+    if (_classPrivateFieldGet(_bytes, this) > _classPrivateFieldGet(_peakBytes, this)) _classPrivateFieldSet(_peakBytes, this, _classPrivateFieldGet(_bytes, this));
+    _classPrivateFieldGet(_stats, this).spilled++;
+    return true;
+  }
+  get(url) {
+    const entry = _classPrivateFieldGet(_index, this).get(url);
+    if (!entry) return undefined;
+    let raw;
+    try {
+      raw = fs.readFileSync(entry.path);
+    } catch (err) {
+      var _this$log3, _this$log3$debug;
+      _classPrivateFieldGet(_stats, this).readFailures++;
+      (_this$log3 = this.log) === null || _this$log3 === void 0 || (_this$log3$debug = _this$log3.debug) === null || _this$log3$debug === void 0 || _this$log3$debug.call(_this$log3, `disk-spill read failed for ${url}: ${err.message}`);
+      _assertClassBrand(_DiskSpillStore_brand, this, _removeEntry).call(this, url, entry);
+      return undefined;
+    }
+    if (entry.isArray) {
+      let arr;
+      try {
+        arr = JSON.parse(raw.toString('utf8')).map(decodeArrayElement);
+      } catch (err) {
+        var _this$log4, _this$log4$debug;
+        _classPrivateFieldGet(_stats, this).readFailures++;
+        (_this$log4 = this.log) === null || _this$log4 === void 0 || (_this$log4$debug = _this$log4.debug) === null || _this$log4$debug === void 0 || _this$log4$debug.call(_this$log4, `disk-spill array-decode failed for ${url}: ${err.message}`);
+        _assertClassBrand(_DiskSpillStore_brand, this, _removeEntry).call(this, url, entry);
+        return undefined;
+      }
+      _classPrivateFieldGet(_stats, this).restored++;
+      return arr;
+    }
+    _classPrivateFieldGet(_stats, this).restored++;
+    return {
+      ...entry.meta,
+      content: raw
+    };
+  }
+  has(url) {
+    return _classPrivateFieldGet(_index, this).has(url);
+  }
+  delete(url) {
+    const entry = _classPrivateFieldGet(_index, this).get(url);
+    if (!entry) return false;
+    _assertClassBrand(_DiskSpillStore_brand, this, _removeEntry).call(this, url, entry);
+    return true;
+  }
+  destroy() {
+    try {
+      if (_classPrivateFieldGet(_ready, this)) fs.rmSync(this.dir, {
+        recursive: true,
+        force: true
+      });
+    } catch (err) {
+      var _this$log5, _this$log5$debug;
+      (_this$log5 = this.log) === null || _this$log5 === void 0 || (_this$log5$debug = _this$log5.debug) === null || _this$log5$debug === void 0 || _this$log5$debug.call(_this$log5, `disk-spill cleanup failed for ${this.dir}: ${err.message}`);
+    }
+    _classPrivateFieldGet(_index, this).clear();
+    _classPrivateFieldSet(_bytes, this, 0);
+    _classPrivateFieldSet(_ready, this, false);
+  }
+  get size() {
+    return _classPrivateFieldGet(_index, this).size;
+  }
+  get bytes() {
+    return _classPrivateFieldGet(_bytes, this);
+  }
+  get ready() {
+    return _classPrivateFieldGet(_ready, this);
+  }
+  get stats() {
+    return {
+      ..._classPrivateFieldGet(_stats, this),
+      currentBytes: _classPrivateFieldGet(_bytes, this),
+      peakBytes: _classPrivateFieldGet(_peakBytes, this),
+      entries: _classPrivateFieldGet(_index, this).size
+    };
+  }
+}
+function _removeEntry(url, entry) {
+  _classPrivateFieldSet(_bytes, this, _classPrivateFieldGet(_bytes, this) - entry.size);
+  _classPrivateFieldGet(_index, this).delete(url);
+  try {
+    fs.unlinkSync(entry.path);
+  } catch {/* best-effort */}
+}
+export function createSpillDir() {
+  const suffix = `${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  return path.join(os.tmpdir(), `percy-cache-${suffix}`);
+}

package/dist/config.js

@@ -7,6 +7,9 @@ export const configSchema = {
       deferUploads: {
         type: 'boolean'
       },
+      archiveDir: {
+        type: 'string'
+      },
       useSystemProxy: {
         type: 'boolean',
         default: false
@@ -422,6 +425,13 @@ export const configSchema = {
       disableCache: {
         type: 'boolean'
       },
+      maxCacheRam: {
+        // 0 has no meaningful semantics — it's neither "unbounded" (use null)
+        // nor "disabled" (use --disable-cache). Reject it at schema time so the
+        // discovery clamp doesn't silently bump it to 25MB.
+        type: ['integer', 'null'],
+        minimum: 1
+      },
       captureMockedServiceWorker: {
         type: 'boolean',
         default: false

package/dist/discovery.js

@@ -2,6 +2,7 @@ import logger from '@percy/logger';
 import Queue from './queue.js';
 import Page from './page.js';
 import { normalizeURL, hostnameMatches, createResource, createRootResource, createPercyCSSResource, createLogResource, yieldAll, snapshotLogName, waitForTimeout, withRetries, waitForSelectorInsideBrowser, isGzipped, maybeScrollToBottom } from './utils.js';
+import { ByteLRU, entrySize, DiskSpillStore, createSpillDir } from './cache/byte-lru.js';
 import { sha256hash } from '@percy/client/utils';
 import Pako from 'pako';
 
@@ -223,10 +224,8 @@ function processSnapshotResources({
   resources = resources.flat();
 
   // include associated snapshot logs matched by meta information
-  resources.push(createLogResource(logger.query(log => {
-    var _log$meta$snapshot, _log$meta$snapshot2;
-    return ((_log$meta$snapshot = log.meta.snapshot) === null || _log$meta$snapshot === void 0 ? void 0 : _log$meta$snapshot.testCase) === snapshot.meta.snapshot.testCase && ((_log$meta$snapshot2 = log.meta.snapshot) === null || _log$meta$snapshot2 === void 0 ? void 0 : _log$meta$snapshot2.name) === snapshot.meta.snapshot.name;
-  })));
+  resources.push(createLogResource(logger.snapshotLogs(snapshot.meta.snapshot)));
+  logger.evictSnapshot(snapshot.meta.snapshot);
   if (process.env.PERCY_GZIP) {
     for (let index = 0; index < resources.length; index++) {
       const alreadyZipped = isGzipped(resources[index].content);
@@ -434,9 +433,74 @@ export async function* discoverSnapshotResources(queue, options, callback) {
     return all;
   }, []));
 }
-
-// Used to cache resources across core instances
 export const RESOURCE_CACHE_KEY = Symbol('resource-cache');
+export const CACHE_STATS_KEY = Symbol('resource-cache-stats');
+export const DISK_SPILL_KEY = Symbol('resource-cache-disk-spill');
+const BYTES_PER_MB = 1_000_000;
+// MAX_RESOURCE_SIZE in network.js is 25MB; caps below that would skip every
+// resource, so we clamp. MIN_REASONABLE_CAP_MB warns on near-useless caps.
+const MAX_RESOURCE_SIZE_MB = 25;
+const MIN_REASONABLE_CAP_MB = 50;
+const DEFAULT_WARN_THRESHOLD_BYTES = 500 * BYTES_PER_MB;
+function makeCacheStats() {
+  return {
+    effectiveMaxCacheRamMB: null,
+    oversizeSkipped: 0,
+    firstEvictionEventFired: false,
+    warningFired: false,
+    unsetModeBytes: 0
+  };
+}
+function readWarnThresholdBytes() {
+  const raw = Number(process.env.PERCY_CACHE_WARN_THRESHOLD_BYTES);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_WARN_THRESHOLD_BYTES;
+}
+
+// Cache lookup shared by the network intercept path. RAM miss falls through
+// to the disk tier; read failures return undefined so the browser refetches.
+// Also resolves the array-valued root-resource shape used for multi-width
+// DOM snapshots, regardless of which tier returned it.
+//
+// Disk hits are promoted back to RAM so a hot URL that was evicted once does
+// not pay the readFileSync cost on every subsequent access — the typical
+// two-tier-cache promotion pattern. ByteLRU's own eviction will then re-spill
+// the actual coldest entry if needed. DISK_SPILL_KEY is only set when the
+// ByteLRU tier is active (see createDiscoveryQueue 'start' handler), so the
+// cache here is guaranteed to be a ByteLRU when we enter this branch.
+export function lookupCacheResource(percy, snapshotResources, cache, url, width) {
+  let resource = snapshotResources.get(url) || cache.get(url);
+  const disk = percy[DISK_SPILL_KEY];
+  if (!resource && disk) {
+    resource = disk.get(url);
+    if (resource) {
+      percy.log.debug(`cache disk-hit: ${url} (disk=${disk.size}/` + `${Math.round(disk.bytes / BYTES_PER_MB)}MB)`);
+      // Promote back to RAM and drop the disk copy. cache.set may itself
+      // evict the LRU entry (which spills back to disk) — that's the
+      // intended LRU dance, not a bug.
+      cache.set(url, resource, entrySize(resource));
+      disk.delete(url);
+    }
+  }
+  if (resource && Array.isArray(resource) && resource[0].root) {
+    const rootResource = resource.find(r => {
+      var _r$widths;
+      return (_r$widths = r.widths) === null || _r$widths === void 0 ? void 0 : _r$widths.includes(width);
+    });
+    resource = rootResource || resource[0];
+  }
+  return resource;
+}
+
+// Fire-and-forget wrapper around the shared telemetry egress on Percy.
+// onEvict callbacks are sync; the microtask hop keeps even sendCacheTelemetry's
+// pre-await synchronous work (header construction, payload serialization) off
+// the eviction-loop hot path.
+function fireCacheEventSafe(percy, message, extra) {
+  // sendCacheTelemetry already swallows pager errors. The trailing .catch is
+  // belt-and-suspenders against Node 14's unhandled-rejection-as-fatal mode
+  // if the catch arm itself ever throws (e.g. log.debug stub explodes).
+  Promise.resolve().then(() => percy.sendCacheTelemetry(message, extra)).catch(() => {});
+}
 
 // Creates an asset discovery queue that uses the percy browser instance to create a page for each
 // snapshot which is used to intercept and capture snapshot resource requests.
@@ -446,21 +510,84 @@ export function createDiscoveryQueue(percy) {
   } = percy.config.discovery;
   let queue = new Queue('discovery');
   let cache;
+  let capBytes = null;
+  // Read once: saveResource consults this on every call.
+  const warnThreshold = readWarnThresholdBytes();
   return queue.set({
     concurrency
-  })
-  // on start, launch the browser and run the queue
-  .handle('start', async () => {
-    cache = percy[RESOURCE_CACHE_KEY] = new Map();
-
-    // If browser.launch() fails it will get captured in
-    // *percy.start()
+  }).handle('start', async () => {
+    const configuredMaxCacheRamMB = percy.config.discovery.maxCacheRam;
+    let effectiveMaxCacheRamMB = configuredMaxCacheRamMB;
+
+    // User's config is not mutated; the post-clamp value lives on stats.
+    if (configuredMaxCacheRamMB != null) {
+      if (configuredMaxCacheRamMB < MAX_RESOURCE_SIZE_MB) {
+        percy.log.warn(`--max-cache-ram=${configuredMaxCacheRamMB}MB is below the ${MAX_RESOURCE_SIZE_MB}MB minimum ` + '(individual resources up to 25MB would otherwise be dropped). ' + `Continuing with the minimum: ${MAX_RESOURCE_SIZE_MB}MB.`);
+        effectiveMaxCacheRamMB = MAX_RESOURCE_SIZE_MB;
+      } else if (configuredMaxCacheRamMB < MIN_REASONABLE_CAP_MB) {
+        percy.log.warn(`--max-cache-ram=${configuredMaxCacheRamMB}MB is very small; ` + 'most resources will not fit and hit rate will be near zero.');
+      }
+      if (percy.config.discovery.disableCache) {
+        percy.log.info('--max-cache-ram is ignored because --disable-cache is set.');
+      }
+      capBytes = effectiveMaxCacheRamMB * BYTES_PER_MB;
+    }
+    if (warnThreshold !== DEFAULT_WARN_THRESHOLD_BYTES) {
+      percy.log.debug(`PERCY_CACHE_WARN_THRESHOLD_BYTES override active: ${warnThreshold} bytes ` + `(default ${DEFAULT_WARN_THRESHOLD_BYTES}).`);
+    }
+    percy[CACHE_STATS_KEY] = makeCacheStats();
+    percy[CACHE_STATS_KEY].effectiveMaxCacheRamMB = capBytes != null ? effectiveMaxCacheRamMB : null;
+    if (capBytes != null) {
+      // Overflow tier: RAM evictions spill here. diskStore.set returns
+      // false on any I/O failure → caller falls back to drop automatically.
+      const diskStore = new DiskSpillStore(createSpillDir(), {
+        log: percy.log
+      });
+      percy[DISK_SPILL_KEY] = diskStore;
+      cache = percy[RESOURCE_CACHE_KEY] = new ByteLRU(capBytes, {
+        onEvict: (key, reason, value) => {
+          if (reason === 'too-big') {
+            percy[CACHE_STATS_KEY].oversizeSkipped++;
+            percy.log.debug(`cache skip (oversize): ${key}`);
+            return;
+          }
+          const spilled = diskStore.set(key, value);
+          percy.log.debug(`cache ${spilled ? 'spill' : 'evict'}: ${key} ` + `(cache ${Math.round(cache.calculatedSize / BYTES_PER_MB)}` + `/${effectiveMaxCacheRamMB}MB, entries=${cache.size}, ` + `disk=${diskStore.size}/${Math.round(diskStore.bytes / BYTES_PER_MB)}MB)`);
+          const stats = percy[CACHE_STATS_KEY];
+          if (stats && !stats.firstEvictionEventFired) {
+            stats.firstEvictionEventFired = true;
+            percy.log.info('Cache eviction active — cap reached, oldest entries spilling to disk.');
+            fireCacheEventSafe(percy, 'cache_eviction_started', {
+              cache_budget_ram_mb: effectiveMaxCacheRamMB,
+              cache_peak_bytes_seen: cache.stats.peakBytes,
+              eviction_count: cache.stats.evictions,
+              disk_spill_enabled: diskStore.ready
+            });
+          }
+        }
+      });
+    } else {
+      cache = percy[RESOURCE_CACHE_KEY] = new Map();
+    }
     await percy.browser.launch();
     queue.run();
-  })
-  // on end, close the browser
-  .handle('end', async () => {
-    await percy.browser.close();
+  }).handle('end', async () => {
+    // Disk-spill cleanup must run even if browser.close() throws — otherwise
+    // the per-run temp dir under os.tmpdir() leaks. CACHE_STATS_KEY is set
+    // alongside DISK_SPILL_KEY in 'start', so the snapshot is always safe.
+    try {
+      await percy.browser.close();
+    } finally {
+      const diskStore = percy[DISK_SPILL_KEY];
+      if (diskStore) {
+        percy[CACHE_STATS_KEY].finalDiskStats = {
+          ...diskStore.stats,
+          ready: diskStore.ready
+        };
+        diskStore.destroy();
+        delete percy[DISK_SPILL_KEY];
+      }
+    }
   })
   // snapshots are unique by name and testCase; when deferred also by widths
   .handle('find', ({
@@ -509,18 +636,9 @@ export function createDiscoveryQueue(percy) {
             disableCache: snapshot.discovery.disableCache,
             allowedHostnames: snapshot.discovery.allowedHostnames,
             disallowedHostnames: snapshot.discovery.disallowedHostnames,
-            getResource: (u, width = null) => {
-              let resource = snapshot.resources.get(u) || cache.get(u);
-              if (resource && Array.isArray(resource) && resource[0].root) {
-                const rootResource = resource.find(r => {
-                  var _r$widths;
-                  return (_r$widths = r.widths) === null || _r$widths === void 0 ? void 0 : _r$widths.includes(width);
-                });
-                resource = rootResource || resource[0];
-              }
-              return resource;
-            },
+            getResource: (u, width = null) => lookupCacheResource(percy, snapshot.resources, cache, u, width),
             saveResource: r => {
+              var _percy$DISK_SPILL_KEY;
               const limitResources = process.env.LIMIT_SNAPSHOT_RESOURCES || false;
               const MAX_RESOURCES = Number(process.env.MAX_SNAPSHOT_RESOURCES) || 749;
               if (limitResources && snapshot.resources.size >= MAX_RESOURCES) {
@@ -528,8 +646,31 @@ export function createDiscoveryQueue(percy) {
                 return;
               }
               snapshot.resources.set(r.url, r);
-              if (!snapshot.discovery.disableCache) {
+              if (snapshot.discovery.disableCache) return;
+
+              // Fresh write supersedes any prior spill — prevents races
+              // where getResource could serve a stale disk copy.
+              if ((_percy$DISK_SPILL_KEY = percy[DISK_SPILL_KEY]) !== null && _percy$DISK_SPILL_KEY !== void 0 && _percy$DISK_SPILL_KEY.has(r.url)) {
+                percy[DISK_SPILL_KEY].delete(r.url);
+              }
+              if (capBytes != null) {
+                // ByteLRU fires onEvict('too-big') for oversize entries;
+                // the oversize_skipped stat + debug log live there.
+                cache.set(r.url, r, entrySize(r));
+              } else {
+                // Subtract the prior entry's footprint before overwriting so
+                // the byte counter tracks current cache contents rather than
+                // cumulative writes. Without this, the same shared CSS saved
+                // across N snapshots would inflate unsetModeBytes by N×.
+                const stats = percy[CACHE_STATS_KEY];
+                const prior = cache.get(r.url);
+                if (prior) stats.unsetModeBytes -= entrySize(prior);
                 cache.set(r.url, r);
+                stats.unsetModeBytes += entrySize(r);
+                if (!stats.warningFired && stats.unsetModeBytes >= warnThreshold) {
+                  stats.warningFired = true;
+                  percy.log.warn(`Percy cache is using ${(stats.unsetModeBytes / BYTES_PER_MB).toFixed(1)}MB. ` + 'If your CI is memory-constrained, set --max-cache-ram. ' + 'See https://www.browserstack.com/docs/percy/cli/managing-cache-memory');
+                }
               }
             }
           }

package/dist/percy.js

@@ -17,7 +17,7 @@ import Pako from 'pako';
 import { base64encode, generatePromise, yieldAll, yieldTo, redactSecrets, detectSystemProxyAndLog, checkSDKVersion, processCorsIframes } from './utils.js';
 import { createPercyServer, createStaticServer } from './api.js';
 import { gatherSnapshots, createSnapshotsQueue, validateSnapshotOptions } from './snapshot.js';
-import { discoverSnapshotResources, createDiscoveryQueue } from './discovery.js';
+import { discoverSnapshotResources, createDiscoveryQueue, RESOURCE_CACHE_KEY, CACHE_STATS_KEY, DISK_SPILL_KEY } from './discovery.js';
 import Monitoring from '@percy/monitoring';
 import { WaitForJob } from './wait-for-job.js';
 const MAX_SUGGESTION_CALLS = 10;
@@ -43,6 +43,8 @@ export class Percy {
   constructor({
     // initial log level
     loglevel,
+    // path to save snapshot data to disk
+    archiveDir,
     // process uploads before the next snapshot
     delayUploads,
     // process uploads after all snapshots
@@ -83,6 +85,7 @@ export class Percy {
     });
     labels ?? (labels = (_config$percy = config.percy) === null || _config$percy === void 0 ? void 0 : _config$percy.labels);
     deferUploads ?? (deferUploads = (_config$percy2 = config.percy) === null || _config$percy2 === void 0 ? void 0 : _config$percy2.deferUploads);
+    if (archiveDir) skipUploads = skipUploads != null ? skipUploads : true;
     this.config = config;
     this.cliStartTime = null;
     if (testing) loglevel = 'silent';
@@ -95,6 +98,7 @@ export class Percy {
     this.skipDiscovery = this.dryRun || !!skipDiscovery;
     this.delayUploads = this.skipUploads || !!delayUploads;
     this.deferUploads = this.skipUploads || !!deferUploads;
+    this.archiveDir = this.skipUploads && archiveDir ? archiveDir : null;
     this.labels = labels;
     this.suggestionsCallCounter = suggestionsCallCounter;
     this.client = new PercyClient({
@@ -132,7 +136,7 @@ export class Percy {
     };
 
     // generator methods are wrapped to autorun and return promises
-    for (let m of ['start', 'stop', 'flush', 'idle', 'snapshot', 'upload']) {
+    for (let m of ['start', 'stop', 'flush', 'idle', 'snapshot', 'upload', 'replaySnapshot']) {
       // the original generator can be referenced with percy.yield.<method>
       let method = (this.yield || (this.yield = {}))[m] = this[m].bind(this);
       this[m] = (...args) => generatePromise(method(...args));
@@ -259,6 +263,15 @@ export class Percy {
         await this.loadAutoConfiguredHostnames();
       }
 
+      // validate and log archive dir if configured
+      if (this.archiveDir) {
+        let {
+          validateArchiveDir
+        } = await import('./archive.js');
+        this.archiveDir = validateArchiveDir(this.archiveDir);
+        this.log.info(`Archiving snapshots to: ${this.archiveDir}`);
+      }
+
       // start the snapshots queue immediately when not delayed or deferred
       if (!this.delayUploads && !this.deferUploads) yield _classPrivateFieldGet(_snapshots, this).start();
       // do not start the discovery queue when not needed
@@ -400,6 +413,11 @@ export class Percy {
         this.log.info(info('Found', _classPrivateFieldGet(_snapshots, this).size));
       }
 
+      // log archive summary
+      if (this.archiveDir && _classPrivateFieldGet(_snapshots, this).size) {
+        this.log.info(`Archived ${_classPrivateFieldGet(_snapshots, this).size} snapshot(s) to: ${this.archiveDir}`);
+      }
+
       // Save domain validation config before closing
       if (!this.skipUploads && !this.skipDiscovery) {
         await this.saveHostnamesToAutoConfigure();
@@ -429,7 +447,67 @@ export class Percy {
       // This issue doesn't comes under regular error logs,
       // it's detected if we just and stop percy server
       await this.checkForNoSnapshotCommandError();
+      // sendBuildLogs goes first — it's the primary egress. cache_summary is
+      // analytics, ordered after so a slow pager hop cannot delay the logs.
       await this.sendBuildLogs();
+      await this.sendCacheSummary();
+    }
+  }
+
+  // Single egress point for cache-tier telemetry. Used by sendCacheSummary
+  // (awaited at stop) and discovery's fire-and-forget eviction event. Returns
+  // early if no build is associated, swallows pager rejections — telemetry
+  // loss must never fail a build.
+  async sendCacheTelemetry(message, extra) {
+    var _this$build2;
+    if (!((_this$build2 = this.build) !== null && _this$build2 !== void 0 && _this$build2.id)) return;
+    try {
+      await this.client.sendBuildEvents(this.build.id, {
+        message,
+        cliVersion: this.client.cliVersion,
+        clientInfo: this.clientInfo,
+        extra
+      });
+    } catch (err) {
+      this.log.debug(`${message} telemetry failed`, err);
+    }
+  }
+
+  // Cache-usage summary fired at stop. The whole method is wrapped — the
+  // contract is "telemetry must never fail percy.stop()", which covers the
+  // payload-construction block as well as the egress.
+  async sendCacheSummary() {
+    try {
+      var _stats$finalDiskStats;
+      const cache = this[RESOURCE_CACHE_KEY];
+      const stats = this[CACHE_STATS_KEY];
+      if (!cache || !stats) return;
+      const cacheStats = typeof cache.stats === 'object' ? cache.stats : null;
+      // diskStore is destroyed by discovery 'end' before this runs, so fall
+      // back to the snapshot captured in stats.finalDiskStats.
+      const diskStore = this[DISK_SPILL_KEY];
+      const diskSnap = (diskStore === null || diskStore === void 0 ? void 0 : diskStore.stats) ?? stats.finalDiskStats;
+      const diskReady = diskStore ? diskStore.ready : !!((_stats$finalDiskStats = stats.finalDiskStats) !== null && _stats$finalDiskStats !== void 0 && _stats$finalDiskStats.ready);
+      await this.sendCacheTelemetry('cache_summary', {
+        cache_budget_ram_mb: stats.effectiveMaxCacheRamMB,
+        hits: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.hits) ?? 0,
+        misses: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.misses) ?? 0,
+        evictions: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.evictions) ?? 0,
+        peak_bytes: (cacheStats === null || cacheStats === void 0 ? void 0 : cacheStats.peakBytes) ?? stats.unsetModeBytes,
+        final_bytes: cache.calculatedSize ?? stats.unsetModeBytes,
+        entry_count: cache.size ?? 0,
+        oversize_skipped: stats.oversizeSkipped,
+        disk_spill_enabled: diskReady,
+        disk_spilled_count: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.spilled) ?? 0,
+        disk_restored_count: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.restored) ?? 0,
+        disk_spill_failures: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.spillFailures) ?? 0,
+        disk_read_failures: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.readFailures) ?? 0,
+        disk_peak_bytes: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.peakBytes) ?? 0,
+        disk_final_bytes: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.currentBytes) ?? 0,
+        disk_final_entries: (diskSnap === null || diskSnap === void 0 ? void 0 : diskSnap.entries) ?? 0
+      });
+    } catch (err) {
+      this.log.debug('cache_summary build failed', err);
     }
   }
   checkAndUpdateConcurrency() {
@@ -487,10 +565,10 @@ export class Percy {
   // snapshots. Once asset discovery has completed for the provided snapshots, the queued task will
   // resolve and an upload task will be queued separately.
   snapshot(options, snapshotPromise = {}) {
-    var _this$build2;
+    var _this$build3;
     if (this.readyState !== 1) {
       throw new Error('Not running');
-    } else if ((_this$build2 = this.build) !== null && _this$build2 !== void 0 && _this$build2.error) {
+    } else if ((_this$build3 = this.build) !== null && _this$build3 !== void 0 && _this$build3.error) {
       throw new Error(this.build.error);
     } else if (Array.isArray(options)) {
       return yieldAll(options.map(o => this.yield.snapshot(o, snapshotPromise)));
@@ -551,6 +629,17 @@ export class Percy {
             config: this.config
           })
         }, snapshot => {
+          // archive snapshot to disk if configured
+          if (this.archiveDir) {
+            import('./archive.js').then(({
+              archiveSnapshot
+            }) => {
+              archiveSnapshot(this.archiveDir, snapshot);
+            }).catch(err => {
+              this.log.error(`Failed to archive snapshot "${snapshot.name}": ${err.message}`);
+            });
+          }
+
           // attaching promise resolve reject so to wait for snapshot to complete
           if (this.syncMode(snapshot)) {
             snapshotPromise[snapshot.name] = new Promise((resolve, reject) => {
@@ -640,6 +729,25 @@ export class Percy {
       }
     }.call(this);
   }
+
+  // Pushes a pre-built snapshot directly to the upload queue without discovery.
+  // Used by the replay command to upload previously archived snapshots.
+  *replaySnapshot(snapshot) {
+    var _this$build4;
+    if (this.readyState !== 1) {
+      throw new Error('Not running');
+    } else if ((_this$build4 = this.build) !== null && _this$build4 !== void 0 && _this$build4.error) {
+      throw new Error(this.build.error);
+    }
+    snapshot.meta = {
+      snapshot: {
+        name: snapshot.name,
+        testCase: snapshot.testCase
+      }
+    };
+    this.log.info(`Replaying snapshot: ${snapshot.name}`, snapshot.meta);
+    _classPrivateFieldGet(_snapshots, this).push(snapshot);
+  }
   shouldSkipAssetDiscovery(tokenType) {
     if (this.testing && JSON.stringify(this.testing) === JSON.stringify({})) {
       return true;
@@ -720,7 +828,7 @@ export class Percy {
   async sendBuildLogs() {
     if (!process.env.PERCY_TOKEN) return;
     try {
-      var _this$build3, _this$build4, _this$build5, _this$build6;
+      var _this$build5, _this$build6, _this$build7, _this$build8;
       const logsObject = {
         clilogs: logger.query(log => !['ci'].includes(log.debug))
       };
@@ -732,10 +840,10 @@ export class Percy {
         logsObject.cilogs = redactedContent;
       }
       const content = base64encode(Pako.gzip(JSON.stringify(logsObject)));
-      const referenceId = (_this$build3 = this.build) !== null && _this$build3 !== void 0 && _this$build3.id ? `build_${(_this$build4 = this.build) === null || _this$build4 === void 0 ? void 0 : _this$build4.id}` : (_this$build5 = this.build) === null || _this$build5 === void 0 ? void 0 : _this$build5.id;
+      const referenceId = (_this$build5 = this.build) !== null && _this$build5 !== void 0 && _this$build5.id ? `build_${(_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id}` : (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id;
       const eventObject = {
         content: content,
-        build_id: (_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id,
+        build_id: (_this$build8 = this.build) === null || _this$build8 === void 0 ? void 0 : _this$build8.id,
         reference_id: referenceId,
         service_name: 'cli',
         base64encoded: true
@@ -808,9 +916,9 @@ export class Percy {
     const newAllowedDomains = Array.from(processedHosts).filter(domain => !autoConfiguredHosts.has(domain));
     const hasNewDomains = newAllowedDomains.length > 0 || newErrorHosts.size > 0;
     try {
-      var _this$build7;
+      var _this$build9;
       await this.client.updateProjectDomainConfig({
-        buildId: (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id,
+        buildId: (_this$build9 = this.build) === null || _this$build9 === void 0 ? void 0 : _this$build9.id,
         allowedDomains: Array.from(processedHosts),
         errorDomains: Array.from(newErrorHosts)
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/core",
-  "version": "1.31.14-beta.0",
+  "version": "1.31.14-beta.2",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     },
     "./utils": "./dist/utils.js",
     "./config": "./dist/config.js",
+    "./archive": "./dist/archive.js",
     "./install": "./dist/install.js",
     "./test/helpers": "./test/helpers/index.js",
     "./test/helpers/server": "./test/helpers/server.js"
@@ -43,12 +44,12 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/client": "1.31.14-beta.0",
-    "@percy/config": "1.31.14-beta.0",
-    "@percy/dom": "1.31.14-beta.0",
-    "@percy/logger": "1.31.14-beta.0",
-    "@percy/monitoring": "1.31.14-beta.0",
-    "@percy/webdriver-utils": "1.31.14-beta.0",
+    "@percy/client": "1.31.14-beta.2",
+    "@percy/config": "1.31.14-beta.2",
+    "@percy/dom": "1.31.14-beta.2",
+    "@percy/logger": "1.31.14-beta.2",
+    "@percy/monitoring": "1.31.14-beta.2",
+    "@percy/webdriver-utils": "1.31.14-beta.2",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
@@ -62,7 +63,7 @@
     "yaml": "^2.4.1"
   },
   "optionalDependencies": {
-    "@percy/cli-doctor": "1.31.14-beta.0"
+    "@percy/cli-doctor": "1.31.14-beta.2"
   },
-  "gitHead": "a87281473a9f5cb69a3030845cc4d6b4b81509b0"
+  "gitHead": "e4fce73023453b77cdef50aac1a9bd5eb70cd01a"
 }