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

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/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

@@ -422,6 +422,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;
@@ -429,7 +429,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 +547,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)));
@@ -720,7 +780,7 @@ export class Percy {
   async sendBuildLogs() {
     if (!process.env.PERCY_TOKEN) return;
     try {
-      var _this$build3, _this$build4, _this$build5, _this$build6;
+      var _this$build4, _this$build5, _this$build6, _this$build7;
       const logsObject = {
         clilogs: logger.query(log => !['ci'].includes(log.debug))
       };
@@ -732,10 +792,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$build4 = this.build) !== null && _this$build4 !== void 0 && _this$build4.id ? `build_${(_this$build5 = this.build) === null || _this$build5 === void 0 ? void 0 : _this$build5.id}` : (_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id;
       const eventObject = {
         content: content,
-        build_id: (_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id,
+        build_id: (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id,
         reference_id: referenceId,
         service_name: 'cli',
         base64encoded: true
@@ -808,9 +868,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$build8;
       await this.client.updateProjectDomainConfig({
-        buildId: (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id,
+        buildId: (_this$build8 = this.build) === null || _this$build8 === void 0 ? void 0 : _this$build8.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.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -43,12 +43,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.1",
+    "@percy/config": "1.31.14-beta.1",
+    "@percy/dom": "1.31.14-beta.1",
+    "@percy/logger": "1.31.14-beta.1",
+    "@percy/monitoring": "1.31.14-beta.1",
+    "@percy/webdriver-utils": "1.31.14-beta.1",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
@@ -62,7 +62,7 @@
     "yaml": "^2.4.1"
   },
   "optionalDependencies": {
-    "@percy/cli-doctor": "1.31.14-beta.0"
+    "@percy/cli-doctor": "1.31.14-beta.1"
   },
-  "gitHead": "a87281473a9f5cb69a3030845cc4d6b4b81509b0"
+  "gitHead": "dd6957822cc94d460fd9c043a44cc4c9c5fcba23"
 }